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