]>
Commit | Line | Data |
---|---|---|
85e923a5 | 1 | /** @file\r |
64a80549 | 2 | Fault Tolerant Write protocol provides boot-time service for fault tolerant \r |
3 | write capability for block devices. The protocol provides for non-volatile \r | |
4 | storage of the intermediate data and private information a caller would need to \r | |
5 | recover from a critical fault, such as a power failure. \r | |
6 | \r | |
cd5ebaa0 | 7 | Copyright (c) 2009 - 2010, Intel Corporation. All rights reserved.<BR>\r |
64a80549 | 8 | This program and the accompanying materials are licensed and made available under \r |
9 | the terms and conditions of the BSD License that accompanies this distribution. \r | |
10 | The full text of the license may be found at\r | |
11 | http://opensource.org/licenses/bsd-license.php. \r | |
12 | \r | |
85e923a5 LG |
13 | THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, \r |
14 | WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. \r | |
15 | \r | |
16 | **/\r | |
17 | \r | |
18 | #ifndef _FW_FAULT_TOLERANT_WRITE_PROTOCOL_H_\r | |
19 | #define _FW_FAULT_TOLERANT_WRITE_PROTOCOL_H_\r | |
20 | \r | |
21 | #define EFI_FAULT_TOLERANT_WRITE_PROTOCOL_GUID \\r | |
22 | { \\r | |
23 | 0x3ebd9e82, 0x2c78, 0x4de6, {0x97, 0x86, 0x8d, 0x4b, 0xfc, 0xb7, 0xc8, 0x81 } \\r | |
24 | }\r | |
25 | \r | |
26 | //\r | |
27 | // Forward reference for pure ANSI compatability\r | |
28 | //\r | |
29 | typedef struct _EFI_FAULT_TOLERANT_WRITE_PROTOCOL EFI_FAULT_TOLERANT_WRITE_PROTOCOL;\r | |
30 | \r | |
31 | /**\r | |
e9b67286 | 32 | Get the size of the largest block that can be updated in a fault-tolerant manner.\r |
85e923a5 LG |
33 | \r |
34 | @param This Indicates a pointer to the calling context.\r | |
e9b67286 | 35 | @param BlockSize A pointer to a caller-allocated UINTN that is\r |
36 | updated to indicate the size of the largest block\r | |
85e923a5 LG |
37 | that can be updated.\r |
38 | \r | |
64a80549 | 39 | @retval EFI_SUCCESS The function completed successfully.\r |
85e923a5 LG |
40 | @retval EFI_ABORTED The function could not complete successfully.\r |
41 | \r | |
42 | **/\r | |
43 | typedef\r | |
44 | EFI_STATUS\r | |
0c1a4aa6 | 45 | (EFIAPI *EFI_FAULT_TOLERANT_WRITE_GET_MAX_BLOCK_SIZE)(\r |
85e923a5 LG |
46 | IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL * This,\r |
47 | OUT UINTN *BlockSize\r | |
48 | );\r | |
49 | \r | |
50 | /**\r | |
51 | Allocates space for the protocol to maintain information about writes.\r | |
e9b67286 | 52 | Since writes must be completed in a fault-tolerant manner and multiple\r |
53 | writes require more resources to be successful, this function\r | |
85e923a5 | 54 | enables the protocol to ensure that enough space exists to track\r |
e9b67286 | 55 | information about upcoming writes.\r |
85e923a5 | 56 | \r |
e9b67286 | 57 | @param This A pointer to the calling context.\r |
85e923a5 LG |
58 | @param CallerId The GUID identifying the write.\r |
59 | @param PrivateDataSize The size of the caller's private data that must be\r | |
60 | recorded for each write.\r | |
e9b67286 | 61 | @param NumberOfWrites The number of fault tolerant block writes that will\r |
85e923a5 LG |
62 | need to occur.\r |
63 | \r | |
64 | @retval EFI_SUCCESS The function completed successfully\r | |
65 | @retval EFI_ABORTED The function could not complete successfully.\r | |
e9b67286 | 66 | @retval EFI_ACCESS_DENIED Not all allocated writes have been completed. All\r |
67 | writes must be completed or aborted before another\r | |
85e923a5 LG |
68 | fault tolerant write can occur.\r |
69 | \r | |
70 | **/\r | |
71 | typedef\r | |
72 | EFI_STATUS\r | |
0c1a4aa6 | 73 | (EFIAPI *EFI_FAULT_TOLERANT_WRITE_ALLOCATE)(\r |
85e923a5 LG |
74 | IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL * This,\r |
75 | IN EFI_GUID * CallerId,\r | |
76 | IN UINTN PrivateDataSize,\r | |
77 | IN UINTN NumberOfWrites\r | |
78 | );\r | |
79 | \r | |
80 | /**\r | |
81 | Starts a target block update. This records information about the write\r | |
e9b67286 | 82 | in fault tolerant storage, and will complete the write in a recoverable\r |
85e923a5 LG |
83 | manner, ensuring at all times that either the original contents or\r |
84 | the modified contents are available.\r | |
85 | \r | |
64a80549 | 86 | @param This The calling context.\r |
85e923a5 LG |
87 | @param Lba The logical block address of the target block.\r |
88 | @param Offset The offset within the target block to place the\r | |
89 | data.\r | |
90 | @param Length The number of bytes to write to the target block.\r | |
91 | @param PrivateData A pointer to private data that the caller requires\r | |
e9b67286 | 92 | to complete any pending writes in the event of a\r |
85e923a5 LG |
93 | fault.\r |
94 | @param FvBlockHandle The handle of FVB protocol that provides services\r | |
e9b67286 | 95 | for reading, writing, and erasing the target block.\r |
85e923a5 LG |
96 | @param Buffer The data to write.\r |
97 | \r | |
64a80549 | 98 | @retval EFI_SUCCESS The function completed successfully.\r |
85e923a5 | 99 | @retval EFI_ABORTED The function could not complete successfully.\r |
e9b67286 | 100 | @retval EFI_BAD_BUFFER_SIZE The write would span a block boundary, which is not\r |
85e923a5 LG |
101 | a valid action.\r |
102 | @retval EFI_ACCESS_DENIED No writes have been allocated.\r | |
e9b67286 | 103 | @retval EFI_NOT_READY The last write has not been completed. Restart()\r |
85e923a5 LG |
104 | must be called to complete it.\r |
105 | \r | |
106 | **/\r | |
107 | typedef\r | |
108 | EFI_STATUS\r | |
0c1a4aa6 | 109 | (EFIAPI *EFI_FAULT_TOLERANT_WRITE_WRITE)(\r |
85e923a5 LG |
110 | IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL * This,\r |
111 | IN EFI_LBA Lba,\r | |
112 | IN UINTN Offset,\r | |
113 | IN UINTN Length,\r | |
114 | IN VOID *PrivateData,\r | |
115 | IN EFI_HANDLE FvbHandle,\r | |
116 | IN VOID *Buffer\r | |
117 | );\r | |
118 | \r | |
119 | /**\r | |
120 | Restarts a previously interrupted write. The caller must provide the\r | |
121 | block protocol needed to complete the interrupted write.\r | |
122 | \r | |
64a80549 | 123 | @param This The calling context.\r |
124 | @param FvBlockProtocol The handle of FVB protocol that provides services.\r | |
e9b67286 | 125 | for reading, writing, and erasing the target block.\r |
85e923a5 | 126 | \r |
64a80549 | 127 | @retval EFI_SUCCESS The function completed successfully.\r |
85e923a5 LG |
128 | @retval EFI_ABORTED The function could not complete successfully.\r |
129 | @retval EFI_ACCESS_DENIED No pending writes exist.\r | |
130 | \r | |
131 | **/\r | |
132 | typedef\r | |
133 | EFI_STATUS\r | |
0c1a4aa6 | 134 | (EFIAPI *EFI_FAULT_TOLERANT_WRITE_RESTART)(\r |
85e923a5 LG |
135 | IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL * This,\r |
136 | IN EFI_HANDLE FvbHandle\r | |
137 | );\r | |
138 | \r | |
139 | /**\r | |
e9b67286 | 140 | Aborts all previously allocated writes.\r |
85e923a5 | 141 | \r |
64a80549 | 142 | @param This The calling context.\r |
85e923a5 | 143 | \r |
64a80549 | 144 | @retval EFI_SUCCESS The function completed successfully.\r |
85e923a5 LG |
145 | @retval EFI_ABORTED The function could not complete successfully.\r |
146 | @retval EFI_NOT_FOUND No allocated writes exist.\r | |
147 | \r | |
148 | **/\r | |
149 | typedef\r | |
150 | EFI_STATUS\r | |
0c1a4aa6 | 151 | (EFIAPI *EFI_FAULT_TOLERANT_WRITE_ABORT)(\r |
85e923a5 LG |
152 | IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL * This\r |
153 | );\r | |
154 | \r | |
155 | /**\r | |
e9b67286 | 156 | Starts a target block update. This function records information about the write\r |
64a80549 | 157 | in fault-tolerant storage and completes the write in a recoverable\r |
85e923a5 LG |
158 | manner, ensuring at all times that either the original contents or\r |
159 | the modified contents are available.\r | |
160 | \r | |
161 | @param This Indicates a pointer to the calling context.\r | |
162 | @param CallerId The GUID identifying the last write.\r | |
163 | @param Lba The logical block address of the last write.\r | |
164 | @param Offset The offset within the block of the last write.\r | |
165 | @param Length The length of the last write.\r | |
e9b67286 | 166 | @param PrivateDataSize On input, the size of the PrivateData buffer. On\r |
167 | output, the size of the private data stored for\r | |
85e923a5 LG |
168 | this write.\r |
169 | @param PrivateData A pointer to a buffer. The function will copy\r | |
e9b67286 | 170 | PrivateDataSize bytes from the private data stored\r |
85e923a5 | 171 | for this write.\r |
e9b67286 | 172 | @param Complete A Boolean value with TRUE indicating that the write\r |
85e923a5 LG |
173 | was completed.\r |
174 | \r | |
64a80549 | 175 | @retval EFI_SUCCESS The function completed successfully.\r |
85e923a5 LG |
176 | @retval EFI_ABORTED The function could not complete successfully.\r |
177 | @retval EFI_NOT_FOUND No allocated writes exist.\r | |
178 | \r | |
179 | **/\r | |
180 | typedef\r | |
181 | EFI_STATUS\r | |
0c1a4aa6 | 182 | (EFIAPI *EFI_FAULT_TOLERANT_WRITE_GET_LAST_WRITE)(\r |
85e923a5 LG |
183 | IN EFI_FAULT_TOLERANT_WRITE_PROTOCOL * This,\r |
184 | OUT EFI_GUID * CallerId,\r | |
185 | OUT EFI_LBA *Lba,\r | |
186 | OUT UINTN *Offset,\r | |
187 | OUT UINTN *Length,\r | |
188 | IN OUT UINTN *PrivateDataSize,\r | |
189 | OUT VOID *PrivateData,\r | |
190 | OUT BOOLEAN *Complete\r | |
191 | );\r | |
192 | \r | |
193 | //\r | |
194 | // Protocol declaration\r | |
195 | //\r | |
196 | struct _EFI_FAULT_TOLERANT_WRITE_PROTOCOL {\r | |
197 | EFI_FAULT_TOLERANT_WRITE_GET_MAX_BLOCK_SIZE GetMaxBlockSize;\r | |
198 | EFI_FAULT_TOLERANT_WRITE_ALLOCATE Allocate;\r | |
199 | EFI_FAULT_TOLERANT_WRITE_WRITE Write;\r | |
200 | EFI_FAULT_TOLERANT_WRITE_RESTART Restart;\r | |
201 | EFI_FAULT_TOLERANT_WRITE_ABORT Abort;\r | |
202 | EFI_FAULT_TOLERANT_WRITE_GET_LAST_WRITE GetLastWrite;\r | |
203 | };\r | |
204 | \r | |
205 | extern EFI_GUID gEfiFaultTolerantWriteProtocolGuid;\r | |
206 | \r | |
207 | #endif\r |