xref: /illumos-gate/usr/src/boot/efi/include/Protocol/BlockIo.h (revision f334afcfaebea1b7dc3430015651d8d748fa8a3e)
1 /** @file
2   Block IO protocol as defined in the UEFI 2.0 specification.
3 
4   The Block IO protocol is used to abstract block devices like hard drives,
5   DVD-ROMs and floppy drives.
6 
7   Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
8   SPDX-License-Identifier: BSD-2-Clause-Patent
9 
10 **/
11 
12 #ifndef __BLOCK_IO_H__
13 #define __BLOCK_IO_H__
14 
15 #define EFI_BLOCK_IO_PROTOCOL_GUID \
16   { \
17     0x964e5b21, 0x6459, 0x11d2, {0x8e, 0x39, 0x0, 0xa0, 0xc9, 0x69, 0x72, 0x3b } \
18   }
19 
20 typedef struct _EFI_BLOCK_IO_PROTOCOL EFI_BLOCK_IO_PROTOCOL;
21 
22 ///
23 /// Protocol GUID name defined in EFI1.1.
24 ///
25 #define BLOCK_IO_PROTOCOL  EFI_BLOCK_IO_PROTOCOL_GUID
26 
27 ///
28 /// Protocol defined in EFI1.1.
29 ///
30 typedef EFI_BLOCK_IO_PROTOCOL EFI_BLOCK_IO;
31 
32 /**
33   Reset the Block Device.
34 
35   @param  This                 Indicates a pointer to the calling context.
36   @param  ExtendedVerification Driver may perform diagnostics on reset.
37 
38   @retval EFI_SUCCESS          The device was reset.
39   @retval EFI_DEVICE_ERROR     The device is not functioning properly and could
40                                not be reset.
41 
42 **/
43 typedef
44 EFI_STATUS
45 (EFIAPI *EFI_BLOCK_RESET)(
46   IN EFI_BLOCK_IO_PROTOCOL          *This,
47   IN BOOLEAN                        ExtendedVerification
48   );
49 
50 /**
51   Read BufferSize bytes from Lba into Buffer.
52 
53   @param  This       Indicates a pointer to the calling context.
54   @param  MediaId    Id of the media, changes every time the media is replaced.
55   @param  Lba        The starting Logical Block Address to read from
56   @param  BufferSize Size of Buffer, must be a multiple of device block size.
57   @param  Buffer     A pointer to the destination buffer for the data. The caller is
58                      responsible for either having implicit or explicit ownership of the buffer.
59 
60   @retval EFI_SUCCESS           The data was read correctly from the device.
61   @retval EFI_DEVICE_ERROR      The device reported an error while performing the read.
62   @retval EFI_NO_MEDIA          There is no media in the device.
63   @retval EFI_MEDIA_CHANGED     The MediaId does not matched the current device.
64   @retval EFI_BAD_BUFFER_SIZE   The Buffer was not a multiple of the block size of the device.
65   @retval EFI_INVALID_PARAMETER The read request contains LBAs that are not valid,
66                                 or the buffer is not on proper alignment.
67 
68 **/
69 typedef
70 EFI_STATUS
71 (EFIAPI *EFI_BLOCK_READ)(
72   IN EFI_BLOCK_IO_PROTOCOL          *This,
73   IN UINT32                         MediaId,
74   IN EFI_LBA                        Lba,
75   IN UINTN                          BufferSize,
76   OUT VOID                          *Buffer
77   );
78 
79 /**
80   Write BufferSize bytes from Lba into Buffer.
81 
82   @param  This       Indicates a pointer to the calling context.
83   @param  MediaId    The media ID that the write request is for.
84   @param  Lba        The starting logical block address to be written. The caller is
85                      responsible for writing to only legitimate locations.
86   @param  BufferSize Size of Buffer, must be a multiple of device block size.
87   @param  Buffer     A pointer to the source buffer for the data.
88 
89   @retval EFI_SUCCESS           The data was written correctly to the device.
90   @retval EFI_WRITE_PROTECTED   The device can not be written to.
91   @retval EFI_DEVICE_ERROR      The device reported an error while performing the write.
92   @retval EFI_NO_MEDIA          There is no media in the device.
93   @retval EFI_MEDIA_CHNAGED     The MediaId does not matched the current device.
94   @retval EFI_BAD_BUFFER_SIZE   The Buffer was not a multiple of the block size of the device.
95   @retval EFI_INVALID_PARAMETER The write request contains LBAs that are not valid,
96                                 or the buffer is not on proper alignment.
97 
98 **/
99 typedef
100 EFI_STATUS
101 (EFIAPI *EFI_BLOCK_WRITE)(
102   IN EFI_BLOCK_IO_PROTOCOL          *This,
103   IN UINT32                         MediaId,
104   IN EFI_LBA                        Lba,
105   IN UINTN                          BufferSize,
106   IN VOID                           *Buffer
107   );
108 
109 /**
110   Flush the Block Device.
111 
112   @param  This              Indicates a pointer to the calling context.
113 
114   @retval EFI_SUCCESS       All outstanding data was written to the device
115   @retval EFI_DEVICE_ERROR  The device reported an error while writting back the data
116   @retval EFI_NO_MEDIA      There is no media in the device.
117 
118 **/
119 typedef
120 EFI_STATUS
121 (EFIAPI *EFI_BLOCK_FLUSH)(
122   IN EFI_BLOCK_IO_PROTOCOL  *This
123   );
124 
125 /**
126   Block IO read only mode data and updated only via members of BlockIO
127 **/
128 typedef struct {
129   ///
130   /// The curent media Id. If the media changes, this value is changed.
131   ///
132   UINT32     MediaId;
133 
134   ///
135   /// TRUE if the media is removable; otherwise, FALSE.
136   ///
137   BOOLEAN    RemovableMedia;
138 
139   ///
140   /// TRUE if there is a media currently present in the device;
141   /// othersise, FALSE. THis field shows the media present status
142   /// as of the most recent ReadBlocks() or WriteBlocks() call.
143   ///
144   BOOLEAN    MediaPresent;
145 
146   ///
147   /// TRUE if LBA 0 is the first block of a partition; otherwise
148   /// FALSE. For media with only one partition this would be TRUE.
149   ///
150   BOOLEAN    LogicalPartition;
151 
152   ///
153   /// TRUE if the media is marked read-only otherwise, FALSE.
154   /// This field shows the read-only status as of the most recent WriteBlocks () call.
155   ///
156   BOOLEAN    ReadOnly;
157 
158   ///
159   /// TRUE if the WriteBlock () function caches write data.
160   ///
161   BOOLEAN    WriteCaching;
162 
163   ///
164   /// The intrinsic block size of the device. If the media changes, then
165   /// this field is updated.
166   ///
167   UINT32     BlockSize;
168 
169   ///
170   /// Supplies the alignment requirement for any buffer to read or write block(s).
171   ///
172   UINT32     IoAlign;
173 
174   ///
175   /// The last logical block address on the device.
176   /// If the media changes, then this field is updated.
177   ///
178   EFI_LBA    LastBlock;
179 
180   ///
181   /// Only present if EFI_BLOCK_IO_PROTOCOL.Revision is greater than or equal to
182   /// EFI_BLOCK_IO_PROTOCOL_REVISION2. Returns the first LBA is aligned to
183   /// a physical block boundary.
184   ///
185   EFI_LBA    LowestAlignedLba;
186 
187   ///
188   /// Only present if EFI_BLOCK_IO_PROTOCOL.Revision is greater than or equal to
189   /// EFI_BLOCK_IO_PROTOCOL_REVISION2. Returns the number of logical blocks
190   /// per physical block.
191   ///
192   UINT32     LogicalBlocksPerPhysicalBlock;
193 
194   ///
195   /// Only present if EFI_BLOCK_IO_PROTOCOL.Revision is greater than or equal to
196   /// EFI_BLOCK_IO_PROTOCOL_REVISION3. Returns the optimal transfer length
197   /// granularity as a number of logical blocks.
198   ///
199   UINT32     OptimalTransferLengthGranularity;
200 } EFI_BLOCK_IO_MEDIA;
201 
202 #define EFI_BLOCK_IO_PROTOCOL_REVISION   0x00010000
203 #define EFI_BLOCK_IO_PROTOCOL_REVISION2  0x00020001
204 #define EFI_BLOCK_IO_PROTOCOL_REVISION3  0x0002001F
205 
206 ///
207 /// Revision defined in EFI1.1.
208 ///
209 #define EFI_BLOCK_IO_INTERFACE_REVISION  EFI_BLOCK_IO_PROTOCOL_REVISION
210 
211 ///
212 ///  This protocol provides control over block devices.
213 ///
214 struct _EFI_BLOCK_IO_PROTOCOL {
215   ///
216   /// The revision to which the block IO interface adheres. All future
217   /// revisions must be backwards compatible. If a future version is not
218   /// back wards compatible, it is not the same GUID.
219   ///
220   UINT64                Revision;
221   ///
222   /// Pointer to the EFI_BLOCK_IO_MEDIA data for this device.
223   ///
224   EFI_BLOCK_IO_MEDIA    *Media;
225 
226   EFI_BLOCK_RESET       Reset;
227   EFI_BLOCK_READ        ReadBlocks;
228   EFI_BLOCK_WRITE       WriteBlocks;
229   EFI_BLOCK_FLUSH       FlushBlocks;
230 };
231 
232 extern EFI_GUID  gEfiBlockIoProtocolGuid;
233 
234 #endif
235