[mirror_edk2.git] / OvmfPkg / VirtioBlkDxe / VirtioBlk.h

/** @file\r
\r
  Internal definitions for the virtio-blk driver, which produces Block I/O\r
  Protocol instances for virtio-blk devices.\r
\r
  Copyright (C) 2012, Red Hat, Inc.\r
\r
  This program and the accompanying materials are licensed and made available\r
  under the terms and conditions of the BSD License which accompanies this\r
  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, WITHOUT\r
  WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
\r
**/\r
\r
#include <Protocol/BlockIo.h>\r
#include <Protocol/ComponentName.h>\r
#include <Protocol/DriverBinding.h>\r
#include <Protocol/PciIo.h>\r
\r
#include "Virtio.h"\r
\r
\r
#define VBLK_SIG SIGNATURE_32 ('V', 'B', 'L', 'K')\r
\r
typedef struct {\r
  //\r
  // Parts of this structure are initialized / torn down in various functions\r
  // at various call depths. The table to the right should make it easier to\r
  // track them.\r
  //\r
  //                    field                     init function       init dpth\r
  //                    ----------------------    ------------------  ---------\r
  UINT32                Signature;             // DriverBindingStart  0\r
  EFI_PCI_IO_PROTOCOL   *PciIo;                // DriverBindingStart  0\r
  UINT64                OriginalPciAttributes; // DriverBindingStart  0\r
  VRING                 Ring;                  // VirtioRingInit      2\r
  EFI_BLOCK_IO_PROTOCOL BlockIo;               // VirtioBlkInit       1\r
  EFI_BLOCK_IO_MEDIA    BlockIoMedia;          // VirtioBlkInit       1\r
} VBLK_DEV;\r
\r
#define VIRTIO_BLK_FROM_BLOCK_IO(BlockIoPointer) \\r
        CR (BlockIoPointer, VBLK_DEV, BlockIo, VBLK_SIG)\r
\r
\r
/**\r
\r
  Device probe function for this driver.\r
\r
  The DXE core calls this function for any given device in order to see if the\r
  driver can drive the device.\r
\r
  Specs relevant in the general sense:\r
\r
  - UEFI Spec 2.3.1 + Errata C:\r
    - 6.3 Protocol Handler Services -- for accessing the underlying device\r
    - 10.1 EFI Driver Binding Protocol -- for exporting ourselves\r
\r
  - Driver Writer's Guide for UEFI 2.3.1 v1.01:\r
    - 5.1.3.4 OpenProtocol() and CloseProtocol() -- for accessing the\r
      underlying device\r
    - 9 Driver Binding Protocol -- for exporting ourselves\r
\r
  Specs relevant in the specific sense:\r
  - UEFI Spec 2.3.1 + Errata C, 13.4 EFI PCI I/O Protocol\r
  - Driver Writer's Guide for UEFI 2.3.1 v1.01, 18 PCI Driver Design\r
    Guidelines, 18.3 PCI drivers.\r
\r
  @param[in]  This                The EFI_DRIVER_BINDING_PROTOCOL object\r
                                  incorporating this driver (independently of\r
                                  any device).\r
\r
  @param[in] DeviceHandle         The device to probe.\r
\r
  @param[in] RemainingDevicePath  Relevant only for bus drivers, ignored.\r
\r
\r
  @retval EFI_SUCCESS      The driver supports the device being probed.\r
\r
  @retval EFI_UNSUPPORTED  Based on virtio-blk PCI discovery, we do not support\r
                           the device.\r
\r
  @return                  Error codes from the OpenProtocol() boot service or\r
                           the PciIo protocol.\r
\r
**/\r
\r
EFI_STATUS\r
EFIAPI\r
VirtioBlkDriverBindingSupported (\r
  IN EFI_DRIVER_BINDING_PROTOCOL *This,\r
  IN EFI_HANDLE                  DeviceHandle,\r
  IN EFI_DEVICE_PATH_PROTOCOL    *RemainingDevicePath\r
  );\r
\r
\r
/**\r
\r
  After we've pronounced support for a specific device in\r
  DriverBindingSupported(), we start managing said device (passed in by the\r
  Driver Exeuction Environment) with the following service.\r
\r
  See DriverBindingSupported() for specification references.\r
\r
  @param[in]  This                The EFI_DRIVER_BINDING_PROTOCOL object\r
                                  incorporating this driver (independently of\r
                                  any device).\r
\r
  @param[in] DeviceHandle         The supported device to drive.\r
\r
  @param[in] RemainingDevicePath  Relevant only for bus drivers, ignored.\r
\r
\r
  @retval EFI_SUCCESS           Driver instance has been created and\r
                                initialized  for the virtio-blk PCI device, it\r
                                is now accessibla via EFI_BLOCK_IO_PROTOCOL.\r
\r
  @retval EFI_OUT_OF_RESOURCES  Memory allocation failed.\r
\r
  @return                       Error codes from the OpenProtocol() boot\r
                                service, the PciIo protocol, VirtioBlkInit(),\r
                                or the InstallProtocolInterface() boot service.\r
\r
**/\r
\r
EFI_STATUS\r
EFIAPI\r
VirtioBlkDriverBindingStart (\r
  IN EFI_DRIVER_BINDING_PROTOCOL *This,\r
  IN EFI_HANDLE                  DeviceHandle,\r
  IN EFI_DEVICE_PATH_PROTOCOL    *RemainingDevicePath\r
  );\r
\r
\r
/**\r
\r
  Stop driving a virtio-blk device and remove its BlockIo interface.\r
\r
  This function replays the success path of DriverBindingStart() in reverse.\r
  The host side virtio-blk device is reset, so that the OS boot loader or the\r
  OS may reinitialize it.\r
\r
  @param[in] This               The EFI_DRIVER_BINDING_PROTOCOL object\r
                                incorporating this driver (independently of any\r
                                device).\r
\r
  @param[in] DeviceHandle       Stop driving this device.\r
\r
  @param[in] NumberOfChildren   Since this function belongs to a device driver\r
                                only (as opposed to a bus driver), the caller\r
                                environment sets NumberOfChildren to zero, and\r
                                we ignore it.\r
\r
  @param[in] ChildHandleBuffer  Ignored (corresponding to NumberOfChildren).\r
\r
**/\r
\r
EFI_STATUS\r
EFIAPI\r
VirtioBlkDriverBindingStop (\r
  IN EFI_DRIVER_BINDING_PROTOCOL *This,\r
  IN EFI_HANDLE                  DeviceHandle,\r
  IN UINTN                       NumberOfChildren,\r
  IN EFI_HANDLE                  *ChildHandleBuffer\r
  );\r
\r
\r
//\r
// UEFI Spec 2.3.1 + Errata C, 12.8 EFI Block I/O Protocol\r
// Driver Writer's Guide for UEFI 2.3.1 v1.01,\r
//   24.2 Block I/O Protocol Implementations\r
//\r
EFI_STATUS\r
EFIAPI\r
VirtioBlkReset (\r
  IN EFI_BLOCK_IO_PROTOCOL *This,\r
  IN BOOLEAN               ExtendedVerification\r
  );\r
\r
\r
/**\r
\r
  ReadBlocks() operation for virtio-blk.\r
\r
  See\r
  - UEFI Spec 2.3.1 + Errata C, 12.8 EFI Block I/O Protocol, 12.8 EFI Block I/O\r
    Protocol, EFI_BLOCK_IO_PROTOCOL.ReadBlocks().\r
  - Driver Writer's Guide for UEFI 2.3.1 v1.01, 24.2.2. ReadBlocks() and\r
    ReadBlocksEx() Implementation.\r
\r
  Parameter checks and conformant return values are implemented in\r
  VerifyReadWriteRequest() and SynchronousRequest().\r
\r
  A zero BufferSize doesn't seem to be prohibited, so do nothing in that case,\r
  successfully.\r
\r
**/\r
\r
EFI_STATUS\r
EFIAPI\r
VirtioBlkReadBlocks (\r
  IN  EFI_BLOCK_IO_PROTOCOL *This,\r
  IN  UINT32                MediaId,\r
  IN  EFI_LBA               Lba,\r
  IN  UINTN                 BufferSize,\r
  OUT VOID                  *Buffer\r
  );\r
\r
\r
/**\r
\r
  WriteBlocks() operation for virtio-blk.\r
\r
  See\r
  - UEFI Spec 2.3.1 + Errata C, 12.8 EFI Block I/O Protocol, 12.8 EFI Block I/O\r
    Protocol, EFI_BLOCK_IO_PROTOCOL.WriteBlocks().\r
  - Driver Writer's Guide for UEFI 2.3.1 v1.01, 24.2.3 WriteBlocks() and\r
    WriteBlockEx() Implementation.\r
\r
  Parameter checks and conformant return values are implemented in\r
  VerifyReadWriteRequest() and SynchronousRequest().\r
\r
  A zero BufferSize doesn't seem to be prohibited, so do nothing in that case,\r
  successfully.\r
\r
**/\r
\r
EFI_STATUS\r
EFIAPI\r
VirtioBlkWriteBlocks (\r
  IN EFI_BLOCK_IO_PROTOCOL *This,\r
  IN UINT32                MediaId,\r
  IN EFI_LBA               Lba,\r
  IN UINTN                 BufferSize,\r
  IN VOID                  *Buffer\r
  );\r
\r
\r
/**\r
\r
  FlushBlocks() operation for virtio-blk.\r
\r
  See\r
  - UEFI Spec 2.3.1 + Errata C, 12.8 EFI Block I/O Protocol, 12.8 EFI Block I/O\r
    Protocol, EFI_BLOCK_IO_PROTOCOL.FlushBlocks().\r
  - Driver Writer's Guide for UEFI 2.3.1 v1.01, 24.2.4 FlushBlocks() and\r
    FlushBlocksEx() Implementation.\r
\r
  If the underlying virtio-blk device doesn't support flushing (ie.\r
  write-caching), then this function should not be called by higher layers,\r
  according to EFI_BLOCK_IO_MEDIA characteristics set in VirtioBlkInit().\r
  Should they do nonetheless, we do nothing, successfully.\r
\r
**/\r
\r
EFI_STATUS\r
EFIAPI\r
VirtioBlkFlushBlocks (\r
  IN EFI_BLOCK_IO_PROTOCOL *This\r
  );\r
\r
\r
//\r
// The purpose of the following scaffolding (EFI_COMPONENT_NAME_PROTOCOL and\r
// EFI_COMPONENT_NAME2_PROTOCOL implementation) is to format the driver's name\r
// in English, for display on standard console devices. This is recommended for\r
// UEFI drivers that follow the UEFI Driver Model. Refer to the Driver Writer's\r
// Guide for UEFI 2.3.1 v1.01, 11 UEFI Driver and Controller Names.\r
//\r
// Device type names ("Virtio Block Device") are not formatted because the\r
// driver supports only that device type. Therefore the driver name suffices\r
// for unambiguous identification.\r
//\r
\r
EFI_STATUS\r
EFIAPI\r
VirtioBlkGetDriverName (\r
  IN  EFI_COMPONENT_NAME_PROTOCOL *This,\r
  IN  CHAR8                       *Language,\r
  OUT CHAR16                      **DriverName\r
  );\r
\r
EFI_STATUS\r
EFIAPI\r
VirtioBlkGetDeviceName (\r
  IN  EFI_COMPONENT_NAME_PROTOCOL *This,\r
  IN  EFI_HANDLE                  DeviceHandle,\r
  IN  EFI_HANDLE                  ChildHandle,\r
  IN  CHAR8                       *Language,\r
  OUT CHAR16                      **ControllerName\r
  );\r
Commit	Line	Data
fd51d759	1	/** @file\r
	2	\r
	3	Internal definitions for the virtio-blk driver, which produces Block I/O\r
	4	Protocol instances for virtio-blk devices.\r
	5	\r
	6	Copyright (C) 2012, Red Hat, Inc.\r
	7	\r
	8	This program and the accompanying materials are licensed and made available\r
	9	under the terms and conditions of the BSD License which accompanies this\r
	10	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, WITHOUT\r
	14	WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
	15	\r
	16	**/\r
	17	\r
	18	#include <Protocol/BlockIo.h>\r
	19	#include <Protocol/ComponentName.h>\r
	20	#include <Protocol/DriverBinding.h>\r
	21	#include <Protocol/PciIo.h>\r
	22	\r
	23	#include "Virtio.h"\r
	24	\r
	25	\r
	26	#define VBLK_SIG SIGNATURE_32 ('V', 'B', 'L', 'K')\r
	27	\r
	28	typedef struct {\r
	29	//\r
	30	// Parts of this structure are initialized / torn down in various functions\r
	31	// at various call depths. The table to the right should make it easier to\r
	32	// track them.\r
	33	//\r
	34	// field init function init dpth\r
	35	// ---------------------- ------------------ ---------\r
	36	UINT32 Signature; // DriverBindingStart 0\r
	37	EFI_PCI_IO_PROTOCOL *PciIo; // DriverBindingStart 0\r
	38	UINT64 OriginalPciAttributes; // DriverBindingStart 0\r
	39	VRING Ring; // VirtioRingInit 2\r
	40	EFI_BLOCK_IO_PROTOCOL BlockIo; // VirtioBlkInit 1\r
	41	EFI_BLOCK_IO_MEDIA BlockIoMedia; // VirtioBlkInit 1\r
	42	} VBLK_DEV;\r
	43	\r
	44	#define VIRTIO_BLK_FROM_BLOCK_IO(BlockIoPointer) \\r
	45	CR (BlockIoPointer, VBLK_DEV, BlockIo, VBLK_SIG)\r
	46	\r
	47	\r
	48	/**\r
	49	\r
	50	Device probe function for this driver.\r
	51	\r
	52	The DXE core calls this function for any given device in order to see if the\r
	53	driver can drive the device.\r
	54	\r
	55	Specs relevant in the general sense:\r
	56	\r
	57	- UEFI Spec 2.3.1 + Errata C:\r
	58	- 6.3 Protocol Handler Services -- for accessing the underlying device\r
	59	- 10.1 EFI Driver Binding Protocol -- for exporting ourselves\r
	60	\r
	61	- Driver Writer's Guide for UEFI 2.3.1 v1.01:\r
	62	- 5.1.3.4 OpenProtocol() and CloseProtocol() -- for accessing the\r
	63	underlying device\r
	64	- 9 Driver Binding Protocol -- for exporting ourselves\r
65	\r
66	Specs relevant in the specific sense:\r
67	- UEFI Spec 2.3.1 + Errata C, 13.4 EFI PCI I/O Protocol\r
68	- Driver Writer's Guide for UEFI 2.3.1 v1.01, 18 PCI Driver Design\r
69	Guidelines, 18.3 PCI drivers.\r
70	\r
71	@param[in] This The EFI_DRIVER_BINDING_PROTOCOL object\r
72	incorporating this driver (independently of\r
73	any device).\r
74	\r
75	@param[in] DeviceHandle The device to probe.\r
76	\r
77	@param[in] RemainingDevicePath Relevant only for bus drivers, ignored.\r
78	\r
79	\r
80	@retval EFI_SUCCESS The driver supports the device being probed.\r
81	\r
82	@retval EFI_UNSUPPORTED Based on virtio-blk PCI discovery, we do not support\r
83	the device.\r
84	\r
85	@return Error codes from the OpenProtocol() boot service or\r
86	the PciIo protocol.\r
87	\r
88	**/\r
89	\r
90	EFI_STATUS\r
91	EFIAPI\r
92	VirtioBlkDriverBindingSupported (\r
93	IN EFI_DRIVER_BINDING_PROTOCOL *This,\r
94	IN EFI_HANDLE DeviceHandle,\r
95	IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath\r
96	);\r
97	\r
98	\r
99	/**\r
100	\r
101	After we've pronounced support for a specific device in\r
102	DriverBindingSupported(), we start managing said device (passed in by the\r
103	Driver Exeuction Environment) with the following service.\r
104	\r
105	See DriverBindingSupported() for specification references.\r
106	\r
107	@param[in] This The EFI_DRIVER_BINDING_PROTOCOL object\r
108	incorporating this driver (independently of\r
109	any device).\r
110	\r
111	@param[in] DeviceHandle The supported device to drive.\r
112	\r
113	@param[in] RemainingDevicePath Relevant only for bus drivers, ignored.\r
114	\r
115	\r
116	@retval EFI_SUCCESS Driver instance has been created and\r
117	initialized for the virtio-blk PCI device, it\r
118	is now accessibla via EFI_BLOCK_IO_PROTOCOL.\r
119	\r
120	@retval EFI_OUT_OF_RESOURCES Memory allocation failed.\r
121	\r
122	@return Error codes from the OpenProtocol() boot\r
123	service, the PciIo protocol, VirtioBlkInit(),\r
124	or the InstallProtocolInterface() boot service.\r
125	\r
126	**/\r
127	\r
128	EFI_STATUS\r
129	EFIAPI\r
130	VirtioBlkDriverBindingStart (\r
131	IN EFI_DRIVER_BINDING_PROTOCOL *This,\r
132	IN EFI_HANDLE DeviceHandle,\r
133	IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath\r
134	);\r
135	\r
136	\r
137	/**\r
138	\r
139	Stop driving a virtio-blk device and remove its BlockIo interface.\r
140	\r
141	This function replays the success path of DriverBindingStart() in reverse.\r
142	The host side virtio-blk device is reset, so that the OS boot loader or the\r
143	OS may reinitialize it.\r
144	\r
145	@param[in] This The EFI_DRIVER_BINDING_PROTOCOL object\r
146	incorporating this driver (independently of any\r
147	device).\r
148	\r
149	@param[in] DeviceHandle Stop driving this device.\r
150	\r
151	@param[in] NumberOfChildren Since this function belongs to a device driver\r
152	only (as opposed to a bus driver), the caller\r
153	environment sets NumberOfChildren to zero, and\r
154	we ignore it.\r
155	\r
156	@param[in] ChildHandleBuffer Ignored (corresponding to NumberOfChildren).\r
157	\r
158	**/\r
159	\r
160	EFI_STATUS\r
161	EFIAPI\r
162	VirtioBlkDriverBindingStop (\r
163	IN EFI_DRIVER_BINDING_PROTOCOL *This,\r
164	IN EFI_HANDLE DeviceHandle,\r
165	IN UINTN NumberOfChildren,\r
166	IN EFI_HANDLE *ChildHandleBuffer\r
167	);\r
168	\r
169	\r
170	//\r
171	// UEFI Spec 2.3.1 + Errata C, 12.8 EFI Block I/O Protocol\r
172	// Driver Writer's Guide for UEFI 2.3.1 v1.01,\r
173	// 24.2 Block I/O Protocol Implementations\r
174	//\r
175	EFI_STATUS\r
176	EFIAPI\r
177	VirtioBlkReset (\r
178	IN EFI_BLOCK_IO_PROTOCOL *This,\r
179	IN BOOLEAN ExtendedVerification\r
180	);\r
181	\r
182	\r
183	/**\r
184	\r
185	ReadBlocks() operation for virtio-blk.\r
186	\r
187	See\r
188	- UEFI Spec 2.3.1 + Errata C, 12.8 EFI Block I/O Protocol, 12.8 EFI Block I/O\r
189	Protocol, EFI_BLOCK_IO_PROTOCOL.ReadBlocks().\r
190	- Driver Writer's Guide for UEFI 2.3.1 v1.01, 24.2.2. ReadBlocks() and\r
191	ReadBlocksEx() Implementation.\r
192	\r
193	Parameter checks and conformant return values are implemented in\r
194	VerifyReadWriteRequest() and SynchronousRequest().\r
195	\r
196	A zero BufferSize doesn't seem to be prohibited, so do nothing in that case,\r
197	successfully.\r
198	\r
199	**/\r
200	\r
201	EFI_STATUS\r
202	EFIAPI\r
203	VirtioBlkReadBlocks (\r
204	IN EFI_BLOCK_IO_PROTOCOL *This,\r
205	IN UINT32 MediaId,\r
206	IN EFI_LBA Lba,\r
207	IN UINTN BufferSize,\r
208	OUT VOID *Buffer\r
209	);\r
210	\r
211	\r
212	/**\r
213	\r
214	WriteBlocks() operation for virtio-blk.\r
215	\r
216	See\r
217	- UEFI Spec 2.3.1 + Errata C, 12.8 EFI Block I/O Protocol, 12.8 EFI Block I/O\r
218	Protocol, EFI_BLOCK_IO_PROTOCOL.WriteBlocks().\r
219	- Driver Writer's Guide for UEFI 2.3.1 v1.01, 24.2.3 WriteBlocks() and\r
220	WriteBlockEx() Implementation.\r
221	\r
222	Parameter checks and conformant return values are implemented in\r
223	VerifyReadWriteRequest() and SynchronousRequest().\r
224	\r
225	A zero BufferSize doesn't seem to be prohibited, so do nothing in that case,\r
226	successfully.\r
227	\r
228	**/\r
229	\r
230	EFI_STATUS\r
231	EFIAPI\r
232	VirtioBlkWriteBlocks (\r
233	IN EFI_BLOCK_IO_PROTOCOL *This,\r
234	IN UINT32 MediaId,\r
235	IN EFI_LBA Lba,\r
236	IN UINTN BufferSize,\r
237	IN VOID *Buffer\r
238	);\r
239	\r
240	\r
241	/**\r
242	\r
243	FlushBlocks() operation for virtio-blk.\r
244	\r
245	See\r
246	- UEFI Spec 2.3.1 + Errata C, 12.8 EFI Block I/O Protocol, 12.8 EFI Block I/O\r
247	Protocol, EFI_BLOCK_IO_PROTOCOL.FlushBlocks().\r
248	- Driver Writer's Guide for UEFI 2.3.1 v1.01, 24.2.4 FlushBlocks() and\r
249	FlushBlocksEx() Implementation.\r
250	\r
251	If the underlying virtio-blk device doesn't support flushing (ie.\r
252	write-caching), then this function should not be called by higher layers,\r
253	according to EFI_BLOCK_IO_MEDIA characteristics set in VirtioBlkInit().\r
254	Should they do nonetheless, we do nothing, successfully.\r
255	\r
256	**/\r
257	\r
258	EFI_STATUS\r
259	EFIAPI\r
260	VirtioBlkFlushBlocks (\r
261	IN EFI_BLOCK_IO_PROTOCOL *This\r
262	);\r
263	\r
264	\r
265	//\r
266	// The purpose of the following scaffolding (EFI_COMPONENT_NAME_PROTOCOL and\r
267	// EFI_COMPONENT_NAME2_PROTOCOL implementation) is to format the driver's name\r
268	// in English, for display on standard console devices. This is recommended for\r
269	// UEFI drivers that follow the UEFI Driver Model. Refer to the Driver Writer's\r
270	// Guide for UEFI 2.3.1 v1.01, 11 UEFI Driver and Controller Names.\r
271	//\r
272	// Device type names ("Virtio Block Device") are not formatted because the\r
273	// driver supports only that device type. Therefore the driver name suffices\r
274	// for unambiguous identification.\r
275	//\r
276	\r
277	EFI_STATUS\r
278	EFIAPI\r
279	VirtioBlkGetDriverName (\r
280	IN EFI_COMPONENT_NAME_PROTOCOL *This,\r
281	IN CHAR8 *Language,\r
282	OUT CHAR16 **DriverName\r
283	);\r
284	\r
285	EFI_STATUS\r
286	EFIAPI\r
287	VirtioBlkGetDeviceName (\r
288	IN EFI_COMPONENT_NAME_PROTOCOL *This,\r
289	IN EFI_HANDLE DeviceHandle,\r
290	IN EFI_HANDLE ChildHandle,\r
291	IN CHAR8 *Language,\r
292	OUT CHAR16 **ControllerName\r
293	);\r