VirtioBlk.h 8.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277
  1. /** @file
  2. Internal definitions for the virtio-blk driver, which produces Block I/O
  3. Protocol instances for virtio-blk devices.
  4. Copyright (C) 2012, Red Hat, Inc.
  5. SPDX-License-Identifier: BSD-2-Clause-Patent
  6. **/
  7. #ifndef _VIRTIO_BLK_DXE_H_
  8. #define _VIRTIO_BLK_DXE_H_
  9. #include <Protocol/BlockIo.h>
  10. #include <Protocol/ComponentName.h>
  11. #include <Protocol/DriverBinding.h>
  12. #include <IndustryStandard/Virtio.h>
  13. #define VBLK_SIG SIGNATURE_32 ('V', 'B', 'L', 'K')
  14. typedef struct {
  15. //
  16. // Parts of this structure are initialized / torn down in various functions
  17. // at various call depths. The table to the right should make it easier to
  18. // track them.
  19. //
  20. // field init function init dpth
  21. // --------------------- ------------------ ---------
  22. UINT32 Signature; // DriverBindingStart 0
  23. VIRTIO_DEVICE_PROTOCOL *VirtIo; // DriverBindingStart 0
  24. EFI_EVENT ExitBoot; // DriverBindingStart 0
  25. VRING Ring; // VirtioRingInit 2
  26. EFI_BLOCK_IO_PROTOCOL BlockIo; // VirtioBlkInit 1
  27. EFI_BLOCK_IO_MEDIA BlockIoMedia; // VirtioBlkInit 1
  28. VOID *RingMap; // VirtioRingMap 2
  29. } VBLK_DEV;
  30. #define VIRTIO_BLK_FROM_BLOCK_IO(BlockIoPointer) \
  31. CR (BlockIoPointer, VBLK_DEV, BlockIo, VBLK_SIG)
  32. /**
  33. Device probe function for this driver.
  34. The DXE core calls this function for any given device in order to see if the
  35. driver can drive the device.
  36. Specs relevant in the general sense:
  37. - UEFI Spec 2.3.1 + Errata C:
  38. - 6.3 Protocol Handler Services -- for accessing the underlying device
  39. - 10.1 EFI Driver Binding Protocol -- for exporting ourselves
  40. - Driver Writer's Guide for UEFI 2.3.1 v1.01:
  41. - 5.1.3.4 OpenProtocol() and CloseProtocol() -- for accessing the
  42. underlying device
  43. - 9 Driver Binding Protocol -- for exporting ourselves
  44. @param[in] This The EFI_DRIVER_BINDING_PROTOCOL object
  45. incorporating this driver (independently of
  46. any device).
  47. @param[in] DeviceHandle The device to probe.
  48. @param[in] RemainingDevicePath Relevant only for bus drivers, ignored.
  49. @retval EFI_SUCCESS The driver supports the device being probed.
  50. @retval EFI_UNSUPPORTED Based on virtio-blk discovery, we do not support
  51. the device.
  52. @return Error codes from the OpenProtocol() boot service.
  53. **/
  54. EFI_STATUS
  55. EFIAPI
  56. VirtioBlkDriverBindingSupported (
  57. IN EFI_DRIVER_BINDING_PROTOCOL *This,
  58. IN EFI_HANDLE DeviceHandle,
  59. IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath
  60. );
  61. /**
  62. After we've pronounced support for a specific device in
  63. DriverBindingSupported(), we start managing said device (passed in by the
  64. Driver Execution Environment) with the following service.
  65. See DriverBindingSupported() for specification references.
  66. @param[in] This The EFI_DRIVER_BINDING_PROTOCOL object
  67. incorporating this driver (independently of
  68. any device).
  69. @param[in] DeviceHandle The supported device to drive.
  70. @param[in] RemainingDevicePath Relevant only for bus drivers, ignored.
  71. @retval EFI_SUCCESS Driver instance has been created and
  72. initialized for the virtio-blk device, it
  73. is now accessible via EFI_BLOCK_IO_PROTOCOL.
  74. @retval EFI_OUT_OF_RESOURCES Memory allocation failed.
  75. @return Error codes from the OpenProtocol() boot
  76. service, VirtioBlkInit(), or the
  77. InstallProtocolInterface() boot service.
  78. **/
  79. EFI_STATUS
  80. EFIAPI
  81. VirtioBlkDriverBindingStart (
  82. IN EFI_DRIVER_BINDING_PROTOCOL *This,
  83. IN EFI_HANDLE DeviceHandle,
  84. IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath
  85. );
  86. /**
  87. Stop driving a virtio-blk device and remove its BlockIo interface.
  88. This function replays the success path of DriverBindingStart() in reverse.
  89. The host side virtio-blk device is reset, so that the OS boot loader or the
  90. OS may reinitialize it.
  91. @param[in] This The EFI_DRIVER_BINDING_PROTOCOL object
  92. incorporating this driver (independently of any
  93. device).
  94. @param[in] DeviceHandle Stop driving this device.
  95. @param[in] NumberOfChildren Since this function belongs to a device driver
  96. only (as opposed to a bus driver), the caller
  97. environment sets NumberOfChildren to zero, and
  98. we ignore it.
  99. @param[in] ChildHandleBuffer Ignored (corresponding to NumberOfChildren).
  100. **/
  101. EFI_STATUS
  102. EFIAPI
  103. VirtioBlkDriverBindingStop (
  104. IN EFI_DRIVER_BINDING_PROTOCOL *This,
  105. IN EFI_HANDLE DeviceHandle,
  106. IN UINTN NumberOfChildren,
  107. IN EFI_HANDLE *ChildHandleBuffer
  108. );
  109. //
  110. // UEFI Spec 2.3.1 + Errata C, 12.8 EFI Block I/O Protocol
  111. // Driver Writer's Guide for UEFI 2.3.1 v1.01,
  112. // 24.2 Block I/O Protocol Implementations
  113. //
  114. EFI_STATUS
  115. EFIAPI
  116. VirtioBlkReset (
  117. IN EFI_BLOCK_IO_PROTOCOL *This,
  118. IN BOOLEAN ExtendedVerification
  119. );
  120. /**
  121. ReadBlocks() operation for virtio-blk.
  122. See
  123. - UEFI Spec 2.3.1 + Errata C, 12.8 EFI Block I/O Protocol, 12.8 EFI Block I/O
  124. Protocol, EFI_BLOCK_IO_PROTOCOL.ReadBlocks().
  125. - Driver Writer's Guide for UEFI 2.3.1 v1.01, 24.2.2. ReadBlocks() and
  126. ReadBlocksEx() Implementation.
  127. Parameter checks and conformant return values are implemented in
  128. VerifyReadWriteRequest() and SynchronousRequest().
  129. A zero BufferSize doesn't seem to be prohibited, so do nothing in that case,
  130. successfully.
  131. **/
  132. EFI_STATUS
  133. EFIAPI
  134. VirtioBlkReadBlocks (
  135. IN EFI_BLOCK_IO_PROTOCOL *This,
  136. IN UINT32 MediaId,
  137. IN EFI_LBA Lba,
  138. IN UINTN BufferSize,
  139. OUT VOID *Buffer
  140. );
  141. /**
  142. WriteBlocks() operation for virtio-blk.
  143. See
  144. - UEFI Spec 2.3.1 + Errata C, 12.8 EFI Block I/O Protocol, 12.8 EFI Block I/O
  145. Protocol, EFI_BLOCK_IO_PROTOCOL.WriteBlocks().
  146. - Driver Writer's Guide for UEFI 2.3.1 v1.01, 24.2.3 WriteBlocks() and
  147. WriteBlockEx() Implementation.
  148. Parameter checks and conformant return values are implemented in
  149. VerifyReadWriteRequest() and SynchronousRequest().
  150. A zero BufferSize doesn't seem to be prohibited, so do nothing in that case,
  151. successfully.
  152. **/
  153. EFI_STATUS
  154. EFIAPI
  155. VirtioBlkWriteBlocks (
  156. IN EFI_BLOCK_IO_PROTOCOL *This,
  157. IN UINT32 MediaId,
  158. IN EFI_LBA Lba,
  159. IN UINTN BufferSize,
  160. IN VOID *Buffer
  161. );
  162. /**
  163. FlushBlocks() operation for virtio-blk.
  164. See
  165. - UEFI Spec 2.3.1 + Errata C, 12.8 EFI Block I/O Protocol, 12.8 EFI Block I/O
  166. Protocol, EFI_BLOCK_IO_PROTOCOL.FlushBlocks().
  167. - Driver Writer's Guide for UEFI 2.3.1 v1.01, 24.2.4 FlushBlocks() and
  168. FlushBlocksEx() Implementation.
  169. If the underlying virtio-blk device doesn't support flushing (ie.
  170. write-caching), then this function should not be called by higher layers,
  171. according to EFI_BLOCK_IO_MEDIA characteristics set in VirtioBlkInit().
  172. Should they do nonetheless, we do nothing, successfully.
  173. **/
  174. EFI_STATUS
  175. EFIAPI
  176. VirtioBlkFlushBlocks (
  177. IN EFI_BLOCK_IO_PROTOCOL *This
  178. );
  179. //
  180. // The purpose of the following scaffolding (EFI_COMPONENT_NAME_PROTOCOL and
  181. // EFI_COMPONENT_NAME2_PROTOCOL implementation) is to format the driver's name
  182. // in English, for display on standard console devices. This is recommended for
  183. // UEFI drivers that follow the UEFI Driver Model. Refer to the Driver Writer's
  184. // Guide for UEFI 2.3.1 v1.01, 11 UEFI Driver and Controller Names.
  185. //
  186. // Device type names ("Virtio Block Device") are not formatted because the
  187. // driver supports only that device type. Therefore the driver name suffices
  188. // for unambiguous identification.
  189. //
  190. EFI_STATUS
  191. EFIAPI
  192. VirtioBlkGetDriverName (
  193. IN EFI_COMPONENT_NAME_PROTOCOL *This,
  194. IN CHAR8 *Language,
  195. OUT CHAR16 **DriverName
  196. );
  197. EFI_STATUS
  198. EFIAPI
  199. VirtioBlkGetDeviceName (
  200. IN EFI_COMPONENT_NAME_PROTOCOL *This,
  201. IN EFI_HANDLE DeviceHandle,
  202. IN EFI_HANDLE ChildHandle,
  203. IN CHAR8 *Language,
  204. OUT CHAR16 **ControllerName
  205. );
  206. #endif // _VIRTIO_BLK_DXE_H_