From: qwang12 Date: Mon, 14 Jul 2008 08:19:45 +0000 (+0000) Subject: Clean up FaultTolerantWriteDxe for Doxygen comments requirement. X-Git-Tag: edk2-stable201903~20753 X-Git-Url: https://git.proxmox.com/?p=mirror_edk2.git;a=commitdiff_plain;h=6aab82140b20fab408f79dd428555b5d03370f72 Clean up FaultTolerantWriteDxe for Doxygen comments requirement. git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@5463 6f19259b-4bc3-4df7-8a09-765794883524 --- diff --git a/MdeModulePkg/Universal/FirmwareVolume/FaultTolerantWriteDxe/FtwLite.c b/MdeModulePkg/Universal/FirmwareVolume/FaultTolerantWriteDxe/FtwLite.c index 25836c470a..264ef4ba5c 100644 --- a/MdeModulePkg/Universal/FirmwareVolume/FaultTolerantWriteDxe/FtwLite.c +++ b/MdeModulePkg/Universal/FirmwareVolume/FaultTolerantWriteDxe/FtwLite.c @@ -32,6 +32,30 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. // // Fault Tolerant Write Protocol API // +/** + Starts a target block update. This function will record data about write + in fault tolerant storage and will complete the write in a recoverable + manner, ensuring at all times that either the original contents or + the modified contents are available. + + + @param This Calling context + @param FvbHandle The handle of FVB protocol that provides services for + reading, writing, and erasing the target block. + @param Lba The logical block address of the target block. + @param Offset The offset within the target block to place the data. + @param NumBytes The number of bytes to write to the target block. + @param Buffer The data to write. + + @retval EFI_SUCCESS The function completed successfully + @retval EFI_BAD_BUFFER_SIZE The write would span a target block, which is not + a valid action. + @retval EFI_ACCESS_DENIED No writes have been allocated. + @retval EFI_NOT_FOUND Cannot find FVB by handle. + @retval EFI_OUT_OF_RESOURCES Cannot allocate memory. + @retval EFI_ABORTED The function could not complete successfully. + +**/ EFI_STATUS EFIAPI FtwLiteWrite ( @@ -42,33 +66,6 @@ FtwLiteWrite ( IN OUT UINTN *NumBytes, IN VOID *Buffer ) -/*++ - -Routine Description: - Starts a target block update. This function will record data about write - in fault tolerant storage and will complete the write in a recoverable - manner, ensuring at all times that either the original contents or - the modified contents are available. - -Arguments: - This - Calling context - FvbHandle - The handle of FVB protocol that provides services for - reading, writing, and erasing the target block. - Lba - The logical block address of the target block. - Offset - The offset within the target block to place the data. - NumBytes - The number of bytes to write to the target block. - Buffer - The data to write. - -Returns: - EFI_SUCCESS - The function completed successfully - EFI_BAD_BUFFER_SIZE - The write would span a target block, which is not - a valid action. - EFI_ACCESS_DENIED - No writes have been allocated. - EFI_NOT_FOUND - Cannot find FVB by handle. - EFI_OUT_OF_RESOURCES - Cannot allocate memory. - EFI_ABORTED - The function could not complete successfully. - ---*/ { EFI_STATUS Status; EFI_FTW_LITE_DEVICE *FtwLiteDevice; @@ -385,28 +382,25 @@ Returns: } +/** + Write a record with fault tolerant mannaer. + Since the content has already backuped in spare block, the write is + guaranteed to be completed with fault tolerant manner. + + + @param FtwLiteDevice The private data of FTW_LITE driver + @param Fvb The FVB protocol that provides services for + reading, writing, and erasing the target block. + + @retval EFI_SUCCESS The function completed successfully + @retval EFI_ABORTED The function could not complete successfully + +**/ EFI_STATUS FtwWriteRecord ( IN EFI_FTW_LITE_DEVICE *FtwLiteDevice, IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *Fvb ) -/*++ - -Routine Description: - Write a record with fault tolerant mannaer. - Since the content has already backuped in spare block, the write is - guaranteed to be completed with fault tolerant manner. - -Arguments: - FtwLiteDevice - The private data of FTW_LITE driver - Fvb - The FVB protocol that provides services for - reading, writing, and erasing the target block. - -Returns: - EFI_SUCCESS - The function completed successfully - EFI_ABORTED - The function could not complete successfully - ---*/ { EFI_STATUS Status; EFI_FTW_LITE_RECORD *Record; @@ -471,28 +465,25 @@ Returns: } +/** + Restarts a previously interrupted write. The caller must provide the + block protocol needed to complete the interrupted write. + + + @param FtwLiteDevice The private data of FTW_LITE driver + FvbHandle - The handle of FVB protocol that provides services for + reading, writing, and erasing the target block. + + @retval EFI_SUCCESS The function completed successfully + @retval EFI_ACCESS_DENIED No pending writes exist + @retval EFI_NOT_FOUND FVB protocol not found by the handle + @retval EFI_ABORTED The function could not complete successfully + +**/ EFI_STATUS FtwRestart ( IN EFI_FTW_LITE_DEVICE *FtwLiteDevice ) -/*++ - -Routine Description: - Restarts a previously interrupted write. The caller must provide the - block protocol needed to complete the interrupted write. - -Arguments: - FtwLiteDevice - The private data of FTW_LITE driver - FvbHandle - The handle of FVB protocol that provides services for - reading, writing, and erasing the target block. - -Returns: - EFI_SUCCESS - The function completed successfully - EFI_ACCESS_DENIED - No pending writes exist - EFI_NOT_FOUND - FVB protocol not found by the handle - EFI_ABORTED - The function could not complete successfully - ---*/ { EFI_STATUS Status; EFI_FTW_LITE_RECORD *Record; @@ -539,24 +530,21 @@ Returns: } -EFI_STATUS -FtwAbort ( - IN EFI_FTW_LITE_DEVICE *FtwLiteDevice - ) -/*++ +/** + Aborts all previous allocated writes. -Routine Description: - Aborts all previous allocated writes. -Arguments: - FtwLiteDevice - The private data of FTW_LITE driver + @param FtwLiteDevice The private data of FTW_LITE driver -Returns: - EFI_SUCCESS - The function completed successfully - EFI_ABORTED - The function could not complete successfully. - EFI_NOT_FOUND - No allocated writes exist. + @retval EFI_SUCCESS The function completed successfully + @retval EFI_ABORTED The function could not complete successfully. + @retval EFI_NOT_FOUND No allocated writes exist. ---*/ +**/ +EFI_STATUS +FtwAbort ( + IN EFI_FTW_LITE_DEVICE *FtwLiteDevice + ) { EFI_STATUS Status; UINTN Offset; @@ -591,26 +579,24 @@ Returns: return EFI_SUCCESS; } +/** + This function is the entry point of the Fault Tolerant Write driver. + + + @param ImageHandle EFI_HANDLE: A handle for the image that is initializing + this driver + @param SystemTable EFI_SYSTEM_TABLE: A pointer to the EFI system table + + @retval EFI_SUCCESS FTW has finished the initialization + @retval EFI_ABORTED FTW initialization error + +**/ EFI_STATUS EFIAPI InitializeFtwLite ( IN EFI_HANDLE ImageHandle, IN EFI_SYSTEM_TABLE *SystemTable ) -/*++ - Routine Description: - This function is the entry point of the Fault Tolerant Write driver. - - Arguments: - ImageHandle - EFI_HANDLE: A handle for the image that is initializing - this driver - SystemTable - EFI_SYSTEM_TABLE: A pointer to the EFI system table - - Returns: - EFI_SUCCESS - FTW has finished the initialization - EFI_ABORTED - FTW initialization error - ---*/ { EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *Fvb; UINTN Index; diff --git a/MdeModulePkg/Universal/FirmwareVolume/FaultTolerantWriteDxe/FtwLite.h b/MdeModulePkg/Universal/FirmwareVolume/FaultTolerantWriteDxe/FtwLite.h index ab775c1967..6199952e94 100644 --- a/MdeModulePkg/Universal/FirmwareVolume/FaultTolerantWriteDxe/FtwLite.h +++ b/MdeModulePkg/Universal/FirmwareVolume/FaultTolerantWriteDxe/FtwLite.h @@ -133,366 +133,344 @@ typedef struct { // // Driver entry point // +/** + This function is the entry point of the Fault Tolerant Write driver. + + + @param ImageHandle EFI_HANDLE: A handle for the image that is initializing + this driver + @param SystemTable EFI_SYSTEM_TABLE: A pointer to the EFI system table + + @retval EFI_SUCCESS FTW has finished the initialization + @retval EFI_ABORTED FTW initialization error + +**/ EFI_STATUS EFIAPI InitializeFtwLite ( IN EFI_HANDLE ImageHandle, IN EFI_SYSTEM_TABLE *SystemTable ) -/*++ - -Routine Description: - This function is the entry point of the Fault Tolerant Write driver. - -Arguments: - ImageHandle - EFI_HANDLE: A handle for the image that is initializing - this driver - SystemTable - EFI_SYSTEM_TABLE: A pointer to the EFI system table - -Returns: - EFI_SUCCESS - FTW has finished the initialization - EFI_ABORTED - FTW initialization error - ---*/ ; // // Fault Tolerant Write Protocol API // +/** + Starts a target block update. This function will record data about write + in fault tolerant storage and will complete the write in a recoverable + manner, ensuring at all times that either the original contents or + the modified contents are available. + + + @param This Calling context + @param FvbHandle The handle of FVB protocol that provides services for + reading, writing, and erasing the target block. + @param Lba The logical block address of the target block. + @param Offset The offset within the target block to place the data. + @param NumBytes The number of bytes to write to the target block. + @param Buffer The data to write. + + @retval EFI_SUCCESS The function completed successfully + @retval EFI_BAD_BUFFER_SIZE The write would span a target block, which is not + a valid action. + @retval EFI_ACCESS_DENIED No writes have been allocated. + @retval EFI_NOT_FOUND Cannot find FVB by handle. + @retval EFI_OUT_OF_RESOURCES Cannot allocate memory. + @retval EFI_ABORTED The function could not complete successfully. + +**/ EFI_STATUS EFIAPI FtwLiteWrite ( - IN EFI_FTW_LITE_PROTOCOL *This, - IN EFI_HANDLE FvbHandle, - IN EFI_LBA Lba, - IN UINTN Offset, - IN UINTN *NumBytes, - IN VOID *Buffer + IN EFI_FTW_LITE_PROTOCOL *This, + IN EFI_HANDLE FvbHandle, + IN EFI_LBA Lba, + IN UINTN Offset, + IN OUT UINTN *NumBytes, + IN VOID *Buffer ) -/*++ - -Routine Description: - Starts a target block update. This function will record data about write - in fault tolerant storage and will complete the write in a recoverable - manner, ensuring at all times that either the original contents or - the modified contents are available. - -Arguments: - This - Calling context - FvbHandle - The handle of FVB protocol that provides services for - reading, writing, and erasing the target block. - Lba - The logical block address of the target block. - Offset - The offset within the target block to place the data. - NumBytes - The number of bytes to write to the target block. - Buffer - The data to write. - -Returns: - EFI_SUCCESS - The function completed successfully - EFI_BAD_BUFFER_SIZE - The write would span a target block, which is not - a valid action. - EFI_ACCESS_DENIED - No writes have been allocated. - EFI_NOT_FOUND - Cannot find FVB by handle. - EFI_OUT_OF_RESOURCES - Cannot allocate memory. - EFI_ABORTED - The function could not complete successfully. - ---*/ ; // // Internal functions // +/** + Restarts a previously interrupted write. The caller must provide the + block protocol needed to complete the interrupted write. + + + @param FtwLiteDevice The private data of FTW_LITE driver + FvbHandle - The handle of FVB protocol that provides services for + reading, writing, and erasing the target block. + + @retval EFI_SUCCESS The function completed successfully + @retval EFI_ACCESS_DENIED No pending writes exist + @retval EFI_NOT_FOUND FVB protocol not found by the handle + @retval EFI_ABORTED The function could not complete successfully + +**/ EFI_STATUS FtwRestart ( IN EFI_FTW_LITE_DEVICE *FtwLiteDevice ) -/*++ +; -Routine Description: - Restarts a previously interrupted write. The caller must provide the - block protocol needed to complete the interrupted write. +/** + Aborts all previous allocated writes. -Arguments: - FtwLiteDevice - The private data of FTW_LITE driver - FvbHandle - The handle of FVB protocol that provides services for - reading, writing, and erasing the target block. -Returns: - EFI_SUCCESS - The function completed successfully - EFI_ACCESS_DENIED - No pending writes exist - EFI_NOT_FOUND - FVB protocol not found by the handle - EFI_ABORTED - The function could not complete successfully + @param FtwLiteDevice The private data of FTW_LITE driver ---*/ -; + @retval EFI_SUCCESS The function completed successfully + @retval EFI_ABORTED The function could not complete successfully. + @retval EFI_NOT_FOUND No allocated writes exist. +**/ EFI_STATUS FtwAbort ( IN EFI_FTW_LITE_DEVICE *FtwLiteDevice ) -/*++ +; -Routine Description: - Aborts all previous allocated writes. -Arguments: - FtwLiteDevice - The private data of FTW_LITE driver +/** + Write a record with fault tolerant mannaer. + Since the content has already backuped in spare block, the write is + guaranteed to be completed with fault tolerant manner. -Returns: - EFI_SUCCESS - The function completed successfully - EFI_ABORTED - The function could not complete successfully. - EFI_NOT_FOUND - No allocated writes exist. ---*/ -; + @param FtwLiteDevice The private data of FTW_LITE driver + @param Fvb The FVB protocol that provides services for + reading, writing, and erasing the target block. + @retval EFI_SUCCESS The function completed successfully + @retval EFI_ABORTED The function could not complete successfully +**/ EFI_STATUS FtwWriteRecord ( IN EFI_FTW_LITE_DEVICE *FtwLiteDevice, IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *Fvb ) -/*++ +; -Routine Description: - Write a record with fault tolerant mannaer. - Since the content has already backuped in spare block, the write is - guaranteed to be completed with fault tolerant manner. +/** + To Erase one block. The size is FTW_BLOCK_SIZE -Arguments: - FtwLiteDevice - The private data of FTW_LITE driver - Fvb - The FVB protocol that provides services for - reading, writing, and erasing the target block. -Returns: - EFI_SUCCESS - The function completed successfully - EFI_ABORTED - The function could not complete successfully + @param FtwLiteDevice Calling context + @param FvBlock FVB Protocol interface + @param Lba Lba of the firmware block ---*/ -; + @retval EFI_SUCCESS Block LBA is Erased successfully + @retval Others Error occurs +**/ EFI_STATUS FtwEraseBlock ( IN EFI_FTW_LITE_DEVICE *FtwLiteDevice, EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *FvBlock, EFI_LBA Lba ) -/*++ +; -Routine Description: - To Erase one block. The size is FTW_BLOCK_SIZE +/** -Arguments: - FtwLiteDevice - Calling context - FvBlock - FVB Protocol interface - Lba - Lba of the firmware block + Erase spare block. -Returns: - EFI_SUCCESS - Block LBA is Erased successfully - Others - Error occurs ---*/ -; + @param FtwLiteDevice Calling context + @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 One or more of the LBAs listed + in the variable argument list do + not exist in the firmware volume. + +**/ EFI_STATUS FtwEraseSpareBlock ( IN EFI_FTW_LITE_DEVICE *FtwLiteDevice ) -/*++ - -Routine Description: - - Erase spare block. - -Arguments: +; - FtwLiteDevice - Calling context +/** + Retrive the proper FVB protocol interface by HANDLE. -Returns: - Status code + @param FvBlockHandle The handle of FVB protocol that provides services for + reading, writing, and erasing the target block. + @param FvBlock The interface of FVB protocol ---*/ -; + @retval EFI_SUCCESS The function completed successfully + @retval EFI_ABORTED The function could not complete successfully +**/ EFI_STATUS FtwGetFvbByHandle ( IN EFI_HANDLE FvBlockHandle, OUT EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL **FvBlock ) -/*++ +; -Routine Description: - Retrive the proper FVB protocol interface by HANDLE. +/** -Arguments: - FvBlockHandle - The handle of FVB protocol that provides services for - reading, writing, and erasing the target block. - FvBlock - The interface of FVB protocol + Get firmware block by address. -Returns: - EFI_SUCCESS - The function completed successfully - EFI_ABORTED - The function could not complete successfully ---*/ -; + @param Address Address specified the block + @param FvBlock The block caller wanted + + @retval EFI_SUCCESS The protocol instance if found. + @retval EFI_NOT_FOUND Block not found + +**/ EFI_STATUS GetFvbByAddress ( IN EFI_PHYSICAL_ADDRESS Address, OUT EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL **FvBlock ) -/*++ - -Routine Description: - - Get firmware block by address. +; -Arguments: +/** - Address - Address specified the block - FvBlock - The block caller wanted + Is it in working block? -Returns: - Status code + @param FtwLiteDevice Calling context + @param FvBlock Fvb protocol instance + @param Lba The block specified - EFI_NOT_FOUND - Block not found - ---*/ -; + @return A BOOLEAN value indicating in working block or not. +**/ BOOLEAN IsInWorkingBlock ( EFI_FTW_LITE_DEVICE *FtwLiteDevice, EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *FvBlock, EFI_LBA Lba ) -/*++ - -Routine Description: - - Is it in working block? +; -Arguments: +/** - FtwLiteDevice - Calling context - FvBlock - Fvb protocol instance - Lba - The block specified + Check whether the block is a boot block. -Returns: - In working block or not + @param FtwLiteDevice Calling context + @param FvBlock Fvb protocol instance + @param Lba Lba value ---*/ -; + @retval FALSE This is a boot block. + @retval TRUE This is not a boot block. +**/ BOOLEAN IsBootBlock ( EFI_FTW_LITE_DEVICE *FtwLiteDevice, EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *FvBlock, EFI_LBA Lba ) -/*++ - -Routine Description: - - Check whether the block is a boot block. - -Arguments: +; - FtwLiteDevice - Calling context - FvBlock - Fvb protocol instance - Lba - Lba value +/** + Copy the content of spare block to a target block. Size is FTW_BLOCK_SIZE. + Spare block is accessed by FTW backup FVB protocol interface. LBA is + FtwLiteDevice->FtwSpareLba. + Target block is accessed by FvBlock protocol interface. LBA is Lba. -Returns: - Is a boot block or not + @param FtwLiteDevice The private data of FTW_LITE driver + @param FvBlock FVB Protocol interface to access target block + @param Lba Lba of the target block ---*/ -; + @retval EFI_SUCCESS Spare block content is copied to target block + @retval EFI_INVALID_PARAMETER Input parameter error + @retval EFI_OUT_OF_RESOURCES Allocate memory error + @retval EFI_ABORTED The function could not complete successfully +**/ EFI_STATUS FlushSpareBlockToTargetBlock ( EFI_FTW_LITE_DEVICE *FtwLiteDevice, EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *FvBlock, EFI_LBA Lba ) -/*++ - -Routine Description: - Copy the content of spare block to a target block. Size is FTW_BLOCK_SIZE. - Spare block is accessed by FTW backup FVB protocol interface. LBA is - FtwLiteDevice->FtwSpareLba. - Target block is accessed by FvBlock protocol interface. LBA is Lba. - -Arguments: - FtwLiteDevice - The private data of FTW_LITE driver - FvBlock - FVB Protocol interface to access target block - Lba - Lba of the target block - -Returns: - EFI_SUCCESS - Spare block content is copied to target block - EFI_INVALID_PARAMETER - Input parameter error - EFI_OUT_OF_RESOURCES - Allocate memory error - EFI_ABORTED - The function could not complete successfully - ---*/ ; +/** + Copy the content of spare block to working block. Size is FTW_BLOCK_SIZE. + Spare block is accessed by FTW backup FVB protocol interface. LBA is + FtwLiteDevice->FtwSpareLba. + Working block is accessed by FTW working FVB protocol interface. LBA is + FtwLiteDevice->FtwWorkBlockLba. + + + @param FtwLiteDevice The private data of FTW_LITE driver + + @retval EFI_SUCCESS Spare block content is copied to target block + @retval EFI_OUT_OF_RESOURCES Allocate memory error + @retval EFI_ABORTED The function could not complete successfully + Notes: + Since the working block header is important when FTW initializes, the + state of the operation should be handled carefully. The Crc value is + calculated without STATE element. + +**/ EFI_STATUS FlushSpareBlockToWorkingBlock ( EFI_FTW_LITE_DEVICE *FtwLiteDevice ) -/*++ - -Routine Description: - Copy the content of spare block to working block. Size is FTW_BLOCK_SIZE. - Spare block is accessed by FTW backup FVB protocol interface. LBA is - FtwLiteDevice->FtwSpareLba. - Working block is accessed by FTW working FVB protocol interface. LBA is - FtwLiteDevice->FtwWorkBlockLba. +; -Arguments: - FtwLiteDevice - The private data of FTW_LITE driver +/** + Copy the content of spare block to a boot block. Size is FTW_BLOCK_SIZE. + Spare block is accessed by FTW backup FVB protocol interface. LBA is + FtwLiteDevice->FtwSpareLba. + Boot block is accessed by BootFvb protocol interface. LBA is 0. -Returns: - EFI_SUCCESS - Spare block content is copied to target block - EFI_OUT_OF_RESOURCES - Allocate memory error - EFI_ABORTED - The function could not complete successfully -Notes: - Since the working block header is important when FTW initializes, the - state of the operation should be handled carefully. The Crc value is - calculated without STATE element. + @param FtwLiteDevice The private data of FTW_LITE driver ---*/ -; + @retval EFI_SUCCESS Spare block content is copied to boot block + @retval EFI_INVALID_PARAMETER Input parameter error + @retval EFI_OUT_OF_RESOURCES Allocate memory error + @retval EFI_ABORTED The function could not complete successfully + Notes: +**/ EFI_STATUS FlushSpareBlockToBootBlock ( EFI_FTW_LITE_DEVICE *FtwLiteDevice ) -/*++ - -Routine Description: - Copy the content of spare block to a boot block. Size is FTW_BLOCK_SIZE. - Spare block is accessed by FTW backup FVB protocol interface. LBA is - FtwLiteDevice->FtwSpareLba. - Boot block is accessed by BootFvb protocol interface. LBA is 0. +; -Arguments: - FtwLiteDevice - The private data of FTW_LITE driver +/** + Update a bit of state on a block device. The location of the bit is + calculated by the (Lba, Offset, bit). Here bit is determined by the + the name of a certain bit. -Returns: - EFI_SUCCESS - Spare block content is copied to boot block - EFI_INVALID_PARAMETER - Input parameter error - EFI_OUT_OF_RESOURCES - Allocate memory error - EFI_ABORTED - The function could not complete successfully -Notes: + @param FvBlock FVB Protocol interface to access SrcBlock and DestBlock + @param Lba Lba of a block + @param Offset Offset on the Lba + @param NewBit New value that will override the old value if it can be change ---*/ -; + @retval EFI_SUCCESS A state bit has been updated successfully + @retval Others Access block device error. + Notes: + Assume all bits of State are inside the same BYTE. + @retval EFI_ABORTED Read block fail +**/ EFI_STATUS FtwUpdateFvState ( IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *FvBlock, @@ -500,178 +478,134 @@ FtwUpdateFvState ( IN UINTN Offset, IN UINT8 NewBit ) -/*++ +; -Routine Description: - Update a bit of state on a block device. The location of the bit is - calculated by the (Lba, Offset, bit). Here bit is determined by the - the name of a certain bit. +/** + Get the last Write record pointer. + The last record is the record whose 'complete' state hasn't been set. + After all, this header may be a EMPTY header entry for next Allocate. -Arguments: - FvBlock - FVB Protocol interface to access SrcBlock and DestBlock - Lba - Lba of a block - Offset - Offset on the Lba - NewBit - New value that will override the old value if it can be change -Returns: - EFI_SUCCESS - A state bit has been updated successfully - Others - Access block device error. + @param FtwLiteDevice Private data of this driver + @param FtwLastRecord Pointer to retrieve the last write record -Notes: - Assume all bits of State are inside the same BYTE. - - EFI_ABORTED - Read block fail ---*/ -; + @retval EFI_SUCCESS Get the last write record successfully + @retval EFI_ABORTED The FTW work space is damaged +**/ EFI_STATUS FtwGetLastRecord ( IN EFI_FTW_LITE_DEVICE *FtwLiteDevice, OUT EFI_FTW_LITE_RECORD **FtwLastRecord ) -/*++ +; -Routine Description: - Get the last Write record pointer. - The last record is the record whose 'complete' state hasn't been set. - After all, this header may be a EMPTY header entry for next Allocate. +/** -Arguments: - FtwLiteDevice - Private data of this driver - FtwLastRecord - Pointer to retrieve the last write record + Check whether a flash buffer is erased. -Returns: - EFI_SUCCESS - Get the last write record successfully - EFI_ABORTED - The FTW work space is damaged ---*/ -; + @param Polarity All 1 or all 0 + @param Buffer Buffer to check + @param BufferSize Size of the buffer + @return A BOOLEAN value indicating erased or not. + +**/ BOOLEAN IsErasedFlashBuffer ( IN BOOLEAN Polarity, IN UINT8 *Buffer, IN UINTN BufferSize ) -/*++ - -Routine Description: - - Check whether a flash buffer is erased. - -Arguments: +; - Polarity - All 1 or all 0 - Buffer - Buffer to check - BufferSize - Size of the buffer +/** + Initialize a work space when there is no work space. -Returns: - Erased or not. + @param WorkingHeader Pointer of working block header ---*/ -; + @retval EFI_SUCCESS The function completed successfully + @retval EFI_ABORTED The function could not complete successfully. +**/ EFI_STATUS InitWorkSpaceHeader ( IN EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER *WorkingHeader ) -/*++ +; -Routine Description: - Initialize a work space when there is no work space. +/** + Read from working block to refresh the work space in memory. -Arguments: - WorkingHeader - Pointer of working block header -Returns: - EFI_SUCCESS - The function completed successfully - EFI_ABORTED - The function could not complete successfully. + @param FtwLiteDevice Point to private data of FTW driver ---*/ -; + @retval EFI_SUCCESS The function completed successfully + @retval EFI_ABORTED The function could not complete successfully. +**/ EFI_STATUS WorkSpaceRefresh ( IN EFI_FTW_LITE_DEVICE *FtwLiteDevice ) -/*++ +; -Routine Description: - Read from working block to refresh the work space in memory. +/** + Check to see if it is a valid work space. -Arguments: - FtwLiteDevice - Point to private data of FTW driver -Returns: - EFI_SUCCESS - The function completed successfully - EFI_ABORTED - The function could not complete successfully. + @param WorkingHeader Pointer of working block header ---*/ -; + @retval EFI_SUCCESS The function completed successfully + @retval EFI_ABORTED The function could not complete successfully. +**/ BOOLEAN IsValidWorkSpace ( IN EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER *WorkingHeader ) -/*++ +; -Routine Description: - Check to see if it is a valid work space. +/** + Reclaim the work space. Get rid of all the completed write records + and write records in the Fault Tolerant work space. -Arguments: - WorkingHeader - Pointer of working block header -Returns: - EFI_SUCCESS - The function completed successfully - EFI_ABORTED - The function could not complete successfully. + @param FtwLiteDevice Point to private data of FTW driver + FtwSpaceBuffer - Buffer to contain the reclaimed clean data + @param BlockBuffer The data buffer for the block. + @param BufferSize Size of the FtwSpaceBuffer ---*/ -; + @retval EFI_SUCCESS The function completed successfully + @retval EFI_BUFFER_TOO_SMALL The FtwSpaceBuffer is too small + @retval EFI_ABORTED The function could not complete successfully. +**/ EFI_STATUS CleanupWorkSpace ( IN EFI_FTW_LITE_DEVICE *FtwLiteDevice, IN OUT UINT8 *BlockBuffer, IN UINTN BufferSize ) -/*++ +; -Routine Description: - Reclaim the work space. Get rid of all the completed write records - and write records in the Fault Tolerant work space. +/** + Reclaim the work space on the working block. -Arguments: - FtwLiteDevice - Point to private data of FTW driver - FtwSpaceBuffer - Buffer to contain the reclaimed clean data - BufferSize - Size of the FtwSpaceBuffer -Returns: - EFI_SUCCESS - The function completed successfully - EFI_BUFFER_TOO_SMALL - The FtwSpaceBuffer is too small - EFI_ABORTED - The function could not complete successfully. + @param FtwLiteDevice Point to private data of FTW driver ---*/ -; + @retval EFI_SUCCESS The function completed successfully + @retval EFI_OUT_OF_RESOURCES Allocate memory error + @retval EFI_ABORTED The function could not complete successfully +**/ EFI_STATUS FtwReclaimWorkSpace ( IN EFI_FTW_LITE_DEVICE *FtwLiteDevice ) -/*++ - -Routine Description: - Reclaim the work space on the working block. - -Arguments: - FtwLiteDevice - Point to private data of FTW driver - -Returns: - EFI_SUCCESS - The function completed successfully - EFI_OUT_OF_RESOURCES - Allocate memory error - EFI_ABORTED - The function could not complete successfully - ---*/ ; #endif diff --git a/MdeModulePkg/Universal/FirmwareVolume/FaultTolerantWriteDxe/FtwMisc.c b/MdeModulePkg/Universal/FirmwareVolume/FaultTolerantWriteDxe/FtwMisc.c index fccf889a3d..eb487b737f 100644 --- a/MdeModulePkg/Universal/FirmwareVolume/FaultTolerantWriteDxe/FtwMisc.c +++ b/MdeModulePkg/Universal/FirmwareVolume/FaultTolerantWriteDxe/FtwMisc.c @@ -15,29 +15,24 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. #include -BOOLEAN -IsErasedFlashBuffer ( - IN BOOLEAN Polarity, - IN UINT8 *Buffer, - IN UINTN BufferSize - ) -/*++ - -Routine Description: +/** Check whether a flash buffer is erased. -Arguments: - - Polarity - All 1 or all 0 - Buffer - Buffer to check - BufferSize - Size of the buffer -Returns: + @param Polarity All 1 or all 0 + @param Buffer Buffer to check + @param BufferSize Size of the buffer - Erased or not. + @return A BOOLEAN value indicating erased or not. ---*/ +**/ +BOOLEAN +IsErasedFlashBuffer ( + IN BOOLEAN Polarity, + IN UINT8 *Buffer, + IN UINTN BufferSize + ) { UINT8 ErasedValue; UINT8 *Ptr; @@ -49,7 +44,7 @@ Returns: } Ptr = Buffer; - while (BufferSize--) { + while ((BufferSize--) != 0) { if (*Ptr++ != ErasedValue) { return FALSE; } @@ -58,27 +53,24 @@ Returns: return TRUE; } +/** + To Erase one block. The size is FTW_BLOCK_SIZE + + + @param FtwLiteDevice Calling context + @param FvBlock FVB Protocol interface + @param Lba Lba of the firmware block + + @retval EFI_SUCCESS Block LBA is Erased successfully + @retval Others Error occurs + +**/ EFI_STATUS FtwEraseBlock ( IN EFI_FTW_LITE_DEVICE *FtwLiteDevice, EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *FvBlock, EFI_LBA Lba ) -/*++ - -Routine Description: - To Erase one block. The size is FTW_BLOCK_SIZE - -Arguments: - FtwLiteDevice - Calling context - FvBlock - FVB Protocol interface - Lba - Lba of the firmware block - -Returns: - EFI_SUCCESS - Block LBA is Erased successfully - Others - Error occurs - ---*/ { return FvBlock->EraseBlocks ( FvBlock, @@ -88,25 +80,32 @@ Returns: ); } -EFI_STATUS -FtwEraseSpareBlock ( - IN EFI_FTW_LITE_DEVICE *FtwLiteDevice - ) -/*++ - -Routine Description: +/** Erase spare block. -Arguments: - FtwLiteDevice - Calling context + @param FtwLiteDevice Calling context -Returns: + @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 One or more of the LBAs listed + in the variable argument list do + not exist in the firmware volume. - Status code ---*/ +**/ +EFI_STATUS +FtwEraseSpareBlock ( + IN EFI_FTW_LITE_DEVICE *FtwLiteDevice + ) { return FtwLiteDevice->FtwBackupFvb->EraseBlocks ( FtwLiteDevice->FtwBackupFvb, @@ -116,25 +115,23 @@ Returns: ); } +/** + Retrive the proper FVB protocol interface by HANDLE. + + + @param FvBlockHandle The handle of FVB protocol that provides services for + reading, writing, and erasing the target block. + @param FvBlock The interface of FVB protocol + + @retval EFI_SUCCESS The function completed successfully + @retval EFI_ABORTED The function could not complete successfully + +**/ EFI_STATUS FtwGetFvbByHandle ( IN EFI_HANDLE FvBlockHandle, OUT EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL **FvBlock ) -/*++ - -Routine Description: - Retrive the proper FVB protocol interface by HANDLE. - -Arguments: - FvBlockHandle - The handle of FVB protocol that provides services for - reading, writing, and erasing the target block. - FvBlock - The interface of FVB protocol - -Returns: - EFI_SUCCESS - The function completed successfully - EFI_ABORTED - The function could not complete successfully ---*/ { // // To get the FVB protocol interface on the handle @@ -146,29 +143,23 @@ Returns: ); } -EFI_STATUS -GetFvbByAddress ( - IN EFI_PHYSICAL_ADDRESS Address, - OUT EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL **FvBlock - ) -/*++ - -Routine Description: +/** Get firmware block by address. -Arguments: - - Address - Address specified the block - FvBlock - The block caller wanted -Returns: + @param Address Address specified the block + @param FvBlock The block caller wanted - Status code + @retval EFI_SUCCESS The protocol instance if found. + @retval EFI_NOT_FOUND Block not found - EFI_NOT_FOUND - Block not found - ---*/ +**/ +EFI_STATUS +GetFvbByAddress ( + IN EFI_PHYSICAL_ADDRESS Address, + OUT EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL **FvBlock + ) { EFI_STATUS Status; EFI_HANDLE *HandleBuffer; @@ -225,29 +216,24 @@ Returns: return Status; } -BOOLEAN -IsInWorkingBlock ( - EFI_FTW_LITE_DEVICE *FtwLiteDevice, - EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *FvBlock, - EFI_LBA Lba - ) -/*++ - -Routine Description: +/** Is it in working block? -Arguments: - FtwLiteDevice - Calling context - FvBlock - Fvb protocol instance - Lba - The block specified + @param FtwLiteDevice Calling context + @param FvBlock Fvb protocol instance + @param Lba The block specified -Returns: + @return A BOOLEAN value indicating in working block or not. - In working block or not - ---*/ +**/ +BOOLEAN +IsInWorkingBlock ( + EFI_FTW_LITE_DEVICE *FtwLiteDevice, + EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *FvBlock, + EFI_LBA Lba + ) { // // If matching the following condition, the target block is in working block. @@ -262,32 +248,29 @@ Returns: ); } +/** + Copy the content of spare block to a target block. Size is FTW_BLOCK_SIZE. + Spare block is accessed by FTW backup FVB protocol interface. LBA is + FtwLiteDevice->FtwSpareLba. + Target block is accessed by FvBlock protocol interface. LBA is Lba. + + + @param FtwLiteDevice The private data of FTW_LITE driver + @param FvBlock FVB Protocol interface to access target block + @param Lba Lba of the target block + + @retval EFI_SUCCESS Spare block content is copied to target block + @retval EFI_INVALID_PARAMETER Input parameter error + @retval EFI_OUT_OF_RESOURCES Allocate memory error + @retval EFI_ABORTED The function could not complete successfully + +**/ EFI_STATUS FlushSpareBlockToTargetBlock ( EFI_FTW_LITE_DEVICE *FtwLiteDevice, EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *FvBlock, EFI_LBA Lba ) -/*++ - -Routine Description: - Copy the content of spare block to a target block. Size is FTW_BLOCK_SIZE. - Spare block is accessed by FTW backup FVB protocol interface. LBA is - FtwLiteDevice->FtwSpareLba. - Target block is accessed by FvBlock protocol interface. LBA is Lba. - -Arguments: - FtwLiteDevice - The private data of FTW_LITE driver - FvBlock - FVB Protocol interface to access target block - Lba - Lba of the target block - -Returns: - EFI_SUCCESS - Spare block content is copied to target block - EFI_INVALID_PARAMETER - Input parameter error - EFI_OUT_OF_RESOURCES - Allocate memory error - EFI_ABORTED - The function could not complete successfully - ---*/ { EFI_STATUS Status; UINTN Length; @@ -356,33 +339,29 @@ Returns: return Status; } -EFI_STATUS -FlushSpareBlockToWorkingBlock ( - EFI_FTW_LITE_DEVICE *FtwLiteDevice - ) -/*++ - -Routine Description: - Copy the content of spare block to working block. Size is FTW_BLOCK_SIZE. - Spare block is accessed by FTW backup FVB protocol interface. LBA is - FtwLiteDevice->FtwSpareLba. - Working block is accessed by FTW working FVB protocol interface. LBA is - FtwLiteDevice->FtwWorkBlockLba. +/** + Copy the content of spare block to working block. Size is FTW_BLOCK_SIZE. + Spare block is accessed by FTW backup FVB protocol interface. LBA is + FtwLiteDevice->FtwSpareLba. + Working block is accessed by FTW working FVB protocol interface. LBA is + FtwLiteDevice->FtwWorkBlockLba. -Arguments: - FtwLiteDevice - The private data of FTW_LITE driver -Returns: - EFI_SUCCESS - Spare block content is copied to target block - EFI_OUT_OF_RESOURCES - Allocate memory error - EFI_ABORTED - The function could not complete successfully + @param FtwLiteDevice The private data of FTW_LITE driver -Notes: - Since the working block header is important when FTW initializes, the - state of the operation should be handled carefully. The Crc value is - calculated without STATE element. + @retval EFI_SUCCESS Spare block content is copied to target block + @retval EFI_OUT_OF_RESOURCES Allocate memory error + @retval EFI_ABORTED The function could not complete successfully + Notes: + Since the working block header is important when FTW initializes, the + state of the operation should be handled carefully. The Crc value is + calculated without STATE element. ---*/ +**/ +EFI_STATUS +FlushSpareBlockToWorkingBlock ( + EFI_FTW_LITE_DEVICE *FtwLiteDevice + ) { EFI_STATUS Status; UINTN Length; diff --git a/MdeModulePkg/Universal/FirmwareVolume/FaultTolerantWriteDxe/FtwWorkSpace.c b/MdeModulePkg/Universal/FirmwareVolume/FaultTolerantWriteDxe/FtwWorkSpace.c index d4dbf1ce8e..3da4d42cd3 100644 --- a/MdeModulePkg/Universal/FirmwareVolume/FaultTolerantWriteDxe/FtwWorkSpace.c +++ b/MdeModulePkg/Universal/FirmwareVolume/FaultTolerantWriteDxe/FtwWorkSpace.c @@ -16,23 +16,20 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. #include -BOOLEAN -IsValidWorkSpace ( - IN EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER *WorkingHeader - ) -/*++ +/** + Check to see if it is a valid work space. -Routine Description: - Check to see if it is a valid work space. -Arguments: - WorkingHeader - Pointer of working block header + @param WorkingHeader Pointer of working block header -Returns: - EFI_SUCCESS - The function completed successfully - EFI_ABORTED - The function could not complete successfully. + @retval EFI_SUCCESS The function completed successfully + @retval EFI_ABORTED The function could not complete successfully. ---*/ +**/ +BOOLEAN +IsValidWorkSpace ( + IN EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER *WorkingHeader + ) { EFI_STATUS Status; EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER WorkingBlockHeader; @@ -85,23 +82,20 @@ Returns: return TRUE; } -EFI_STATUS -InitWorkSpaceHeader ( - IN EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER *WorkingHeader - ) -/*++ +/** + Initialize a work space when there is no work space. -Routine Description: - Initialize a work space when there is no work space. -Arguments: - WorkingHeader - Pointer of working block header + @param WorkingHeader Pointer of working block header -Returns: - EFI_SUCCESS - The function completed successfully - EFI_ABORTED - The function could not complete successfully. + @retval EFI_SUCCESS The function completed successfully + @retval EFI_ABORTED The function could not complete successfully. ---*/ +**/ +EFI_STATUS +InitWorkSpaceHeader ( + IN EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER *WorkingHeader + ) { EFI_STATUS Status; @@ -143,6 +137,24 @@ Returns: return EFI_SUCCESS; } +/** + Update a bit of state on a block device. The location of the bit is + calculated by the (Lba, Offset, bit). Here bit is determined by the + the name of a certain bit. + + + @param FvBlock FVB Protocol interface to access SrcBlock and DestBlock + @param Lba Lba of a block + @param Offset Offset on the Lba + @param NewBit New value that will override the old value if it can be change + + @retval EFI_SUCCESS A state bit has been updated successfully + @retval Others Access block device error. + Notes: + Assume all bits of State are inside the same BYTE. + @retval EFI_ABORTED Read block fail + +**/ EFI_STATUS FtwUpdateFvState ( IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *FvBlock, @@ -150,28 +162,6 @@ FtwUpdateFvState ( IN UINTN Offset, IN UINT8 NewBit ) -/*++ - -Routine Description: - Update a bit of state on a block device. The location of the bit is - calculated by the (Lba, Offset, bit). Here bit is determined by the - the name of a certain bit. - -Arguments: - FvBlock - FVB Protocol interface to access SrcBlock and DestBlock - Lba - Lba of a block - Offset - Offset on the Lba - NewBit - New value that will override the old value if it can be change - -Returns: - EFI_SUCCESS - A state bit has been updated successfully - Others - Access block device error. - -Notes: - Assume all bits of State are inside the same BYTE. - - EFI_ABORTED - Read block fail ---*/ { EFI_STATUS Status; UINT8 State; @@ -199,27 +189,24 @@ Notes: return Status; } +/** + Get the last Write record pointer. + The last record is the record whose 'complete' state hasn't been set. + After all, this header may be a EMPTY header entry for next Allocate. + + + @param FtwLiteDevice Private data of this driver + @param FtwLastRecord Pointer to retrieve the last write record + + @retval EFI_SUCCESS Get the last write record successfully + @retval EFI_ABORTED The FTW work space is damaged + +**/ EFI_STATUS FtwGetLastRecord ( IN EFI_FTW_LITE_DEVICE *FtwLiteDevice, OUT EFI_FTW_LITE_RECORD **FtwLastRecord ) -/*++ - -Routine Description: - Get the last Write record pointer. - The last record is the record whose 'complete' state hasn't been set. - After all, this header may be a EMPTY header entry for next Allocate. - -Arguments: - FtwLiteDevice - Private data of this driver - FtwLastRecord - Pointer to retrieve the last write record - -Returns: - EFI_SUCCESS - Get the last write record successfully - EFI_ABORTED - The FTW work space is damaged - ---*/ { EFI_FTW_LITE_RECORD *Record; @@ -241,23 +228,20 @@ Returns: return EFI_SUCCESS; } -EFI_STATUS -WorkSpaceRefresh ( - IN EFI_FTW_LITE_DEVICE *FtwLiteDevice - ) -/*++ +/** + Read from working block to refresh the work space in memory. -Routine Description: - Read from working block to refresh the work space in memory. -Arguments: - FtwLiteDevice - Point to private data of FTW driver + @param FtwLiteDevice Point to private data of FTW driver -Returns: - EFI_SUCCESS - The function completed successfully - EFI_ABORTED - The function could not complete successfully. + @retval EFI_SUCCESS The function completed successfully + @retval EFI_ABORTED The function could not complete successfully. ---*/ +**/ +EFI_STATUS +WorkSpaceRefresh ( + IN EFI_FTW_LITE_DEVICE *FtwLiteDevice + ) { EFI_STATUS Status; UINTN Length; @@ -313,29 +297,26 @@ Returns: return EFI_SUCCESS; } +/** + Reclaim the work space. Get rid of all the completed write records + and write records in the Fault Tolerant work space. + + + @param FtwLiteDevice Point to private data of FTW driver + @param FtwSpaceBuffer Buffer to contain the reclaimed clean data + @param BufferSize Size of the FtwSpaceBuffer + + @retval EFI_SUCCESS The function completed successfully + @retval EFI_BUFFER_TOO_SMALL The FtwSpaceBuffer is too small + @retval EFI_ABORTED The function could not complete successfully. + +**/ EFI_STATUS CleanupWorkSpace ( IN EFI_FTW_LITE_DEVICE *FtwLiteDevice, IN OUT UINT8 *FtwSpaceBuffer, IN UINTN BufferSize ) -/*++ - -Routine Description: - Reclaim the work space. Get rid of all the completed write records - and write records in the Fault Tolerant work space. - -Arguments: - FtwLiteDevice - Point to private data of FTW driver - FtwSpaceBuffer - Buffer to contain the reclaimed clean data - BufferSize - Size of the FtwSpaceBuffer - -Returns: - EFI_SUCCESS - The function completed successfully - EFI_BUFFER_TOO_SMALL - The FtwSpaceBuffer is too small - EFI_ABORTED - The function could not complete successfully. - ---*/ { UINTN Length; EFI_FTW_LITE_RECORD *Record; @@ -376,24 +357,21 @@ Returns: return EFI_SUCCESS; } -EFI_STATUS -FtwReclaimWorkSpace ( - IN EFI_FTW_LITE_DEVICE *FtwLiteDevice - ) -/*++ +/** + Reclaim the work space on the working block. -Routine Description: - Reclaim the work space on the working block. -Arguments: - FtwLiteDevice - Point to private data of FTW driver + @param FtwLiteDevice Point to private data of FTW driver -Returns: - EFI_SUCCESS - The function completed successfully - EFI_OUT_OF_RESOURCES - Allocate memory error - EFI_ABORTED - The function could not complete successfully + @retval EFI_SUCCESS The function completed successfully + @retval EFI_OUT_OF_RESOURCES Allocate memory error + @retval EFI_ABORTED The function could not complete successfully ---*/ +**/ +EFI_STATUS +FtwReclaimWorkSpace ( + IN EFI_FTW_LITE_DEVICE *FtwLiteDevice + ) { EFI_STATUS Status; UINT8 *TempBuffer; diff --git a/MdeModulePkg/Universal/FirmwareVolume/FaultTolerantWriteDxe/Ia32/Ia32FtwMisc.c b/MdeModulePkg/Universal/FirmwareVolume/FaultTolerantWriteDxe/Ia32/Ia32FtwMisc.c index 2ca858c4dd..e626f1da65 100644 --- a/MdeModulePkg/Universal/FirmwareVolume/FaultTolerantWriteDxe/Ia32/Ia32FtwMisc.c +++ b/MdeModulePkg/Universal/FirmwareVolume/FaultTolerantWriteDxe/Ia32/Ia32FtwMisc.c @@ -33,26 +33,21 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. #define GEN_STATUS 0xD4 #define TOP_SWAP_BIT (1 << 13) -STATIC -UINT32 -ReadPciRegister ( - IN UINT32 Offset - ) -/*++ - -Routine Description: +/** Read PCI register value. + This is a internal function. -Arguments: - - Offset - Offset of the register -Returns: + @param Offset Offset of the register - The value. + @return The pci register value. ---*/ +**/ +UINT32 +ReadPciRegister ( + IN UINT32 Offset + ) { EFI_STATUS Status; UINT32 Value; @@ -82,28 +77,23 @@ Returns: return Value; } -STATIC -EFI_STATUS -GetSwapState ( - IN EFI_FTW_LITE_DEVICE *FtwLiteDevice, - OUT BOOLEAN *SwapState - ) -/*++ - -Routine Description: +/** Get swap state -Arguments: + This is a internal function. - FtwLiteDevice - Calling context - SwapState - Swap state + @param FtwLiteDevice Calling context + @param SwapState Swap state -Returns: + @retval EFI_SUCCESS State successfully got - EFI_SUCCESS - State successfully got - ---*/ +**/ +EFI_STATUS +GetSwapState ( + IN EFI_FTW_LITE_DEVICE *FtwLiteDevice, + OUT BOOLEAN *SwapState + ) { // // Top swap status is 13 bit @@ -113,30 +103,26 @@ Returns: return EFI_SUCCESS; } -STATIC +/** + Set swap state. + + This is a internal function. + + @param FtwLiteDevice Indicates a pointer to the calling context. + @param TopSwap New swap state + + @retval EFI_SUCCESS The function completed successfully + Note: + the Top-Swap bit (bit 13, D31: F0, Offset D4h). Note that + software will not be able to clear the Top-Swap bit until the system is + rebooted without GNT[A]# being pulled down. + +**/ EFI_STATUS SetSwapState ( IN EFI_FTW_LITE_DEVICE *FtwLiteDevice, IN BOOLEAN TopSwap ) -/*++ - -Routine Description: - Set swap state. - -Arguments: - FtwLiteDevice - Indicates a pointer to the calling context. - TopSwap - New swap state - -Returns: - EFI_SUCCESS - The function completed successfully - -Note: - the Top-Swap bit (bit 13, D31: F0, Offset D4h). Note that - software will not be able to clear the Top-Swap bit until the system is - rebooted without GNT[A]# being pulled down. - ---*/ { UINT32 GenStatus; EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL *PciRootBridgeIo; @@ -188,29 +174,25 @@ Note: return EFI_SUCCESS; } -BOOLEAN -IsBootBlock ( - EFI_FTW_LITE_DEVICE *FtwLiteDevice, - EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *FvBlock, - EFI_LBA Lba - ) -/*++ - -Routine Description: +/** Check whether the block is a boot block. -Arguments: - - FtwLiteDevice - Calling context - FvBlock - Fvb protocol instance - Lba - Lba value -Returns: + @param FtwLiteDevice Calling context + @param FvBlock Fvb protocol instance + @param Lba Lba value - Is a boot block or not + @retval FALSE This is a boot block. + @retval TRUE This is not a boot block. ---*/ +**/ +BOOLEAN +IsBootBlock ( + EFI_FTW_LITE_DEVICE *FtwLiteDevice, + EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *FvBlock, + EFI_LBA Lba + ) { EFI_STATUS Status; EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *BootFvb; @@ -225,46 +207,40 @@ Returns: return (BOOLEAN) (FvBlock == BootFvb); } +/** + Copy the content of spare block to a boot block. Size is FTW_BLOCK_SIZE. + Spare block is accessed by FTW backup FVB protocol interface. LBA is + FtwLiteDevice->FtwSpareLba. + Boot block is accessed by BootFvb protocol interface. LBA is 0. + + + @param FtwLiteDevice The private data of FTW_LITE driver + + @retval EFI_SUCCESS Spare block content is copied to boot block + @retval EFI_INVALID_PARAMETER Input parameter error + @retval EFI_OUT_OF_RESOURCES Allocate memory error + @retval EFI_ABORTED The function could not complete successfully + Notes: + FTW will do extra work on boot block update. + FTW should depend on a protocol of EFI_ADDRESS_RANGE_SWAP_PROTOCOL, + which is produced by a chipset driver. + FTW updating boot block steps: + 1. Erase top swap block (0xFFFE-0xFFFEFFFF) and write data to it ready + 2. Read data from top swap block to memory buffer + 3. SetSwapState(EFI_SWAPPED) + 4. Erasing boot block (0xFFFF-0xFFFFFFFF) + 5. Programming boot block until the boot block is ok. + 6. SetSwapState(UNSWAPPED) + Notes: + 1. Since the SwapState bit is saved in CMOS, FTW can restore and continue + even in the scenario of power failure. + 2. FTW shall not allow to update boot block when battery state is error. + +**/ EFI_STATUS FlushSpareBlockToBootBlock ( EFI_FTW_LITE_DEVICE *FtwLiteDevice ) -/*++ - -Routine Description: - Copy the content of spare block to a boot block. Size is FTW_BLOCK_SIZE. - Spare block is accessed by FTW backup FVB protocol interface. LBA is - FtwLiteDevice->FtwSpareLba. - Boot block is accessed by BootFvb protocol interface. LBA is 0. - -Arguments: - FtwLiteDevice - The private data of FTW_LITE driver - -Returns: - EFI_SUCCESS - Spare block content is copied to boot block - EFI_INVALID_PARAMETER - Input parameter error - EFI_OUT_OF_RESOURCES - Allocate memory error - EFI_ABORTED - The function could not complete successfully - -Notes: - FTW will do extra work on boot block update. - FTW should depend on a protocol of EFI_ADDRESS_RANGE_SWAP_PROTOCOL, - which is produced by a chipset driver. - - FTW updating boot block steps: - 1. Erase top swap block (0xFFFE-0xFFFEFFFF) and write data to it ready - 2. Read data from top swap block to memory buffer - 3. SetSwapState(EFI_SWAPPED) - 4. Erasing boot block (0xFFFF-0xFFFFFFFF) - 5. Programming boot block until the boot block is ok. - 6. SetSwapState(UNSWAPPED) - - Notes: - 1. Since the SwapState bit is saved in CMOS, FTW can restore and continue - even in the scenario of power failure. - 2. FTW shall not allow to update boot block when battery state is error. - ---*/ { EFI_STATUS Status; UINTN Length; diff --git a/MdeModulePkg/Universal/FirmwareVolume/FaultTolerantWriteDxe/Ipf/IpfFtwMisc.c b/MdeModulePkg/Universal/FirmwareVolume/FaultTolerantWriteDxe/Ipf/IpfFtwMisc.c index 20b7f566b9..e7087c8548 100644 --- a/MdeModulePkg/Universal/FirmwareVolume/FaultTolerantWriteDxe/Ipf/IpfFtwMisc.c +++ b/MdeModulePkg/Universal/FirmwareVolume/FaultTolerantWriteDxe/Ipf/IpfFtwMisc.c @@ -21,83 +21,69 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. // #define BOOT_BLOCK_BASE -STATIC +/** + + Get swap state + This is a internal function. + + @param FtwLiteDevice Calling context + @param SwapState Swap state + + @retval EFI_SUCCESS State successfully got + +**/ EFI_STATUS GetSwapState ( IN EFI_FTW_LITE_DEVICE *FtwLiteDevice, OUT BOOLEAN *SwapState ) -/*++ - -Routine Description: - - Get swap state - -Arguments: +{ + return EFI_SUCCESS; +} - FtwLiteDevice - Calling context - SwapState - Swap state +/** + Set swap state. + This is a internal function. -Returns: - EFI_SUCCESS - State successfully got + @param FtwLiteDevice Indicates a pointer to the calling context. + @param TopSwap New swap state ---*/ -{ - return EFI_SUCCESS; -} + @retval EFI_SUCCESS The function completed successfully + Note: + the Top-Swap bit (bit 13, D31: F0, Offset D4h). Note that + software will not be able to clear the Top-Swap bit until the system is + rebooted without GNT[A]# being pulled down. -STATIC +**/ EFI_STATUS SetSwapState ( IN EFI_FTW_LITE_DEVICE *FtwLiteDevice, IN BOOLEAN TopSwap ) -/*++ +{ + return EFI_SUCCESS; +} -Routine Description: - Set swap state. +/** -Arguments: - FtwLiteDevice - Indicates a pointer to the calling context. - TopSwap - New swap state + Check whether the block is a boot block. -Returns: - EFI_SUCCESS - The function completed successfully -Note: - the Top-Swap bit (bit 13, D31: F0, Offset D4h). Note that - software will not be able to clear the Top-Swap bit until the system is - rebooted without GNT[A]# being pulled down. + @param FtwLiteDevice Calling context + @param FvBlock Fvb protocol instance + @param Lba Lba value ---*/ -{ - return EFI_SUCCESS; -} + @retval FALSE This is a boot block. + @retval TRUE This is not a boot block. +**/ BOOLEAN IsBootBlock ( EFI_FTW_LITE_DEVICE *FtwLiteDevice, EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *FvBlock, EFI_LBA Lba ) -/*++ - -Routine Description: - - Check whether the block is a boot block. - -Arguments: - - FtwLiteDevice - Calling context - FvBlock - Fvb protocol instance - Lba - Lba value - -Returns: - - Is a boot block or not - ---*/ { // // IPF doesn't support safe bootblock update @@ -106,30 +92,26 @@ Returns: return FALSE; } -EFI_STATUS -FlushSpareBlockToBootBlock ( - EFI_FTW_LITE_DEVICE *FtwLiteDevice - ) -/*++ - -Routine Description: - Copy the content of spare block to a boot block. Size is FTW_BLOCK_SIZE. - Spare block is accessed by FTW backup FVB protocol interface. LBA is - FtwLiteDevice->FtwSpareLba. - Boot block is accessed by BootFvb protocol interface. LBA is 0. +/** + Copy the content of spare block to a boot block. Size is FTW_BLOCK_SIZE. + Spare block is accessed by FTW backup FVB protocol interface. LBA is + FtwLiteDevice->FtwSpareLba. + Boot block is accessed by BootFvb protocol interface. LBA is 0. -Arguments: - FtwLiteDevice - The private data of FTW_LITE driver -Returns: - EFI_SUCCESS - Spare block content is copied to boot block - EFI_INVALID_PARAMETER - Input parameter error - EFI_OUT_OF_RESOURCES - Allocate memory error - EFI_ABORTED - The function could not complete successfully + @param FtwLiteDevice The private data of FTW_LITE driver -Notes: + @retval EFI_SUCCESS Spare block content is copied to boot block + @retval EFI_INVALID_PARAMETER Input parameter error + @retval EFI_OUT_OF_RESOURCES Allocate memory error + @retval EFI_ABORTED The function could not complete successfully + Notes: ---*/ +**/ +EFI_STATUS +FlushSpareBlockToBootBlock ( + EFI_FTW_LITE_DEVICE *FtwLiteDevice + ) { return EFI_SUCCESS; } diff --git a/MdeModulePkg/Universal/FirmwareVolume/FaultTolerantWriteDxe/x64/x64FtwMisc.c b/MdeModulePkg/Universal/FirmwareVolume/FaultTolerantWriteDxe/x64/x64FtwMisc.c index b782b2042d..0474d78546 100644 --- a/MdeModulePkg/Universal/FirmwareVolume/FaultTolerantWriteDxe/x64/x64FtwMisc.c +++ b/MdeModulePkg/Universal/FirmwareVolume/FaultTolerantWriteDxe/x64/x64FtwMisc.c @@ -1,4 +1,4 @@ -/** +/** @file X64 platform related code to support FtwLite. @@ -21,111 +21,92 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. // #define BOOT_BLOCK_BASE -// STATIC +/** + + Get swap state. + + + @param FtwLiteDevice Calling context + @param SwapState Swap state + + @retval EFI_SUCCESS State successfully read. + +**/ EFI_STATUS GetSwapState ( IN EFI_FTW_LITE_DEVICE *FtwLiteDevice, OUT BOOLEAN *SwapState ) -/*++ - -Routine Description: - - Get swap state - -Arguments: +{ + return EFI_SUCCESS; +} - FtwLiteDevice - Calling context - SwapState - Swap state +/** + Set swap state. -Returns: - EFI_SUCCESS - State successfully got + @param FtwLiteDevice Indicates a pointer to the calling context. + @param TopSwap New swap state ---*/ -{ - return EFI_SUCCESS; -} + @retval EFI_SUCCESS The function completed successfully + Note: + the Top-Swap bit (bit 13, D31: F0, Offset D4h). Note that + software will not be able to clear the Top-Swap bit until the system is + rebooted without GNT[A]# being pulled down. -// STATIC +**/ EFI_STATUS SetSwapState ( IN EFI_FTW_LITE_DEVICE *FtwLiteDevice, IN BOOLEAN TopSwap ) -/*++ +{ + return EFI_SUCCESS; +} -Routine Description: - Set swap state. +/** -Arguments: - FtwLiteDevice - Indicates a pointer to the calling context. - TopSwap - New swap state + Check whether the block is a boot block. -Returns: - EFI_SUCCESS - The function completed successfully -Note: - the Top-Swap bit (bit 13, D31: F0, Offset D4h). Note that - software will not be able to clear the Top-Swap bit until the system is - rebooted without GNT[A]# being pulled down. + @param FtwLiteDevice Calling context + @param FvBlock Fvb protocol instance + @param Lba Lba value ---*/ -{ - return EFI_SUCCESS; -} + @retval FALSE This is a boot block. + @retval TRUE This is not a boot block. +**/ BOOLEAN IsBootBlock ( EFI_FTW_LITE_DEVICE *FtwLiteDevice, EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *FvBlock, EFI_LBA Lba ) -/*++ - -Routine Description: - - Check whether the block is a boot block. - -Arguments: +{ + return FALSE; +} - FtwLiteDevice - Calling context - FvBlock - Fvb protocol instance - Lba - Lba value +/** + Copy the content of spare block to a boot block. Size is FTW_BLOCK_SIZE. + Spare block is accessed by FTW backup FVB protocol interface. LBA is + FtwLiteDevice->FtwSpareLba. + Boot block is accessed by BootFvb protocol interface. LBA is 0. -Returns: - Is a boot block or not + @param FtwLiteDevice The private data of FTW_LITE driver ---*/ -{ - return FALSE; -} + @retval EFI_SUCCESS Spare block content is copied to boot block + @retval EFI_INVALID_PARAMETER Input parameter error + @retval EFI_OUT_OF_RESOURCES Allocate memory error + @retval EFI_ABORTED The function could not complete successfully + Notes: +**/ EFI_STATUS FlushSpareBlockToBootBlock ( EFI_FTW_LITE_DEVICE *FtwLiteDevice ) -/*++ - -Routine Description: - Copy the content of spare block to a boot block. Size is FTW_BLOCK_SIZE. - Spare block is accessed by FTW backup FVB protocol interface. LBA is - FtwLiteDevice->FtwSpareLba. - Boot block is accessed by BootFvb protocol interface. LBA is 0. - -Arguments: - FtwLiteDevice - The private data of FTW_LITE driver - -Returns: - EFI_SUCCESS - Spare block content is copied to boot block - EFI_INVALID_PARAMETER - Input parameter error - EFI_OUT_OF_RESOURCES - Allocate memory error - EFI_ABORTED - The function could not complete successfully - -Notes: - ---*/ { return EFI_SUCCESS; }