[mirror_edk2.git] / MdePkg / Include / Protocol / FirmwareVolumeBlock.h

/** @file\r
  This file provides control over block-oriented firmware devices.\r
\r
  Copyright (c) 2006 - 2007, Intel Corporation                                                         \r
  All rights reserved. This program and the accompanying materials                          \r
  are licensed and made available under the terms and conditions of the BSD License         \r
  which accompanies this distribution.  The full text of the license may be found at        \r
  http://opensource.org/licenses/bsd-license.php                                            \r
\r
  THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,                     \r
  WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.             \r
\r
  @par Revision Reference: PI\r
  Version 1.00.\r
\r
**/\r
\r
#ifndef __FIRMWARE_VOLUME_BLOCK_H__\r
#define __FIRMWARE_VOLUME_BLOCK_H__\r
\r
\r
#define EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL_GUID \\r
  { 0xDE28BC59, 0x6228, 0x41BD, {0xBD, 0xF6, 0xA3, 0xB9, 0xAD,0xB5, 0x8D, 0xA1 } }\r
\r
\r
typedef struct _EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL;\r
\r
/**\r
  The GetAttributes() function retrieves the attributes and\r
  current settings of the block. Status Codes Returned\r
\r
  @param This   Indicates the EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL\r
                instance.\r
\r
  @param Attributes Pointer to EFI_FVB_ATTRIBUTES in which the\r
                    attributes and current settings are\r
                    returned. Type EFI_FVB_ATTRIBUTES is defined\r
                    in EFI_FIRMWARE_VOLUME_HEADER.\r
\r
  @retval EFI_SUCCESS The firmware volume attributes were\r
                      returned.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI * EFI_FVB_GET_ATTRIBUTES) (\r
  IN CONST  EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL  *This,\r
  OUT       EFI_FVB_ATTRIBUTES                  *Attributes\r
);\r
\r
\r
/**\r
  The SetAttributes() function sets configurable firmware volume\r
  attributes and returns the new settings of the firmware volume.\r
\r
  @param This   Indicates the EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL\r
                instance.\r
\r
  @param Attributes   On input, Attributes is a pointer to\r
                      EFI_FVB_ATTRIBUTES that contains the\r
                      desired firmware volume settings. On\r
                      successful return, it contains the new\r
                      settings of the firmware volume. Type\r
                      EFI_FVB_ATTRIBUTES is defined in\r
                      EFI_FIRMWARE_VOLUME_HEADER.\r
\r
  \r
  @retval EFI_SUCCESS The firmware volume attributes were\r
                      returned.\r
\r
  @retval EFI_INVALID_PARAMETER The attributes requested are in\r
                                conflict with the capabilities\r
                                as declared in the firmware\r
                                volume header.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI * EFI_FVB_SET_ATTRIBUTES) (\r
  IN CONST  EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL  *This,\r
  IN OUT    EFI_FVB_ATTRIBUTES                  *Attributes\r
);\r
\r
\r
/**\r
  The GetPhysicalAddress() function retrieves the base address of\r
  a memory-mapped firmware volume. This function should be called\r
  only for memory-mapped firmware volumes.\r
\r
  @param This   Indicates the EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL\r
                nstance.\r
  \r
  @param Address  Pointer to a caller-allocated\r
                  EFI_PHYSICAL_ADDRESS that, on successful\r
                  return from GetPhysicalAddress(), contains the\r
                  base address of the firmware volume. Type\r
                  EFI_PHYSICAL_ADDRESS is defined in\r
                  AllocatePages() in the UEFI 2.0 specification.\r
  \r
  @retval EFI_SUCCESS The firmware volume base address is\r
                      returned.\r
  \r
  @retval EFI_NOT_SUPPORTED The firmware volume is not memory\r
                            mapped.\r
\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI * EFI_FVB_GET_PHYSICAL_ADDRESS) (\r
  IN CONST  EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL  *This,\r
  OUT       EFI_PHYSICAL_ADDRESS                *Address\r
);\r
\r
/**\r
  The GetBlockSize() function retrieves the size of the requested\r
  block. It also returns the number of additional blocks with\r
  the identical size. The GetBlockSize() function is used to\r
  retrieve the block map (see EFI_FIRMWARE_VOLUME_HEADER).\r
\r
\r
  @param This   Indicates the EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL\r
                instance.\r
\r
  @param Lba  Indicates the block for which to return the size.\r
              Type EFI_LBA is defined in the BLOCK_IO Protocol\r
              (section 11.6) in the UEFI 2.0 specification.\r
\r
  @param BlockSize  Pointer to a caller-allocated UINTN in which\r
                    the size of the block is returned.\r
\r
  @param NumberOfBlocks Pointer to a caller-allocated UINTN in\r
                        which the number of consecutive blocks,\r
                        starting with Lba, is returned. All\r
                        blocks in this range have a size of\r
                        BlockSize.\r
\r
  \r
  @retval EFI_SUCCESS The firmware volume base address is\r
                      returned.\r
  \r
  @retval EFI_INVALID_PARAMETER   The requested LBA is out of\r
                                  range.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI * EFI_FVB_GET_BLOCK_SIZE) (\r
  IN CONST  EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL  *This,\r
  IN        EFI_LBA                             Lba,\r
  OUT       UINTN                               *BlockSize,\r
  OUT       UINTN                               *NumberOfBlocks\r
);\r
\r
\r
/**\r
  The Read() function reads the requested number of bytes from the\r
  requested block and stores them in the provided buffer.\r
  Implementations should be mindful that the firmware volume\r
  might be in the ReadDisabled state. If it is in this state,\r
  the Read() function must return the status code\r
  EFI_ACCESS_DENIED without modifying the contents of the\r
  buffer. The Read() function must also prevent spanning block\r
  boundaries. If a read is requested that would span a block\r
  boundary, the read must read up to the boundary but not\r
  beyond. The output parameter NumBytes must be set to correctly\r
  indicate the number of bytes actually read. The caller must be\r
  aware that a read may be partially completed.\r
\r
  @param This Indicates the EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL\r
              instance. Lba The starting logical block index\r
              from which to read. Type EFI_LBA is defined in the\r
              BLOCK_IO Protocol (section 11.6) in the UEFI 2.0\r
              specification.\r
\r
  @param Offset Offset into the block at which to begin reading.\r
\r
  @param NumBytes Pointer to a UINTN. At entry, *NumBytes\r
                  contains the total size of the buffer. At\r
                  exit, *NumBytes contains the total number of\r
                  bytes read.\r
\r
  @param Buffer   Pointer to a caller-allocated buffer that will\r
                  be used to hold the data that is read.\r
\r
  @retval EFI_SUCCESS The firmware volume was read successfully\r
                      and contents are in Buffer.\r
  \r
  @retval EFI_BAD_BUFFER_SIZE Read attempted across an LBA\r
                              boundary. On output, NumBytes\r
                              contains the total number of bytes\r
                              returned in Buffer.\r
  \r
  @retval EFI_ACCESS_DENIED   The firmware volume is in the\r
                              ReadDisabled state.\r
  \r
  @retval EFI_DEVICE_ERROR    The block device is not\r
                              functioning correctly and could\r
                              not be read.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_FVB_READ) (\r
  IN CONST  EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL  *This,\r
  IN        EFI_LBA                             Lba,\r
  IN        UINTN                               Offset,\r
  IN OUT    UINTN                               *NumBytes,\r
  IN OUT    UINT8                               *Buffer\r
);\r
\r
\r
\r
/**\r
  The Write() function writes the specified number of bytes from\r
  the provided buffer to the specified block and offset. If the\r
  firmware volume is sticky write, the caller must ensure that\r
  all the bits of the specified range to write are in the\r
  EFI_FVB_ERASE_POLARITY state before calling the Write()\r
  function, or else the result will be unpredictable. This\r
  unpredictability arises because, for a sticky-write firmware\r
  volume, a write may negate a bit in the EFI_FVB_ERASE_POLARITY\r
  state but it cannot flip it back again. In general, before\r
  calling the Write() function, the caller should call the\r
  EraseBlocks() function first to erase the specified block to\r
  write. A block erase cycle will transition bits from the\r
  (NOT)EFI_FVB_ERASE_POLARITY state back to the\r
  EFI_FVB_ERASE_POLARITY state. Implementations should be\r
  mindful that the firmware volume might be in the WriteDisabled\r
  state. If it is in this state, the Write() function must\r
  return the status code EFI_ACCESS_DENIED without modifying the\r
  contents of the firmware volume. The Write() function must\r
  also prevent spanning block boundaries. If a write is\r
  requested that spans a block boundary, the write must store up\r
  to the boundary but not beyond. The output parameter NumBytes\r
  must be set to correctly indicate the number of bytes actually\r
  written. The caller must be aware that a write may be\r
  partially completed. All writes, partial or otherwise, must be\r
  fully flushed to the hardware before the Write() service\r
  returns.\r
\r
  @param This Indicates the EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL\r
              instance.\r
  \r
  @param Lba  The starting logical block index to write to. Type\r
              EFI_LBA is defined in the BLOCK_IO Protocol\r
              (section 11.6) in the UEFI 2.0 specification.\r
              Offset Offset into the block at which to begin\r
              writing.\r
  \r
  @param NumBytes Pointer to a UINTN. At entry, *NumBytes\r
                  contains the total size of the buffer. At\r
                  exit, *NumBytes contains the total number of\r
                  bytes actually written.\r
  \r
  @param Buffer Pointer to a caller-allocated buffer that\r
                contains the source for the write.\r
  \r
  @retval EFI_SUCCESS The firmware volume was written\r
                      successfully.\r
  \r
  @retval EFI_BAD_BUFFER_SIZE The write was attempted across an\r
                              LBA boundary. On output, NumBytes\r
                              contains the total number of bytes\r
                              actually written.\r
  \r
  @retval EFI_ACCESS_DENIED   The firmware volume is in the\r
                              WriteDisabled state.\r
  \r
  @retval EFI_DEVICE_ERROR    The block device is malfunctioning\r
                              and could not be written.\r
\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI * EFI_FVB_WRITE) (\r
  IN CONST  EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL  *This,\r
  IN        EFI_LBA                             Lba,\r
  IN        UINTN                               Offset,\r
  IN OUT    UINTN                               *NumBytes,\r
  IN        UINT8                               *Buffer\r
);\r
\r
\r
\r
\r
//\r
// EFI_LBA_LIST_TERMINATOR\r
//\r
#define EFI_LBA_LIST_TERMINATOR   0xFFFFFFFFFFFFFFFFULL\r
\r
\r
/**\r
  The EraseBlocks() function erases one or more blocks as denoted\r
  by the variable argument list. The entire parameter list of\r
  blocks must be verified before erasing any blocks. If a block is\r
  requested that does not exist within the associated firmware\r
  volume (it has a larger index than the last block of the\r
  firmware volume), the EraseBlocks() function must return the\r
  status code EFI_INVALID_PARAMETER without modifying the contents\r
  of the firmware volume. Implementations should be mindful that\r
  the firmware volume might be in the WriteDisabled state. If it\r
  is in this state, the EraseBlocks() function must return the\r
  status code EFI_ACCESS_DENIED without modifying the contents of\r
  the firmware volume. All calls to EraseBlocks() must be fully\r
  flushed to the hardware before the EraseBlocks() service\r
  returns.\r
\r
  @param This   Indicates the EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL\r
                instance.\r
\r
  @param ...    The variable argument list is a list of tuples.\r
                Each tuple describes a range of LBAs to erase\r
                and consists of the following:\r
                - An EFI_LBA that indicates the starting LBA\r
                - A UINTN that indicates the number of blocks to\r
                  erase\r
\r
                The list is terminated with an\r
                EFI_LBA_LIST_TERMINATOR. For example, the\r
                following indicates that two ranges of blocks\r
                (5-7 and 10-11) are to be erased: EraseBlocks\r
                (This, 5, 3, 10, 2, EFI_LBA_LIST_TERMINATOR);\r
\r
  @retval EFI_SUCCESS The erase request was successfully\r
                      completed.\r
  \r
  @retval EFI_ACCESS_DENIED   The firmware volume is in the\r
                              WriteDisabled state.\r
  @retval EFI_DEVICE_ERROR  The block device is not functioning\r
                            correctly and could not be written.\r
                            The firmware device may have been\r
                            partially erased.\r
  @retval EFI_INVALID_PARAMETER One or more of the LBAs listed\r
                                in the variable argument list do\r
                                not exist in the firmware volume.  \r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI * EFI_FVB_ERASE_BLOCKS) (\r
  IN CONST  EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL  *This,\r
  ...\r
);\r
\r
\r
\r
/**\r
  The Firmware Volume Block Protocol is the low-level interface\r
  to a firmware volume. File-level access to a firmware volume\r
  should not be done using the Firmware Volume Block Protocol.\r
  Normal access to a firmware volume must use the Firmware\r
  Volume Protocol. Typically, only the file system driver that\r
  produces the Firmware Volume Protocol will bind to the\r
  Firmware Volume Block Protocol. The Firmware Volume Block\r
  Protocol provides the following:\r
  - Byte-level read/write functionality.\r
  - Block-level erase functionality.\r
  - It further exposes device-hardening features, such as may be\r
    equired to protect the firmware from unwanted overwriting\r
    and/or erasure.\r
  - It is useful to layer a file system driver on top of the\r
    Firmware Volume Block Protocol.\r
\r
  This file system driver produces the Firmware Volume Protocol,\r
  which provides file-level access to a firmware volume. The\r
  Firmware Volume Protocol abstracts the file system that is\r
  used to format the firmware volume and the hardware\r
  device-hardening features that may be present.\r
\r
\r
  @param GetPhysicalAddress   Retrieves the memory-mapped\r
                              address of the firmware volume.\r
                              See the GetPhysicalAddress()\r
                              function description. \r
\r
  @param GetBlockSize   Retrieves the size for a specific block.\r
                        Also returns the number of consecutive\r
                        similarly sized blocks. See the\r
                        GetBlockSize() function description.\r
\r
  @param Read   Reads n bytes into a buffer from the firmware\r
                volume hardware. See the Read() function\r
                description.\r
\r
  @param Write  Writes n bytes from a buffer into the firmware\r
                volume hardware. See the Write() function\r
                description.\r
\r
  @param EraseBlocks  Erases specified block(s) and sets all\r
                      values as indicated by the\r
                      EFI_FVB_ERASE_POLARITY bit. See the\r
                      EraseBlocks() function description. Type\r
                      EFI_FVB_ERASE_POLARITY is defined in\r
                      EFI_FIRMWARE_VOLUME_HEADER. ParentHandle\r
                      Handle of the parent firmware volume. Type\r
                      EFI_HANDLE is defined in\r
                      InstallProtocolInterface() in the UEFI 2.0\r
                      specification.\r
  \r
  @param GetAttributes Retrieves the current volume attributes.\r
                       See the GetAttributes() function\r
                       description.\r
  \r
  @param SetAttributes Sets the current volume attributes. See\r
                       the SetAttributes() function description.\r
  \r
\r
**/\r
struct _EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL {\r
  EFI_FVB_GET_ATTRIBUTES        GetAttributes;\r
  EFI_FVB_SET_ATTRIBUTES        SetAttributes;\r
  EFI_FVB_GET_PHYSICAL_ADDRESS  GetPhysicalAddress;\r
  EFI_FVB_GET_BLOCK_SIZE        GetBlockSize;\r
  EFI_FVB_READ                  Read;\r
  EFI_FVB_WRITE                 Write;\r
  EFI_FVB_ERASE_BLOCKS          EraseBlocks;\r
  EFI_HANDLE                    ParentHandle;\r
};\r
\r
\r
extern EFI_GUID gEfiFirmwareVolumeBlockProtocolGuid;\r
\r
\r
#endif\r
Commit	Line	Data
d1f95000	1	/** @file\r
	2	This file provides control over block-oriented firmware devices.\r
	3	\r
	4	Copyright (c) 2006 - 2007, Intel Corporation \r
	5	All rights reserved. This program and the accompanying materials \r
	6	are licensed and made available under the terms and conditions of the BSD License \r
	7	which accompanies this distribution. The full text of the license may be found at \r
	8	http://opensource.org/licenses/bsd-license.php \r
	9	\r
	10	THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, \r
	11	WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. \r
	12	\r
d1f95000	13	@par Revision Reference: PI\r
	14	Version 1.00.\r
	15	\r
	16	**/\r
	17	\r
	18	#ifndef __FIRMWARE_VOLUME_BLOCK_H__\r
	19	#define __FIRMWARE_VOLUME_BLOCK_H__\r
	20	\r
	21	\r
	22	#define EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL_GUID \\r
e26ac2b5	23	{ 0xDE28BC59, 0x6228, 0x41BD, {0xBD, 0xF6, 0xA3, 0xB9, 0xAD,0xB5, 0x8D, 0xA1 } }\r
d1f95000	24	\r
	25	\r
	26	typedef struct _EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL;\r
	27	\r
	28	/**\r
	29	The GetAttributes() function retrieves the attributes and\r
	30	current settings of the block. Status Codes Returned\r
	31	\r
	32	@param This Indicates the EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL\r
	33	instance.\r
	34	\r
	35	@param Attributes Pointer to EFI_FVB_ATTRIBUTES in which the\r
	36	attributes and current settings are\r
	37	returned. Type EFI_FVB_ATTRIBUTES is defined\r
	38	in EFI_FIRMWARE_VOLUME_HEADER.\r
	39	\r
	40	@retval EFI_SUCCESS The firmware volume attributes were\r
	41	returned.\r
	42	\r
	43	**/\r
	44	typedef\r
	45	EFI_STATUS\r
	46	(EFIAPI * EFI_FVB_GET_ATTRIBUTES) (\r
	47	IN CONST EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *This,\r
	48	OUT EFI_FVB_ATTRIBUTES *Attributes\r
	49	);\r
	50	\r
	51	\r
	52	/**\r
	53	The SetAttributes() function sets configurable firmware volume\r
	54	attributes and returns the new settings of the firmware volume.\r
	55	\r
	56	@param This Indicates the EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL\r
	57	instance.\r
	58	\r
	59	@param Attributes On input, Attributes is a pointer to\r
	60	EFI_FVB_ATTRIBUTES that contains the\r
	61	desired firmware volume settings. On\r
	62	successful return, it contains the new\r
	63	settings of the firmware volume. Type\r
	64	EFI_FVB_ATTRIBUTES is defined in\r
	65	EFI_FIRMWARE_VOLUME_HEADER.\r
	66	\r
	67	\r
	68	@retval EFI_SUCCESS The firmware volume attributes were\r
	69	returned.\r
	70	\r
	71	@retval EFI_INVALID_PARAMETER The attributes requested are in\r
	72	conflict with the capabilities\r
	73	as declared in the firmware\r
	74	volume header.\r
	75	\r
	76	**/\r
	77	typedef\r
	78	EFI_STATUS\r
	79	(EFIAPI * EFI_FVB_SET_ATTRIBUTES) (\r
	80	IN CONST EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *This,\r
	81	IN OUT EFI_FVB_ATTRIBUTES *Attributes\r
	82	);\r
	83	\r
	84	\r
	85	/**\r
	86	The GetPhysicalAddress() function retrieves the base address of\r
	87	a memory-mapped firmware volume. This function should be called\r
88	only for memory-mapped firmware volumes.\r
89	\r
90	@param This Indicates the EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL\r
91	nstance.\r
92	\r
93	@param Address Pointer to a caller-allocated\r
94	EFI_PHYSICAL_ADDRESS that, on successful\r
95	return from GetPhysicalAddress(), contains the\r
96	base address of the firmware volume. Type\r
97	EFI_PHYSICAL_ADDRESS is defined in\r
98	AllocatePages() in the UEFI 2.0 specification.\r
99	\r
100	@retval EFI_SUCCESS The firmware volume base address is\r
101	returned.\r
102	\r
103	@retval EFI_NOT_SUPPORTED The firmware volume is not memory\r
104	mapped.\r
105	\r
106	\r
107	**/\r
108	typedef\r
109	EFI_STATUS\r
110	(EFIAPI * EFI_FVB_GET_PHYSICAL_ADDRESS) (\r
111	IN CONST EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *This,\r
112	OUT EFI_PHYSICAL_ADDRESS *Address\r
113	);\r
114	\r
115	/**\r
116	The GetBlockSize() function retrieves the size of the requested\r
117	block. It also returns the number of additional blocks with\r
118	the identical size. The GetBlockSize() function is used to\r
119	retrieve the block map (see EFI_FIRMWARE_VOLUME_HEADER).\r
120	\r
121	\r
122	@param This Indicates the EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL\r
123	instance.\r
124	\r
125	@param Lba Indicates the block for which to return the size.\r
126	Type EFI_LBA is defined in the BLOCK_IO Protocol\r
127	(section 11.6) in the UEFI 2.0 specification.\r
128	\r
129	@param BlockSize Pointer to a caller-allocated UINTN in which\r
130	the size of the block is returned.\r
131	\r
132	@param NumberOfBlocks Pointer to a caller-allocated UINTN in\r
133	which the number of consecutive blocks,\r
134	starting with Lba, is returned. All\r
135	blocks in this range have a size of\r
136	BlockSize.\r
137	\r
138	\r
139	@retval EFI_SUCCESS The firmware volume base address is\r
140	returned.\r
141	\r
142	@retval EFI_INVALID_PARAMETER The requested LBA is out of\r
143	range.\r
144	\r
145	**/\r
146	typedef\r
147	EFI_STATUS\r
148	(EFIAPI * EFI_FVB_GET_BLOCK_SIZE) (\r
149	IN CONST EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *This,\r
de339b9d	150	IN EFI_LBA Lba,\r
d1f95000	151	OUT UINTN *BlockSize,\r
	152	OUT UINTN *NumberOfBlocks\r
	153	);\r
	154	\r
	155	\r
	156	/**\r
	157	The Read() function reads the requested number of bytes from the\r
	158	requested block and stores them in the provided buffer.\r
	159	Implementations should be mindful that the firmware volume\r
	160	might be in the ReadDisabled state. If it is in this state,\r
	161	the Read() function must return the status code\r
	162	EFI_ACCESS_DENIED without modifying the contents of the\r
	163	buffer. The Read() function must also prevent spanning block\r
	164	boundaries. If a read is requested that would span a block\r
	165	boundary, the read must read up to the boundary but not\r
	166	beyond. The output parameter NumBytes must be set to correctly\r
	167	indicate the number of bytes actually read. The caller must be\r
	168	aware that a read may be partially completed.\r
	169	\r
	170	@param This Indicates the EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL\r
	171	instance. Lba The starting logical block index\r
	172	from which to read. Type EFI_LBA is defined in the\r
	173	BLOCK_IO Protocol (section 11.6) in the UEFI 2.0\r
	174	specification.\r
	175	\r
	176	@param Offset Offset into the block at which to begin reading.\r
	177	\r
	178	@param NumBytes Pointer to a UINTN. At entry, *NumBytes\r
	179	contains the total size of the buffer. At\r
	180	exit, *NumBytes contains the total number of\r
	181	bytes read.\r
	182	\r
	183	@param Buffer Pointer to a caller-allocated buffer that will\r
	184	be used to hold the data that is read.\r
	185	\r
	186	@retval EFI_SUCCESS The firmware volume was read successfully\r
	187	and contents are in Buffer.\r
	188	\r
	189	@retval EFI_BAD_BUFFER_SIZE Read attempted across an LBA\r
	190	boundary. On output, NumBytes\r
	191	contains the total number of bytes\r
	192	returned in Buffer.\r
	193	\r
	194	@retval EFI_ACCESS_DENIED The firmware volume is in the\r
	195	ReadDisabled state.\r
	196	\r
	197	@retval EFI_DEVICE_ERROR The block device is not\r
	198	functioning correctly and could\r
	199	not be read.\r
	200	\r
	201	**/\r
	202	typedef\r
	203	EFI_STATUS\r
	204	(EFIAPI *EFI_FVB_READ) (\r
	205	IN CONST EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *This,\r
de339b9d	206	IN EFI_LBA Lba,\r
de339b9d	207	IN UINTN Offset,\r
d1f95000	208	IN OUT UINTN *NumBytes,\r
96219b7d	209	IN OUT UINT8 *Buffer\r
d1f95000	210	);\r
	211	\r
	212	\r
	213	\r
	214	/**\r
	215	The Write() function writes the specified number of bytes from\r
	216	the provided buffer to the specified block and offset. If the\r
	217	firmware volume is sticky write, the caller must ensure that\r
	218	all the bits of the specified range to write are in the\r
	219	EFI_FVB_ERASE_POLARITY state before calling the Write()\r
	220	function, or else the result will be unpredictable. This\r
	221	unpredictability arises because, for a sticky-write firmware\r
	222	volume, a write may negate a bit in the EFI_FVB_ERASE_POLARITY\r
	223	state but it cannot flip it back again. In general, before\r
	224	calling the Write() function, the caller should call the\r
	225	EraseBlocks() function first to erase the specified block to\r
	226	write. A block erase cycle will transition bits from the\r
	227	(NOT)EFI_FVB_ERASE_POLARITY state back to the\r
	228	EFI_FVB_ERASE_POLARITY state. Implementations should be\r
	229	mindful that the firmware volume might be in the WriteDisabled\r
	230	state. If it is in this state, the Write() function must\r
	231	return the status code EFI_ACCESS_DENIED without modifying the\r
	232	contents of the firmware volume. The Write() function must\r
	233	also prevent spanning block boundaries. If a write is\r
	234	requested that spans a block boundary, the write must store up\r
	235	to the boundary but not beyond. The output parameter NumBytes\r
	236	must be set to correctly indicate the number of bytes actually\r
	237	written. The caller must be aware that a write may be\r
	238	partially completed. All writes, partial or otherwise, must be\r
	239	fully flushed to the hardware before the Write() service\r
	240	returns.\r
	241	\r
	242	@param This Indicates the EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL\r
	243	instance.\r
	244	\r
	245	@param Lba The starting logical block index to write to. Type\r
	246	EFI_LBA is defined in the BLOCK_IO Protocol\r
	247	(section 11.6) in the UEFI 2.0 specification.\r
	248	Offset Offset into the block at which to begin\r
	249	writing.\r
	250	\r
	251	@param NumBytes Pointer to a UINTN. At entry, *NumBytes\r
	252	contains the total size of the buffer. At\r
	253	exit, *NumBytes contains the total number of\r
	254	bytes actually written.\r
	255	\r
	256	@param Buffer Pointer to a caller-allocated buffer that\r
	257	contains the source for the write.\r
	258	\r
	259	@retval EFI_SUCCESS The firmware volume was written\r
	260	successfully.\r
	261	\r
	262	@retval EFI_BAD_BUFFER_SIZE The write was attempted across an\r
	263	LBA boundary. On output, NumBytes\r
	264	contains the total number of bytes\r
	265	actually written.\r
	266	\r
	267	@retval EFI_ACCESS_DENIED The firmware volume is in the\r
	268	WriteDisabled state.\r
	269	\r
	270	@retval EFI_DEVICE_ERROR The block device is malfunctioning\r
	271	and could not be written.\r
	272	\r
	273	\r
274	**/\r
275	typedef\r
276	EFI_STATUS\r
277	(EFIAPI * EFI_FVB_WRITE) (\r
278	IN CONST EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *This,\r
de339b9d	279	IN EFI_LBA Lba,\r
de339b9d	280	IN UINTN Offset,\r
d1f95000	281	IN OUT UINTN *NumBytes,\r
85c528bd	282	IN UINT8 *Buffer\r
d1f95000	283	);\r
	284	\r
	285	\r
	286	\r
	287	\r
	288	//\r
	289	// EFI_LBA_LIST_TERMINATOR\r
	290	//\r
	291	#define EFI_LBA_LIST_TERMINATOR 0xFFFFFFFFFFFFFFFFULL\r
	292	\r
	293	\r
	294	/**\r
	295	The EraseBlocks() function erases one or more blocks as denoted\r
	296	by the variable argument list. The entire parameter list of\r
	297	blocks must be verified before erasing any blocks. If a block is\r
	298	requested that does not exist within the associated firmware\r
	299	volume (it has a larger index than the last block of the\r
	300	firmware volume), the EraseBlocks() function must return the\r
	301	status code EFI_INVALID_PARAMETER without modifying the contents\r
	302	of the firmware volume. Implementations should be mindful that\r
	303	the firmware volume might be in the WriteDisabled state. If it\r
	304	is in this state, the EraseBlocks() function must return the\r
	305	status code EFI_ACCESS_DENIED without modifying the contents of\r
	306	the firmware volume. All calls to EraseBlocks() must be fully\r
	307	flushed to the hardware before the EraseBlocks() service\r
	308	returns.\r
	309	\r
	310	@param This Indicates the EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL\r
	311	instance.\r
	312	\r
	313	@param ... The variable argument list is a list of tuples.\r
	314	Each tuple describes a range of LBAs to erase\r
	315	and consists of the following:\r
	316	- An EFI_LBA that indicates the starting LBA\r
	317	- A UINTN that indicates the number of blocks to\r
	318	erase\r
	319	\r
	320	The list is terminated with an\r
	321	EFI_LBA_LIST_TERMINATOR. For example, the\r
	322	following indicates that two ranges of blocks\r
	323	(5-7 and 10-11) are to be erased: EraseBlocks\r
	324	(This, 5, 3, 10, 2, EFI_LBA_LIST_TERMINATOR);\r
	325	\r
	326	@retval EFI_SUCCESS The erase request was successfully\r
	327	completed.\r
	328	\r
	329	@retval EFI_ACCESS_DENIED The firmware volume is in the\r
	330	WriteDisabled state.\r
	331	@retval EFI_DEVICE_ERROR The block device is not functioning\r
	332	correctly and could not be written.\r
	333	The firmware device may have been\r
	334	partially erased.\r
	335	@retval EFI_INVALID_PARAMETER One or more of the LBAs listed\r
	336	in the variable argument list do\r
	337	not exist in the firmware volume. \r
	338	\r
	339	**/\r
	340	typedef\r
	341	EFI_STATUS\r
	342	(EFIAPI * EFI_FVB_ERASE_BLOCKS) (\r
	343	IN CONST EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *This,\r
	344	...\r
	345	);\r
	346	\r
347	\r
348	\r
349	/**\r
350	The Firmware Volume Block Protocol is the low-level interface\r
351	to a firmware volume. File-level access to a firmware volume\r
352	should not be done using the Firmware Volume Block Protocol.\r
353	Normal access to a firmware volume must use the Firmware\r
354	Volume Protocol. Typically, only the file system driver that\r
355	produces the Firmware Volume Protocol will bind to the\r
356	Firmware Volume Block Protocol. The Firmware Volume Block\r
357	Protocol provides the following:\r
358	- Byte-level read/write functionality.\r
359	- Block-level erase functionality.\r
360	- It further exposes device-hardening features, such as may be\r
361	equired to protect the firmware from unwanted overwriting\r
362	and/or erasure.\r
363	- It is useful to layer a file system driver on top of the\r
364	Firmware Volume Block Protocol.\r
365	\r
366	This file system driver produces the Firmware Volume Protocol,\r
367	which provides file-level access to a firmware volume. The\r
368	Firmware Volume Protocol abstracts the file system that is\r
369	used to format the firmware volume and the hardware\r
370	device-hardening features that may be present.\r
371	\r
372	\r
373	@param GetPhysicalAddress Retrieves the memory-mapped\r
374	address of the firmware volume.\r
375	See the GetPhysicalAddress()\r
376	function description. \r
377	\r
378	@param GetBlockSize Retrieves the size for a specific block.\r
379	Also returns the number of consecutive\r
380	similarly sized blocks. See the\r
381	GetBlockSize() function description.\r
382	\r
383	@param Read Reads n bytes into a buffer from the firmware\r
384	volume hardware. See the Read() function\r
385	description.\r
386	\r
387	@param Write Writes n bytes from a buffer into the firmware\r
388	volume hardware. See the Write() function\r
389	description.\r
390	\r
391	@param EraseBlocks Erases specified block(s) and sets all\r
392	values as indicated by the\r
393	EFI_FVB_ERASE_POLARITY bit. See the\r
394	EraseBlocks() function description. Type\r
395	EFI_FVB_ERASE_POLARITY is defined in\r
396	EFI_FIRMWARE_VOLUME_HEADER. ParentHandle\r
397	Handle of the parent firmware volume. Type\r
398	EFI_HANDLE is defined in\r
399	InstallProtocolInterface() in the UEFI 2.0\r
400	specification.\r
401	\r
402	@param GetAttributes Retrieves the current volume attributes.\r
403	See the GetAttributes() function\r
404	description.\r
405	\r
406	@param SetAttributes Sets the current volume attributes. See\r
407	the SetAttributes() function description.\r
408	\r
409	\r
410	**/\r
411	struct _EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL {\r
412	EFI_FVB_GET_ATTRIBUTES GetAttributes;\r
413	EFI_FVB_SET_ATTRIBUTES SetAttributes;\r
414	EFI_FVB_GET_PHYSICAL_ADDRESS GetPhysicalAddress;\r
415	EFI_FVB_GET_BLOCK_SIZE GetBlockSize;\r
416	EFI_FVB_READ Read;\r
417	EFI_FVB_WRITE Write;\r
418	EFI_FVB_ERASE_BLOCKS EraseBlocks;\r
419	EFI_HANDLE ParentHandle;\r
420	};\r
421	\r
422	\r
423	extern EFI_GUID gEfiFirmwareVolumeBlockProtocolGuid;\r
424	\r
425	\r
426	#endif\r