Skip to content

Commit ebb2808

Browse files
carlossanlopRon Petrusha
carlossanlop
authored and
Ron Petrusha
committed
Automatically port Reflection.PortableExecutable.DebugDirectory* APIs (#3196)
* Automatically port Reflection.PortableExecutable.DebugDirectory* * Made direct edits. * Made direct edits. * Added edits directly * Update DebugDirectoryEntryType.xml
1 parent 76e7228 commit ebb2808

File tree

3 files changed

+87
-49
lines changed

3 files changed

+87
-49
lines changed

‎xml/System.Reflection.PortableExecutable/DebugDirectoryBuilder.xml

Lines changed: 30 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,7 @@
3737
</AssemblyInfo>
3838
<Parameters />
3939
<Docs>
40-
<summary>To be added.</summary>
40+
<summary>Initializes a new instance of the <see cref="T:System.Reflection.PortableExecutable.DebugDirectoryBuilder" /> class.</summary>
4141
<remarks>To be added.</remarks>
4242
</Docs>
4343
</Member>
@@ -65,11 +65,14 @@
6565
<Parameter Name="portablePdbVersion" Type="System.UInt16" Index="2" FrameworkAlternate="netcore-1.1;netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0" />
6666
</Parameters>
6767
<Docs>
68-
<param name="pdbPath">To be added.</param>
69-
<param name="pdbContentId">To be added.</param>
70-
<param name="portablePdbVersion">To be added.</param>
71-
<summary>To be added.</summary>
68+
<param name="pdbPath">The path to the PDB. It should not be empty.</param>
69+
<param name="pdbContentId">The unique id of the PDB content.</param>
70+
<param name="portablePdbVersion">The version of Portable PDB format (e.g. 0x0100 for 1.0), or 0 if the PDB is not portable.</param>
71+
<summary>Adds a CodeView entry.</summary>
7272
<remarks>To be added.</remarks>
73+
<exception cref="T:System.ArgumentNullException"><paramref name="pdbPath" /> is <see langword="null" />.</exception>
74+
<exception cref="T:System.ArgumentException"><paramref name="pdbPath" /> contains a NUL character.</exception>
75+
<exception cref="T:System.ArgumentOutOfRangeException"><paramref name="portablePdbVersion" /> is smaller than 0x0100.</exception>
7376
</Docs>
7477
</Member>
7578
<Member MemberName="AddEmbeddedPortablePdbEntry">
@@ -95,10 +98,12 @@
9598
<Parameter Name="portablePdbVersion" Type="System.UInt16" Index="1" FrameworkAlternate="netcore-1.1;netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0" />
9699
</Parameters>
97100
<Docs>
98-
<param name="debugMetadata">To be added.</param>
99-
<param name="portablePdbVersion">To be added.</param>
100-
<summary>To be added.</summary>
101+
<param name="debugMetadata">A Portable PDB metadata builder.</param>
102+
<param name="portablePdbVersion">The version of Portable PDB format (e.g. 0x0100 for 1.0).</param>
103+
<summary>Adds an Embedded Portable PDB entry.</summary>
101104
<remarks>To be added.</remarks>
105+
<exception cref="T:System.ArgumentNullException"><paramref name="debugMetadata" /> is <see langword="null" />.</exception>
106+
<exception cref="T:System.ArgumentOutOfRangeException"><paramref name="portablePdbVersion" /> is smaller than 0x0100.</exception>
102107
</Docs>
103108
</Member>
104109
<Member MemberName="AddEntry">
@@ -123,10 +128,10 @@
123128
<Parameter Name="stamp" Type="System.UInt32" Index="2" FrameworkAlternate="netcore-2.1;netcore-2.2;netcore-3.0" />
124129
</Parameters>
125130
<Docs>
126-
<param name="type">To be added.</param>
127-
<param name="version">To be added.</param>
128-
<param name="stamp">To be added.</param>
129-
<summary>To be added.</summary>
131+
<param name="type">The entry type.</param>
132+
<param name="version">The entry version.</param>
133+
<param name="stamp">The entry stamp.</param>
134+
<summary>Adds an entry of the specified type.</summary>
130135
<remarks>To be added.</remarks>
131136
</Docs>
132137
</Member>
@@ -157,13 +162,13 @@
157162
<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" />
158163
</Parameters>
159164
<Docs>
160-
<typeparam name="TData">To be added.</typeparam>
161-
<param name="type">To be added.</param>
162-
<param name="version">To be added.</param>
163-
<param name="stamp">To be added.</param>
164-
<param name="data">To be added.</param>
165-
<param name="dataSerializer">To be added.</param>
166-
<summary>To be added.</summary>
165+
<typeparam name="TData">The type of the data passed to <paramref name="dataSerializer" />.</typeparam>
166+
<param name="type">The entry type.</param>
167+
<param name="version">The entry version.</param>
168+
<param name="stamp">The entry stamp.</param>
169+
<param name="data">The data to pass to <paramref name="dataSerializer" />.</param>
170+
<param name="dataSerializer">A serializer for serializing data to a <see cref="T:System.Reflection.Metadata.BlobBuilder" />.</param>
171+
<summary>Adds an entry of the specified type and serializes its data.</summary>
167172
<remarks>To be added.</remarks>
168173
</Docs>
169174
</Member>
@@ -188,10 +193,12 @@
188193
<Parameter Name="checksum" Type="System.Collections.Immutable.ImmutableArray&lt;System.Byte&gt;" Index="1" FrameworkAlternate="netcore-2.1;netcore-2.2;netcore-3.0" />
189194
</Parameters>
190195
<Docs>
191-
<param name="algorithmName">To be added.</param>
192-
<param name="checksum">To be added.</param>
193-
<summary>To be added.</summary>
196+
<param name="algorithmName">The hash algorithm name (for example, "SHA256").</param>
197+
<param name="checksum">The checksum.</param>
198+
<summary>Adds PDB checksum entry.</summary>
194199
<remarks>To be added.</remarks>
200+
<exception cref="T:System.ArgumentNullException"><paramref name="algorithmName" /> or <paramref name="checksum" /> is <see langword="null" />.</exception>
201+
<exception cref="T:System.ArgumentException"><paramref name="algorithmName" /> or <paramref name="checksum" /> is empty.</exception>
195202
</Docs>
196203
</Member>
197204
<Member MemberName="AddReproducibleEntry">
@@ -214,7 +221,7 @@
214221
</ReturnValue>
215222
<Parameters />
216223
<Docs>
217-
<summary>To be added.</summary>
224+
<summary>Adds a reproducible entry.</summary>
218225
<remarks>To be added.</remarks>
219226
</Docs>
220227
</Member>

‎xml/System.Reflection.PortableExecutable/DebugDirectoryEntry.xml

Lines changed: 27 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@
2323
</Attribute>
2424
</Attributes>
2525
<Docs>
26-
<summary>To be added.</summary>
26+
<summary>Identifies the location, size and format of a block of debug information.</summary>
2727
<remarks>To be added.</remarks>
2828
</Docs>
2929
<Members>
@@ -60,7 +60,7 @@
6060
<param name="dataSize">To be added.</param>
6161
<param name="dataRelativeVirtualAddress">To be added.</param>
6262
<param name="dataPointer">To be added.</param>
63-
<summary>To be added.</summary>
63+
<summary>Initializes a new instance of the <see cref="T:System.Reflection.PortableExecutable.DebugDirectoryEntry" /> structure.</summary>
6464
<remarks>To be added.</remarks>
6565
</Docs>
6666
</Member>
@@ -84,8 +84,8 @@
8484
<ReturnType>System.Int32</ReturnType>
8585
</ReturnValue>
8686
<Docs>
87-
<summary>To be added.</summary>
88-
<value>To be added.</value>
87+
<summary>Gets the file pointer to the debug data.</summary>
88+
<value>The file pointer to the debug data.</value>
8989
<remarks>To be added.</remarks>
9090
</Docs>
9191
</Member>
@@ -109,8 +109,8 @@
109109
<ReturnType>System.Int32</ReturnType>
110110
</ReturnValue>
111111
<Docs>
112-
<summary>To be added.</summary>
113-
<value>To be added.</value>
112+
<summary>Gets the address of the debug data when loaded, relative to the image base.</summary>
113+
<value>The address of the debug data relative to the image base.</value>
114114
<remarks>To be added.</remarks>
115115
</Docs>
116116
</Member>
@@ -134,8 +134,8 @@
134134
<ReturnType>System.Int32</ReturnType>
135135
</ReturnValue>
136136
<Docs>
137-
<summary>To be added.</summary>
138-
<value>To be added.</value>
137+
<summary>Gets the size of the debug data (not including the debug directory itself).</summary>
138+
<value>the size of the debug data (excluding the debug directory).</value>
139139
<remarks>To be added.</remarks>
140140
</Docs>
141141
</Member>
@@ -158,8 +158,8 @@
158158
<ReturnType>System.Boolean</ReturnType>
159159
</ReturnValue>
160160
<Docs>
161-
<summary>To be added.</summary>
162-
<value>To be added.</value>
161+
<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>
162+
<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>
163163
<remarks>To be added.</remarks>
164164
</Docs>
165165
</Member>
@@ -183,8 +183,8 @@
183183
<ReturnType>System.UInt16</ReturnType>
184184
</ReturnValue>
185185
<Docs>
186-
<summary>To be added.</summary>
187-
<value>To be added.</value>
186+
<summary>Gets the major version number of the debug data format.</summary>
187+
<value>The major version number of the debug data format.</value>
188188
<remarks>To be added.</remarks>
189189
</Docs>
190190
</Member>
@@ -208,8 +208,8 @@
208208
<ReturnType>System.UInt16</ReturnType>
209209
</ReturnValue>
210210
<Docs>
211-
<summary>To be added.</summary>
212-
<value>To be added.</value>
211+
<summary>Gets the minor version number of the debug data format.</summary>
212+
<value>The minor version number of the debug data format.</value>
213213
<remarks>To be added.</remarks>
214214
</Docs>
215215
</Member>
@@ -233,9 +233,17 @@
233233
<ReturnType>System.UInt32</ReturnType>
234234
</ReturnValue>
235235
<Docs>
236-
<summary>To be added.</summary>
237-
<value>To be added.</value>
238-
<remarks>To be added.</remarks>
236+
<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>
237+
<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>
238+
<remarks>
239+
<format type="text/markdown"><![CDATA[
240+
241+
## Remarks
242+
243+
The algorithm used to calculate this value is an implementation detail of the tool that produced the file.
244+
245+
]]></format>
246+
</remarks>
239247
</Docs>
240248
</Member>
241249
<Member MemberName="Type">
@@ -258,8 +266,8 @@
258266
<ReturnType>System.Reflection.PortableExecutable.DebugDirectoryEntryType</ReturnType>
259267
</ReturnValue>
260268
<Docs>
261-
<summary>To be added.</summary>
262-
<value>To be added.</value>
269+
<summary>Gets the format of the debugging information.</summary>
270+
<value>The format of the debugging information.</value>
263271
<remarks>To be added.</remarks>
264272
</Docs>
265273
</Member>

‎xml/System.Reflection.PortableExecutable/DebugDirectoryEntryType.xml

Lines changed: 30 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,30 @@
1818
</Base>
1919
<Docs>
2020
<summary>To be added.</summary>
21-
<remarks>To be added.</remarks>
21+
<remarks>
22+
<format type="text/markdown"><![CDATA[
23+
24+
## Remarks
25+
26+
See the following for the specifications related to individual enumeration members:
27+
28+
|Member|Specification|
29+
|---|---|
30+
|`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)|
31+
|`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)|
32+
|`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)|
33+
|`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)|
34+
35+
### DebugDirectoryEntryType.Reproducible
36+
37+
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.).
38+
39+
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.
40+
41+
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.
42+
43+
]]></format>
44+
</remarks>
2245
</Docs>
2346
<Members>
2447
<Member MemberName="CodeView">
@@ -42,7 +65,7 @@
4265
</ReturnValue>
4366
<MemberValue>2</MemberValue>
4467
<Docs>
45-
<summary>To be added.</summary>
68+
<summary>Associated PDB file description.</summary>
4669
</Docs>
4770
</Member>
4871
<Member MemberName="Coff">
@@ -66,7 +89,7 @@
6689
</ReturnValue>
6790
<MemberValue>1</MemberValue>
6891
<Docs>
69-
<summary>To be added.</summary>
92+
<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>
7093
</Docs>
7194
</Member>
7295
<Member MemberName="EmbeddedPortablePdb">
@@ -89,7 +112,7 @@
89112
</ReturnValue>
90113
<MemberValue>17</MemberValue>
91114
<Docs>
92-
<summary>To be added.</summary>
115+
<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>
93116
</Docs>
94117
</Member>
95118
<Member MemberName="PdbChecksum">
@@ -110,7 +133,7 @@
110133
</ReturnValue>
111134
<MemberValue>19</MemberValue>
112135
<Docs>
113-
<summary>To be added.</summary>
136+
<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>
114137
</Docs>
115138
</Member>
116139
<Member MemberName="Reproducible">
@@ -134,7 +157,7 @@
134157
</ReturnValue>
135158
<MemberValue>16</MemberValue>
136159
<Docs>
137-
<summary>To be added.</summary>
160+
<summary>The presence of this entry indicates a deterministic PE/COFF file. See the Remarks section for more information.</summary>
138161
</Docs>
139162
</Member>
140163
<Member MemberName="Unknown">
@@ -158,7 +181,7 @@
158181
</ReturnValue>
159182
<MemberValue>0</MemberValue>
160183
<Docs>
161-
<summary>To be added.</summary>
184+
<summary>An unknown value that should be ignored by all tools.</summary>
162185
</Docs>
163186
</Member>
164187
</Members>

0 commit comments

Comments
 (0)