xref: /illumos-gate/usr/src/boot/efi/include/Protocol/DiskIo2.h (revision f334afcfaebea1b7dc3430015651d8d748fa8a3e)
1 /** @file
2   Disk I/O 2 protocol as defined in the UEFI 2.4 specification.
3 
4   The Disk I/O 2 protocol defines an extension to the Disk I/O protocol to enable
5   non-blocking / asynchronous byte-oriented disk operation.
6 
7   Copyright (c) 2013 - 2018, Intel Corporation. All rights reserved.<BR>
8   SPDX-License-Identifier: BSD-2-Clause-Patent
9 
10 **/
11 
12 #ifndef __DISK_IO2_H__
13 #define __DISK_IO2_H__
14 
15 #define EFI_DISK_IO2_PROTOCOL_GUID \
16   { \
17     0x151c8eae, 0x7f2c, 0x472c, \
18     {0x9e, 0x54, 0x98, 0x28, 0x19, 0x4f, 0x6a, 0x88} \
19   }
20 
21 typedef struct _EFI_DISK_IO2_PROTOCOL EFI_DISK_IO2_PROTOCOL;
22 
23 /**
24   The struct of Disk IO2 Token.
25 **/
26 typedef struct {
27   //
28   // If Event is NULL, then blocking I/O is performed.
29   // If Event is not NULL and non-blocking I/O is supported, then non-blocking I/O is performed,
30   // and Event will be signaled when the I/O request is completed.
31   // The caller must be prepared to handle the case where the callback associated with Event occurs
32   // before the original asynchronous I/O request call returns.
33   //
34   EFI_EVENT     Event;
35 
36   //
37   // Defines whether or not the signaled event encountered an error.
38   //
39   EFI_STATUS    TransactionStatus;
40 } EFI_DISK_IO2_TOKEN;
41 
42 /**
43   Terminate outstanding asynchronous requests to a device.
44 
45   @param This                   Indicates a pointer to the calling context.
46 
47   @retval EFI_SUCCESS           All outstanding requests were successfully terminated.
48   @retval EFI_DEVICE_ERROR      The device reported an error while performing the cancel
49                                 operation.
50 **/
51 typedef
52 EFI_STATUS
53 (EFIAPI *EFI_DISK_CANCEL_EX)(
54   IN EFI_DISK_IO2_PROTOCOL *This
55   );
56 
57 /**
58   Reads a specified number of bytes from a device.
59 
60   @param This                   Indicates a pointer to the calling context.
61   @param MediaId                ID of the medium to be read.
62   @param Offset                 The starting byte offset on the logical block I/O device to read from.
63   @param Token                  A pointer to the token associated with the transaction.
64                                 If this field is NULL, synchronous/blocking IO is performed.
65   @param  BufferSize            The size in bytes of Buffer. The number of bytes to read from the device.
66   @param  Buffer                A pointer to the destination buffer for the data.
67                                 The caller is responsible either having implicit or explicit ownership of the buffer.
68 
69   @retval EFI_SUCCESS           If Event is NULL (blocking I/O): The data was read correctly from the device.
70                                 If Event is not NULL (asynchronous I/O): The request was successfully queued for processing.
71                                                                          Event will be signaled upon completion.
72   @retval EFI_DEVICE_ERROR      The device reported an error while performing the write.
73   @retval EFI_NO_MEDIA          There is no medium in the device.
74   @retval EFI_MEDIA_CHNAGED     The MediaId is not for the current medium.
75   @retval EFI_INVALID_PARAMETER The read request contains device addresses that are not valid for the device.
76   @retval EFI_OUT_OF_RESOURCES  The request could not be completed due to a lack of resources.
77 
78 **/
79 typedef
80 EFI_STATUS
81 (EFIAPI *EFI_DISK_READ_EX)(
82   IN EFI_DISK_IO2_PROTOCOL        *This,
83   IN UINT32                       MediaId,
84   IN UINT64                       Offset,
85   IN OUT EFI_DISK_IO2_TOKEN       *Token,
86   IN UINTN                        BufferSize,
87   OUT VOID                        *Buffer
88   );
89 
90 /**
91   Writes a specified number of bytes to a device.
92 
93   @param This        Indicates a pointer to the calling context.
94   @param MediaId     ID of the medium to be written.
95   @param Offset      The starting byte offset on the logical block I/O device to write to.
96   @param Token       A pointer to the token associated with the transaction.
97                      If this field is NULL, synchronous/blocking IO is performed.
98   @param BufferSize  The size in bytes of Buffer. The number of bytes to write to the device.
99   @param Buffer      A pointer to the buffer containing the data to be written.
100 
101   @retval EFI_SUCCESS           If Event is NULL (blocking I/O): The data was written correctly to the device.
102                                 If Event is not NULL (asynchronous I/O): The request was successfully queued for processing.
103                                                                          Event will be signaled upon completion.
104   @retval EFI_WRITE_PROTECTED   The device cannot be written to.
105   @retval EFI_DEVICE_ERROR      The device reported an error while performing the write operation.
106   @retval EFI_NO_MEDIA          There is no medium in the device.
107   @retval EFI_MEDIA_CHNAGED     The MediaId is not for the current medium.
108   @retval EFI_INVALID_PARAMETER The write request contains device addresses that are not valid for the device.
109   @retval EFI_OUT_OF_RESOURCES  The request could not be completed due to a lack of resources.
110 
111 **/
112 typedef
113 EFI_STATUS
114 (EFIAPI *EFI_DISK_WRITE_EX)(
115   IN EFI_DISK_IO2_PROTOCOL        *This,
116   IN UINT32                       MediaId,
117   IN UINT64                       Offset,
118   IN OUT EFI_DISK_IO2_TOKEN       *Token,
119   IN UINTN                        BufferSize,
120   IN VOID                         *Buffer
121   );
122 
123 /**
124   Flushes all modified data to the physical device.
125 
126   @param This        Indicates a pointer to the calling context.
127   @param MediaId     ID of the medium to be written.
128   @param Token       A pointer to the token associated with the transaction.
129                      If this field is NULL, synchronous/blocking IO is performed.
130 
131   @retval EFI_SUCCESS           If Event is NULL (blocking I/O): The data was flushed successfully to the device.
132                                 If Event is not NULL (asynchronous I/O): The request was successfully queued for processing.
133                                                                          Event will be signaled upon completion.
134   @retval EFI_WRITE_PROTECTED   The device cannot be written to.
135   @retval EFI_DEVICE_ERROR      The device reported an error while performing the write operation.
136   @retval EFI_NO_MEDIA          There is no medium in the device.
137   @retval EFI_MEDIA_CHNAGED     The MediaId is not for the current medium.
138   @retval EFI_OUT_OF_RESOURCES  The request could not be completed due to a lack of resources.
139 **/
140 typedef
141 EFI_STATUS
142 (EFIAPI *EFI_DISK_FLUSH_EX)(
143   IN EFI_DISK_IO2_PROTOCOL        *This,
144   IN OUT EFI_DISK_IO2_TOKEN       *Token
145   );
146 
147 #define EFI_DISK_IO2_PROTOCOL_REVISION  0x00020000
148 
149 ///
150 /// This protocol is used to abstract Block I/O interfaces.
151 ///
152 struct _EFI_DISK_IO2_PROTOCOL {
153   ///
154   /// The revision to which the disk I/O interface adheres. All future
155   /// revisions must be backwards compatible. If a future version is not
156   /// backwards compatible, it is not the same GUID.
157   ///
158   UINT64                Revision;
159   EFI_DISK_CANCEL_EX    Cancel;
160   EFI_DISK_READ_EX      ReadDiskEx;
161   EFI_DISK_WRITE_EX     WriteDiskEx;
162   EFI_DISK_FLUSH_EX     FlushDiskEx;
163 };
164 
165 extern EFI_GUID  gEfiDiskIo2ProtocolGuid;
166 
167 #endif
168