Add API doc to PE relocation

xoofx · xoofx · commit 4847d506bb8e · 2024-10-02T09:15:12.000+02:00
diff --git a/src/LibObjectFile/PE/PEFile.Relocate.cs b/src/LibObjectFile/PE/PEFile.Relocate.cs
@@ -7,11 +7,12 @@
 
 namespace LibObjectFile.PE;
 
-/// <summary>
-/// A Portable Executable file that can be read, modified and written.
-/// </summary>
 partial class PEFile
 {
+    /// <summary>
+    /// Relocates the PE file to a new image base.
+    /// </summary>
+    /// <param name="newImageBase">The new image base.</param>
     public void Relocate(ulong newImageBase)
     {
         var diagnostics = new DiagnosticBag();
@@ -22,6 +23,11 @@ public void Relocate(ulong newImageBase)
         }
     }
 
+    /// <summary>
+    /// Relocates the PE file to a new image base.
+    /// </summary>
+    /// <param name="newImageBase">The new image base.</param>
+    /// <param name="diagnostics">The diagnostic bag to collect errors and warnings.</param>
     public void Relocate(ulong newImageBase, DiagnosticBag diagnostics)
     {
         if (IsPE32 && newImageBase > uint.MaxValue)
@@ -36,7 +42,7 @@ public void Relocate(ulong newImageBase, DiagnosticBag diagnostics)
             // Nothing to do
             return;
         }
-        
+
         // If we don't have a base relocation directory, we can just update the ImageBase
         var baseRelocationDirectory = Directories.BaseRelocation;
         if (baseRelocationDirectory is null)
@@ -59,12 +65,13 @@ public void Relocate(ulong newImageBase, DiagnosticBag diagnostics)
             var section = baseRelocationBlock.PageLink.Container;
             if (section is null)
             {
-                diagnostics.Error(DiagnosticId.PE_ERR_VerifyContextInvalidObject, $"The {nameof(PEBaseRelocationBlock.PageLink)} in the base relocation block {baseRelocationBlock} at index #{i} in the {nameof(PEBaseRelocationDirectory)} is null and missing a link to an actual section");
+                diagnostics.Error(DiagnosticId.PE_ERR_VerifyContextInvalidObject,
+                    $"The {nameof(PEBaseRelocationBlock.PageLink)} in the base relocation block {baseRelocationBlock} at index #{i} in the {nameof(PEBaseRelocationDirectory)} is null and missing a link to an actual section");
                 return;
             }
 
             var pageBaseRva = baseRelocationBlock.PageLink.RVA();
-            
+
             var relocations = CollectionsMarshal.AsSpan(baseRelocationBlock.Relocations);
             try
             {
@@ -77,11 +84,13 @@ public void Relocate(ulong newImageBase, DiagnosticBag diagnostics)
                     {
                         if (sectionData is null)
                         {
-                            diagnostics.Error(DiagnosticId.PE_ERR_BaseRelocationInvalid, $"Unable to find the section data for the rva {rva} in the base relocation block {baseRelocationBlock} at index #{i} in the {nameof(PEBaseRelocationDirectory)}");
+                            diagnostics.Error(DiagnosticId.PE_ERR_BaseRelocationInvalid,
+                                $"Unable to find the section data for the rva {rva} in the base relocation block {baseRelocationBlock} at index #{i} in the {nameof(PEBaseRelocationDirectory)}");
                             return;
                         }
 
-                        diagnostics.Warning(DiagnosticId.PE_WRN_BaseRelocationInVirtualMemory, $"Invalid RVA {rva} found in virtual memory from base relocation block {baseRelocationBlock} at index #{i} in the {nameof(PEBaseRelocationDirectory)}");
+                        diagnostics.Warning(DiagnosticId.PE_WRN_BaseRelocationInVirtualMemory,
+                            $"Invalid RVA {rva} found in virtual memory from base relocation block {baseRelocationBlock} at index #{i} in the {nameof(PEBaseRelocationDirectory)}");
                         continue;
                     }
 
@@ -102,6 +111,7 @@ public void Relocate(ulong newImageBase, DiagnosticBag diagnostics)
                             {
                                 goto WarningOutOfBound;
                             }
+
                             break;
                         case PEBaseRelocationType.Low:
                             if (sectionData.CanReadWriteAt(offsetInSectionData, sizeof(ushort)))
@@ -112,6 +122,7 @@ public void Relocate(ulong newImageBase, DiagnosticBag diagnostics)
                             {
                                 goto WarningOutOfBound;
                             }
+
                             break;
                         case PEBaseRelocationType.HighLow:
                             if (sectionData.CanReadWriteAt(offsetInSectionData, sizeof(uint)))
@@ -122,6 +133,7 @@ public void Relocate(ulong newImageBase, DiagnosticBag diagnostics)
                             {
                                 goto WarningOutOfBound;
                             }
+
                             break;
                         case PEBaseRelocationType.HighAdj:
 
@@ -142,6 +154,7 @@ public void Relocate(ulong newImageBase, DiagnosticBag diagnostics)
                             {
                                 goto WarningOutOfBound;
                             }
+
                             break;
                         case PEBaseRelocationType.Dir64:
                             if (sectionData.CanReadWriteAt(offsetInSectionData, sizeof(ulong)))
@@ -152,6 +165,7 @@ public void Relocate(ulong newImageBase, DiagnosticBag diagnostics)
                             {
                                 goto WarningOutOfBound;
                             }
+
                             break;
                         default:
                             diagnostics.Error(DiagnosticId.PE_ERR_BaseRelocationInvalid, $"Unsupported relocation type {relocation.Type} #{j} in {nameof(PEBaseRelocationBlock)} {baseRelocationBlock}.");
@@ -160,7 +174,8 @@ public void Relocate(ulong newImageBase, DiagnosticBag diagnostics)
 
                     continue;
                     WarningOutOfBound:
-                    diagnostics.Warning(DiagnosticId.PE_WRN_BaseRelocationInVirtualMemory, $"Cannot process base relocation block {baseRelocationBlock} at index #{i} in the {nameof(PEBaseRelocationDirectory)}. The linked address is out of bound.");
+                    diagnostics.Warning(DiagnosticId.PE_WRN_BaseRelocationInVirtualMemory,
+                        $"Cannot process base relocation block {baseRelocationBlock} at index #{i} in the {nameof(PEBaseRelocationDirectory)}. The linked address is out of bound.");
                     continue;
 
                 }
@@ -174,5 +189,4 @@ public void Relocate(ulong newImageBase, DiagnosticBag diagnostics)
 
         OptionalHeader.ImageBase = newImageBase;
     }
-    
 }

Original file line number	Diff line number	Diff line change
`@@ -7,11 +7,12 @@`
`7`	`7`
`8`	`8`	`namespace LibObjectFile.PE;`
`9`	`9`
`10`		`-/// <summary>`
`11`		`-/// A Portable Executable file that can be read, modified and written.`
`12`		`-/// </summary>`
`13`	`10`	`partial class PEFile`
`14`	`11`	`{`
	`12`	`+ /// <summary>`
	`13`	`+ /// Relocates the PE file to a new image base.`
	`14`	`+ /// </summary>`
	`15`	`+ /// <param name="newImageBase">The new image base.</param>`
`15`	`16`	`public void Relocate(ulong newImageBase)`
`16`	`17`	`{`
`17`	`18`	`var diagnostics = new DiagnosticBag();`
`@@ -22,6 +23,11 @@ public void Relocate(ulong newImageBase)`
`22`	`23`	`}`
`23`	`24`	`}`
`24`	`25`
	`26`	`+ /// <summary>`
	`27`	`+ /// Relocates the PE file to a new image base.`
	`28`	`+ /// </summary>`
	`29`	`+ /// <param name="newImageBase">The new image base.</param>`
	`30`	`+ /// <param name="diagnostics">The diagnostic bag to collect errors and warnings.</param>`
`25`	`31`	`public void Relocate(ulong newImageBase, DiagnosticBag diagnostics)`
`26`	`32`	`{`
`27`	`33`	`if (IsPE32 && newImageBase > uint.MaxValue)`
`@@ -36,7 +42,7 @@ public void Relocate(ulong newImageBase, DiagnosticBag diagnostics)`
`36`	`42`	`// Nothing to do`
`37`	`43`	`return;`
`38`	`44`	`}`
`39`		`-`
	`45`	`+`
`40`	`46`	`// If we don't have a base relocation directory, we can just update the ImageBase`
`41`	`47`	`var baseRelocationDirectory = Directories.BaseRelocation;`
`42`	`48`	`if (baseRelocationDirectory is null)`
`@@ -59,12 +65,13 @@ public void Relocate(ulong newImageBase, DiagnosticBag diagnostics)`
`59`	`65`	`var section = baseRelocationBlock.PageLink.Container;`
`60`	`66`	`if (section is null)`
`61`	`67`	`{`
`62`		`- diagnostics.Error(DiagnosticId.PE_ERR_VerifyContextInvalidObject, $"The {nameof(PEBaseRelocationBlock.PageLink)} in the base relocation block {baseRelocationBlock} at index #{i} in the {nameof(PEBaseRelocationDirectory)} is null and missing a link to an actual section");`
	`68`	`+ diagnostics.Error(DiagnosticId.PE_ERR_VerifyContextInvalidObject,`
	`69`	`+ $"The {nameof(PEBaseRelocationBlock.PageLink)} in the base relocation block {baseRelocationBlock} at index #{i} in the {nameof(PEBaseRelocationDirectory)} is null and missing a link to an actual section");`
`63`	`70`	`return;`
`64`	`71`	`}`
`65`	`72`
`66`	`73`	`var pageBaseRva = baseRelocationBlock.PageLink.RVA();`
`67`		`-`
	`74`	`+`
`68`	`75`	`var relocations = CollectionsMarshal.AsSpan(baseRelocationBlock.Relocations);`
`69`	`76`	`try`
`70`	`77`	`{`
`@@ -77,11 +84,13 @@ public void Relocate(ulong newImageBase, DiagnosticBag diagnostics)`
`77`	`84`	`{`
`78`	`85`	`if (sectionData is null)`
`79`	`86`	`{`
`80`		`- diagnostics.Error(DiagnosticId.PE_ERR_BaseRelocationInvalid, $"Unable to find the section data for the rva {rva} in the base relocation block {baseRelocationBlock} at index #{i} in the {nameof(PEBaseRelocationDirectory)}");`
	`87`	`+ diagnostics.Error(DiagnosticId.PE_ERR_BaseRelocationInvalid,`
	`88`	`+ $"Unable to find the section data for the rva {rva} in the base relocation block {baseRelocationBlock} at index #{i} in the {nameof(PEBaseRelocationDirectory)}");`
`81`	`89`	`return;`
`82`	`90`	`}`
`83`	`91`
`84`		`- diagnostics.Warning(DiagnosticId.PE_WRN_BaseRelocationInVirtualMemory, $"Invalid RVA {rva} found in virtual memory from base relocation block {baseRelocationBlock} at index #{i} in the {nameof(PEBaseRelocationDirectory)}");`
	`92`	`+ diagnostics.Warning(DiagnosticId.PE_WRN_BaseRelocationInVirtualMemory,`
	`93`	`+ $"Invalid RVA {rva} found in virtual memory from base relocation block {baseRelocationBlock} at index #{i} in the {nameof(PEBaseRelocationDirectory)}");`
`85`	`94`	`continue;`
`86`	`95`	`}`
`87`	`96`
`@@ -102,6 +111,7 @@ public void Relocate(ulong newImageBase, DiagnosticBag diagnostics)`
`102`	`111`	`{`
`103`	`112`	`goto WarningOutOfBound;`
`104`	`113`	`}`
	`114`	`+`
`105`	`115`	`break;`
`106`	`116`	`case PEBaseRelocationType.Low:`
`107`	`117`	`if (sectionData.CanReadWriteAt(offsetInSectionData, sizeof(ushort)))`
`@@ -112,6 +122,7 @@ public void Relocate(ulong newImageBase, DiagnosticBag diagnostics)`
`112`	`122`	`{`
`113`	`123`	`goto WarningOutOfBound;`
`114`	`124`	`}`
	`125`	`+`
`115`	`126`	`break;`
`116`	`127`	`case PEBaseRelocationType.HighLow:`
`117`	`128`	`if (sectionData.CanReadWriteAt(offsetInSectionData, sizeof(uint)))`
`@@ -122,6 +133,7 @@ public void Relocate(ulong newImageBase, DiagnosticBag diagnostics)`
`122`	`133`	`{`
`123`	`134`	`goto WarningOutOfBound;`
`124`	`135`	`}`
	`136`	`+`
`125`	`137`	`break;`
`126`	`138`	`case PEBaseRelocationType.HighAdj:`
`127`	`139`
`@@ -142,6 +154,7 @@ public void Relocate(ulong newImageBase, DiagnosticBag diagnostics)`
`142`	`154`	`{`
`143`	`155`	`goto WarningOutOfBound;`
`144`	`156`	`}`
	`157`	`+`
`145`	`158`	`break;`
`146`	`159`	`case PEBaseRelocationType.Dir64:`
`147`	`160`	`if (sectionData.CanReadWriteAt(offsetInSectionData, sizeof(ulong)))`
`@@ -152,6 +165,7 @@ public void Relocate(ulong newImageBase, DiagnosticBag diagnostics)`
`152`	`165`	`{`
`153`	`166`	`goto WarningOutOfBound;`
`154`	`167`	`}`
	`168`	`+`
`155`	`169`	`break;`
`156`	`170`	`default:`
`157`	`171`	`diagnostics.Error(DiagnosticId.PE_ERR_BaseRelocationInvalid, $"Unsupported relocation type {relocation.Type} #{j} in {nameof(PEBaseRelocationBlock)} {baseRelocationBlock}.");`
`@@ -160,7 +174,8 @@ public void Relocate(ulong newImageBase, DiagnosticBag diagnostics)`
`160`	`174`
`161`	`175`	`continue;`
`162`	`176`	`WarningOutOfBound:`
`163`		`- diagnostics.Warning(DiagnosticId.PE_WRN_BaseRelocationInVirtualMemory, $"Cannot process base relocation block {baseRelocationBlock} at index #{i} in the {nameof(PEBaseRelocationDirectory)}. The linked address is out of bound.");`
	`177`	`+ diagnostics.Warning(DiagnosticId.PE_WRN_BaseRelocationInVirtualMemory,`
	`178`	`+ $"Cannot process base relocation block {baseRelocationBlock} at index #{i} in the {nameof(PEBaseRelocationDirectory)}. The linked address is out of bound.");`
`164`	`179`	`continue;`
`165`	`180`
`166`	`181`	`}`
`@@ -174,5 +189,4 @@ public void Relocate(ulong newImageBase, DiagnosticBag diagnostics)`
`174`	`189`
`175`	`190`	`OptionalHeader.ImageBase = newImageBase;`
`176`	`191`	`}`
`177`		`-`
`178`	`192`	`}`