Update function headers to clarify the contract of each function and
improve readability.
Signed-off-by: Taylor Beebe <t...@taylorbeebe.com>
Cc: Jian J Wang <jian.j.w...@intel.com>
Cc: Liming Gao <gaolim...@byosoft.com.cn>
Cc: Dandan Bi <dandan...@intel.com>
---
MdeModulePkg/Library/ImagePropertiesRecordLib/ImagePropertiesRecordLib.c | 220
++++++++++----------
MdeModulePkg/Include/Library/ImagePropertiesRecordLib.h | 114
+++++-----
2 files changed, 162 insertions(+), 172 deletions(-)
diff --git
a/MdeModulePkg/Library/ImagePropertiesRecordLib/ImagePropertiesRecordLib.c
b/MdeModulePkg/Library/ImagePropertiesRecordLib/ImagePropertiesRecordLib.c
index 9ac3afdaa202..0c96e4220964 100644
--- a/MdeModulePkg/Library/ImagePropertiesRecordLib/ImagePropertiesRecordLib.c
+++ b/MdeModulePkg/Library/ImagePropertiesRecordLib/ImagePropertiesRecordLib.c
@@ -23,14 +23,13 @@
((EFI_MEMORY_DESCRIPTOR *)((UINT8 *)(MemoryDescriptor) + (Size)))
/**
- Converts a number of EFI_PAGEs to a size in bytes.
+ Converts a number of pages to a size in bytes.
NOTE: Do not use EFI_PAGES_TO_SIZE because it handles UINTN only.
- @param Pages The number of EFI_PAGES.
+ @param[in] Pages The number of EFI_PAGES.
- @return The number of bytes associated with the number of EFI_PAGEs
specified
- by Pages.
+ @retval The number of bytes associated with the input number of pages.
**/
STATIC
UINT64
@@ -46,10 +45,9 @@ EfiPagesToSize (
NOTE: Do not use EFI_SIZE_TO_PAGES because it handles UINTN only.
- @param Size A size in bytes.
+ @param[in] Size A size in bytes.
- @return The number of EFI_PAGESs associated with the number of bytes
specified
- by Size.
+ @retval The number of pages associated with the input number of bytes.
**/
STATIC
@@ -62,12 +60,12 @@ EfiSizeToPages (
}
/**
- Sort memory map entries based upon PhysicalStart, from low to high.
+ Sort memory map entries based upon PhysicalStart from low to high.
- @param MemoryMap A pointer to the buffer in which firmware
places
- the current memory map.
- @param MemoryMapSize Size, in bytes, of the MemoryMap buffer.
- @param DescriptorSize Size, in bytes, of an individual
EFI_MEMORY_DESCRIPTOR.
+ @param[in, out] MemoryMap A pointer to the buffer in which firmware
places
+ the current memory map.
+ @param[in] MemoryMapSize Size, in bytes, of the MemoryMap buffer.
+ @param[in] DescriptorSize Size, in bytes, of an individual
EFI_MEMORY_DESCRIPTOR.
**/
STATIC
VOID
@@ -106,11 +104,12 @@ SortMemoryMap (
/**
Return the first image record, whose [ImageBase, ImageSize] covered by
[Buffer, Length].
- @param Buffer Start Address
- @param Length Address length
- @param ImageRecordList Image record list
+ @param[in] Buffer Starting Address
+ @param[in] Length Length to check
+ @param[in] ImageRecordList A list of IMAGE_PROPERTIES_RECORD entries to
check against
+ the memory range Buffer -> Buffer + Length
- @return first image record covered by [buffer, length]
+ @retval The first image record covered by [Buffer, Length]
**/
STATIC
IMAGE_PROPERTIES_RECORD *
@@ -145,17 +144,19 @@ GetImageRecordByAddress (
}
/**
- Set the memory map to new entries, according to one old entry,
- based upon PE code section and data section in image record
+ Break up the input OldRecord into multiple new records based on the code
+ and data sections in the input ImageRecord.
- @param ImageRecord An image record whose [ImageBase, ImageSize]
covered
- by old memory map entry.
- @param NewRecord A pointer to several new memory map entries.
- The caller gurantee the buffer size be 1 +
- (SplitRecordCount * DescriptorSize) calculated
- below.
- @param OldRecord A pointer to one old memory map entry.
- @param DescriptorSize Size, in bytes, of an individual
EFI_MEMORY_DESCRIPTOR.
+ @param[in] ImageRecord An IMAGE_PROPERTIES_RECORD whose
ImageBase and
+ ImageSize is covered by by OldRecord.
+ @param[in, out] NewRecord A pointer to several new memory map
entries.
+ The caller gurantee the buffer size be 1
+
+ (SplitRecordCount * DescriptorSize)
calculated
+ below.
+ @param[in] OldRecord A pointer to one old memory map entry.
+ @param[in] DescriptorSize The size, in bytes, of an individual
EFI_MEMORY_DESCRIPTOR.
+
+ @retval The number of new descriptors created.
**/
STATIC
UINTN
@@ -245,16 +246,16 @@ SetNewRecord (
}
/**
- Return the max number of new splitted entries, according to one old entry,
- based upon PE code section and data section.
+ Return the maximum number of new entries required to describe the code and
data sections
+ of all images covered by the input OldRecord.
- @param OldRecord A pointer to one old memory map entry.
- @param ImageRecordList A list of IMAGE_PROPERTIES_RECORD entries
used when searching
- for an image record contained by the memory
range described in
- the existing EFI memory map descriptor
OldRecord
+ @param[in] OldRecord A pointer to one old memory map entry.
+ @param[in] ImageRecordList A list of IMAGE_PROPERTIES_RECORD entries used
when searching
+ for an image record contained by the memory
range described by
+ OldRecord
- @retval 0 no entry need to be splitted.
- @return the max number of new splitted entries
+ @retval The maximum number of new descriptors required to describe the code
and data sections
+ of all images covered by OldRecord.
**/
STATIC
UINTN
@@ -290,22 +291,20 @@ GetMaxSplitRecordCount (
}
/**
- Split the memory map to new entries, according to one old entry,
- based upon PE code section and data section.
+ Split the memory map into new entries based upon the PE code and data
sections
+ in ImageRecordList covered by the input OldRecord.
- @param OldRecord A pointer to one old memory map entry.
- @param NewRecord A pointer to several new memory map
entries.
- The caller gurantee the buffer size be 1
+
- (SplitRecordCount * DescriptorSize)
calculated
- below.
- @param MaxSplitRecordCount The max number of splitted entries
- @param DescriptorSize Size, in bytes, of an individual
EFI_MEMORY_DESCRIPTOR.
- @param ImageRecordList A list of IMAGE_PROPERTIES_RECORD
entries used when searching
- for an image record contained by the
memory range described in
- the existing EFI memory map descriptor
OldRecord
+ @param[in] OldRecord A pointer to one old memory map
entry.
+ @param[in, out] NewRecord A pointer to several new memory map
entries.
+ The caller gurantee the buffer size
be
+ (SplitRecordCount * DescriptorSize).
+ @param[in] MaxSplitRecordCount The maximum number of entries
post-split.
+ @param[in] DescriptorSize The size, in bytes, of an individual
EFI_MEMORY_DESCRIPTOR.
+ @param[in] ImageRecordList A list of IMAGE_PROPERTIES_RECORD
entries used when searching
+ for an image record contained by the
memory range described in
+ the existing EFI memory map
descriptor OldRecord
- @retval 0 no entry is splitted.
- @return the real number of splitted record.
+ @retval The number of split entries.
**/
STATIC
UINTN
@@ -403,54 +402,42 @@ SplitRecord (
}
/**
- Split the original memory map, and add more entries to describe PE code
section and data section.
- This function will set EfiRuntimeServicesData to be EFI_MEMORY_XP.
- This function will merge entries with same attributes finally.
+ Split the original memory map and add more entries to describe PE code
+ and data sections for each image in the input ImageRecordList.
- NOTE: It assumes PE code/data section are page aligned.
- NOTE: It assumes enough entry is prepared for new memory map.
+ NOTE: This function assumes PE code/data section are page aligned.
+ NOTE: This function assumes there are enough entries for the new memory map.
- Split table:
- +---------------+
- | Record X |
- +---------------+
- | Record RtCode |
- +---------------+
- | Record Y |
- +---------------+
- ==>
- +---------------+
- | Record X |
- +---------------+ ----
- | Record RtData | |
- +---------------+ |
- | Record RtCode | |-> PE/COFF1
- +---------------+ |
- | Record RtData | |
- +---------------+ ----
- | Record RtData | |
- +---------------+ |
- | Record RtCode | |-> PE/COFF2
- +---------------+ |
- | Record RtData | |
- +---------------+ ----
- | Record Y |
- +---------------+
+ | | | | | | | |
+ | 4K PAGE | DATA | CODE | DATA | CODE | DATA | 4K PAGE |
+ | | | | | | | |
+ Assume the above memory region is the result of one split memory map
descriptor. It's unlikely
+ that a linker will orient an image this way, but the caller must assume the
worst case scenario.
+ This image layout example contains code sections oriented in a way that
maximizes the number of
+ descriptors which would be required to describe each section. To ensure we
have enough space
+ for every descriptor of the broken up memory map, the caller must assume
that every image will
+ have the maximum number of code sections oriented in a way which maximizes
the number of data
+ sections with unrelated memory regions flanking each image within a single
descriptor.
- @param MemoryMapSize A pointer to the size, in bytes, of
the
- MemoryMap buffer. On input, this is
the size of
- old MemoryMap before split. The
actual buffer
- size of MemoryMap is MemoryMapSize +
- (AdditionalRecordCount *
DescriptorSize) calculated
- below. On output, it is the size of
new MemoryMap
- after split.
- @param MemoryMap A pointer to the buffer in which
firmware places
- the current memory map.
- @param DescriptorSize Size, in bytes, of an individual
EFI_MEMORY_DESCRIPTOR.
- @param ImageRecordList A list of IMAGE_PROPERTIES_RECORD
entries used when searching
- for an image record contained by the
memory range described in
- EFI memory map descriptors.
- @param NumberOfAdditionalDescriptors The number of unused descriptors at
the end of the input MemoryMap.
+ Given an image record list, the caller should use the following formula when
allocating extra descriptors:
+ NumberOfAdditionalDescriptors = (MemoryMapSize / DescriptorSize) +
+ ((2 * <Most Code Segments in a Single
Image> + 3) * <Number of Images>)
+
+ @param[in, out] MemoryMapSize IN: The size, in bytes, of
the old memory map before the split.
+ OUT: The size, in bytes, of
the used descriptors of the split
+ memory map
+ @param[in, out] MemoryMap IN: A pointer to the
buffer containing the current memory map.
+ This buffer must have
enough space to accomodate the "worst case"
+ scenario where every
image in ImageRecordList needs a new descriptor
+ to describe its code
and data sections.
+ OUT: A pointer to the
updated memory map with separated image section
+ descriptors.
+ @param[in] DescriptorSize The size, in bytes, of an
individual EFI_MEMORY_DESCRIPTOR.
+ @param[in] ImageRecordList A list of
IMAGE_PROPERTIES_RECORD entries used when searching
+ for an image record
contained by the memory range described in
+ EFI memory map descriptors.
+ @param[in] NumberOfAdditionalDescriptors The number of unused
descriptors at the end of the input MemoryMap.
+ The formula in the
description should be used to calculate this value.
**/
VOID
EFIAPI
@@ -523,10 +510,10 @@ SplitTable (
}
/**
- Swap two code sections in image record.
+ Swap two code sections in a single IMAGE_PROPERTIES_RECORD.
- @param FirstImageRecordCodeSection first code section in image record
- @param SecondImageRecordCodeSection second code section in image record
+ @param[in] FirstImageRecordCodeSection The first code section
+ @param[in] SecondImageRecordCodeSection The second code section
**/
STATIC
VOID
@@ -548,9 +535,9 @@ SwapImageRecordCodeSection (
}
/**
- Sort code section in image record, based upon CodeSegmentBase from low to
high.
+ Sort the code sections in the input ImageRecord based upon CodeSegmentBase
from low to high.
- @param ImageRecord image record to be sorted
+ @param[in] ImageRecord IMAGE_PROPERTIES_RECORD to be sorted
**/
VOID
EFIAPI
@@ -597,12 +584,15 @@ SortImageRecordCodeSection (
}
/**
- Check if code section in image record is valid.
+ Check if the code sections in the input ImageRecord are valid.
+ The code sections are valid if they don't overlap, are contained
+ within the the ImageRecord's ImageBase and ImageSize, and are
+ contained within the MAX_ADDRESS.
- @param ImageRecord image record to be checked
+ @param[in] ImageRecord IMAGE_PROPERTIES_RECORD to be checked
- @retval TRUE image record is valid
- @retval FALSE image record is invalid
+ @retval TRUE The code sections in the input ImageRecord are valid
+ @retval FALSE The code sections in the input ImageRecord are invalid
**/
BOOLEAN
EFIAPI
@@ -662,8 +652,8 @@ IsImageRecordCodeSectionValid (
/**
Swap two image records.
- @param FirstImageRecord first image record.
- @param SecondImageRecord second image record.
+ @param[in] FirstImageRecord The first image record.
+ @param[in] SecondImageRecord The second image record.
**/
STATIC
VOID
@@ -690,9 +680,9 @@ SwapImageRecord (
}
/**
- Sort image record based upon the ImageBase from low to high.
+ Sort the input ImageRecordList based upon the ImageBase from low to high.
- @param ImageRecordList Image record list to be sorted
+ @param[in] ImageRecordList Image record list to be sorted
**/
VOID
EFIAPI
@@ -739,7 +729,10 @@ SortImageRecord (
/**
Dump image record.
- @param[in] ImageRecordList A list of IMAGE_PROPERTIES_RECORD entries
+/**
+ Debug dumps the input list of IMAGE_PROPERTIES_RECORD structs
+
+ @param[in] ImageRecordList Head of the IMAGE_PROPERTIES_RECORD list
**/
VOID
EFIAPI
@@ -766,13 +759,16 @@ DumpImageRecord (
}
/**
- Find image record according to image base and size.
+ Find image properties record according to image base and size in the
+ input ImageRecordList.
- @param ImageBase Base of PE image
- @param ImageSize Size of PE image
- @param ImageRecordList Image record list to be searched
+ @param[in] ImageBase Base of PE image
+ @param[in] ImageSize Size of PE image
+ @param[in] ImageRecordList Image record list to be searched
- @return image record
+ @retval NULL No IMAGE_PROPERTIES_RECORD matches ImageBase
+ and ImageSize in the input ImageRecordList
+ @retval Other The found IMAGE_PROPERTIES_RECORD
**/
IMAGE_PROPERTIES_RECORD *
EFIAPI
diff --git a/MdeModulePkg/Include/Library/ImagePropertiesRecordLib.h
b/MdeModulePkg/Include/Library/ImagePropertiesRecordLib.h
index 99e030c988f3..107255d9e16d 100644
--- a/MdeModulePkg/Include/Library/ImagePropertiesRecordLib.h
+++ b/MdeModulePkg/Include/Library/ImagePropertiesRecordLib.h
@@ -32,54 +32,42 @@ typedef struct {
} IMAGE_PROPERTIES_RECORD;
/**
- Split the original memory map, and add more entries to describe PE code
section and data section.
- This function will set EfiRuntimeServicesData to be EFI_MEMORY_XP.
- This function will merge entries with same attributes finally.
+ Split the original memory map and add more entries to describe PE code
+ and data sections for each image in the input ImageRecordList.
- NOTE: It assumes PE code/data section are page aligned.
- NOTE: It assumes enough entry is prepared for new memory map.
+ NOTE: This function assumes PE code/data section are page aligned.
+ NOTE: This function assumes there are enough entries for the new memory map.
- Split table:
- +---------------+
- | Record X |
- +---------------+
- | Record RtCode |
- +---------------+
- | Record Y |
- +---------------+
- ==>
- +---------------+
- | Record X |
- +---------------+ ----
- | Record RtData | |
- +---------------+ |
- | Record RtCode | |-> PE/COFF1
- +---------------+ |
- | Record RtData | |
- +---------------+ ----
- | Record RtData | |
- +---------------+ |
- | Record RtCode | |-> PE/COFF2
- +---------------+ |
- | Record RtData | |
- +---------------+ ----
- | Record Y |
- +---------------+
+ | | | | | | | |
+ | 4K PAGE | DATA | CODE | DATA | CODE | DATA | 4K PAGE |
+ | | | | | | | |
+ Assume the above memory region is the result of one split memory map
descriptor. It's unlikely
+ that a linker will orient an image this way, but the caller must assume the
worst case scenario.
+ This image layout example contains code sections oriented in a way that
maximizes the number of
+ descriptors which would be required to describe each section. To ensure we
have enough space
+ for every descriptor of the broken up memory map, the caller must assume
that every image will
+ have the maximum number of code sections oriented in a way which maximizes
the number of data
+ sections with unrelated memory regions flanking each image within a single
descriptor.
- @param MemoryMapSize A pointer to the size, in bytes, of
the
- MemoryMap buffer. On input, this is
the size of
- old MemoryMap before split. The
actual buffer
- size of MemoryMap is MemoryMapSize +
- (AdditionalRecordCount *
DescriptorSize) calculated
- below. On output, it is the size of
new MemoryMap
- after split.
- @param MemoryMap A pointer to the buffer in which
firmware places
- the current memory map.
- @param DescriptorSize Size, in bytes, of an individual
EFI_MEMORY_DESCRIPTOR.
- @param ImageRecordList A list of IMAGE_PROPERTIES_RECORD
entries used when searching
- for an image record contained by the
memory range described in
- EFI memory map descriptors.
- @param NumberOfAdditionalDescriptors The number of unused descriptors at
the end of the input MemoryMap.
+ Given an image record list, the caller should use the following formula when
allocating extra descriptors:
+ NumberOfAdditionalDescriptors = (MemoryMapSize / DescriptorSize) +
+ ((2 * <Most Code Segments in a Single
Image> + 3) * <Number of Images>)
+
+ @param[in, out] MemoryMapSize IN: The size, in bytes, of
the old memory map before the split.
+ OUT: The size, in bytes, of
the used descriptors of the split
+ memory map
+ @param[in, out] MemoryMap IN: A pointer to the
buffer containing the current memory map.
+ This buffer must have
enough space to accomodate the "worst case"
+ scenario where every
image in ImageRecordList needs a new descriptor
+ to describe its code
and data sections.
+ OUT: A pointer to the
updated memory map with separated image section
+ descriptors.
+ @param[in] DescriptorSize The size, in bytes, of an
individual EFI_MEMORY_DESCRIPTOR.
+ @param[in] ImageRecordList A list of
IMAGE_PROPERTIES_RECORD entries used when searching
+ for an image record
contained by the memory range described in
+ EFI memory map descriptors.
+ @param[in] NumberOfAdditionalDescriptors The number of unused
descriptors at the end of the input MemoryMap.
+ The formula in the
description should be used to calculate this value.
**/
VOID
EFIAPI
@@ -92,9 +80,9 @@ SplitTable (
);
/**
- Sort code section in image record, based upon CodeSegmentBase from low to
high.
+ Sort the code sections in the input ImageRecord based upon CodeSegmentBase
from low to high.
- @param ImageRecord image record to be sorted
+ @param[in] ImageRecord IMAGE_PROPERTIES_RECORD to be sorted
**/
VOID
EFIAPI
@@ -103,12 +91,15 @@ SortImageRecordCodeSection (
);
/**
- Check if code section in image record is valid.
+ Check if the code sections in the input ImageRecord are valid.
+ The code sections are valid if they don't overlap, are contained
+ within the the ImageRecord's ImageBase and ImageSize, and are
+ contained within the MAX_ADDRESS.
- @param ImageRecord image record to be checked
+ @param[in] ImageRecord IMAGE_PROPERTIES_RECORD to be checked
- @retval TRUE image record is valid
- @retval FALSE image record is invalid
+ @retval TRUE The code sections in the input ImageRecord are valid
+ @retval FALSE The code sections in the input ImageRecord are invalid
**/
BOOLEAN
EFIAPI
@@ -117,9 +108,9 @@ IsImageRecordCodeSectionValid (
);
/**
- Sort image record based upon the ImageBase from low to high.
+ Sort the input ImageRecordList based upon the ImageBase from low to high.
- @param ImageRecordList Image record list to be sorted
+ @param[in] ImageRecordList A list of IMAGE_PROPERTIES_RECORD entries
**/
VOID
EFIAPI
@@ -128,13 +119,16 @@ SortImageRecord (
);
/**
- Find image record according to image base and size.
+ Find image properties record according to image base and size in the
+ input ImageRecordList.
- @param ImageBase Base of PE image
- @param ImageSize Size of PE image
- @param ImageRecordList Image record list to be searched
+ @param[in] ImageBase Base of PE image
+ @param[in] ImageSize Size of PE image
+ @param[in] ImageRecordList Image record list to be searched
- @return image record
+ @retval NULL No IMAGE_PROPERTIES_RECORD matches ImageBase
+ and ImageSize in the input ImageRecordList
+ @retval Other The found IMAGE_PROPERTIES_RECORD
**/
IMAGE_PROPERTIES_RECORD *
EFIAPI
@@ -145,9 +139,9 @@ FindImageRecord (
);
/**
- Dump image record.
+ DEBUG dump the input ImageRecordList.
- @param[in] ImageRecordList A list of IMAGE_PROPERTIES_RECORD entries
+ @param[in] ImageRecordList Head of the IMAGE_PROPERTIES_RECORD list
**/
VOID
EFIAPI
--
2.41.0.windows.2
-=-=-=-=-=-=-=-=-=-=-=-
Groups.io Links: You receive all messages sent to this group.
View/Reply Online (#107210): https://edk2.groups.io/g/devel/message/107210
Mute This Topic: https://groups.io/mt/100342609/21656
Group Owner: devel+ow...@edk2.groups.io
Unsubscribe: https://edk2.groups.io/g/devel/unsub [arch...@mail-archive.com]
-=-=-=-=-=-=-=-=-=-=-=-
