diff options
| author | qwang12 <qwang12@6f19259b-4bc3-4df7-8a09-765794883524> | 2008-07-14 08:19:45 +0000 |
|---|---|---|
| committer | qwang12 <qwang12@6f19259b-4bc3-4df7-8a09-765794883524> | 2008-07-14 08:19:45 +0000 |
| commit | 6aab82140b20fab408f79dd428555b5d03370f72 (patch) | |
| tree | b2ad76f53cd6161b7e018f97fe80f83c303cfa21 | |
| parent | b414ea4b21bf58098fd95f83fe79bb6fbc2e6ea1 (diff) | |
| download | edk2-platforms-6aab82140b20fab408f79dd428555b5d03370f72.tar.xz | |
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
7 files changed, 718 insertions, 902 deletions
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 <FtwLite.h>
-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 <FtwLite.h>
-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;
}
|