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