1 /** @file 2 Virtio Device 3 4 DISCLAIMER: the VIRTIO_DEVICE_PROTOCOL introduced here is a work in progress, 5 and should not be used outside of the EDK II tree. 6 7 Copyright (c) 2013, ARM Ltd. All rights reserved.<BR> 8 9 This program and the accompanying materials are licensed and made available 10 under the terms and conditions of the BSD License which accompanies this 11 distribution. The full text of the license may be found at 12 http://opensource.org/licenses/bsd-license.php 13 14 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, WITHOUT 15 WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. 16 17 **/ 18 19 #ifndef __VIRTIO_DEVICE_H__ 20 #define __VIRTIO_DEVICE_H__ 21 22 // VirtIo Specification Revision: Major[31:24].Minor[23:16].Revision[15:0 23 #define VIRTIO_SPEC_REVISION(major,minor,revision) \ 24 ((((major) & 0xFF) << 24) | (((minor) & 0xFF) << 16) | ((revision) & 0xFFFF)) 25 26 #define VIRTIO_DEVICE_PROTOCOL_GUID { \ 27 0xfa920010, 0x6785, 0x4941, {0xb6, 0xec, 0x49, 0x8c, 0x57, 0x9f, 0x16, 0x0a }\ 28 } 29 30 typedef struct _VIRTIO_DEVICE_PROTOCOL VIRTIO_DEVICE_PROTOCOL; 31 32 /** 33 34 Read a word from the device-specific I/O region of the Virtio Header. 35 36 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL 37 38 @param[in] FieldOffset Source offset. 39 40 @param[in] FieldSize Source field size in bytes, must be in {1, 2, 4, 8}. 41 42 @param[in] BufferSize Number of bytes available in the target buffer. Must 43 equal FieldSize. 44 45 @param[out] Buffer Target buffer. 46 47 @retval EFI_SUCCESS The data was read successfully. 48 @retval EFI_UNSUPPORTED The underlying IO device doesn't support the 49 provided address offset and read size. 50 @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a 51 lack of resources. 52 @retval EFI_INVALID_PARAMETER One or more parameters are invalid. 53 54 **/ 55 typedef 56 EFI_STATUS 57 (EFIAPI *VIRTIO_DEVICE_READ) ( 58 IN VIRTIO_DEVICE_PROTOCOL *This, 59 IN UINTN FieldOffset, 60 IN UINTN FieldSize, 61 IN UINTN BufferSize, 62 OUT VOID *Buffer 63 ); 64 65 /** 66 67 Write a word to the device-specific I/O region of the Virtio Header. 68 69 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL 70 71 @param[in] FieldOffset Destination offset. 72 73 @param[in] FieldSize Destination field size in bytes, 74 must be in {1, 2, 4, 8}. 75 76 @param[out] Value Value to write. 77 78 @retval EFI_SUCCESS The data was written successfully. 79 @retval EFI_UNSUPPORTED The underlying IO device doesn't support the 80 provided address offset and write size. 81 @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a 82 lack of resources. 83 @retval EFI_INVALID_PARAMETER One or more parameters are invalid. 84 85 **/ 86 typedef 87 EFI_STATUS 88 (EFIAPI *VIRTIO_DEVICE_WRITE) ( 89 IN VIRTIO_DEVICE_PROTOCOL *This, 90 IN UINTN FieldOffset, 91 IN UINTN FieldSize, 92 IN UINT64 Value 93 ); 94 95 /** 96 Read the device features field from the Virtio Header. 97 98 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL 99 100 @param[out] DeviceFeatures The 32-bit device features field. 101 102 @retval EFI_SUCCESS The data was read successfully. 103 @retval EFI_UNSUPPORTED The underlying IO device doesn't support the 104 provided address offset and read size. 105 @retval EFI_INVALID_PARAMETER DeviceFeatures is NULL 106 **/ 107 typedef 108 EFI_STATUS 109 (EFIAPI *VIRTIO_GET_DEVICE_FEATURES) ( 110 IN VIRTIO_DEVICE_PROTOCOL *This, 111 OUT UINT32 *DeviceFeatures 112 ); 113 114 /** 115 Write the guest features field in the Virtio Header. 116 117 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL 118 119 @param[in] Features The 32-bit guest guest features field 120 121 **/ 122 typedef 123 EFI_STATUS 124 (EFIAPI *VIRTIO_SET_GUEST_FEATURES) ( 125 IN VIRTIO_DEVICE_PROTOCOL *This, 126 IN UINT32 Features 127 ); 128 129 /** 130 Read the queue address field from the Virtio Header. 131 132 QueueAddress is the address of the virtqueue divided by 4096. 133 134 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL 135 136 @param[out] QueueAddress The 32-bit queue address field. 137 138 @retval EFI_SUCCESS The data was read successfully. 139 @retval EFI_UNSUPPORTED The underlying IO device doesn't support the 140 provided address offset and read size. 141 @retval EFI_INVALID_PARAMETER QueueAddress is NULL 142 **/ 143 typedef 144 EFI_STATUS 145 (EFIAPI *VIRTIO_GET_QUEUE_ADDRESS) ( 146 IN VIRTIO_DEVICE_PROTOCOL *This, 147 OUT UINT32 *QueueAddress 148 ); 149 150 /** 151 Write the queue address field in the Virtio Header. 152 153 The parameter Address must be the base address of the virtqueue divided 154 by 4096. 155 156 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL 157 158 @param[in] Address The 32-bit Queue Address field 159 160 @retval EFI_SUCCESS The data was written successfully. 161 @retval EFI_UNSUPPORTED The underlying IO device doesn't support the 162 provided address offset and write size. 163 **/ 164 typedef 165 EFI_STATUS 166 (EFIAPI *VIRTIO_SET_QUEUE_ADDRESS) ( 167 IN VIRTIO_DEVICE_PROTOCOL *This, 168 IN UINT32 Address 169 ); 170 171 /** 172 173 Write the queue select field in the Virtio Header. 174 175 Writing to the queue select field sets the index of the queue to which 176 operations such as SetQueueAlign and GetQueueNumMax apply. 177 178 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL 179 180 @param[in] Index The index of the queue to select 181 182 @retval EFI_SUCCESS The data was written successfully. 183 @retval EFI_UNSUPPORTED The underlying IO device doesn't support the 184 provided address offset and write size. 185 **/ 186 typedef 187 EFI_STATUS 188 (EFIAPI *VIRTIO_SET_QUEUE_SEL) ( 189 IN VIRTIO_DEVICE_PROTOCOL *This, 190 IN UINT16 Index 191 ); 192 193 /** 194 195 Write the queue notify field in the Virtio Header. 196 197 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL 198 199 @param[in] Address The 32-bit Queue Notify field 200 201 @retval EFI_SUCCESS The data was written successfully. 202 @retval EFI_UNSUPPORTED The underlying IO device doesn't support the 203 provided address offset and write size. 204 **/ 205 typedef 206 EFI_STATUS 207 (EFIAPI *VIRTIO_SET_QUEUE_NOTIFY) ( 208 IN VIRTIO_DEVICE_PROTOCOL *This, 209 IN UINT16 Index 210 ); 211 212 /** 213 Write the queue alignment field in the Virtio Header. 214 215 The queue to which the alignment applies is selected by the Queue Select 216 field. 217 218 Note: This operation is not implemented by the VirtIo over PCI. The PCI 219 implementation of this protocol returns EFI_SUCCESS. 220 221 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL 222 223 @param[in] Alignment The alignment boundary of the Used Ring in bytes. 224 Must be a power of 2. 225 226 @retval EFI_SUCCESS The data was written successfully. 227 @retval EFI_UNSUPPORTED The underlying IO device doesn't support the 228 provided address offset and write size. 229 **/ 230 typedef 231 EFI_STATUS 232 (EFIAPI *VIRTIO_SET_QUEUE_ALIGN) ( 233 IN VIRTIO_DEVICE_PROTOCOL *This, 234 IN UINT32 Alignment 235 ); 236 237 /** 238 Write the guest page size. 239 240 Note: This operation is not implemented by the VirtIo over PCI. The PCI 241 implementation of this protocol returns EFI_SUCCESS. 242 243 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL 244 245 @param[in] PageSize Size of the Guest page in bytes. 246 Must be a power of 2. 247 248 @retval EFI_SUCCESS The data was written successfully. 249 @retval EFI_UNSUPPORTED The underlying IO device doesn't support the 250 provided address offset and write size. 251 **/ 252 typedef 253 EFI_STATUS 254 (EFIAPI *VIRTIO_SET_PAGE_SIZE) ( 255 IN VIRTIO_DEVICE_PROTOCOL *This, 256 IN UINT32 PageSize 257 ); 258 259 /** 260 261 Get the size of the virtqueue selected by the queue select field. 262 263 See Virtio spec Section 2.3 264 265 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL 266 267 @param[out] QueueNumMax The size of the virtqueue in bytes. 268 Always a power of 2. 269 270 @retval EFI_SUCCESS The data was read successfully. 271 @retval EFI_UNSUPPORTED The underlying IO device doesn't support the 272 provided address offset and read size. 273 @retval EFI_INVALID_PARAMETER QueueNumMax is NULL 274 **/ 275 typedef 276 EFI_STATUS 277 (EFIAPI *VIRTIO_GET_QUEUE_NUM_MAX) ( 278 IN VIRTIO_DEVICE_PROTOCOL *This, 279 OUT UINT16 *QueueNumMax 280 ); 281 282 /** 283 284 Write to the QueueNum field in the Virtio Header. 285 286 This function only applies to Virtio-MMIO and may be a stub for other 287 implementations. See Virtio Spec appendix X. 288 289 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL 290 291 @param[in] QueueSize The number of elements in the queue. 292 293 @retval EFI_SUCCESS The data was written successfully. 294 @retval EFI_UNSUPPORTED The underlying IO device doesn't support the 295 provided address offset and write size. 296 **/ 297 typedef 298 EFI_STATUS 299 (EFIAPI *VIRTIO_SET_QUEUE_NUM) ( 300 IN VIRTIO_DEVICE_PROTOCOL *This, 301 IN UINT16 QueueSize 302 ); 303 304 /** 305 306 Get the DeviceStatus field from the Virtio Header. 307 308 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL 309 310 @param[out] DeviceStatus The 8-bit value for the Device status field 311 312 @retval EFI_SUCCESS The data was read successfully. 313 @retval EFI_UNSUPPORTED The underlying IO device doesn't support the 314 provided address offset and read size. 315 @retval EFI_INVALID_PARAMETER DeviceStatus is NULL 316 **/ 317 typedef 318 EFI_STATUS 319 (EFIAPI *VIRTIO_GET_DEVICE_STATUS) ( 320 IN VIRTIO_DEVICE_PROTOCOL *This, 321 OUT UINT8 *DeviceStatus 322 ); 323 324 /** 325 326 Write the DeviceStatus field in the Virtio Header. 327 328 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL 329 330 @param[in] DeviceStatus The 8-bit value for the Device status field 331 332 @retval EFI_SUCCESS The data was written successfully. 333 @retval EFI_UNSUPPORTED The underlying IO device doesn't support the 334 provided address offset and write size. 335 **/ 336 typedef 337 EFI_STATUS 338 (EFIAPI *VIRTIO_SET_DEVICE_STATUS) ( 339 IN VIRTIO_DEVICE_PROTOCOL *This, 340 IN UINT8 DeviceStatus 341 ); 342 343 344 /// 345 /// This protocol provides an abstraction over the VirtIo transport layer 346 /// 347 /// DISCLAIMER: this protocol is a work in progress, and should not be used 348 /// outside of the EDK II tree. 349 /// 350 struct _VIRTIO_DEVICE_PROTOCOL { 351 /// VirtIo Specification Revision encoded with VIRTIO_SPEC_REVISION() 352 UINT32 Revision; 353 /// From the Virtio Spec 354 INT32 SubSystemDeviceId; 355 356 VIRTIO_GET_DEVICE_FEATURES GetDeviceFeatures; 357 VIRTIO_SET_GUEST_FEATURES SetGuestFeatures; 358 359 VIRTIO_GET_QUEUE_ADDRESS GetQueueAddress; 360 VIRTIO_SET_QUEUE_ADDRESS SetQueueAddress; 361 362 VIRTIO_SET_QUEUE_SEL SetQueueSel; 363 364 VIRTIO_SET_QUEUE_NOTIFY SetQueueNotify; 365 366 VIRTIO_SET_QUEUE_ALIGN SetQueueAlign; 367 VIRTIO_SET_PAGE_SIZE SetPageSize; 368 369 VIRTIO_GET_QUEUE_NUM_MAX GetQueueNumMax; 370 VIRTIO_SET_QUEUE_NUM SetQueueNum; 371 372 VIRTIO_GET_DEVICE_STATUS GetDeviceStatus; 373 VIRTIO_SET_DEVICE_STATUS SetDeviceStatus; 374 375 // Functions to read/write Device Specific headers 376 VIRTIO_DEVICE_WRITE WriteDevice; 377 VIRTIO_DEVICE_READ ReadDevice; 378 }; 379 380 extern EFI_GUID gVirtioDeviceProtocolGuid; 381 382 #endif 383