VirtualBox

source: vbox/trunk/src/VBox/Devices/EFI/Firmware/OvmfPkg/VirtioBlkDxe/VirtioBlk.h@ 58803

Last change on this file since 58803 was 58464, checked in by vboxsync, 9 years ago

EFI/Firmware: Export new files and directories.

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

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette