Add MinidumpCrashpadModule, its list form, their writers, and their tests

minidump/minidump_extensions.h

Index: minidump/minidump_extensions.h
diff --git a/minidump/minidump_extensions.h b/minidump/minidump_extensions.h
index e7618e3e0368c22cae715c013dd0ef0dd051703f..bd92f3eb67a2dee94b9e3208984fe6e32ac8cba8 100644
--- a/minidump/minidump_extensions.h
+++ b/minidump/minidump_extensions.h
@@ -316,29 +316,106 @@ struct __attribute__((packed, aligned(4))) MinidumpSimpleStringDictionary {
   MinidumpSimpleStringDictionaryEntry entries[0];
 };
 
+//! \brief Additional Crashpad-specific information about a module carried
+//!     within a minidump file.
+//!
+//! This structure augments the information provided by MINIDUMP_MODULE. The
+//! minidump file must contain a module list stream
+//! (::kMinidumpStreamTypeModuleList) in order for this structure to appear.
+//!
+//! This structure is versioned. When changing this structure, leave the
+//! existing structure intact so that earlier parsers will be able to understand
+//! the fields they are aware of, and make additions at the end of the
+//! structure. Revise #kVersion and document each field’s validity based on
+//! #version, so that newer parsers will be able to determine whether the added
+//! fields are valid or not.
+//!
+//! \sa MinidumpCrashpadModuleList
+struct __attribute__((packed, aligned(4))) MinidumpCrashpadModule {

[Robert Sesek, 2014/10/23 19:25:25]

I think "CrashpadModule" is a bit of a misnomer. Maybe
"MinidumpModuleCrashpadInfo" to go along with "MinidumpCrashpadInfo" ? It's kind
of a bikeshedy thing, and it would be a lot of renaming, though, so consider
this optional.

[Mark Mentovai, 2014/10/23 19:47:53]

Robert Sesek wrote:
Not totally bikeshedding. I renamed everything. Now it’s clearer that it’s not a
“Crashpad module.”

+  //! \brief The structure’s currently-defined version number.
+  //!
+  //! \sa version
+  static const uint32_t kVersion = 1;
+
+  //! \brief The structure’s version number.
+  //!
+  //! Readers can use this field to determine which other fields in the
+  //! structure are valid. Upon encountering a value greater than #kVersion, a
+  //! reader should assume that the structure’s layout is compatible with the
+  //! structure defined as having value #kVersion.
+  //!
+  //! Writers may produce values less than #kVersion in this field if there is
+  //! no need for any fields present in later versions.
+  uint32_t version;
+
+  //! \brief A link to a MINIDUMP_MODULE structure in the module list stream.
+  //!
+  //! This field is an index into MINIDUMP_MODULE_LIST::Modules. This field’s
+  //! value must be in the range of MINIDUMP_MODULE_LIST::NumberOfEntries.
+  //!
+  //! This field is present when #version is at least `1`.
+  uint32_t minidump_module_list_index;
+
+  //! \brief A MinidumpSimpleStringDictionary pointing to strings interpreted as
+  //!     key-value pairs. The module controls the data that appears here.
+  //!
+  //! This field is present when #version is at least `1`.
+  MINIDUMP_LOCATION_DESCRIPTOR simple_annotations;
+};
+
+//! \brief Additional Crashpad-specific information about modules carried within
+//!     a minidump file.
+//!
+//! This structure augments the information provided by
+//! MINIDUMP_MODULE_LIST. The minidump file must contain a module list stream
+//! (::kMinidumpStreamTypeModuleList) in order for this structure to appear.
+struct __attribute__((packed, aligned(4))) MinidumpCrashpadModuleList {
+  //! \brief The number of modules present in the #modules array.

[Robert Sesek, 2014/10/23 19:25:25]

#crahspad_modules, although I think that's a bit of a misnomer as discussed
above.

[Mark Mentovai, 2014/10/23 19:47:53]

Robert Sesek wrote:
Given the renaming, I simplified and am just calling these “modules” now.

+  //!
+  //! This may be less than the value of MINIDUMP_MODULE_LIST::NumberOfModules
+  //! because not every MINIDUMP_MODULE structure carried within the minidump
+  //! file will necessarily have Crashpad-specific information provided by a
+  //! MinidumpCrashpadModule structure.
+  uint32_t count;
+
+  //! \brief Pointers to MinidumpCrashpadModule structures.
+  //!
+  //! These are referenced indirectly through MINIDUMP_LOCATION_DESCRIPTOR
+  //! pointers to allow for future growth of the MinidumpCrashpadModule
+  //! structure.
+  MINIDUMP_LOCATION_DESCRIPTOR crashpad_modules[0];
+};
+
 //! \brief Additional Crashpad-specific information carried within a minidump
 //!     file.
+//!
+//! This structure is versioned. When changing this structure, leave the
+//! existing structure intact so that earlier parsers will be able to understand
+//! the fields they are aware of, and make additions at the end of the
+//! structure. Revise #kVersion and document each field’s validity based on
+//! #version, so that newer parsers will be able to determine whether the added
+//! fields are valid or not.
 struct __attribute__((packed, aligned(4))) MinidumpCrashpadInfo {
-  //! \brief The size of the entire structure, in bytes.
+  //! \brief The structure’s currently-defined version number.
   //!
   //! \sa version
-  uint32_t size;
+  static const uint32_t kVersion = 1;
 
-  //! \brief The structure’s version number. This can be used to determine which
-  //!     other fields in the structure are valid.
+  //! \brief The structure’s version number.
   //!
-  //! \sa size
+  //! Readers can use this field to determine which other fields in the
+  //! structure are valid. Upon encountering a value greater than #kVersion, a
+  //! reader should assume that the structure’s layout is compatible with the
+  //! structure defined as having value #kVersion.
+  //!
+  //! Writers may produce values less than #kVersion in this field if there is
+  //! no need for any fields present in later versions.
   uint32_t version;
 
-  //! \brief A MinidumpSimpleStringDictionary pointing to strings interpreted as
-  //!     key-value pairs. The process that crashed controlled the data that
-  //!     appears here.
-  //!
-  //! If MINIDUMP_LOCATION_DESCRIPTOR::DataSize is `0`, no key-value pairs are
-  //! present, and MINIDUMP_LOCATION_DESCRIPTOR::Rva should not be consulted.
+  //! \brief A pointer to a MinidumpCrashpadModuleList structure.
   //!
   //! This field is present when #version is at least `1`.
-  MINIDUMP_LOCATION_DESCRIPTOR simple_annotations;
+  MINIDUMP_LOCATION_DESCRIPTOR crashpad_module_list;
 };
 
 }  // namespace crashpad