1 /** @file 2 3 Utility functions used by virtio device drivers. 4 5 Copyright (C) 2012-2016, Red Hat, Inc. 6 Portion of Copyright (C) 2013, ARM Ltd. 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 #include <Library/BaseLib.h> 19 #include <Library/BaseMemoryLib.h> 20 #include <Library/DebugLib.h> 21 #include <Library/MemoryAllocationLib.h> 22 #include <Library/UefiBootServicesTableLib.h> 23 24 #include <Library/VirtioLib.h> 25 26 27 /** 28 29 Configure a virtio ring. 30 31 This function sets up internal storage (the guest-host communication area) 32 and lays out several "navigation" (ie. no-ownership) pointers to parts of 33 that storage. 34 35 Relevant sections from the virtio-0.9.5 spec: 36 - 1.1 Virtqueues, 37 - 2.3 Virtqueue Configuration. 38 39 @param[in] The number of descriptors to allocate for the 40 virtio ring, as requested by the host. 41 42 @param[out] Ring The virtio ring to set up. 43 44 @retval EFI_OUT_OF_RESOURCES AllocatePages() failed to allocate contiguous 45 pages for the requested QueueSize. Fields of 46 Ring have indeterminate value. 47 48 @retval EFI_SUCCESS Allocation and setup successful. Ring->Base 49 (and nothing else) is responsible for 50 deallocation. 51 52 **/ 53 EFI_STATUS 54 EFIAPI 55 VirtioRingInit ( 56 IN UINT16 QueueSize, 57 OUT VRING *Ring 58 ) 59 { 60 UINTN RingSize; 61 volatile UINT8 *RingPagesPtr; 62 63 RingSize = ALIGN_VALUE ( 64 sizeof *Ring->Desc * QueueSize + 65 sizeof *Ring->Avail.Flags + 66 sizeof *Ring->Avail.Idx + 67 sizeof *Ring->Avail.Ring * QueueSize + 68 sizeof *Ring->Avail.UsedEvent, 69 EFI_PAGE_SIZE); 70 71 RingSize += ALIGN_VALUE ( 72 sizeof *Ring->Used.Flags + 73 sizeof *Ring->Used.Idx + 74 sizeof *Ring->Used.UsedElem * QueueSize + 75 sizeof *Ring->Used.AvailEvent, 76 EFI_PAGE_SIZE); 77 78 Ring->NumPages = EFI_SIZE_TO_PAGES (RingSize); 79 Ring->Base = AllocatePages (Ring->NumPages); 80 if (Ring->Base == NULL) { 81 return EFI_OUT_OF_RESOURCES; 82 } 83 SetMem (Ring->Base, RingSize, 0x00); 84 RingPagesPtr = Ring->Base; 85 86 Ring->Desc = (volatile VOID *) RingPagesPtr; 87 RingPagesPtr += sizeof *Ring->Desc * QueueSize; 88 89 Ring->Avail.Flags = (volatile VOID *) RingPagesPtr; 90 RingPagesPtr += sizeof *Ring->Avail.Flags; 91 92 Ring->Avail.Idx = (volatile VOID *) RingPagesPtr; 93 RingPagesPtr += sizeof *Ring->Avail.Idx; 94 95 Ring->Avail.Ring = (volatile VOID *) RingPagesPtr; 96 RingPagesPtr += sizeof *Ring->Avail.Ring * QueueSize; 97 98 Ring->Avail.UsedEvent = (volatile VOID *) RingPagesPtr; 99 RingPagesPtr += sizeof *Ring->Avail.UsedEvent; 100 101 RingPagesPtr = (volatile UINT8 *) Ring->Base + 102 ALIGN_VALUE (RingPagesPtr - (volatile UINT8 *) Ring->Base, 103 EFI_PAGE_SIZE); 104 105 Ring->Used.Flags = (volatile VOID *) RingPagesPtr; 106 RingPagesPtr += sizeof *Ring->Used.Flags; 107 108 Ring->Used.Idx = (volatile VOID *) RingPagesPtr; 109 RingPagesPtr += sizeof *Ring->Used.Idx; 110 111 Ring->Used.UsedElem = (volatile VOID *) RingPagesPtr; 112 RingPagesPtr += sizeof *Ring->Used.UsedElem * QueueSize; 113 114 Ring->Used.AvailEvent = (volatile VOID *) RingPagesPtr; 115 RingPagesPtr += sizeof *Ring->Used.AvailEvent; 116 117 Ring->QueueSize = QueueSize; 118 return EFI_SUCCESS; 119 } 120 121 122 /** 123 124 Tear down the internal resources of a configured virtio ring. 125 126 The caller is responsible to stop the host from using this ring before 127 invoking this function: the VSTAT_DRIVER_OK bit must be clear in 128 VhdrDeviceStatus. 129 130 @param[out] Ring The virtio ring to clean up. 131 132 **/ 133 VOID 134 EFIAPI 135 VirtioRingUninit ( 136 IN OUT VRING *Ring 137 ) 138 { 139 FreePages (Ring->Base, Ring->NumPages); 140 SetMem (Ring, sizeof *Ring, 0x00); 141 } 142 143 144 /** 145 146 Turn off interrupt notifications from the host, and prepare for appending 147 multiple descriptors to the virtio ring. 148 149 The calling driver must be in VSTAT_DRIVER_OK state. 150 151 @param[in,out] Ring The virtio ring we intend to append descriptors to. 152 153 @param[out] Indices The DESC_INDICES structure to initialize. 154 155 **/ 156 VOID 157 EFIAPI 158 VirtioPrepare ( 159 IN OUT VRING *Ring, 160 OUT DESC_INDICES *Indices 161 ) 162 { 163 // 164 // Prepare for virtio-0.9.5, 2.4.2 Receiving Used Buffers From the Device. 165 // We're going to poll the answer, the host should not send an interrupt. 166 // 167 *Ring->Avail.Flags = (UINT16) VRING_AVAIL_F_NO_INTERRUPT; 168 169 // 170 // Prepare for virtio-0.9.5, 2.4.1 Supplying Buffers to the Device. 171 // 172 // Since we support only one in-flight descriptor chain, we can always build 173 // that chain starting at entry #0 of the descriptor table. 174 // 175 Indices->HeadDescIdx = 0; 176 Indices->NextDescIdx = Indices->HeadDescIdx; 177 } 178 179 180 /** 181 182 Append a contiguous buffer for transmission / reception via the virtio ring. 183 184 This function implements the following section from virtio-0.9.5: 185 - 2.4.1.1 Placing Buffers into the Descriptor Table 186 187 Free space is taken as granted, since the individual drivers support only 188 synchronous requests and host side status is processed in lock-step with 189 request submission. It is the calling driver's responsibility to verify the 190 ring size in advance. 191 192 The caller is responsible for initializing *Indices with VirtioPrepare() 193 first. 194 195 @param[in,out] Ring The virtio ring to append the buffer to, as a 196 descriptor. 197 198 @param[in] BufferPhysAddr (Guest pseudo-physical) start address of the 199 transmit / receive buffer. 200 201 @param[in] BufferSize Number of bytes to transmit or receive. 202 203 @param[in] Flags A bitmask of VRING_DESC_F_* flags. The caller 204 computes this mask dependent on further buffers to 205 append and transfer direction. 206 VRING_DESC_F_INDIRECT is unsupported. The 207 VRING_DESC.Next field is always set, but the host 208 only interprets it dependent on VRING_DESC_F_NEXT. 209 210 @param[in,out] Indices Indices->HeadDescIdx is not accessed. 211 On input, Indices->NextDescIdx identifies the next 212 descriptor to carry the buffer. On output, 213 Indices->NextDescIdx is incremented by one, modulo 214 2^16. 215 216 **/ 217 VOID 218 EFIAPI 219 VirtioAppendDesc ( 220 IN OUT VRING *Ring, 221 IN UINTN BufferPhysAddr, 222 IN UINT32 BufferSize, 223 IN UINT16 Flags, 224 IN OUT DESC_INDICES *Indices 225 ) 226 { 227 volatile VRING_DESC *Desc; 228 229 Desc = &Ring->Desc[Indices->NextDescIdx++ % Ring->QueueSize]; 230 Desc->Addr = BufferPhysAddr; 231 Desc->Len = BufferSize; 232 Desc->Flags = Flags; 233 Desc->Next = Indices->NextDescIdx % Ring->QueueSize; 234 } 235 236 237 /** 238 239 Notify the host about the descriptor chain just built, and wait until the 240 host processes it. 241 242 @param[in] VirtIo The target virtio device to notify. 243 244 @param[in] VirtQueueId Identifies the queue for the target device. 245 246 @param[in,out] Ring The virtio ring with descriptors to submit. 247 248 @param[in] Indices Indices->NextDescIdx is not accessed. 249 Indices->HeadDescIdx identifies the head descriptor 250 of the descriptor chain. 251 252 @param[out] UsedLen On success, the total number of bytes, consecutively 253 across the buffers linked by the descriptor chain, 254 that the host wrote. May be NULL if the caller 255 doesn't care, or can compute the same information 256 from device-specific request structures linked by the 257 descriptor chain. 258 259 @return Error code from VirtIo->SetQueueNotify() if it fails. 260 261 @retval EFI_SUCCESS Otherwise, the host processed all descriptors. 262 263 **/ 264 EFI_STATUS 265 EFIAPI 266 VirtioFlush ( 267 IN VIRTIO_DEVICE_PROTOCOL *VirtIo, 268 IN UINT16 VirtQueueId, 269 IN OUT VRING *Ring, 270 IN DESC_INDICES *Indices, 271 OUT UINT32 *UsedLen OPTIONAL 272 ) 273 { 274 UINT16 NextAvailIdx; 275 UINT16 LastUsedIdx; 276 EFI_STATUS Status; 277 UINTN PollPeriodUsecs; 278 279 // 280 // virtio-0.9.5, 2.4.1.2 Updating the Available Ring 281 // 282 // It is not exactly clear from the wording of the virtio-0.9.5 283 // specification, but each entry in the Available Ring references only the 284 // head descriptor of any given descriptor chain. 285 // 286 NextAvailIdx = *Ring->Avail.Idx; 287 // 288 // (Due to our lock-step progress, this is where the host will produce the 289 // used element with the head descriptor's index in it.) 290 // 291 LastUsedIdx = NextAvailIdx; 292 Ring->Avail.Ring[NextAvailIdx++ % Ring->QueueSize] = 293 Indices->HeadDescIdx % Ring->QueueSize; 294 295 // 296 // virtio-0.9.5, 2.4.1.3 Updating the Index Field 297 // 298 MemoryFence(); 299 *Ring->Avail.Idx = NextAvailIdx; 300 301 // 302 // virtio-0.9.5, 2.4.1.4 Notifying the Device -- gratuitous notifications are 303 // OK. 304 // 305 MemoryFence(); 306 Status = VirtIo->SetQueueNotify (VirtIo, VirtQueueId); 307 if (EFI_ERROR (Status)) { 308 return Status; 309 } 310 311 // 312 // virtio-0.9.5, 2.4.2 Receiving Used Buffers From the Device 313 // Wait until the host processes and acknowledges our descriptor chain. The 314 // condition we use for polling is greatly simplified and relies on the 315 // synchronous, lock-step progress. 316 // 317 // Keep slowing down until we reach a poll period of slightly above 1 ms. 318 // 319 PollPeriodUsecs = 1; 320 MemoryFence(); 321 while (*Ring->Used.Idx != NextAvailIdx) { 322 gBS->Stall (PollPeriodUsecs); // calls AcpiTimerLib::MicroSecondDelay 323 324 if (PollPeriodUsecs < 1024) { 325 PollPeriodUsecs *= 2; 326 } 327 MemoryFence(); 328 } 329 330 MemoryFence(); 331 332 if (UsedLen != NULL) { 333 volatile CONST VRING_USED_ELEM *UsedElem; 334 335 UsedElem = &Ring->Used.UsedElem[LastUsedIdx % Ring->QueueSize]; 336 ASSERT (UsedElem->Id == Indices->HeadDescIdx); 337 *UsedLen = UsedElem->Len; 338 } 339 340 return EFI_SUCCESS; 341 } 342 343 344 /** 345 346 Report the feature bits to the VirtIo 1.0 device that the VirtIo 1.0 driver 347 understands. 348 349 In VirtIo 1.0, a device can reject a self-inconsistent feature bitmap through 350 the new VSTAT_FEATURES_OK status bit. (For example if the driver requests a 351 higher level feature but clears a prerequisite feature.) This function is a 352 small wrapper around VIRTIO_DEVICE_PROTOCOL.SetGuestFeatures() that also 353 verifies if the VirtIo 1.0 device accepts the feature bitmap. 354 355 @param[in] VirtIo Report feature bits to this device. 356 357 @param[in] Features The set of feature bits that the driver wishes 358 to report. The caller is responsible to perform 359 any masking before calling this function; the 360 value is directly written with 361 VIRTIO_DEVICE_PROTOCOL.SetGuestFeatures(). 362 363 @param[in,out] DeviceStatus On input, the status byte most recently written 364 to the device's status register. On output (even 365 on error), DeviceStatus will be updated so that 366 it is suitable for further status bit 367 manipulation and writing to the device's status 368 register. 369 370 @retval EFI_SUCCESS The device accepted the configuration in Features. 371 372 @return EFI_UNSUPPORTED The device rejected the configuration in Features. 373 374 @retval EFI_UNSUPPORTED VirtIo->Revision is smaller than 1.0.0. 375 376 @return Error codes from the SetGuestFeatures(), 377 SetDeviceStatus(), GetDeviceStatus() member 378 functions. 379 380 **/ 381 EFI_STATUS 382 EFIAPI 383 Virtio10WriteFeatures ( 384 IN VIRTIO_DEVICE_PROTOCOL *VirtIo, 385 IN UINT64 Features, 386 IN OUT UINT8 *DeviceStatus 387 ) 388 { 389 EFI_STATUS Status; 390 391 if (VirtIo->Revision < VIRTIO_SPEC_REVISION (1, 0, 0)) { 392 return EFI_UNSUPPORTED; 393 } 394 395 Status = VirtIo->SetGuestFeatures (VirtIo, Features); 396 if (EFI_ERROR (Status)) { 397 return Status; 398 } 399 400 *DeviceStatus |= VSTAT_FEATURES_OK; 401 Status = VirtIo->SetDeviceStatus (VirtIo, *DeviceStatus); 402 if (EFI_ERROR (Status)) { 403 return Status; 404 } 405 406 Status = VirtIo->GetDeviceStatus (VirtIo, DeviceStatus); 407 if (EFI_ERROR (Status)) { 408 return Status; 409 } 410 411 if ((*DeviceStatus & VSTAT_FEATURES_OK) == 0) { 412 Status = EFI_UNSUPPORTED; 413 } 414 415 return Status; 416 } 417
