//\r
\r
/**\r
- Reads specified number of bytes into a buffer from the specified block\r
-\r
- @param Instance The FV instance to be read from.\r
- @param Lba The logical block address to be read from\r
- @param Offset Offset into the block at which to begin reading\r
- @param NumBytes Pointer that on input contains the total size of\r
- the buffer. On output, it contains the total number\r
- of bytes read\r
- @param Buffer Pointer to a caller allocated buffer that will be\r
- used to hold the data read\r
-\r
- @retval EFI_INVALID_PARAMETER Invalid parameter\r
- @retval EFI_SUCESS Sucess to Read block\r
- @retval Others Fail to read block\r
+ Reads specified number of bytes into a buffer from the specified block.\r
+\r
+ The EfiFvbReadBlock() function reads the requested number of bytes from\r
+ the requested block in the specified firmware volume and stores them in\r
+ the provided buffer. Implementations should be mindful that the firmware\r
+ volume might be in the ReadDisabled state. If it is in this state, the \r
+ EfiFvbReadBlock() function must return the status code EFI_ACCESS_DENIED\r
+ without modifying the contents of the buffer.\r
+ \r
+ The EfiFvbReadBlock() function must also prevent spanning block boundaries.\r
+ If a read is requested that would span a block boundary, the read must read\r
+ up to the boundary but not beyond. The output parameter NumBytes must be\r
+ set to correctly indicate the number of bytes actually read. \r
+ The caller must be aware that a read may be partially completed.\r
+\r
+ If NumBytes is NULL, then ASSERT().\r
+\r
+ If Buffer is NULL, then ASSERT().\r
+\r
+ @param[in] Instance The FV instance to be read from.\r
+ @param[in] Lba The logical block address to be read from\r
+ @param[in] Offset The offset relative to the block, at which to begin reading.\r
+ @param[in, out] NumBytes Pointer to a UINTN. On input, *NumBytes contains the total\r
+ size of the buffer. On output, it contains the actual number\r
+ of bytes read.\r
+ @param[out] Buffer Pointer to a caller allocated buffer that will be\r
+ used to hold the data read.\r
+\r
+ @retval EFI_SUCCESS The firmware volume was read successfully and contents are in Buffer.\r
+ @retval EFI_BAD_BUFFER_SIZE Read attempted across an LBA boundary. On output, NumBytes contains the total number of bytes returned in Buffer.\r
+ @retval EFI_ACCESS_DENIED The firmware volume is in the ReadDisabled state.\r
+ @retval EFI_DEVICE_ERROR The block device is not functioning correctly and could not be read.\r
+ @retval EFI_INVALID_PARAMETER Invalid parameter, Instance is larger than the max FVB number. Lba index is larger than the last block of the firmware volume. Offset is larger than the block size.\r
+\r
**/\r
EFI_STATUS\r
EfiFvbReadBlock (\r
}\r
\r
/**\r
- Writes specified number of bytes from the input buffer to the block\r
-\r
- @param Instance The FV instance to be written to\r
- @param Lba The starting logical block index to write to\r
- @param Offset Offset into the block at which to begin writing\r
- @param NumBytes Pointer that on input contains the total size of\r
- the buffer. On output, it contains the total number\r
- of bytes actually written\r
- @param Buffer Pointer to a caller allocated buffer that contains\r
- the source for the write\r
-\r
- @retval EFI_INVALID_PARAMETER Invalid parameter\r
- @retval EFI_SUCESS Sucess to write block\r
- @retval Others Fail to write block\r
+ Writes specified number of bytes from the input buffer to the block\r
+\r
+ The EfiFvbWriteBlock() function writes the specified number of bytes\r
+ from the provided buffer to the specified block and offset in the \r
+ requested firmware volume. \r
+\r
+ If the firmware volume is sticky write, the caller must ensure that\r
+ all the bits of the specified range to write are in the EFI_FVB_ERASE_POLARITY\r
+ state before calling the EfiFvbWriteBlock() function, or else the \r
+ result will be unpredictable. This unpredictability arises because,\r
+ for a sticky-write firmware volume, a write may negate a bit in the \r
+ EFI_FVB_ERASE_POLARITY state but it cannot flip it back again. In \r
+ general, before calling the EfiFvbWriteBlock() function, the caller\r
+ should call the EfiFvbEraseBlock() function first to erase the specified\r
+ block to write. A block erase cycle will transition bits from the\r
+ (NOT)EFI_FVB_ERASE_POLARITY state back to the EFI_FVB_ERASE_POLARITY state.\r
+ Implementations should be mindful that the firmware volume might be \r
+ in the WriteDisabled state. If it is in this state, the EfiFvbWriteBlock()\r
+ function must return the status code EFI_ACCESS_DENIED without modifying\r
+ the contents of the firmware volume.\r
+ \r
+ The EfiFvbWriteBlock() function must also prevent spanning block boundaries.\r
+ If a write is requested that spans a block boundary, the write must store\r
+ up to the boundary but not beyond. The output parameter NumBytes must be \r
+ set to correctly indicate the number of bytes actually written. The caller\r
+ must be aware that a write may be partially completed.\r
+ All writes, partial or otherwise, must be fully flushed to the hardware \r
+ before the EfiFvbWriteBlock() function returns. \r
+ \r
+ If NumBytes is NULL, then ASSERT().\r
+\r
+ @param Instance The FV instance to be written to\r
+ @param Lba The starting logical block index to write to\r
+ @param Offset The offset relative to the block, at which to begin writting.\r
+ @param NumBytes Pointer to a UINTN. On input, *NumBytes contains\r
+ the total size of the buffer. On output, it contains\r
+ the actual number of bytes written.\r
+ @param Buffer Pointer to a caller allocated buffer that contains\r
+ the source for the write\r
+\r
+ @retval EFI_SUCCESS The firmware volume was written successfully.\r
+ @retval EFI_BAD_BUFFER_SIZE The write was attempted across an LBA boundary. \r
+ On output, NumBytes contains the total number of bytes actually written.\r
+ @retval EFI_ACCESS_DENIED The firmware volume is in the WriteDisabled state.\r
+ @retval EFI_DEVICE_ERROR The block device is malfunctioning and could not be written.\r
+ @retval EFI_INVALID_PARAMETER Invalid parameter, Instance is larger than the max FVB number. \r
+ Lba index is larger than the last block of the firmware volume.\r
+ Offset is larger than the block size.\r
**/\r
EFI_STATUS\r
EfiFvbWriteBlock (\r
}\r
\r
/**\r
- Erases and initializes a firmware volume block\r
+ Erases and initializes a firmware volume block.\r
+\r
+ The EfiFvbEraseBlock() function erases one block specified by Lba.\r
+ Implementations should be mindful that the firmware volume might \r
+ be in the WriteDisabled state. If it is in this state, the EfiFvbEraseBlock()\r
+ function must return the status code EFI_ACCESS_DENIED without \r
+ modifying the contents of the firmware volume. If Instance is \r
+ larger than the max FVB number, or Lba index is larger than the\r
+ last block of the firmware volume, this function return the status\r
+ code EFI_INVALID_PARAMETER.\r
+ \r
+ All calls to EfiFvbEraseBlock() must be fully flushed to the \r
+ hardware before this function returns. \r
\r
- @param Instance The FV instance to be erased\r
- @param Lba The logical block index to be erased\r
+ @param[in] Instance The FV instance to be erased.\r
+ @param[in] Lba The logical block index to be erased from.\r
+ \r
+ @retval EFI_SUCCESS The erase request was successfully completed.\r
+ @retval EFI_ACCESS_DENIED The firmware volume is in the WriteDisabled state.\r
+ @retval EFI_DEVICE_ERROR The block device is not functioning correctly and\r
+ could not be written. The firmware device may \r
+ have been partially erased.\r
+ @retval EFI_INVALID_PARAMETER Invalid parameter. Instance is larger than the max\r
+ FVB number. Lba index is larger than the last block\r
+ of the firmware volume. \r
\r
- @retval EFI_INVALID_PARAMETER Invalid parameter\r
- @retval EFI_SUCESS Sucess to erase block\r
- @retval Others Fail to erase block\r
**/\r
EFI_STATUS\r
EfiFvbEraseBlock (\r
}\r
\r
/**\r
- Retrieves attributes, insures positive polarity of attribute bits, returns\r
- resulting attributes in output parameter\r
+ Retrieves the attributes and current settings of the specified block, \r
+ returns resulting attributes in output parameter.\r
+\r
+ The EfiFvbGetAttributes() function retrieves the attributes and current\r
+ settings of the block specified by Instance. If Instance is larger than\r
+ the max FVB number, this function returns the status code EFI_INVALID_PARAMETER.\r
\r
- @param Instance The FV instance whose attributes is going to be returned\r
- @param Attributes Output buffer which contains attributes\r
+ If Attributes is NULL, then ASSERT().\r
\r
- @retval EFI_INVALID_PARAMETER Invalid parameter\r
- @retval EFI_SUCESS Sucess to get Fv attribute\r
- @retval Others Fail to get Fv attribute\r
+ @param[in] Instance The FV instance to be operated.\r
+ @param[out] Attributes Pointer to EFI_FVB_ATTRIBUTES_2 in which the\r
+ attributes and current settings are returned.\r
+\r
+ @retval EFI_EFI_SUCCESS The firmware volume attributes were returned.\r
+ @retval EFI_INVALID_PARAMETER Invalid parameter. Instance is larger than the max FVB number. \r
**/\r
EFI_STATUS\r
EfiFvbGetVolumeAttributes (\r
}\r
\r
/**\r
- Modifies the current settings of the firmware volume according to the\r
- input parameter, and returns the new setting of the volume\r
-\r
- @param Instance The FV instance whose attributes is going to be\r
- modified\r
- @param Attributes On input, it is a pointer to EFI_FVB_ATTRIBUTES_2\r
- containing the desired firmware volume settings.\r
- On successful return, it contains the new settings\r
- of the firmware volume\r
-\r
- @retval EFI_INVALID_PARAMETER Invalid parameter\r
- @retval EFI_SUCESS Sucess to set Fv attribute\r
- @retval Others Fail to set Fv attribute\r
+ Modify the attributes and current settings of the specified block\r
+ according to the input parameter.\r
+\r
+ The EfiFvbSetAttributes() function sets configurable firmware volume\r
+ attributes and returns the new settings of the firmware volume specified\r
+ by Instance. If Instance is larger than the max FVB number, this function\r
+ returns the status code EFI_INVALID_PARAMETER.\r
+\r
+ If Attributes is NULL, then ASSERT().\r
+\r
+ @param[in] Instance The FV instance to be operated.\r
+ @param[in, out]Attributes On input, Attributes is a pointer to EFI_FVB_ATTRIBUTES_2\r
+ that contains the desired firmware volume settings. \r
+ On successful return, it contains the new settings of the firmware volume.\r
+\r
+ @retval EFI_EFI_SUCCESS The firmware volume attributes were modified successfully.\r
+ @retval EFI_INVALID_PARAMETER Invalid parameter. Instance is larger than the max FVB number.\r
+\r
**/\r
EFI_STATUS\r
EfiFvbSetVolumeAttributes (\r
}\r
\r
/**\r
- Retrieves the physical address of a memory mapped FV\r
+ Retrieves the physical address of the specified memory mapped FV.\r
\r
- @param Instance The FV instance whose base address is going to be\r
- returned\r
- @param BaseAddress Pointer to a caller allocated EFI_PHYSICAL_ADDRESS\r
- that on successful return, contains the base address\r
- of the firmware volume.\r
+ Retrieve the base address of a memory-mapped firmware volume specified by Instance.\r
+ If Instance is larger than the max FVB number, this function returns the status \r
+ code EFI_INVALID_PARAMETER.\r
+ \r
+ If BaseAddress is NULL, then ASSERT().\r
+\r
+ @param[in] Instance The FV instance to be operated.\r
+ @param[out] BaseAddress Pointer to a caller allocated EFI_PHYSICAL_ADDRESS \r
+ that on successful return, contains the base address\r
+ of the firmware volume. \r
+\r
+ @retval EFI_EFI_SUCCESS The firmware volume base address is returned.\r
+ @retval EFI_INVALID_PARAMETER Invalid parameter. Instance is larger than the max FVB number. \r
\r
- @retval EFI_INVALID_PARAMETER Invalid parameter\r
- @retval EFI_SUCESS Sucess to get physical address\r
- @retval Others Fail to get physical address\r
**/\r
EFI_STATUS\r
EfiFvbGetPhysicalAddress (\r
}\r
\r
/**\r
- Retrieve the size of a logical block\r
-\r
- @param Instance The FV instance whose block size is going to be\r
- returned\r
- @param Lba Indicates which block to return the size for.\r
- @param BlockSize A pointer to a caller allocated UINTN in which\r
- the size of the block is returned\r
- @param NumOfBlocks a pointer to a caller allocated UINTN in which the\r
- number of consecutive blocks starting with Lba is\r
- returned. All blocks in this range have a size of\r
- BlockSize\r
-\r
- @retval EFI_INVALID_PARAMETER Invalid parameter\r
- @retval EFI_SUCESS Sucess to get block size\r
- @retval Others Fail to get block size\r
+ Retrieve the block size of the specified fv.\r
+ \r
+ The EfiFvbGetBlockSize() function retrieves the size of the requested block. \r
+ It also returns the number of additional blocks with the identical size. \r
+ If Instance is larger than the max FVB number, or Lba index is larger than\r
+ the last block of the firmware volume, this function return the status code\r
+ EFI_INVALID_PARAMETER.\r
+\r
+ If BlockSize is NULL, then ASSERT().\r
+ \r
+ If NumOfBlocks is NULL, then ASSERT().\r
+\r
+ @param[in] Instance The FV instance to be operated.\r
+ @param[in] Lba Indicates which block to return the size for.\r
+ @param[out] BlockSize Pointer to a caller-allocated UINTN in which the\r
+ size of the block is returned.\r
+ @param[out] NumOfBlocks Pointer to a caller-allocated UINTN in which the \r
+ number of consecutive blocks, starting with Lba, \r
+ is returned. All blocks in this range have a size of BlockSize.\r
+\r
+ @retval EFI_EFI_SUCCESS The firmware volume base address is returned.\r
+ @retval EFI_INVALID_PARAMETER Invalid parameter. Instance is larger than the max FVB number.\r
+ Lba index is larger than the last block of the firmware volume.\r
+\r
**/\r
EFI_STATUS\r
EfiFvbGetBlockSize (\r
}\r
\r
/**\r
- Erases and initializes a specified range of a firmware volume\r
-\r
- @param Instance The FV instance to be erased\r
- @param StartLba The starting logical block index to be erased\r
- @param OffsetStartLba Offset into the starting block at which to\r
- begin erasing\r
- @param LastLba The last logical block index to be erased\r
- @param OffsetLastLba Offset into the last block at which to end erasing\r
-\r
- @retval EFI_INVALID_PARAMETER Invalid parameter\r
- @retval EFI_SUCESS Sucess to erase custom block range\r
- @retval Others Fail to erase custom block range\r
+ Erases and initializes a specified range of a firmware volume.\r
+\r
+ The EfiFvbEraseCustomBlockRange() function erases the specified range in the firmware\r
+ volume index by Instance. If Instance is larger than the max FVB number, StartLba or \r
+ LastLba index is larger than the last block of the firmware volume, StartLba > LastLba\r
+ or StartLba equal to LastLba but OffsetStartLba > OffsetLastLba, this function return \r
+ the status code EFI_INVALID_PARAMETER.\r
+\r
+ @param[in] Instance The FV instance to be operated.\r
+ @param[in] StartLba The starting logical block index to be erased.\r
+ @param[in] OffsetStartLba Offset into the starting block at which to \r
+ begin erasing. \r
+ @param[in] LastLba The last logical block index to be erased.\r
+ @param[in] OffsetLastLba Offset into the last block at which to end erasing. \r
+\r
+ @retval EFI_EFI_SUCCESS Successfully erase custom block range\r
+ @retval EFI_INVALID_PARAMETER Invalid parameter. Instance is larger than the max FVB number. \r
+ @retval EFI_UNSUPPORTED Firmware volume block device has no this capability.\r
+\r
**/\r
EFI_STATUS\r
EfiFvbEraseCustomBlockRange (\r
projects / mirror_edk2.git / blobdiff