[mirror_edk2.git] / MdePkg / Include / Protocol / DiskIo2.h

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