pe: add lots of documentation

* Documented the DOS header
* Partially documented COFF header and added more machine constants
* Started documenting optional header
* Documented standard fields
* Nearly fully documented the PE optional header

src/pe/characteristic.rs

@@ -1,3 +1,6 @@
+//! Constants for flags that indicate attributes of the object or image file. These flags are used in the
+//! [`goblin::pe::header::CoffHeader::characteristics`](crate::pe::header::CoffHeader::characteristics) field.
+
 /*
 type characteristic =
     | IMAGE_FILE_RELOCS_STRIPPED
@@ -73,27 +76,65 @@ let show_type characteristics =
   else "MANY"                   (* print all *)
  */
 
+/// Image only, Windows CE, and Microsoft Windows NT and later. This indicates that the file does not
+/// contain base relocations and must therefore be loaded at its preferred base address. If the base address
+/// is not available, the loader reports an error. The default behavior of the linker is to strip base relocations
+/// from executable (EXE) files.
 pub const IMAGE_FILE_RELOCS_STRIPPED: u16 = 0x0001;
+
+/// Image only. This indicates that the image file is valid and can be run.
+/// If this flag is not set, it indicates a linker error.
 pub const IMAGE_FILE_EXECUTABLE_IMAGE: u16 = 0x0002;
+
+/// COFF line numbers have been removed. This flag is deprecated and should be zero.
 pub const IMAGE_FILE_LINE_NUMS_STRIPPED: u16 = 0x0004;
+
+/// COFF symbol table entries for local symbols have been removed. This flag is deprecated and should be zero.
 pub const IMAGE_FILE_LOCAL_SYMS_STRIPPED: u16 = 0x0008;
+
+/// Obsolete. Aggressively trim working set. This flag is deprecated for Windows 2000 and later and must be zero.
 pub const IMAGE_FILE_AGGRESSIVE_WS_TRIM: u16 = 0x0010;
+
+/// Application can handle > 2-GB addresses.
 pub const IMAGE_FILE_LARGE_ADDRESS_AWARE: u16 = 0x0020;
+
+/// This flag is reserved for future use.
 pub const RESERVED: u16 = 0x0040;
+
+/// Little endian: the least significant bit (LSB) precedes the most significant bit (MSB) in memory.
+/// This flag is deprecated and should be zero.
 pub const IMAGE_FILE_BYTES_REVERSED_LO: u16 = 0x0080;
+
+/// Machine is based on a 32-bit-word architecture.
 pub const IMAGE_FILE_32BIT_MACHINE: u16 = 0x0100;
+
+/// Debugging information is removed from the image file.
 pub const IMAGE_FILE_DEBUG_STRIPPED: u16 = 0x0200;
+
+/// If the image is on removable media, fully load it and copy it to the swap file.
 pub const IMAGE_FILE_REMOVABLE_RUN_FROM_SWAP: u16 = 0x0400;
+
+/// If the image is on network media, fully load it and copy it to the swap file.
 pub const IMAGE_FILE_NET_RUN_FROM_SWAP: u16 = 0x0800;
+
+/// The image file is a system file, not a user program.
 pub const IMAGE_FILE_SYSTEM: u16 = 0x1000;
+
+/// The image file is a dynamic-link library (DLL). Such files are considered executable files for almost all purposes, although they cannot be directly run.
 pub const IMAGE_FILE_DLL: u16 = 0x2000;
+
+/// The file should be run only on a uniprocessor machine.
 pub const IMAGE_FILE_UP_SYSTEM_ONLY: u16 = 0x4000;
+
+/// Big endian: the MSB precedes the LSB in memory. This flag is deprecated and should be zero.
 pub const IMAGE_FILE_BYTES_REVERSED_HI: u16 = 0x8000;
 
+/// Checks whether the characteristics value indicates that the file is a DLL (dynamically-linked library).
 pub fn is_dll(characteristics: u16) -> bool {
     characteristics & IMAGE_FILE_DLL == IMAGE_FILE_DLL
 }
 
+/// Checks whether the characteristics value indicates that the file is an executable.
 pub fn is_exe(characteristics: u16) -> bool {
     characteristics & IMAGE_FILE_EXECUTABLE_IMAGE == IMAGE_FILE_EXECUTABLE_IMAGE
 }

src/pe/dll_characteristic.rs

@@ -0,0 +1,38 @@
+//! Constants for characteristics of image files. These constants are used in the
+//! [`goblin::pe::optional_header::WindowsFields::dll_characteristics`](crate::pe::optional_header::WindowsFields::dll_characteristics)
+//! field.
+//!
+//! The values 0x0001, 0x0002, 0x0004, 0x0008 are reserved for future use and must be zero.
+
+/// Image can handle a high entropy 64-bit virtual address space.
+pub const IMAGE_DLLCHARACTERISTICS_HIGH_ENTROPY_VA: u16 = 0x0020;
+
+/// DLL can be relocated at load time.
+pub const IMAGE_DLLCHARACTERISTICS_DYNAMIC_BASE: u16 = 0x0040;
+
+/// Code Integrity checks are enforced.
+pub const IMAGE_DLLCHARACTERISTICS_FORCE_INTEGRITY: u16 = 0x0080;
+
+/// Image is NX compatible.
+pub const IMAGE_DLLCHARACTERISTICS_NX_COMPAT: u16 = 0x0100;
+
+/// Isolation aware, but do not isolate the image.
+pub const IMAGE_DLLCHARACTERISTICS_NO_ISOLATION: u16 = 0x0200;
+
+/// Does not use structured exception (SE) handling. No SE handler may be called in this image.
+pub const IMAGE_DLLCHARACTERISTICS_NO_SEH: u16 = 0x0400;
+
+/// Do not bind the image.
+pub const IMAGE_DLLCHARACTERISTICS_NO_BIND: u16 = 0x0800;
+
+/// Image must execute in an AppContainer.
+pub const IMAGE_DLLCHARACTERISTICS_APPCONTAINER: u16 = 0x1000;
+
+/// A WDM driver.
+pub const IMAGE_DLLCHARACTERISTICS_WDM_DRIVER: u16 = 0x2000;
+
+/// Image supports Control Flow Guard.
+pub const IMAGE_DLLCHARACTERISTICS_GUARD_CF: u16 = 0x4000;
+
+/// Terminal Server aware.
+pub const IMAGE_DLLCHARACTERISTICS_TERMINAL_SERVER_AWARE: u16 = 0x8000;