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