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 1 commit
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
51 changes: 29 additions & 22 deletions xml/System.Reflection.PortableExecutable/DebugDirectoryBuilder.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
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">Path to the PDB. Shall not be empty.</param>
<param name="pdbContentId">Unique id of the PDB content.</param>
<param name="portablePdbVersion">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 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">Portable PDB metadata builder.</param>
<param name="portablePdbVersion">Version of Portable PDB format (e.g. 0x0100 for 1.0).</param>
<summary>Adds 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">Entry type.</param>
<param name="version">Entry version.</param>
<param name="stamp">Entry stamp.</param>
<summary>Adds an entry.</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">Type of data passed to <paramref name="dataSerializer" />.</typeparam>
<param name="type">Entry type.</param>
<param name="version">Entry version.</param>
<param name="stamp">Entry stamp.</param>
<param name="data">Data passed to <paramref name="dataSerializer" />.</param>
<param name="dataSerializer">Serializes data to a <see cref="T:System.Reflection.Metadata.BlobBuilder" />.</param>
<summary>Adds an entry.</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">Hash algorithm name (e.g. "SHA256").</param>
<param name="checksum">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 Reproducible entry.</summary>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand Down
28 changes: 18 additions & 10 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 @@ -84,7 +84,7 @@
<ReturnType>System.Int32</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<summary>The file pointer to the debug data.</summary>
<value>To be added.</value>
<remarks>To be added.</remarks>
</Docs>
Expand All @@ -109,7 +109,7 @@
<ReturnType>System.Int32</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<summary>The address of the debug data when loaded, relative to the image base.</summary>
<value>To be added.</value>
<remarks>To be added.</remarks>
</Docs>
Expand All @@ -134,7 +134,7 @@
<ReturnType>System.Int32</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<summary>The size of the debug data (not including the debug directory itself).</summary>
<value>To be added.</value>
<remarks>To be added.</remarks>
</Docs>
Expand All @@ -158,7 +158,7 @@
<ReturnType>System.Boolean</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<summary><see langword="true" /> if the entry is a <see cref="F:System.Reflection.PortableExecutable.DebugDirectoryEntryType.CodeView" /> entry pointing to a Portable PDB.</summary>
<value>To be added.</value>
<remarks>To be added.</remarks>
</Docs>
Expand All @@ -183,7 +183,7 @@
<ReturnType>System.UInt16</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<summary>The major version number of the debug data format.</summary>
<value>To be added.</value>
<remarks>To be added.</remarks>
</Docs>
Expand All @@ -208,7 +208,7 @@
<ReturnType>System.UInt16</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<summary>The minor version number of the debug data format.</summary>
<value>To be added.</value>
<remarks>To be added.</remarks>
</Docs>
Expand All @@ -233,9 +233,17 @@
<ReturnType>System.UInt32</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<summary>The time and date that the debug data was created if the PE/COFF file is not deterministic, otherwise a value based on the hash of the content.</summary>
<value>To be added.</value>
<remarks>To be added.</remarks>
<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,7 +266,7 @@
<ReturnType>System.Reflection.PortableExecutable.DebugDirectoryEntryType</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<summary>The format of debugging information.</summary>
<value>To be added.</value>
<remarks>To be added.</remarks>
</Docs>
Expand Down
75 changes: 69 additions & 6 deletions xml/System.Reflection.PortableExecutable/DebugDirectoryEntryType.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,16 @@
</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>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks

See https://github.com/dotnet/corefx/blob/master/src/System.Reflection.Metadata/specs/PE-COFF.md#codeview-debug-directory-entry-type-2 for specification.

]]></format>
</remarks>
</Docs>
</Member>
<Member MemberName="Coff">
Expand All @@ -66,7 +75,16 @@
</ReturnValue>
<MemberValue>1</MemberValue>
<Docs>
<summary>To be added.</summary>
<summary>The COFF debug information (line numbers, symbol table, and string table).</summary>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks

This type of debug information is also pointed to by fields in the file headers.

]]></format>
</remarks>
</Docs>
</Member>
<Member MemberName="EmbeddedPortablePdb">
Expand All @@ -89,7 +107,21 @@
</ReturnValue>
<MemberValue>17</MemberValue>
<Docs>
<summary>To be added.</summary>
<summary>The entry points to a blob containing Embedded Portable PDB.</summary>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks

The Embedded Portable PDB blob has the following format:

blob ::= uncompressed-size data
Data spans the remainder of the blob and contains a Deflate-compressed Portable PDB.

See https://github.com/dotnet/corefx/blob/master/src/System.Reflection.Metadata/specs/PE-COFF.md#embedded-portable-pdb-debug-directory-entry-type-17 for specification.

]]></format>
</remarks>
</Docs>
</Member>
<Member MemberName="PdbChecksum">
Expand All @@ -110,7 +142,20 @@
</ReturnValue>
<MemberValue>19</MemberValue>
<Docs>
<summary>To be added.</summary>
<summary>The entry stores crypto hash of the content of the symbol file the PE/COFF file was built with.</summary>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks

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, in case multiple PDBs were produced during the build of the PE/COFF file (e.g. private and public symbols).

See https://github.com/dotnet/corefx/blob/master/src/System.Reflection.Metadata/specs/PE-COFF.md#pdb-checksum-debug-directory-entry-type-19 for specification.

]]></format>
</remarks>
</Docs>
</Member>
<Member MemberName="Reproducible">
Expand All @@ -134,7 +179,25 @@
</ReturnValue>
<MemberValue>16</MemberValue>
<Docs>
<summary>To be added.</summary>
<summary>Presence of this entry indicates deterministic PE/COFF file.</summary>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks
Copy link
Member

Choose a reason for hiding this comment

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

Remarks [](start = 1, length = 9)

Empty remarks?


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 field `TimeDateStamp` in 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 Type zeroed.

See https://github.com/dotnet/corefx/blob/master/src/System.Reflection.Metadata/specs/PE-COFF.md#deterministic-debug-directory-entry-type-16 for specification.


]]></format>
</remarks>
</Docs>
</Member>
<Member MemberName="Unknown">
Expand All @@ -158,7 +221,7 @@
</ReturnValue>
<MemberValue>0</MemberValue>
<Docs>
<summary>To be added.</summary>
<summary>An unknown value that is ignored by all tools.</summary>
Copy link
Member

Choose a reason for hiding this comment

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

"should be ignored"?

</Docs>
</Member>
</Members>
Expand Down