From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mail02.groups.io (mail02.groups.io [66.175.222.108]) by spool.mail.gandi.net (Postfix) with ESMTPS id C99F57803DA for ; Tue, 25 Jul 2023 01:35:40 +0000 (UTC) DKIM-Signature: a=rsa-sha256; bh=ZxcHHoMOsLrQZsaGPimKVuMjjhfCDltLEpDtfQskWhI=; c=relaxed/simple; d=groups.io; h=X-Received:X-Received:X-Received:X-Gm-Message-State:X-Google-Smtp-Source:X-Received:X-Received:From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References:MIME-Version:Precedence:List-Subscribe:List-Help:Sender:List-Id:Mailing-List:Delivered-To:Reply-To:List-Unsubscribe-Post:List-Unsubscribe:Content-Transfer-Encoding; s=20140610; t=1690248939; v=1; b=J26Ab70EwitIwgCtretrQceUHxbaL1oiR87o9ofNXUbhYAooHg5Kx/Dsq9bwoZtUlJpK37ct kZQrTQ2TVu516fLodSu6zWdbrEdt2gPk7yxRvje3inVQk+fKCnkwSKxOXqcODBMrPDyJN2yCXMZ byzw+keGHJZDvpQt+otWa5bA= X-Received: by 127.0.0.2 with SMTP id l9cJYY7687511xH8CmfvrlRX; Mon, 24 Jul 2023 18:35:39 -0700 X-Received: from mail-pl1-f176.google.com (mail-pl1-f176.google.com [209.85.214.176]) by mx.groups.io with SMTP id smtpd.web11.11430.1690248934966436817 for ; Mon, 24 Jul 2023 18:35:35 -0700 X-Received: by mail-pl1-f176.google.com with SMTP id d9443c01a7336-1b89d47ffb6so25186045ad.2 for ; Mon, 24 Jul 2023 18:35:34 -0700 (PDT) X-Gm-Message-State: HHEfZTRhRNCiIRix0q99HQaux7686176AA= X-Google-Smtp-Source: APBJJlGx/TdGBJF99Lb1eoXT9GVAmjy0QzpKqEvTShEdMBZTIJ7NXf5GEYcZngqYwLNnUcL4YtURog== X-Received: by 2002:a17:902:bd86:b0:1b8:3590:358a with SMTP id q6-20020a170902bd8600b001b83590358amr7606480pls.19.1690248934126; Mon, 24 Jul 2023 18:35:34 -0700 (PDT) X-Received: from localhost.localdomain ([50.46.230.135]) by smtp.gmail.com with ESMTPSA id f8-20020a170902ce8800b001b893b689a0sm9630868plg.84.2023.07.24.18.35.33 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 24 Jul 2023 18:35:33 -0700 (PDT) From: "Taylor Beebe" To: devel@edk2.groups.io Cc: Jian J Wang , Liming Gao , Dandan Bi Subject: [edk2-devel] [PATCH v3 13/14] MdeModulePkg: Update Function Headers in ImagePropertiesRecordLib Date: Mon, 24 Jul 2023 18:35:12 -0700 Message-ID: <20230725013513.1403-14-t@taylorbeebe.com> In-Reply-To: <20230725013513.1403-1-t@taylorbeebe.com> References: <20230725013513.1403-1-t@taylorbeebe.com> MIME-Version: 1.0 Precedence: Bulk List-Subscribe: List-Help: Sender: devel@edk2.groups.io List-Id: Mailing-List: list devel@edk2.groups.io; contact devel+owner@edk2.groups.io Reply-To: devel@edk2.groups.io,t@taylorbeebe.com List-Unsubscribe-Post: List-Unsubscribe=One-Click List-Unsubscribe: Content-Transfer-Encoding: 8bit X-GND-Status: LEGIT Authentication-Results: spool.mail.gandi.net; dkim=pass header.d=groups.io header.s=20140610 header.b=J26Ab70E; dmarc=none; spf=pass (spool.mail.gandi.net: domain of bounce@groups.io designates 66.175.222.108 as permitted sender) smtp.mailfrom=bounce@groups.io Update function headers to clarify the contract of each function and improve readability. Signed-off-by: Taylor Beebe Cc: Jian J Wang Cc: Liming Gao Cc: Dandan Bi --- 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 * + 3) * ) + + @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 * + 3) * ) + + @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/7686176 Group Owner: devel+owner@edk2.groups.io Unsubscribe: https://edk2.groups.io/g/devel/unsub [rebecca@openfw.io] -=-=-=-=-=-=-=-=-=-=-=-