From 1b88ce8644ee13fadd46746a85f9f6cdfb50831e Mon Sep 17 00:00:00 2001 From: eric_tian Date: Tue, 7 Oct 2008 08:41:19 +0000 Subject: [PATCH] sync the comments of FvbServiceLib library class with Mde Library Spec. git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@6079 6f19259b-4bc3-4df7-8a09-765794883524 --- MdeModulePkg/Library/EdkFvbServiceLib/Fvb.c | 284 +++++++++++++------- MdePkg/Include/Library/FvbServiceLib.h | 257 ++++++++++++------ 2 files changed, 375 insertions(+), 166 deletions(-) diff --git a/MdeModulePkg/Library/EdkFvbServiceLib/Fvb.c b/MdeModulePkg/Library/EdkFvbServiceLib/Fvb.c index 733e77b019..d1aa6041dd 100644 --- a/MdeModulePkg/Library/EdkFvbServiceLib/Fvb.c +++ b/MdeModulePkg/Library/EdkFvbServiceLib/Fvb.c @@ -335,20 +335,40 @@ FvbLibInitialize ( // /** - Reads specified number of bytes into a buffer from the specified block - - @param Instance The FV instance to be read from. - @param Lba The logical block address to be read from - @param Offset Offset into the block at which to begin reading - @param NumBytes Pointer that on input contains the total size of - the buffer. On output, it contains the total number - of bytes read - @param Buffer Pointer to a caller allocated buffer that will be - used to hold the data read - - @retval EFI_INVALID_PARAMETER Invalid parameter - @retval EFI_SUCESS Sucess to Read block - @retval Others Fail to read block + Reads specified number of bytes into a buffer from the specified block. + + The EfiFvbReadBlock() function reads the requested number of bytes from + the requested block in the specified firmware volume and stores them in + the provided buffer. Implementations should be mindful that the firmware + volume might be in the ReadDisabled state. If it is in this state, the + EfiFvbReadBlock() function must return the status code EFI_ACCESS_DENIED + without modifying the contents of the buffer. + + The EfiFvbReadBlock() function must also prevent spanning block boundaries. + If a read is requested that would span a block boundary, the read must read + up to the boundary but not beyond. The output parameter NumBytes must be + set to correctly indicate the number of bytes actually read. + The caller must be aware that a read may be partially completed. + + If NumBytes is NULL, then ASSERT(). + + If Buffer is NULL, then ASSERT(). + + @param[in] Instance The FV instance to be read from. + @param[in] Lba The logical block address to be read from + @param[in] Offset The offset relative to the block, at which to begin reading. + @param[in, out] NumBytes Pointer to a UINTN. On input, *NumBytes contains the total + size of the buffer. On output, it contains the actual number + of bytes read. + @param[out] Buffer Pointer to a caller allocated buffer that will be + used to hold the data read. + + @retval EFI_SUCCESS The firmware volume was read successfully and contents are in Buffer. + @retval EFI_BAD_BUFFER_SIZE Read attempted across an LBA boundary. On output, NumBytes contains the total number of bytes returned in Buffer. + @retval EFI_ACCESS_DENIED The firmware volume is in the ReadDisabled state. + @retval EFI_DEVICE_ERROR The block device is not functioning correctly and could not be read. + @retval EFI_INVALID_PARAMETER Invalid parameter, Instance is larger than the max FVB number. Lba index is larger than the last block of the firmware volume. Offset is larger than the block size. + **/ EFI_STATUS EfiFvbReadBlock ( @@ -374,20 +394,54 @@ EfiFvbReadBlock ( } /** - Writes specified number of bytes from the input buffer to the block - - @param Instance The FV instance to be written to - @param Lba The starting logical block index to write to - @param Offset Offset into the block at which to begin writing - @param NumBytes Pointer that on input contains the total size of - the buffer. On output, it contains the total number - of bytes actually written - @param Buffer Pointer to a caller allocated buffer that contains - the source for the write - - @retval EFI_INVALID_PARAMETER Invalid parameter - @retval EFI_SUCESS Sucess to write block - @retval Others Fail to write block + Writes specified number of bytes from the input buffer to the block + + The EfiFvbWriteBlock() function writes the specified number of bytes + from the provided buffer to the specified block and offset in the + requested firmware volume. + + If the firmware volume is sticky write, the caller must ensure that + all the bits of the specified range to write are in the EFI_FVB_ERASE_POLARITY + state before calling the EfiFvbWriteBlock() function, or else the + result will be unpredictable. This unpredictability arises because, + for a sticky-write firmware volume, a write may negate a bit in the + EFI_FVB_ERASE_POLARITY state but it cannot flip it back again. In + general, before calling the EfiFvbWriteBlock() function, the caller + should call the EfiFvbEraseBlock() function first to erase the specified + block to write. A block erase cycle will transition bits from the + (NOT)EFI_FVB_ERASE_POLARITY state back to the EFI_FVB_ERASE_POLARITY state. + Implementations should be mindful that the firmware volume might be + in the WriteDisabled state. If it is in this state, the EfiFvbWriteBlock() + function must return the status code EFI_ACCESS_DENIED without modifying + the contents of the firmware volume. + + The EfiFvbWriteBlock() function must also prevent spanning block boundaries. + If a write is requested that spans a block boundary, the write must store + up to the boundary but not beyond. The output parameter NumBytes must be + set to correctly indicate the number of bytes actually written. The caller + must be aware that a write may be partially completed. + All writes, partial or otherwise, must be fully flushed to the hardware + before the EfiFvbWriteBlock() function returns. + + If NumBytes is NULL, then ASSERT(). + + @param Instance The FV instance to be written to + @param Lba The starting logical block index to write to + @param Offset The offset relative to the block, at which to begin writting. + @param NumBytes Pointer to a UINTN. On input, *NumBytes contains + the total size of the buffer. On output, it contains + the actual number of bytes written. + @param Buffer Pointer to a caller allocated buffer that contains + the source for the write + + @retval EFI_SUCCESS The firmware volume was written successfully. + @retval EFI_BAD_BUFFER_SIZE The write was attempted across an LBA boundary. + On output, NumBytes contains the total number of bytes actually written. + @retval EFI_ACCESS_DENIED The firmware volume is in the WriteDisabled state. + @retval EFI_DEVICE_ERROR The block device is malfunctioning and could not be written. + @retval EFI_INVALID_PARAMETER Invalid parameter, Instance is larger than the max FVB number. + Lba index is larger than the last block of the firmware volume. + Offset is larger than the block size. **/ EFI_STATUS EfiFvbWriteBlock ( @@ -412,14 +466,32 @@ EfiFvbWriteBlock ( } /** - Erases and initializes a firmware volume block + Erases and initializes a firmware volume block. + + The EfiFvbEraseBlock() function erases one block specified by Lba. + Implementations should be mindful that the firmware volume might + be in the WriteDisabled state. If it is in this state, the EfiFvbEraseBlock() + function must return the status code EFI_ACCESS_DENIED without + modifying the contents of the firmware volume. If Instance is + larger than the max FVB number, or Lba index is larger than the + last block of the firmware volume, this function return the status + code EFI_INVALID_PARAMETER. + + All calls to EfiFvbEraseBlock() must be fully flushed to the + hardware before this function returns. - @param Instance The FV instance to be erased - @param Lba The logical block index to be erased + @param[in] Instance The FV instance to be erased. + @param[in] Lba The logical block index to be erased from. + + @retval EFI_SUCCESS The erase request was successfully completed. + @retval EFI_ACCESS_DENIED The firmware volume is in the WriteDisabled state. + @retval EFI_DEVICE_ERROR The block device is not functioning correctly and + could not be written. The firmware device may + have been partially erased. + @retval EFI_INVALID_PARAMETER Invalid parameter. Instance is larger than the max + FVB number. Lba index is larger than the last block + of the firmware volume. - @retval EFI_INVALID_PARAMETER Invalid parameter - @retval EFI_SUCESS Sucess to erase block - @retval Others Fail to erase block **/ EFI_STATUS EfiFvbEraseBlock ( @@ -439,15 +511,21 @@ EfiFvbEraseBlock ( } /** - Retrieves attributes, insures positive polarity of attribute bits, returns - resulting attributes in output parameter + Retrieves the attributes and current settings of the specified block, + returns resulting attributes in output parameter. + + The EfiFvbGetAttributes() function retrieves the attributes and current + settings of the block specified by Instance. If Instance is larger than + the max FVB number, this function returns the status code EFI_INVALID_PARAMETER. - @param Instance The FV instance whose attributes is going to be returned - @param Attributes Output buffer which contains attributes + If Attributes is NULL, then ASSERT(). - @retval EFI_INVALID_PARAMETER Invalid parameter - @retval EFI_SUCESS Sucess to get Fv attribute - @retval Others Fail to get Fv attribute + @param[in] Instance The FV instance to be operated. + @param[out] Attributes Pointer to EFI_FVB_ATTRIBUTES_2 in which the + attributes and current settings are returned. + + @retval EFI_EFI_SUCCESS The firmware volume attributes were returned. + @retval EFI_INVALID_PARAMETER Invalid parameter. Instance is larger than the max FVB number. **/ EFI_STATUS EfiFvbGetVolumeAttributes ( @@ -469,19 +547,24 @@ EfiFvbGetVolumeAttributes ( } /** - Modifies the current settings of the firmware volume according to the - input parameter, and returns the new setting of the volume - - @param Instance The FV instance whose attributes is going to be - modified - @param Attributes On input, it is a pointer to EFI_FVB_ATTRIBUTES_2 - containing the desired firmware volume settings. - On successful return, it contains the new settings - of the firmware volume - - @retval EFI_INVALID_PARAMETER Invalid parameter - @retval EFI_SUCESS Sucess to set Fv attribute - @retval Others Fail to set Fv attribute + Modify the attributes and current settings of the specified block + according to the input parameter. + + The EfiFvbSetAttributes() function sets configurable firmware volume + attributes and returns the new settings of the firmware volume specified + by Instance. If Instance is larger than the max FVB number, this function + returns the status code EFI_INVALID_PARAMETER. + + If Attributes is NULL, then ASSERT(). + + @param[in] Instance The FV instance to be operated. + @param[in, out]Attributes On input, Attributes is a pointer to EFI_FVB_ATTRIBUTES_2 + that contains the desired firmware volume settings. + On successful return, it contains the new settings of the firmware volume. + + @retval EFI_EFI_SUCCESS The firmware volume attributes were modified successfully. + @retval EFI_INVALID_PARAMETER Invalid parameter. Instance is larger than the max FVB number. + **/ EFI_STATUS EfiFvbSetVolumeAttributes ( @@ -503,17 +586,22 @@ EfiFvbSetVolumeAttributes ( } /** - Retrieves the physical address of a memory mapped FV + Retrieves the physical address of the specified memory mapped FV. - @param Instance The FV instance whose base address is going to be - returned - @param BaseAddress Pointer to a caller allocated EFI_PHYSICAL_ADDRESS - that on successful return, contains the base address - of the firmware volume. + Retrieve the base address of a memory-mapped firmware volume specified by Instance. + If Instance is larger than the max FVB number, this function returns the status + code EFI_INVALID_PARAMETER. + + If BaseAddress is NULL, then ASSERT(). + + @param[in] Instance The FV instance to be operated. + @param[out] BaseAddress Pointer to a caller allocated EFI_PHYSICAL_ADDRESS + that on successful return, contains the base address + of the firmware volume. + + @retval EFI_EFI_SUCCESS The firmware volume base address is returned. + @retval EFI_INVALID_PARAMETER Invalid parameter. Instance is larger than the max FVB number. - @retval EFI_INVALID_PARAMETER Invalid parameter - @retval EFI_SUCESS Sucess to get physical address - @retval Others Fail to get physical address **/ EFI_STATUS EfiFvbGetPhysicalAddress ( @@ -535,21 +623,30 @@ EfiFvbGetPhysicalAddress ( } /** - Retrieve the size of a logical block - - @param Instance The FV instance whose block size is going to be - returned - @param Lba Indicates which block to return the size for. - @param BlockSize A pointer to a caller allocated UINTN in which - the size of the block is returned - @param NumOfBlocks a pointer to a caller allocated UINTN in which the - number of consecutive blocks starting with Lba is - returned. All blocks in this range have a size of - BlockSize - - @retval EFI_INVALID_PARAMETER Invalid parameter - @retval EFI_SUCESS Sucess to get block size - @retval Others Fail to get block size + Retrieve the block size of the specified fv. + + The EfiFvbGetBlockSize() function retrieves the size of the requested block. + It also returns the number of additional blocks with the identical size. + If Instance is larger than the max FVB number, or Lba index is larger than + the last block of the firmware volume, this function return the status code + EFI_INVALID_PARAMETER. + + If BlockSize is NULL, then ASSERT(). + + If NumOfBlocks is NULL, then ASSERT(). + + @param[in] Instance The FV instance to be operated. + @param[in] Lba Indicates which block to return the size for. + @param[out] BlockSize Pointer to a caller-allocated UINTN in which the + size of the block is returned. + @param[out] NumOfBlocks Pointer to a caller-allocated UINTN in which the + number of consecutive blocks, starting with Lba, + is returned. All blocks in this range have a size of BlockSize. + + @retval EFI_EFI_SUCCESS The firmware volume base address is returned. + @retval EFI_INVALID_PARAMETER Invalid parameter. Instance is larger than the max FVB number. + Lba index is larger than the last block of the firmware volume. + **/ EFI_STATUS EfiFvbGetBlockSize ( @@ -574,18 +671,25 @@ EfiFvbGetBlockSize ( } /** - Erases and initializes a specified range of a firmware volume - - @param Instance The FV instance to be erased - @param StartLba The starting logical block index to be erased - @param OffsetStartLba Offset into the starting block at which to - begin erasing - @param LastLba The last logical block index to be erased - @param OffsetLastLba Offset into the last block at which to end erasing - - @retval EFI_INVALID_PARAMETER Invalid parameter - @retval EFI_SUCESS Sucess to erase custom block range - @retval Others Fail to erase custom block range + Erases and initializes a specified range of a firmware volume. + + The EfiFvbEraseCustomBlockRange() function erases the specified range in the firmware + volume index by Instance. If Instance is larger than the max FVB number, StartLba or + LastLba index is larger than the last block of the firmware volume, StartLba > LastLba + or StartLba equal to LastLba but OffsetStartLba > OffsetLastLba, this function return + the status code EFI_INVALID_PARAMETER. + + @param[in] Instance The FV instance to be operated. + @param[in] StartLba The starting logical block index to be erased. + @param[in] OffsetStartLba Offset into the starting block at which to + begin erasing. + @param[in] LastLba The last logical block index to be erased. + @param[in] OffsetLastLba Offset into the last block at which to end erasing. + + @retval EFI_EFI_SUCCESS Successfully erase custom block range + @retval EFI_INVALID_PARAMETER Invalid parameter. Instance is larger than the max FVB number. + @retval EFI_UNSUPPORTED Firmware volume block device has no this capability. + **/ EFI_STATUS EfiFvbEraseCustomBlockRange ( diff --git a/MdePkg/Include/Library/FvbServiceLib.h b/MdePkg/Include/Library/FvbServiceLib.h index cbbeabf0f9..cd2ca642c8 100644 --- a/MdePkg/Include/Library/FvbServiceLib.h +++ b/MdePkg/Include/Library/FvbServiceLib.h @@ -17,18 +17,38 @@ /** Reads specified number of bytes into a buffer from the specified block. - - @param[in] Instance The FV instance to be read from. - @param[in] Lba The logical block address to be read from - @param[in] Offset Offset into the block at which to begin reading - @param[in, out] NumBytes Pointer that on input contains the total size of - the buffer. On output, it contains the total number - of bytes read. - @param[out] Buffer Pointer to a caller allocated buffer that will be - used to hold the data read. - - @retval EFI_EFI_SUCCESS Buffer contains data read from FVB - @retval EFI_INVALID_PARAMETER invalid parameter + + The EfiFvbReadBlock() function reads the requested number of bytes from + the requested block in the specified firmware volume and stores them in + the provided buffer. Implementations should be mindful that the firmware + volume might be in the ReadDisabled state. If it is in this state, the + EfiFvbReadBlock() function must return the status code EFI_ACCESS_DENIED + without modifying the contents of the buffer. + + The EfiFvbReadBlock() function must also prevent spanning block boundaries. + If a read is requested that would span a block boundary, the read must read + up to the boundary but not beyond. The output parameter NumBytes must be + set to correctly indicate the number of bytes actually read. + The caller must be aware that a read may be partially completed. + + If NumBytes is NULL, then ASSERT(). + + If Buffer is NULL, then ASSERT(). + + @param[in] Instance The FV instance to be read from. + @param[in] Lba The logical block address to be read from + @param[in] Offset The offset relative to the block, at which to begin reading. + @param[in, out] NumBytes Pointer to a UINTN. On input, *NumBytes contains the total + size of the buffer. On output, it contains the actual number + of bytes read. + @param[out] Buffer Pointer to a caller allocated buffer that will be + used to hold the data read. + + @retval EFI_SUCCESS The firmware volume was read successfully and contents are in Buffer. + @retval EFI_BAD_BUFFER_SIZE Read attempted across an LBA boundary. On output, NumBytes contains the total number of bytes returned in Buffer. + @retval EFI_ACCESS_DENIED The firmware volume is in the ReadDisabled state. + @retval EFI_DEVICE_ERROR The block device is not functioning correctly and could not be read. + @retval EFI_INVALID_PARAMETER Invalid parameter, Instance is larger than the max FVB number. Lba index is larger than the last block of the firmware volume. Offset is larger than the block size. **/ EFI_STATUS @@ -42,21 +62,55 @@ EfiFvbReadBlock ( ); -/** - Writes specified number of bytes from the input buffer to the block. - - @param[in] Instance The FV instance to be read from. - @param[in] Lba The logical block address to be write to - @param[in] Offset Offset into the block at which to begin writing - @param[in, out] NumBytes Pointer that on input contains the total size of - the buffer. On output, it contains the total number - of bytes actually written. - @param[in] Buffer Pointer to a caller allocated buffer that contains - the source for the write. - - @retval EFI_EFI_SUCCESS Buffer written to FVB - @retval EFI_INVALID_PARAMETER invalid parameter - +/** + Writes specified number of bytes from the input buffer to the block + + The EfiFvbWriteBlock() function writes the specified number of bytes + from the provided buffer to the specified block and offset in the + requested firmware volume. + + If the firmware volume is sticky write, the caller must ensure that + all the bits of the specified range to write are in the EFI_FVB_ERASE_POLARITY + state before calling the EfiFvbWriteBlock() function, or else the + result will be unpredictable. This unpredictability arises because, + for a sticky-write firmware volume, a write may negate a bit in the + EFI_FVB_ERASE_POLARITY state but it cannot flip it back again. In + general, before calling the EfiFvbWriteBlock() function, the caller + should call the EfiFvbEraseBlock() function first to erase the specified + block to write. A block erase cycle will transition bits from the + (NOT)EFI_FVB_ERASE_POLARITY state back to the EFI_FVB_ERASE_POLARITY state. + Implementations should be mindful that the firmware volume might be + in the WriteDisabled state. If it is in this state, the EfiFvbWriteBlock() + function must return the status code EFI_ACCESS_DENIED without modifying + the contents of the firmware volume. + + The EfiFvbWriteBlock() function must also prevent spanning block boundaries. + If a write is requested that spans a block boundary, the write must store + up to the boundary but not beyond. The output parameter NumBytes must be + set to correctly indicate the number of bytes actually written. The caller + must be aware that a write may be partially completed. + All writes, partial or otherwise, must be fully flushed to the hardware + before the EfiFvbWriteBlock() function returns. + + If NumBytes is NULL, then ASSERT(). + + @param Instance The FV instance to be written to + @param Lba The starting logical block index to write to + @param Offset The offset relative to the block, at which to begin writting. + @param NumBytes Pointer to a UINTN. On input, *NumBytes contains + the total size of the buffer. On output, it contains + the actual number of bytes written. + @param Buffer Pointer to a caller allocated buffer that contains + the source for the write + + @retval EFI_SUCCESS The firmware volume was written successfully. + @retval EFI_BAD_BUFFER_SIZE The write was attempted across an LBA boundary. + On output, NumBytes contains the total number of bytes actually written. + @retval EFI_ACCESS_DENIED The firmware volume is in the WriteDisabled state. + @retval EFI_DEVICE_ERROR The block device is malfunctioning and could not be written. + @retval EFI_INVALID_PARAMETER Invalid parameter, Instance is larger than the max FVB number. + Lba index is larger than the last block of the firmware volume. + Offset is larger than the block size. **/ EFI_STATUS EFIAPI @@ -71,12 +125,30 @@ EfiFvbWriteBlock ( /** Erases and initializes a firmware volume block. + + The EfiFvbEraseBlock() function erases one block specified by Lba. + Implementations should be mindful that the firmware volume might + be in the WriteDisabled state. If it is in this state, the EfiFvbEraseBlock() + function must return the status code EFI_ACCESS_DENIED without + modifying the contents of the firmware volume. If Instance is + larger than the max FVB number, or Lba index is larger than the + last block of the firmware volume, this function return the status + code EFI_INVALID_PARAMETER. + + All calls to EfiFvbEraseBlock() must be fully flushed to the + hardware before this function returns. @param[in] Instance The FV instance to be erased. - @param[in] Lba The logical block address to be erased. - - @retval EFI_EFI_SUCCESS Lba was erased - @retval EFI_INVALID_PARAMETER invalid parameter + @param[in] Lba The logical block index to be erased from. + + @retval EFI_SUCCESS The erase request was successfully completed. + @retval EFI_ACCESS_DENIED The firmware volume is in the WriteDisabled state. + @retval EFI_DEVICE_ERROR The block device is not functioning correctly and + could not be written. The firmware device may + have been partially erased. + @retval EFI_INVALID_PARAMETER Invalid parameter. Instance is larger than the max + FVB number. Lba index is larger than the last block + of the firmware volume. **/ EFI_STATUS @@ -88,16 +160,21 @@ EfiFvbEraseBlock ( /** - Retrieves attributes, insures positive polarity of attribute bits, returns - resulting attributes in output parameter. - - @param[in] Instance The FV instance. - @param[out] Attributes The FV instance whose attributes is going to be - returned. + Retrieves the attributes and current settings of the specified block, + returns resulting attributes in output parameter. + + The EfiFvbGetAttributes() function retrieves the attributes and current + settings of the block specified by Instance. If Instance is larger than + the max FVB number, this function returns the status code EFI_INVALID_PARAMETER. + + If Attributes is NULL, then ASSERT(). - @retval EFI_EFI_SUCCESS Valid Attributes were returned - @retval EFI_INVALID_PARAMETER invalid parameter + @param[in] Instance The FV instance to be operated. + @param[out] Attributes Pointer to EFI_FVB_ATTRIBUTES_2 in which the + attributes and current settings are returned. + @retval EFI_EFI_SUCCESS The firmware volume attributes were returned. + @retval EFI_INVALID_PARAMETER Invalid parameter. Instance is larger than the max FVB number. **/ EFI_STATUS EFIAPI @@ -108,17 +185,23 @@ EfiFvbGetVolumeAttributes ( /** - Modifies the current settings of the firmware volume according to the - input parameter, and returns the new setting of the volume. - - @param[in] Instance The FV instance. - @param[in, out]Attributes On input, it is a pointer to EFI_FVB_ATTRIBUTES_2 - containing the desired firmware volume settings. - On successful return, it contains the new settings - of the firmware volume. + Modify the attributes and current settings of the specified block + according to the input parameter. + + The EfiFvbSetAttributes() function sets configurable firmware volume + attributes and returns the new settings of the firmware volume specified + by Instance. If Instance is larger than the max FVB number, this function + returns the status code EFI_INVALID_PARAMETER. + + If Attributes is NULL, then ASSERT(). + + @param[in] Instance The FV instance to be operated. + @param[in, out]Attributes On input, Attributes is a pointer to EFI_FVB_ATTRIBUTES_2 + that contains the desired firmware volume settings. + On successful return, it contains the new settings of the firmware volume. - @retval EFI_EFI_SUCCESS Attributes were updated - @retval EFI_INVALID_PARAMETER invalid parameter + @retval EFI_EFI_SUCCESS The firmware volume attributes were modified successfully. + @retval EFI_INVALID_PARAMETER Invalid parameter. Instance is larger than the max FVB number. **/ EFI_STATUS @@ -130,15 +213,21 @@ EfiFvbSetVolumeAttributes ( /** - Retrieves the physical address of a memory mapped FV. + Retrieves the physical address of the specified memory mapped FV. + + Retrieve the base address of a memory-mapped firmware volume specified by Instance. + If Instance is larger than the max FVB number, this function returns the status + code EFI_INVALID_PARAMETER. + + If BaseAddress is NULL, then ASSERT(). - @param[in] Instance The FV instance - @param[out] BaseAddress Pointer to a caller allocated EFI_PHYSICAL_ADDRESS - that on successful return, contains the base address - of the firmware volume. + @param[in] Instance The FV instance to be operated. + @param[out] BaseAddress Pointer to a caller allocated EFI_PHYSICAL_ADDRESS + that on successful return, contains the base address + of the firmware volume. - @retval EFI_EFI_SUCCESS BaseAddress was returned - @retval EFI_INVALID_PARAMETER invalid parameter + @retval EFI_EFI_SUCCESS The firmware volume base address is returned. + @retval EFI_INVALID_PARAMETER Invalid parameter. Instance is larger than the max FVB number. **/ EFI_STATUS @@ -150,19 +239,29 @@ EfiFvbGetPhysicalAddress ( /** - Retrieve the size of a logical block. + Retrieve the block size of the specified fv. + + The EfiFvbGetBlockSize() function retrieves the size of the requested block. + It also returns the number of additional blocks with the identical size. + If Instance is larger than the max FVB number, or Lba index is larger than + the last block of the firmware volume, this function return the status code + EFI_INVALID_PARAMETER. + + If BlockSize is NULL, then ASSERT(). + + If NumOfBlocks is NULL, then ASSERT(). - @param[in] Instance The FV instance - @param[in] Lba Indicates which block to return the size for. - @param[out] BlockSize A pointer to a caller allocated UINTN in which - the size of the block is returned. - @param[out] NumOfBlocks a pointer to a caller allocated UINTN in which the - number of consecutive blocks starting with Lba is - returned. All blocks in this range have a size of - BlockSize. + @param[in] Instance The FV instance to be operated. + @param[in] Lba Indicates which block to return the size for. + @param[out] BlockSize Pointer to a caller-allocated UINTN in which the + size of the block is returned. + @param[out] NumOfBlocks Pointer to a caller-allocated UINTN in which the + number of consecutive blocks, starting with Lba, + is returned. All blocks in this range have a size of BlockSize. - @retval EFI_EFI_SUCCESS BlockSize and NumOfBlocks returned - @retval EFI_INVALID_PARAMETER invalid parameter + @retval EFI_EFI_SUCCESS The firmware volume base address is returned. + @retval EFI_INVALID_PARAMETER Invalid parameter. Instance is larger than the max FVB number. + Lba index is larger than the last block of the firmware volume. **/ EFI_STATUS @@ -177,17 +276,23 @@ EfiFvbGetBlockSize ( /** Erases and initializes a specified range of a firmware volume. + + The EfiFvbEraseCustomBlockRange() function erases the specified range in the firmware + volume index by Instance. If Instance is larger than the max FVB number, StartLba or + LastLba index is larger than the last block of the firmware volume, StartLba > LastLba + or StartLba equal to LastLba but OffsetStartLba > OffsetLastLba, this function return + the status code EFI_INVALID_PARAMETER. - @param[in] Instance The FV instance. - @param[in] StartLba The starting logical block index to be erased. - @param[in] OffsetStartLba Offset into the starting block at which to - begin erasing. - @param[in] LastLba The last logical block index to be erased. - @param[in] OffsetLastLba Offset into the last block at which to end erasing. + @param[in] Instance The FV instance to be operated. + @param[in] StartLba The starting logical block index to be erased. + @param[in] OffsetStartLba Offset into the starting block at which to + begin erasing. + @param[in] LastLba The last logical block index to be erased. + @param[in] OffsetLastLba Offset into the last block at which to end erasing. - @retval EFI_EFI_SUCCESS Range was erased - @retval EFI_INVALID_PARAMETER invalid parameter - @retval EFI_UNSUPPORTED Range can not be erased + @retval EFI_EFI_SUCCESS Successfully erase custom block range + @retval EFI_INVALID_PARAMETER Invalid parameter. Instance is larger than the max FVB number. + @retval EFI_UNSUPPORTED Firmware volume block device has no this capability. **/ EFI_STATUS -- 2.39.2