Skip to content

Automatically port Reflection.PortableExecutable.DebugDirectory* APIs #3196

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Oct 11, 2019
Merged

Automatically port Reflection.PortableExecutable.DebugDirectory* APIs #3196

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
f73ea32
Automatically port Reflection.PortableExecutable.DebugDirectory*
carlossanlop Sep 16, 2019
804feb5
Made direct edits.
Sep 26, 2019
d20e03e
Made direct edits.
Sep 26, 2019
35a5426
Added edits directly
Sep 26, 2019
58d9db2
Update DebugDirectoryEntryType.xml
Oct 11, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
53 changes: 30 additions & 23 deletions xml/System.Reflection.PortableExecutable/DebugDirectoryBuilder.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@
</AssemblyInfo>
<Parameters />
<Docs>
<summary>To be added.</summary>
<summary>Initializes a new instance of the <see cref="T:System.Reflection.PortableExecutable.DebugDirectoryBuilder" /> class.</summary>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand Down Expand Up @@ -65,11 +65,14 @@
<Parameter Name="portablePdbVersion" Type="System.UInt16" Index="2" FrameworkAlternate="netcore-1.1;netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0" />
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we provide a type description?

</Parameters>
<Docs>
<param name="pdbPath">To be added.</param>
<param name="pdbContentId">To be added.</param>
<param name="portablePdbVersion">To be added.</param>
<summary>To be added.</summary>
<param name="pdbPath">The path to the PDB. It should not be empty.</param>
<param name="pdbContentId">The unique id of the PDB content.</param>
<param name="portablePdbVersion">The version of Portable PDB format (e.g. 0x0100 for 1.0), or 0 if the PDB is not portable.</param>
<summary>Adds a CodeView entry.</summary>
<remarks>To be added.</remarks>
<exception cref="T:System.ArgumentNullException"><paramref name="pdbPath" /> is <see langword="null" />.</exception>
<exception cref="T:System.ArgumentException"><paramref name="pdbPath" /> contains a NUL character.</exception>
<exception cref="T:System.ArgumentOutOfRangeException"><paramref name="portablePdbVersion" /> is smaller than 0x0100.</exception>
</Docs>
</Member>
<Member MemberName="AddEmbeddedPortablePdbEntry">
Expand All @@ -95,10 +98,12 @@
<Parameter Name="portablePdbVersion" Type="System.UInt16" Index="1" FrameworkAlternate="netcore-1.1;netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0" />
</Parameters>
<Docs>
<param name="debugMetadata">To be added.</param>
<param name="portablePdbVersion">To be added.</param>
<summary>To be added.</summary>
<param name="debugMetadata">A Portable PDB metadata builder.</param>
<param name="portablePdbVersion">The version of Portable PDB format (e.g. 0x0100 for 1.0).</param>
<summary>Adds an Embedded Portable PDB entry.</summary>
<remarks>To be added.</remarks>
<exception cref="T:System.ArgumentNullException"><paramref name="debugMetadata" /> is <see langword="null" />.</exception>
<exception cref="T:System.ArgumentOutOfRangeException"><paramref name="portablePdbVersion" /> is smaller than 0x0100.</exception>
</Docs>
</Member>
<Member MemberName="AddEntry">
Expand All @@ -123,10 +128,10 @@
<Parameter Name="stamp" Type="System.UInt32" Index="2" FrameworkAlternate="netcore-2.1;netcore-2.2;netcore-3.0" />
</Parameters>
<Docs>
<param name="type">To be added.</param>
<param name="version">To be added.</param>
<param name="stamp">To be added.</param>
<summary>To be added.</summary>
<param name="type">The entry type.</param>
<param name="version">The entry version.</param>
<param name="stamp">The entry stamp.</param>
<summary>Adds an entry of the specified type.</summary>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand Down Expand Up @@ -157,13 +162,13 @@
<Parameter Name="dataSerializer" Type="System.Action&lt;System.Reflection.Metadata.BlobBuilder,TData&gt;" Index="4" FrameworkAlternate="netcore-2.1;netcore-2.2;netcore-3.0" />
</Parameters>
<Docs>
<typeparam name="TData">To be added.</typeparam>
<param name="type">To be added.</param>
<param name="version">To be added.</param>
<param name="stamp">To be added.</param>
<param name="data">To be added.</param>
<param name="dataSerializer">To be added.</param>
<summary>To be added.</summary>
<typeparam name="TData">The type of the data passed to <paramref name="dataSerializer" />.</typeparam>
<param name="type">The entry type.</param>
<param name="version">The entry version.</param>
<param name="stamp">The entry stamp.</param>
<param name="data">The data to pass to <paramref name="dataSerializer" />.</param>
<param name="dataSerializer">A serializer for serializing data to a <see cref="T:System.Reflection.Metadata.BlobBuilder" />.</param>
<summary>Adds an entry of the specified type and serializes its data.</summary>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand All @@ -188,10 +193,12 @@
<Parameter Name="checksum" Type="System.Collections.Immutable.ImmutableArray&lt;System.Byte&gt;" Index="1" FrameworkAlternate="netcore-2.1;netcore-2.2;netcore-3.0" />
</Parameters>
<Docs>
<param name="algorithmName">To be added.</param>
<param name="checksum">To be added.</param>
<summary>To be added.</summary>
<param name="algorithmName">The hash algorithm name (for example, "SHA256").</param>
<param name="checksum">The checksum.</param>
<summary>Adds PDB checksum entry.</summary>
<remarks>To be added.</remarks>
<exception cref="T:System.ArgumentNullException"><paramref name="algorithmName" /> or <paramref name="checksum" /> is <see langword="null" />.</exception>
<exception cref="T:System.ArgumentException"><paramref name="algorithmName" /> or <paramref name="checksum" /> is empty.</exception>
</Docs>
</Member>
<Member MemberName="AddReproducibleEntry">
Expand All @@ -214,7 +221,7 @@
</ReturnValue>
<Parameters />
<Docs>
<summary>To be added.</summary>
<summary>Adds a reproducible entry.</summary>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand Down
46 changes: 27 additions & 19 deletions xml/System.Reflection.PortableExecutable/DebugDirectoryEntry.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@
</Attribute>
</Attributes>
<Docs>
<summary>To be added.</summary>
<summary>Identifies the location, size and format of a block of debug information.</summary>
<remarks>To be added.</remarks>
</Docs>
<Members>
Expand Down Expand Up @@ -60,7 +60,7 @@
<param name="dataSize">To be added.</param>
<param name="dataRelativeVirtualAddress">To be added.</param>
<param name="dataPointer">To be added.</param>
<summary>To be added.</summary>
<summary>Initializes a new instance of the <see cref="T:System.Reflection.PortableExecutable.DebugDirectoryEntry" /> structure.</summary>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand All @@ -84,8 +84,8 @@
<ReturnType>System.Int32</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<value>To be added.</value>
<summary>Gets the file pointer to the debug data.</summary>
<value>The file pointer to the debug data.</value>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand All @@ -109,8 +109,8 @@
<ReturnType>System.Int32</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<value>To be added.</value>
<summary>Gets the address of the debug data when loaded, relative to the image base.</summary>
<value>The address of the debug data relative to the image base.</value>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand All @@ -134,8 +134,8 @@
<ReturnType>System.Int32</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<value>To be added.</value>
<summary>Gets the size of the debug data (not including the debug directory itself).</summary>
<value>the size of the debug data (excluding the debug directory).</value>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand All @@ -158,8 +158,8 @@
<ReturnType>System.Boolean</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<value>To be added.</value>
<summary>Gets a value that indicates if the entry is a <see cref="F:System.Reflection.PortableExecutable.DebugDirectoryEntryType.CodeView" /> entry that points to a Portable PDB.</summary>
<value><see langword="true" /> if the entry is a <see cref="F:System.Reflection.PortableExecutable.DebugDirectoryEntryType.CodeView" /> entry pointing to a Portable PDB; otherwise, <see langword="false" />.</value>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand All @@ -183,8 +183,8 @@
<ReturnType>System.UInt16</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<value>To be added.</value>
<summary>Gets the major version number of the debug data format.</summary>
<value>The major version number of the debug data format.</value>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand All @@ -208,8 +208,8 @@
<ReturnType>System.UInt16</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<value>To be added.</value>
<summary>Gets the minor version number of the debug data format.</summary>
<value>The minor version number of the debug data format.</value>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand All @@ -233,9 +233,17 @@
<ReturnType>System.UInt32</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<value>To be added.</value>
<remarks>To be added.</remarks>
<summary>Get the time and date that the debug data was created if the PE/COFF file is not deterministic; otherwise, gets a value based on the hash of the content.</summary>
<value>for a non-deterministic PE/COFF file, the time and date that the debug data was created; otherwise, a value based on the hash of the content.</value>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks

The algorithm used to calculate this value is an implementation detail of the tool that produced the file.

]]></format>
</remarks>
</Docs>
</Member>
<Member MemberName="Type">
Expand All @@ -258,8 +266,8 @@
<ReturnType>System.Reflection.PortableExecutable.DebugDirectoryEntryType</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<value>To be added.</value>
<summary>Gets the format of the debugging information.</summary>
<value>The format of the debugging information.</value>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand Down
37 changes: 30 additions & 7 deletions xml/System.Reflection.PortableExecutable/DebugDirectoryEntryType.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,30 @@
</Base>
<Docs>
<summary>To be added.</summary>
<remarks>To be added.</remarks>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks

See the following for the specifications related to individual enumeration members:

|Member|Specification|
|---|---|
|`CodeView`|[CodeView Debug Directory Entry (type 2)](https://github.com/dotnet/corefx/blob/master/src/System.Reflection.Metadata/specs/PE-COFF.md#codeview-debug-directory-entry-type-2)|
|`EmbeddedPortablePdb`|[Embedded Portale PDB Debu Directory Entry (type 17)](https://github.com/dotnet/corefx/blob/master/src/System.Reflection.Metadata/specs/PE-COFF.md#embedded-portable-pdb-debug-directory-entry-type-17)|
|`PdbChecksum`|[PDB Checksum Debug Directory Entry (type 19)](https://github.com/dotnet/corefx/blob/master/src/System.Reflection.Metadata/specs/PE-COFF.md#pdb-checksum-debug-directory-entry-type-19)|
|`Reproducible`|See [Deterministic Debug Directory Entry (type 16)](https://github.com/dotnet/corefx/blob/master/src/System.Reflection.Metadata/specs/PE-COFF.md#deterministic-debug-directory-entry-type-16)|

### DebugDirectoryEntryType.Reproducible

The tool that produced the deterministic PE/COFF file guarantees that the entire content of the file is based solely on documented inputs given to the tool (such as source files, resource files, compiler options, etc.) rather than ambient environment variables (such as the current time, the operating system, the bitness of the process running the tool, etc.).

The value of the `TimeDateStamp` field in the COFF File Header of a deterministic PE/COFF file does not indicate the date and time when the file was produced and should not be interpreted that way. Instead, the value of the field is derived from a hash of the file content. The algorithm to calculate this value is an implementation detail of the tool that produced the file.

The debug directory entry of type <xref:System.Reflection.PortableExecutable.DebugDirectoryEntryType.Reproducible> must have all fields except for <xref:System.Reflection.PortableExecutable.DebugDirectoryEntry.Type?displayProperty=nameWithType> zeroed.

]]></format>
</remarks>
</Docs>
<Members>
<Member MemberName="CodeView">
Expand All @@ -42,7 +65,7 @@
</ReturnValue>
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It would be good to add an enum type description.

<MemberValue>2</MemberValue>
<Docs>
<summary>To be added.</summary>
<summary>Associated PDB file description.</summary>
</Docs>
</Member>
<Member MemberName="Coff">
Expand All @@ -66,7 +89,7 @@
</ReturnValue>
<MemberValue>1</MemberValue>
<Docs>
<summary>To be added.</summary>
<summary>The COFF debug information (line numbers, symbol table, and string table). This type of debug information is also pointed to by fields in the file headers.</summary>
</Docs>
</Member>
<Member MemberName="EmbeddedPortablePdb">
Expand All @@ -89,7 +112,7 @@
</ReturnValue>
<MemberValue>17</MemberValue>
<Docs>
<summary>To be added.</summary>
<summary><para>The entry points to a blob containing Embedded Portable PDB. The Embedded Portable PDB blob has the following format:</para><para>- blob ::= uncompressed-size data</para><para>- Data spans the remainder of the blob and contains a Deflate-compressed Portable PDB.</para></summary>
</Docs>
</Member>
<Member MemberName="PdbChecksum">
Expand All @@ -110,7 +133,7 @@
</ReturnValue>
<MemberValue>19</MemberValue>
<Docs>
<summary>To be added.</summary>
<summary>The entry stores a crypto hash of the content of the symbol file the PE/COFF file was built with. The hash can be used to validate that a given PDB file was built with the PE/COFF file and not altered in any way. More than one entry can be present if multiple PDBs were produced during the build of the PE/COFF file (e.g. private and public symbols).</summary>
</Docs>
</Member>
<Member MemberName="Reproducible">
Expand All @@ -134,7 +157,7 @@
</ReturnValue>
<MemberValue>16</MemberValue>
<Docs>
<summary>To be added.</summary>
<summary>The presence of this entry indicates a deterministic PE/COFF file. See the Remarks section for more information.</summary>
</Docs>
</Member>
<Member MemberName="Unknown">
Expand All @@ -158,7 +181,7 @@
</ReturnValue>
<MemberValue>0</MemberValue>
<Docs>
<summary>To be added.</summary>
<summary>An unknown value that should be ignored by all tools.</summary>
</Docs>
</Member>
</Members>
Expand Down