OvmfPkg/VirtioScsiDxe/VirtioScsi.c

   1 /** @file
   2
   3   This driver produces Extended SCSI Pass Thru Protocol instances for
   4   virtio-scsi devices.
   5
   6   The implementation is basic:
   7
   8   - No hotplug / hot-unplug.
   9
  10   - Although EFI_EXT_SCSI_PASS_THRU_PROTOCOL.PassThru() could be a good match
  11     for multiple in-flight virtio-scsi requests, we stick to synchronous
  12     requests for now.
  13
  14   - Timeouts are not supported for EFI_EXT_SCSI_PASS_THRU_PROTOCOL.PassThru().
  15
  16   - Only one channel is supported. (At the time of this writing, host-side
  17     virtio-scsi supports a single channel too.)
  18
  19   - Only one request queue is used (for the one synchronous request).
  20
  21   - The ResetChannel() and ResetTargetLun() functions of
  22     EFI_EXT_SCSI_PASS_THRU_PROTOCOL are not supported (which is allowed by the
  23     UEFI 2.3.1 Errata C specification), although
  24     VIRTIO_SCSI_T_TMF_LOGICAL_UNIT_RESET could be a good match. That would
  25     however require client code for the control queue, which is deemed
  26     unreasonable for now.
  27
  28   Copyright (C) 2012, Red Hat, Inc.
  29   Copyright (c) 2012 - 2014, Intel Corporation. All rights reserved.<BR>
  30   Copyright (c) 2017, AMD Inc, All rights reserved.<BR>
  31
  32   This program and the accompanying materials are licensed and made available
  33   under the terms and conditions of the BSD License which accompanies this
  34   distribution. The full text of the license may be found at
  35   http://opensource.org/licenses/bsd-license.php
  36
  37   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, WITHOUT
  38   WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  39
  40 **/
  41
  42 #include <IndustryStandard/VirtioScsi.h>
  43 #include <Library/BaseMemoryLib.h>
  44 #include <Library/DebugLib.h>
  45 #include <Library/MemoryAllocationLib.h>
  46 #include <Library/UefiBootServicesTableLib.h>
  47 #include <Library/UefiLib.h>
  48 #include <Library/VirtioLib.h>
  49
  50 #include "VirtioScsi.h"
  51
  52 /**
  53
  54   Convenience macros to read and write configuration elements of the
  55   virtio-scsi VirtIo device.
  56
  57   The following macros make it possible to specify only the "core parameters"
  58   for such accesses and to derive the rest. By the time VIRTIO_CFG_WRITE()
  59   returns, the transaction will have been completed.
  60
  61   @param[in] Dev       Pointer to the VSCSI_DEV structure.
  62
  63   @param[in] Field     A field name from VSCSI_HDR, identifying the virtio-scsi
  64                        configuration item to access.
  65
  66   @param[in] Value     (VIRTIO_CFG_WRITE() only.) The value to write to the
  67                        selected configuration item.
  68
  69   @param[out] Pointer  (VIRTIO_CFG_READ() only.) The object to receive the
  70                        value read from the configuration item. Its type must be
  71                        one of UINT8, UINT16, UINT32, UINT64.
  72
  73
  74   @return  Status codes returned by Virtio->WriteDevice() / Virtio->ReadDevice().
  75
  76 **/
  77
  78 #define VIRTIO_CFG_WRITE(Dev, Field, Value)  ((Dev)->VirtIo->WriteDevice (  \
  79                                                 (Dev)->VirtIo,              \
  80                                                 OFFSET_OF_VSCSI (Field),    \
  81                                                 SIZE_OF_VSCSI (Field),      \
  82                                                 (Value)                     \
  83                                                 ))
  84
  85 #define VIRTIO_CFG_READ(Dev, Field, Pointer) ((Dev)->VirtIo->ReadDevice (   \
  86                                                 (Dev)->VirtIo,              \
  87                                                 OFFSET_OF_VSCSI (Field),    \
  88                                                 SIZE_OF_VSCSI (Field),      \
  89                                                 sizeof *(Pointer),          \
  90                                                 (Pointer)                   \
  91                                                 ))
  92
  93
  94 //
  95 // UEFI Spec 2.3.1 + Errata C, 14.7 Extended SCSI Pass Thru Protocol specifies
  96 // the PassThru() interface. Beside returning a status code, the function must
  97 // set some fields in the EFI_EXT_SCSI_PASS_THRU_SCSI_REQUEST_PACKET in/out
  98 // parameter on return. The following is a full list of those fields, for
  99 // easier validation of PopulateRequest(), ParseResponse(), and
 100 // ReportHostAdapterError() below.
 101 //
 102 // - InTransferLength
 103 // - OutTransferLength
 104 // - HostAdapterStatus
 105 // - TargetStatus
 106 // - SenseDataLength
 107 // - SenseData
 108 //
 109 // On any return from the PassThru() interface, these fields must be set,
 110 // except if the returned status code is explicitly exempt. (Actually the
 111 // implementation here conservatively sets these fields even in case not all
 112 // of them would be required by the specification.)
 113 //
 114
 115 /**
 116
 117   Populate a virtio-scsi request from the Extended SCSI Pass Thru Protocol
 118   packet.
 119
 120   The caller is responsible for pre-zeroing the virtio-scsi request. The
 121   Extended SCSI Pass Thru Protocol packet is modified, to be forwarded outwards
 122   by VirtioScsiPassThru(), if invalid or unsupported parameters are detected.
 123
 124   @param[in] Dev          The virtio-scsi host device the packet targets.
 125
 126   @param[in] Target       The SCSI target controlled by the virtio-scsi host
 127                           device.
 128
 129   @param[in] Lun          The Logical Unit Number under the SCSI target.
 130
 131   @param[in out] Packet   The Extended SCSI Pass Thru Protocol packet the
 132                           function translates to a virtio-scsi request. On
 133                           failure this parameter relays error contents.
 134
 135   @param[out]    Request  The pre-zeroed virtio-scsi request to populate. This
 136                           parameter is volatile-qualified because we expect the
 137                           caller to append it to a virtio ring, thus
 138                           assignments to Request must be visible when the
 139                           function returns.
 140
 141
 142   @retval EFI_SUCCESS  The Extended SCSI Pass Thru Protocol packet was valid,
 143                        Request has been populated.
 144
 145   @return              Otherwise, invalid or unsupported parameters were
 146                        detected. Status codes are meant for direct forwarding
 147                        by the EFI_EXT_SCSI_PASS_THRU_PROTOCOL.PassThru()
 148                        implementation.
 149
 150 **/
 151 STATIC
 152 EFI_STATUS
 153 EFIAPI
 154 PopulateRequest (
 155   IN     CONST    VSCSI_DEV                                   *Dev,
 156   IN              UINT16                                      Target,
 157   IN              UINT64                                      Lun,
 158   IN OUT          EFI_EXT_SCSI_PASS_THRU_SCSI_REQUEST_PACKET  *Packet,
 159   OUT    volatile VIRTIO_SCSI_REQ                             *Request
 160   )
 161 {
 162   UINTN Idx;
 163
 164   if (
 165       //
 166       // bidirectional transfer was requested, but the host doesn't support it
 167       //
 168       (Packet->InTransferLength > 0 && Packet->OutTransferLength > 0 &&
 169        !Dev->InOutSupported) ||
 170
 171       //
 172       // a target / LUN was addressed that's impossible to encode for the host
 173       //
 174       Target > 0xFF || Lun >= 0x4000 ||
 175
 176       //
 177       // Command Descriptor Block bigger than VIRTIO_SCSI_CDB_SIZE
 178       //
 179       Packet->CdbLength > VIRTIO_SCSI_CDB_SIZE ||
 180
 181       //
 182       // From virtio-0.9.5, 2.3.2 Descriptor Table:
 183       // "no descriptor chain may be more than 2^32 bytes long in total".
 184       //
 185       (UINT64) Packet->InTransferLength + Packet->OutTransferLength > SIZE_1GB
 186       ) {
 187
 188     //
 189     // this error code doesn't require updates to the Packet output fields
 190     //
 191     return EFI_UNSUPPORTED;
 192   }
 193
 194   if (
 195       //
 196       // addressed invalid device
 197       //
 198       Target > Dev->MaxTarget || Lun > Dev->MaxLun ||
 199
 200       //
 201       // invalid direction (there doesn't seem to be a macro for the "no data
 202       // transferred" "direction", eg. for TEST UNIT READY)
 203       //
 204       Packet->DataDirection > EFI_EXT_SCSI_DATA_DIRECTION_BIDIRECTIONAL ||
 205
 206       //
 207       // trying to receive, but destination pointer is NULL, or contradicting
 208       // transfer direction
 209       //
 210       (Packet->InTransferLength > 0 &&
 211        (Packet->InDataBuffer == NULL ||
 212         Packet->DataDirection == EFI_EXT_SCSI_DATA_DIRECTION_WRITE
 213         )
 214        ) ||
 215
 216       //
 217       // trying to send, but source pointer is NULL, or contradicting transfer
 218       // direction
 219       //
 220       (Packet->OutTransferLength > 0 &&
 221        (Packet->OutDataBuffer == NULL ||
 222         Packet->DataDirection == EFI_EXT_SCSI_DATA_DIRECTION_READ
 223         )
 224        )
 225       ) {
 226
 227     //
 228     // this error code doesn't require updates to the Packet output fields
 229     //
 230     return EFI_INVALID_PARAMETER;
 231   }
 232
 233   //
 234   // Catch oversized requests eagerly. If this condition evaluates to false,
 235   // then the combined size of a bidirectional request will not exceed the
 236   // virtio-scsi device's transfer limit either.
 237   //
 238   if (ALIGN_VALUE (Packet->OutTransferLength, 512) / 512
 239         > Dev->MaxSectors / 2 ||
 240       ALIGN_VALUE (Packet->InTransferLength,  512) / 512
 241         > Dev->MaxSectors / 2) {
 242     Packet->InTransferLength  = (Dev->MaxSectors / 2) * 512;
 243     Packet->OutTransferLength = (Dev->MaxSectors / 2) * 512;
 244     Packet->HostAdapterStatus =
 245                         EFI_EXT_SCSI_STATUS_HOST_ADAPTER_DATA_OVERRUN_UNDERRUN;
 246     Packet->TargetStatus      = EFI_EXT_SCSI_STATUS_TARGET_GOOD;
 247     Packet->SenseDataLength   = 0;
 248     return EFI_BAD_BUFFER_SIZE;
 249   }
 250
 251   //
 252   // target & LUN encoding: see virtio-0.9.5, Appendix I: SCSI Host Device,
 253   // Device Operation: request queues
 254   //
 255   Request->Lun[0] = 1;
 256   Request->Lun[1] = (UINT8) Target;
 257   Request->Lun[2] = (UINT8) (((UINT32)Lun >> 8) | 0x40);
 258   Request->Lun[3] = (UINT8) Lun;
 259
 260   //
 261   // CopyMem() would cast away the "volatile" qualifier before access, which is
 262   // undefined behavior (ISO C99 6.7.3p5)
 263   //
 264   for (Idx = 0; Idx < Packet->CdbLength; ++Idx) {
 265     Request->Cdb[Idx] = ((UINT8 *) Packet->Cdb)[Idx];
 266   }
 267
 268   return EFI_SUCCESS;
 269 }
 270
 271
 272 /**
 273
 274   Parse the virtio-scsi device's response, translate it to an EFI status code,
 275   and update the Extended SCSI Pass Thru Protocol packet, to be returned by
 276   the EFI_EXT_SCSI_PASS_THRU_PROTOCOL.PassThru() implementation.
 277
 278   @param[in out] Packet  The Extended SCSI Pass Thru Protocol packet that has
 279                          been translated to a virtio-scsi request with
 280                          PopulateRequest(), and processed by the host. On
 281                          output this parameter is updated with response or
 282                          error contents.
 283
 284   @param[in] Response    The virtio-scsi response structure to parse. We expect
 285                          it to come from a virtio ring, thus it is qualified
 286                          volatile.
 287
 288
 289   @return  PassThru() status codes mandated by UEFI Spec 2.3.1 + Errata C, 14.7
 290            Extended SCSI Pass Thru Protocol.
 291
 292 **/
 293 STATIC
 294 EFI_STATUS
 295 EFIAPI
 296 ParseResponse (
 297   IN OUT                EFI_EXT_SCSI_PASS_THRU_SCSI_REQUEST_PACKET *Packet,
 298   IN     CONST volatile VIRTIO_SCSI_RESP                           *Response
 299   )
 300 {
 301   UINTN ResponseSenseLen;
 302   UINTN Idx;
 303
 304   //
 305   // return sense data (length and contents) in all cases, truncated if needed
 306   //
 307   ResponseSenseLen = MIN (Response->SenseLen, VIRTIO_SCSI_SENSE_SIZE);
 308   if (Packet->SenseDataLength > ResponseSenseLen) {
 309     Packet->SenseDataLength = (UINT8) ResponseSenseLen;
 310   }
 311   for (Idx = 0; Idx < Packet->SenseDataLength; ++Idx) {
 312     ((UINT8 *) Packet->SenseData)[Idx] = Response->Sense[Idx];
 313   }
 314
 315   //
 316   // Report actual transfer lengths. The logic below covers all three
 317   // DataDirections (read, write, bidirectional).
 318   //
 319   // -+- @ 0
 320   //  |
 321   //  | write                                       ^  @ Residual (unprocessed)
 322   //  |                                             |
 323   // -+- @ OutTransferLength                       -+- @ InTransferLength
 324   //  |                                             |
 325   //  | read                                        |
 326   //  |                                             |
 327   //  V  @ OutTransferLength + InTransferLength    -+- @ 0
 328   //
 329   if (Response->Residual <= Packet->InTransferLength) {
 330     Packet->InTransferLength  -= Response->Residual;
 331   }
 332   else {
 333     Packet->OutTransferLength -= Response->Residual - Packet->InTransferLength;
 334     Packet->InTransferLength   = 0;
 335   }
 336
 337   //
 338   // report target status in all cases
 339   //
 340   Packet->TargetStatus = Response->Status;
 341
 342   //
 343   // host adapter status and function return value depend on virtio-scsi
 344   // response code
 345   //
 346   switch (Response->Response) {
 347   case VIRTIO_SCSI_S_OK:
 348     Packet->HostAdapterStatus = EFI_EXT_SCSI_STATUS_HOST_ADAPTER_OK;
 349     return EFI_SUCCESS;
 350
 351   case VIRTIO_SCSI_S_OVERRUN:
 352     Packet->HostAdapterStatus =
 353                         EFI_EXT_SCSI_STATUS_HOST_ADAPTER_DATA_OVERRUN_UNDERRUN;
 354     break;
 355
 356   case VIRTIO_SCSI_S_BAD_TARGET:
 357     //
 358     // This is non-intuitive but explicitly required by the
 359     // EFI_EXT_SCSI_PASS_THRU_PROTOCOL.PassThru() specification for
 360     // disconnected (but otherwise valid) target / LUN addresses.
 361     //
 362     Packet->HostAdapterStatus =
 363                               EFI_EXT_SCSI_STATUS_HOST_ADAPTER_TIMEOUT_COMMAND;
 364     return EFI_TIMEOUT;
 365
 366   case VIRTIO_SCSI_S_RESET:
 367     Packet->HostAdapterStatus = EFI_EXT_SCSI_STATUS_HOST_ADAPTER_BUS_RESET;
 368     break;
 369
 370   case VIRTIO_SCSI_S_BUSY:
 371     Packet->HostAdapterStatus = EFI_EXT_SCSI_STATUS_HOST_ADAPTER_OK;
 372     return EFI_NOT_READY;
 373
 374   //
 375   // Lump together the rest. The mapping for VIRTIO_SCSI_S_ABORTED is
 376   // intentional as well, not an oversight.
 377   //
 378   case VIRTIO_SCSI_S_ABORTED:
 379   case VIRTIO_SCSI_S_TRANSPORT_FAILURE:
 380   case VIRTIO_SCSI_S_TARGET_FAILURE:
 381   case VIRTIO_SCSI_S_NEXUS_FAILURE:
 382   case VIRTIO_SCSI_S_FAILURE:
 383   default:
 384     Packet->HostAdapterStatus = EFI_EXT_SCSI_STATUS_HOST_ADAPTER_OTHER;
 385   }
 386
 387   return EFI_DEVICE_ERROR;
 388 }
 389
 390
 391 /**
 392
 393   The function can be used to create a fake host adapter error.
 394
 395   When VirtioScsiPassThru() is failed due to some reasons then this function
 396   can be called to construct a host adapter error.
 397
 398   @param[out] Packet  The Extended SCSI Pass Thru Protocol packet that the host
 399                       adapter error shall be placed in.
 400
 401
 402   @retval EFI_DEVICE_ERROR  The function returns this status code
 403                             unconditionally, to be propagated by
 404                             VirtioScsiPassThru().
 405
 406 **/
 407 STATIC
 408 EFI_STATUS
 409 ReportHostAdapterError (
 410   OUT EFI_EXT_SCSI_PASS_THRU_SCSI_REQUEST_PACKET  *Packet
 411   )
 412 {
 413   Packet->InTransferLength  = 0;
 414   Packet->OutTransferLength = 0;
 415   Packet->HostAdapterStatus = EFI_EXT_SCSI_STATUS_HOST_ADAPTER_OTHER;
 416   Packet->TargetStatus      = EFI_EXT_SCSI_STATUS_TARGET_GOOD;
 417   Packet->SenseDataLength   = 0;
 418   return EFI_DEVICE_ERROR;
 419 }
 420
 421
 422 //
 423 // The next seven functions implement EFI_EXT_SCSI_PASS_THRU_PROTOCOL
 424 // for the virtio-scsi HBA. Refer to UEFI Spec 2.3.1 + Errata C, sections
 425 // - 14.1 SCSI Driver Model Overview,
 426 // - 14.7 Extended SCSI Pass Thru Protocol.
 427 //
 428
 429 EFI_STATUS
 430 EFIAPI
 431 VirtioScsiPassThru (
 432   IN     EFI_EXT_SCSI_PASS_THRU_PROTOCOL            *This,
 433   IN     UINT8                                      *Target,
 434   IN     UINT64                                     Lun,
 435   IN OUT EFI_EXT_SCSI_PASS_THRU_SCSI_REQUEST_PACKET *Packet,
 436   IN     EFI_EVENT                                  Event   OPTIONAL
 437   )
 438 {
 439   VSCSI_DEV                 *Dev;
 440   UINT16                    TargetValue;
 441   EFI_STATUS                Status;
 442   volatile VIRTIO_SCSI_REQ  Request;
 443   volatile VIRTIO_SCSI_RESP *Response;
 444   VOID                      *ResponseBuffer;
 445   DESC_INDICES              Indices;
 446   VOID                      *RequestMapping;
 447   VOID                      *ResponseMapping;
 448   VOID                      *InDataMapping;
 449   VOID                      *OutDataMapping;
 450   EFI_PHYSICAL_ADDRESS      RequestDeviceAddress;
 451   EFI_PHYSICAL_ADDRESS      ResponseDeviceAddress;
 452   EFI_PHYSICAL_ADDRESS      InDataDeviceAddress;
 453   EFI_PHYSICAL_ADDRESS      OutDataDeviceAddress;
 454   VOID                      *InDataBuffer;
 455   UINTN                     InDataNumPages;
 456   BOOLEAN                   OutDataBufferIsMapped;
 457
 458   ZeroMem ((VOID*) &Request, sizeof (Request));
 459
 460   Dev = VIRTIO_SCSI_FROM_PASS_THRU (This);
 461   CopyMem (&TargetValue, Target, sizeof TargetValue);
 462
 463   InDataBuffer = NULL;
 464   OutDataBufferIsMapped = FALSE;
 465   InDataNumPages = 0;
 466
 467   Status = PopulateRequest (Dev, TargetValue, Lun, Packet, &Request);
 468   if (EFI_ERROR (Status)) {
 469     return Status;
 470   }
 471
 472   //
 473   // Map the virtio-scsi Request header buffer
 474   //
 475   Status = VirtioMapAllBytesInSharedBuffer (
 476              Dev->VirtIo,
 477              VirtioOperationBusMasterRead,
 478              (VOID *) &Request,
 479              sizeof Request,
 480              &RequestDeviceAddress,
 481              &RequestMapping);
 482   if (EFI_ERROR (Status)) {
 483     return ReportHostAdapterError (Packet);
 484   }
 485
 486   //
 487   // Map the input buffer
 488   //
 489   if (Packet->InTransferLength > 0) {
 490     //
 491     // Allocate a intermediate input buffer. This is mainly to handle the
 492     // following case:
 493     //  * caller submits a bi-directional request
 494     //  * we perform the request fine
 495     //  * but we fail to unmap the "InDataMapping"
 496     //
 497     // In that case simply returing the EFI_DEVICE_ERROR is not sufficient. In
 498     // addition to the error code we also need to update Packet fields
 499     // accordingly so that we report the full loss of the incoming transfer.
 500     //
 501     // We allocate a temporary buffer and map it with BusMasterCommonBuffer. If
 502     // the Virtio request is successful then we copy the data from temporary
 503     // buffer into Packet->InDataBuffer.
 504     //
 505     InDataNumPages = EFI_SIZE_TO_PAGES ((UINTN)Packet->InTransferLength);
 506     Status = Dev->VirtIo->AllocateSharedPages (
 507                             Dev->VirtIo,
 508                             InDataNumPages,
 509                             &InDataBuffer
 510                             );
 511     if (EFI_ERROR (Status)) {
 512       Status = ReportHostAdapterError (Packet);
 513       goto UnmapRequestBuffer;
 514     }
 515
 516     ZeroMem (InDataBuffer, Packet->InTransferLength);
 517
 518     Status = VirtioMapAllBytesInSharedBuffer (
 519                Dev->VirtIo,
 520                VirtioOperationBusMasterCommonBuffer,
 521                InDataBuffer,
 522                Packet->InTransferLength,
 523                &InDataDeviceAddress,
 524                &InDataMapping
 525                );
 526     if (EFI_ERROR (Status)) {
 527       Status = ReportHostAdapterError (Packet);
 528       goto FreeInDataBuffer;
 529     }
 530   }
 531
 532   //
 533   // Map the output buffer
 534   //
 535   if (Packet->OutTransferLength > 0) {
 536     Status = VirtioMapAllBytesInSharedBuffer (
 537                Dev->VirtIo,
 538                VirtioOperationBusMasterRead,
 539                Packet->OutDataBuffer,
 540                Packet->OutTransferLength,
 541                &OutDataDeviceAddress,
 542                &OutDataMapping
 543                );
 544     if (EFI_ERROR (Status)) {
 545       Status = ReportHostAdapterError (Packet);
 546       goto UnmapInDataBuffer;
 547     }
 548
 549     OutDataBufferIsMapped = TRUE;
 550   }
 551
 552   //
 553   // Response header is bi-direction (we preset with host status and expect
 554   // the device to update it). Allocate a response buffer which can be mapped
 555   // to access equally by both processor and device.
 556   //
 557   Status = Dev->VirtIo->AllocateSharedPages (
 558                           Dev->VirtIo,
 559                           EFI_SIZE_TO_PAGES (sizeof *Response),
 560                           &ResponseBuffer
 561                           );
 562   if (EFI_ERROR (Status)) {
 563     Status = ReportHostAdapterError (Packet);
 564     goto UnmapOutDataBuffer;
 565   }
 566
 567   Response = ResponseBuffer;
 568
 569   ZeroMem ((VOID *)Response, sizeof (*Response));
 570
 571   //
 572   // preset a host status for ourselves that we do not accept as success
 573   //
 574   Response->Response = VIRTIO_SCSI_S_FAILURE;
 575
 576   //
 577   // Map the response buffer with BusMasterCommonBuffer so that response
 578   // buffer can be accessed by both host and device.
 579   //
 580   Status = VirtioMapAllBytesInSharedBuffer (
 581              Dev->VirtIo,
 582              VirtioOperationBusMasterCommonBuffer,
 583              ResponseBuffer,
 584              sizeof (*Response),
 585              &ResponseDeviceAddress,
 586              &ResponseMapping
 587              );
 588   if (EFI_ERROR (Status)) {
 589     Status = ReportHostAdapterError (Packet);
 590     goto FreeResponseBuffer;
 591   }
 592
 593   VirtioPrepare (&Dev->Ring, &Indices);
 594
 595   //
 596   // ensured by VirtioScsiInit() -- this predicate, in combination with the
 597   // lock-step progress, ensures we don't have to track free descriptors.
 598   //
 599   ASSERT (Dev->Ring.QueueSize >= 4);
 600
 601   //
 602   // enqueue Request
 603   //
 604   VirtioAppendDesc (
 605     &Dev->Ring,
 606     RequestDeviceAddress,
 607     sizeof Request,
 608     VRING_DESC_F_NEXT,
 609     &Indices
 610     );
 611
 612   //
 613   // enqueue "dataout" if any
 614   //
 615   if (Packet->OutTransferLength > 0) {
 616     VirtioAppendDesc (
 617       &Dev->Ring,
 618       OutDataDeviceAddress,
 619       Packet->OutTransferLength,
 620       VRING_DESC_F_NEXT,
 621       &Indices
 622       );
 623   }
 624
 625   //
 626   // enqueue Response, to be written by the host
 627   //
 628   VirtioAppendDesc (
 629     &Dev->Ring,
 630     ResponseDeviceAddress,
 631     sizeof *Response,
 632     VRING_DESC_F_WRITE | (Packet->InTransferLength > 0 ? VRING_DESC_F_NEXT : 0),
 633     &Indices
 634     );
 635
 636   //
 637   // enqueue "datain" if any, to be written by the host
 638   //
 639   if (Packet->InTransferLength > 0) {
 640     VirtioAppendDesc (
 641       &Dev->Ring,
 642       InDataDeviceAddress,
 643       Packet->InTransferLength,
 644       VRING_DESC_F_WRITE,
 645       &Indices
 646       );
 647   }
 648
 649   // If kicking the host fails, we must fake a host adapter error.
 650   // EFI_NOT_READY would save us the effort, but it would also suggest that the
 651   // caller retry.
 652   //
 653   if (VirtioFlush (Dev->VirtIo, VIRTIO_SCSI_REQUEST_QUEUE, &Dev->Ring,
 654         &Indices, NULL) != EFI_SUCCESS) {
 655     Status = ReportHostAdapterError (Packet);
 656     goto UnmapResponseBuffer;
 657   }
 658
 659   Status = ParseResponse (Packet, Response);
 660
 661   //
 662   // If virtio request was successful and it was a CPU read request then we
 663   // have used an intermediate buffer. Copy the data from intermediate buffer
 664   // to the final buffer.
 665   //
 666   if (InDataBuffer != NULL) {
 667     CopyMem (Packet->InDataBuffer, InDataBuffer, Packet->InTransferLength);
 668   }
 669
 670 UnmapResponseBuffer:
 671   Dev->VirtIo->UnmapSharedBuffer (Dev->VirtIo, ResponseMapping);
 672
 673 FreeResponseBuffer:
 674   Dev->VirtIo->FreeSharedPages (
 675                  Dev->VirtIo,
 676                  EFI_SIZE_TO_PAGES (sizeof *Response),
 677                  ResponseBuffer
 678                  );
 679
 680 UnmapOutDataBuffer:
 681   if (OutDataBufferIsMapped) {
 682     Dev->VirtIo->UnmapSharedBuffer (Dev->VirtIo, OutDataMapping);
 683   }
 684
 685 UnmapInDataBuffer:
 686   if (InDataBuffer != NULL) {
 687     Dev->VirtIo->UnmapSharedBuffer (Dev->VirtIo, InDataMapping);
 688   }
 689
 690 FreeInDataBuffer:
 691   if (InDataBuffer != NULL) {
 692     Dev->VirtIo->FreeSharedPages (Dev->VirtIo, InDataNumPages, InDataBuffer);
 693   }
 694
 695 UnmapRequestBuffer:
 696   Dev->VirtIo->UnmapSharedBuffer (Dev->VirtIo, RequestMapping);
 697
 698   return Status;
 699 }
 700
 701
 702 EFI_STATUS
 703 EFIAPI
 704 VirtioScsiGetNextTargetLun (
 705   IN     EFI_EXT_SCSI_PASS_THRU_PROTOCOL *This,
 706   IN OUT UINT8                           **TargetPointer,
 707   IN OUT UINT64                          *Lun
 708   )
 709 {
 710   UINT8     *Target;
 711   UINTN     Idx;
 712   UINT16    LastTarget;
 713   VSCSI_DEV *Dev;
 714
 715   //
 716   // the TargetPointer input parameter is unnecessarily a pointer-to-pointer
 717   //
 718   Target = *TargetPointer;
 719
 720   //
 721   // Search for first non-0xFF byte. If not found, return first target & LUN.
 722   //
 723   for (Idx = 0; Idx < TARGET_MAX_BYTES && Target[Idx] == 0xFF; ++Idx)
 724     ;
 725   if (Idx == TARGET_MAX_BYTES) {
 726     SetMem (Target, TARGET_MAX_BYTES, 0x00);
 727     *Lun = 0;
 728     return EFI_SUCCESS;
 729   }
 730
 731   //
 732   // see the TARGET_MAX_BYTES check in "VirtioScsi.h"
 733   //
 734   CopyMem (&LastTarget, Target, sizeof LastTarget);
 735
 736   //
 737   // increment (target, LUN) pair if valid on input
 738   //
 739   Dev = VIRTIO_SCSI_FROM_PASS_THRU (This);
 740   if (LastTarget > Dev->MaxTarget || *Lun > Dev->MaxLun) {
 741     return EFI_INVALID_PARAMETER;
 742   }
 743
 744   if (*Lun < Dev->MaxLun) {
 745     ++*Lun;
 746     return EFI_SUCCESS;
 747   }
 748
 749   if (LastTarget < Dev->MaxTarget) {
 750     *Lun = 0;
 751     ++LastTarget;
 752     CopyMem (Target, &LastTarget, sizeof LastTarget);
 753     return EFI_SUCCESS;
 754   }
 755
 756   return EFI_NOT_FOUND;
 757 }
 758
 759
 760 EFI_STATUS
 761 EFIAPI
 762 VirtioScsiBuildDevicePath (
 763   IN     EFI_EXT_SCSI_PASS_THRU_PROTOCOL *This,
 764   IN     UINT8                           *Target,
 765   IN     UINT64                          Lun,
 766   IN OUT EFI_DEVICE_PATH_PROTOCOL        **DevicePath
 767   )
 768 {
 769   UINT16           TargetValue;
 770   VSCSI_DEV        *Dev;
 771   SCSI_DEVICE_PATH *ScsiDevicePath;
 772
 773   if (DevicePath == NULL) {
 774     return EFI_INVALID_PARAMETER;
 775   }
 776
 777   CopyMem (&TargetValue, Target, sizeof TargetValue);
 778   Dev = VIRTIO_SCSI_FROM_PASS_THRU (This);
 779   if (TargetValue > Dev->MaxTarget || Lun > Dev->MaxLun || Lun > 0xFFFF) {
 780     return EFI_NOT_FOUND;
 781   }
 782
 783   ScsiDevicePath = AllocatePool (sizeof *ScsiDevicePath);
 784   if (ScsiDevicePath == NULL) {
 785     return EFI_OUT_OF_RESOURCES;
 786   }
 787
 788   ScsiDevicePath->Header.Type      = MESSAGING_DEVICE_PATH;
 789   ScsiDevicePath->Header.SubType   = MSG_SCSI_DP;
 790   ScsiDevicePath->Header.Length[0] = (UINT8)  sizeof *ScsiDevicePath;
 791   ScsiDevicePath->Header.Length[1] = (UINT8) (sizeof *ScsiDevicePath >> 8);
 792   ScsiDevicePath->Pun              = TargetValue;
 793   ScsiDevicePath->Lun              = (UINT16) Lun;
 794
 795   *DevicePath = &ScsiDevicePath->Header;
 796   return EFI_SUCCESS;
 797 }
 798
 799
 800 EFI_STATUS
 801 EFIAPI
 802 VirtioScsiGetTargetLun (
 803   IN  EFI_EXT_SCSI_PASS_THRU_PROTOCOL *This,
 804   IN  EFI_DEVICE_PATH_PROTOCOL        *DevicePath,
 805   OUT UINT8                           **TargetPointer,
 806   OUT UINT64                          *Lun
 807   )
 808 {
 809   SCSI_DEVICE_PATH *ScsiDevicePath;
 810   VSCSI_DEV        *Dev;
 811   UINT8            *Target;
 812
 813   if (DevicePath == NULL || TargetPointer == NULL || *TargetPointer == NULL ||
 814       Lun == NULL) {
 815     return EFI_INVALID_PARAMETER;
 816   }
 817
 818   if (DevicePath->Type    != MESSAGING_DEVICE_PATH ||
 819       DevicePath->SubType != MSG_SCSI_DP) {
 820     return EFI_UNSUPPORTED;
 821   }
 822
 823   ScsiDevicePath = (SCSI_DEVICE_PATH *) DevicePath;
 824   Dev = VIRTIO_SCSI_FROM_PASS_THRU (This);
 825   if (ScsiDevicePath->Pun > Dev->MaxTarget ||
 826       ScsiDevicePath->Lun > Dev->MaxLun) {
 827     return EFI_NOT_FOUND;
 828   }
 829
 830   //
 831   // a) the TargetPointer input parameter is unnecessarily a pointer-to-pointer
 832   // b) see the TARGET_MAX_BYTES check in "VirtioScsi.h"
 833   // c) ScsiDevicePath->Pun is an UINT16
 834   //
 835   Target = *TargetPointer;
 836   CopyMem (Target, &ScsiDevicePath->Pun, 2);
 837   SetMem (Target + 2, TARGET_MAX_BYTES - 2, 0x00);
 838
 839   *Lun = ScsiDevicePath->Lun;
 840   return EFI_SUCCESS;
 841 }
 842
 843
 844 EFI_STATUS
 845 EFIAPI
 846 VirtioScsiResetChannel (
 847   IN EFI_EXT_SCSI_PASS_THRU_PROTOCOL *This
 848   )
 849 {
 850   return EFI_UNSUPPORTED;
 851 }
 852
 853
 854 EFI_STATUS
 855 EFIAPI
 856 VirtioScsiResetTargetLun (
 857   IN EFI_EXT_SCSI_PASS_THRU_PROTOCOL *This,
 858   IN UINT8                           *Target,
 859   IN UINT64                          Lun
 860   )
 861 {
 862   return EFI_UNSUPPORTED;
 863 }
 864
 865
 866 EFI_STATUS
 867 EFIAPI
 868 VirtioScsiGetNextTarget (
 869   IN EFI_EXT_SCSI_PASS_THRU_PROTOCOL *This,
 870   IN OUT UINT8                       **TargetPointer
 871   )
 872 {
 873   UINT8     *Target;
 874   UINTN     Idx;
 875   UINT16    LastTarget;
 876   VSCSI_DEV *Dev;
 877
 878   //
 879   // the TargetPointer input parameter is unnecessarily a pointer-to-pointer
 880   //
 881   Target = *TargetPointer;
 882
 883   //
 884   // Search for first non-0xFF byte. If not found, return first target.
 885   //
 886   for (Idx = 0; Idx < TARGET_MAX_BYTES && Target[Idx] == 0xFF; ++Idx)
 887     ;
 888   if (Idx == TARGET_MAX_BYTES) {
 889     SetMem (Target, TARGET_MAX_BYTES, 0x00);
 890     return EFI_SUCCESS;
 891   }
 892
 893   //
 894   // see the TARGET_MAX_BYTES check in "VirtioScsi.h"
 895   //
 896   CopyMem (&LastTarget, Target, sizeof LastTarget);
 897
 898   //
 899   // increment target if valid on input
 900   //
 901   Dev = VIRTIO_SCSI_FROM_PASS_THRU (This);
 902   if (LastTarget > Dev->MaxTarget) {
 903     return EFI_INVALID_PARAMETER;
 904   }
 905
 906   if (LastTarget < Dev->MaxTarget) {
 907     ++LastTarget;
 908     CopyMem (Target, &LastTarget, sizeof LastTarget);
 909     return EFI_SUCCESS;
 910   }
 911
 912   return EFI_NOT_FOUND;
 913 }
 914
 915
 916 STATIC
 917 EFI_STATUS
 918 EFIAPI
 919 VirtioScsiInit (
 920   IN OUT VSCSI_DEV *Dev
 921   )
 922 {
 923   UINT8      NextDevStat;
 924   EFI_STATUS Status;
 925   UINT64     RingBaseShift;
 926   UINT64     Features;
 927   UINT16     MaxChannel; // for validation only
 928   UINT32     NumQueues;  // for validation only
 929   UINT16     QueueSize;
 930
 931   //
 932   // Execute virtio-0.9.5, 2.2.1 Device Initialization Sequence.
 933   //
 934   NextDevStat = 0;             // step 1 -- reset device
 935   Status = Dev->VirtIo->SetDeviceStatus (Dev->VirtIo, NextDevStat);
 936   if (EFI_ERROR (Status)) {
 937     goto Failed;
 938   }
 939
 940   NextDevStat |= VSTAT_ACK;    // step 2 -- acknowledge device presence
 941   Status = Dev->VirtIo->SetDeviceStatus (Dev->VirtIo, NextDevStat);
 942   if (EFI_ERROR (Status)) {
 943     goto Failed;
 944   }
 945
 946   NextDevStat |= VSTAT_DRIVER; // step 3 -- we know how to drive it
 947   Status = Dev->VirtIo->SetDeviceStatus (Dev->VirtIo, NextDevStat);
 948   if (EFI_ERROR (Status)) {
 949     goto Failed;
 950   }
 951
 952   //
 953   // Set Page Size - MMIO VirtIo Specific
 954   //
 955   Status = Dev->VirtIo->SetPageSize (Dev->VirtIo, EFI_PAGE_SIZE);
 956   if (EFI_ERROR (Status)) {
 957     goto Failed;
 958   }
 959
 960   //
 961   // step 4a -- retrieve and validate features
 962   //
 963   Status = Dev->VirtIo->GetDeviceFeatures (Dev->VirtIo, &Features);
 964   if (EFI_ERROR (Status)) {
 965     goto Failed;
 966   }
 967   Dev->InOutSupported = (BOOLEAN) ((Features & VIRTIO_SCSI_F_INOUT) != 0);
 968
 969   Status = VIRTIO_CFG_READ (Dev, MaxChannel, &MaxChannel);
 970   if (EFI_ERROR (Status)) {
 971     goto Failed;
 972   }
 973   if (MaxChannel != 0) {
 974     //
 975     // this driver is for a single-channel virtio-scsi HBA
 976     //
 977     Status = EFI_UNSUPPORTED;
 978     goto Failed;
 979   }
 980
 981   Status = VIRTIO_CFG_READ (Dev, NumQueues, &NumQueues);
 982   if (EFI_ERROR (Status)) {
 983     goto Failed;
 984   }
 985   if (NumQueues < 1) {
 986     Status = EFI_UNSUPPORTED;
 987     goto Failed;
 988   }
 989
 990   Status = VIRTIO_CFG_READ (Dev, MaxTarget, &Dev->MaxTarget);
 991   if (EFI_ERROR (Status)) {
 992     goto Failed;
 993   }
 994   if (Dev->MaxTarget > PcdGet16 (PcdVirtioScsiMaxTargetLimit)) {
 995     Dev->MaxTarget = PcdGet16 (PcdVirtioScsiMaxTargetLimit);
 996   }
 997
 998   Status = VIRTIO_CFG_READ (Dev, MaxLun, &Dev->MaxLun);
 999   if (EFI_ERROR (Status)) {
1000     goto Failed;
1001   }
1002   if (Dev->MaxLun > PcdGet32 (PcdVirtioScsiMaxLunLimit)) {
1003     Dev->MaxLun = PcdGet32 (PcdVirtioScsiMaxLunLimit);
1004   }
1005
1006   Status = VIRTIO_CFG_READ (Dev, MaxSectors, &Dev->MaxSectors);
1007   if (EFI_ERROR (Status)) {
1008     goto Failed;
1009   }
1010   if (Dev->MaxSectors < 2) {
1011     //
1012     // We must be able to halve it for bidirectional transfers
1013     // (see EFI_BAD_BUFFER_SIZE in PopulateRequest()).
1014     //
1015     Status = EFI_UNSUPPORTED;
1016     goto Failed;
1017   }
1018
1019   Features &= VIRTIO_SCSI_F_INOUT | VIRTIO_F_VERSION_1;
1020
1021   //
1022   // In virtio-1.0, feature negotiation is expected to complete before queue
1023   // discovery, and the device can also reject the selected set of features.
1024   //
1025   if (Dev->VirtIo->Revision >= VIRTIO_SPEC_REVISION (1, 0, 0)) {
1026     Status = Virtio10WriteFeatures (Dev->VirtIo, Features, &NextDevStat);
1027     if (EFI_ERROR (Status)) {
1028       goto Failed;
1029     }
1030   }
1031
1032   //
1033   // step 4b -- allocate request virtqueue
1034   //
1035   Status = Dev->VirtIo->SetQueueSel (Dev->VirtIo, VIRTIO_SCSI_REQUEST_QUEUE);
1036   if (EFI_ERROR (Status)) {
1037     goto Failed;
1038   }
1039   Status = Dev->VirtIo->GetQueueNumMax (Dev->VirtIo, &QueueSize);
1040   if (EFI_ERROR (Status)) {
1041     goto Failed;
1042   }
1043   //
1044   // VirtioScsiPassThru() uses at most four descriptors
1045   //
1046   if (QueueSize < 4) {
1047     Status = EFI_UNSUPPORTED;
1048     goto Failed;
1049   }
1050
1051   Status = VirtioRingInit (Dev->VirtIo, QueueSize, &Dev->Ring);
1052   if (EFI_ERROR (Status)) {
1053     goto Failed;
1054   }
1055
1056   //
1057   // If anything fails from here on, we must release the ring resources
1058   //
1059   Status = VirtioRingMap (
1060              Dev->VirtIo,
1061              &Dev->Ring,
1062              &RingBaseShift,
1063              &Dev->RingMap
1064              );
1065   if (EFI_ERROR (Status)) {
1066     goto ReleaseQueue;
1067   }
1068
1069   //
1070   // Additional steps for MMIO: align the queue appropriately, and set the
1071   // size. If anything fails from here on, we must unmap the ring resources.
1072   //
1073   Status = Dev->VirtIo->SetQueueNum (Dev->VirtIo, QueueSize);
1074   if (EFI_ERROR (Status)) {
1075     goto UnmapQueue;
1076   }
1077
1078   Status = Dev->VirtIo->SetQueueAlign (Dev->VirtIo, EFI_PAGE_SIZE);
1079   if (EFI_ERROR (Status)) {
1080     goto UnmapQueue;
1081   }
1082
1083   //
1084   // step 4c -- Report GPFN (guest-physical frame number) of queue.
1085   //
1086   Status = Dev->VirtIo->SetQueueAddress (
1087                           Dev->VirtIo,
1088                           &Dev->Ring,
1089                           RingBaseShift
1090                           );
1091   if (EFI_ERROR (Status)) {
1092     goto UnmapQueue;
1093   }
1094
1095   //
1096   // step 5 -- Report understood features and guest-tuneables.
1097   //
1098   if (Dev->VirtIo->Revision < VIRTIO_SPEC_REVISION (1, 0, 0)) {
1099     Features &= ~(UINT64)VIRTIO_F_VERSION_1;
1100     Status = Dev->VirtIo->SetGuestFeatures (Dev->VirtIo, Features);
1101     if (EFI_ERROR (Status)) {
1102       goto UnmapQueue;
1103     }
1104   }
1105
1106   //
1107   // We expect these maximum sizes from the host. Since they are
1108   // guest-negotiable, ask for them rather than just checking them.
1109   //
1110   Status = VIRTIO_CFG_WRITE (Dev, CdbSize, VIRTIO_SCSI_CDB_SIZE);
1111   if (EFI_ERROR (Status)) {
1112     goto UnmapQueue;
1113   }
1114   Status = VIRTIO_CFG_WRITE (Dev, SenseSize, VIRTIO_SCSI_SENSE_SIZE);
1115   if (EFI_ERROR (Status)) {
1116     goto UnmapQueue;
1117   }
1118
1119   //
1120   // step 6 -- initialization complete
1121   //
1122   NextDevStat |= VSTAT_DRIVER_OK;
1123   Status = Dev->VirtIo->SetDeviceStatus (Dev->VirtIo, NextDevStat);
1124   if (EFI_ERROR (Status)) {
1125     goto UnmapQueue;
1126   }
1127
1128   //
1129   // populate the exported interface's attributes
1130   //
1131   Dev->PassThru.Mode             = &Dev->PassThruMode;
1132   Dev->PassThru.PassThru         = &VirtioScsiPassThru;
1133   Dev->PassThru.GetNextTargetLun = &VirtioScsiGetNextTargetLun;
1134   Dev->PassThru.BuildDevicePath  = &VirtioScsiBuildDevicePath;
1135   Dev->PassThru.GetTargetLun     = &VirtioScsiGetTargetLun;
1136   Dev->PassThru.ResetChannel     = &VirtioScsiResetChannel;
1137   Dev->PassThru.ResetTargetLun   = &VirtioScsiResetTargetLun;
1138   Dev->PassThru.GetNextTarget    = &VirtioScsiGetNextTarget;
1139
1140   //
1141   // AdapterId is a target for which no handle will be created during bus scan.
1142   // Prevent any conflict with real devices.
1143   //
1144   Dev->PassThruMode.AdapterId = 0xFFFFFFFF;
1145
1146   //
1147   // Set both physical and logical attributes for non-RAID SCSI channel. See
1148   // Driver Writer's Guide for UEFI 2.3.1 v1.01, 20.1.5 Implementing Extended
1149   // SCSI Pass Thru Protocol.
1150   //
1151   Dev->PassThruMode.Attributes = EFI_EXT_SCSI_PASS_THRU_ATTRIBUTES_PHYSICAL |
1152                                  EFI_EXT_SCSI_PASS_THRU_ATTRIBUTES_LOGICAL;
1153
1154   //
1155   // no restriction on transfer buffer alignment
1156   //
1157   Dev->PassThruMode.IoAlign = 0;
1158
1159   return EFI_SUCCESS;
1160
1161 UnmapQueue:
1162   Dev->VirtIo->UnmapSharedBuffer (Dev->VirtIo, Dev->RingMap);
1163
1164 ReleaseQueue:
1165   VirtioRingUninit (Dev->VirtIo, &Dev->Ring);
1166
1167 Failed:
1168   //
1169   // Notify the host about our failure to setup: virtio-0.9.5, 2.2.2.1 Device
1170   // Status. VirtIo access failure here should not mask the original error.
1171   //
1172   NextDevStat |= VSTAT_FAILED;
1173   Dev->VirtIo->SetDeviceStatus (Dev->VirtIo, NextDevStat);
1174
1175   Dev->InOutSupported = FALSE;
1176   Dev->MaxTarget      = 0;
1177   Dev->MaxLun         = 0;
1178   Dev->MaxSectors     = 0;
1179
1180   return Status; // reached only via Failed above
1181 }
1182
1183
1184 STATIC
1185 VOID
1186 EFIAPI
1187 VirtioScsiUninit (
1188   IN OUT VSCSI_DEV *Dev
1189   )
1190 {
1191   //
1192   // Reset the virtual device -- see virtio-0.9.5, 2.2.2.1 Device Status. When
1193   // VIRTIO_CFG_WRITE() returns, the host will have learned to stay away from
1194   // the old comms area.
1195   //
1196   Dev->VirtIo->SetDeviceStatus (Dev->VirtIo, 0);
1197
1198   Dev->InOutSupported = FALSE;
1199   Dev->MaxTarget      = 0;
1200   Dev->MaxLun         = 0;
1201   Dev->MaxSectors     = 0;
1202
1203   Dev->VirtIo->UnmapSharedBuffer (Dev->VirtIo, Dev->RingMap);
1204   VirtioRingUninit (Dev->VirtIo, &Dev->Ring);
1205
1206   SetMem (&Dev->PassThru,     sizeof Dev->PassThru,     0x00);
1207   SetMem (&Dev->PassThruMode, sizeof Dev->PassThruMode, 0x00);
1208 }
1209
1210
1211 //
1212 // Event notification function enqueued by ExitBootServices().
1213 //
1214
1215 STATIC
1216 VOID
1217 EFIAPI
1218 VirtioScsiExitBoot (
1219   IN  EFI_EVENT Event,
1220   IN  VOID      *Context
1221   )
1222 {
1223   VSCSI_DEV *Dev;
1224
1225   //
1226   // Reset the device. This causes the hypervisor to forget about the virtio
1227   // ring.
1228   //
1229   // We allocated said ring in EfiBootServicesData type memory, and code
1230   // executing after ExitBootServices() is permitted to overwrite it.
1231   //
1232   Dev = Context;
1233   Dev->VirtIo->SetDeviceStatus (Dev->VirtIo, 0);
1234
1235   //
1236   // Unmap the ring buffer so that hypervisor will not be able to get
1237   // readable data after device reset.
1238   //
1239   Dev->VirtIo->UnmapSharedBuffer (Dev->VirtIo, Dev->RingMap);
1240 }
1241
1242
1243 //
1244 // Probe, start and stop functions of this driver, called by the DXE core for
1245 // specific devices.
1246 //
1247 // The following specifications document these interfaces:
1248 // - Driver Writer's Guide for UEFI 2.3.1 v1.01, 9 Driver Binding Protocol
1249 // - UEFI Spec 2.3.1 + Errata C, 10.1 EFI Driver Binding Protocol
1250 //
1251 // The implementation follows:
1252 // - Driver Writer's Guide for UEFI 2.3.1 v1.01
1253 //   - 5.1.3.4 OpenProtocol() and CloseProtocol()
1254 // - UEFI Spec 2.3.1 + Errata C
1255 //   -  6.3 Protocol Handler Services
1256 //
1257
1258 EFI_STATUS
1259 EFIAPI
1260 VirtioScsiDriverBindingSupported (
1261   IN EFI_DRIVER_BINDING_PROTOCOL *This,
1262   IN EFI_HANDLE                  DeviceHandle,
1263   IN EFI_DEVICE_PATH_PROTOCOL    *RemainingDevicePath
1264   )
1265 {
1266   EFI_STATUS             Status;
1267   VIRTIO_DEVICE_PROTOCOL *VirtIo;
1268
1269   //
1270   // Attempt to open the device with the VirtIo set of interfaces. On success,
1271   // the protocol is "instantiated" for the VirtIo device. Covers duplicate open
1272   // attempts (EFI_ALREADY_STARTED).
1273   //
1274   Status = gBS->OpenProtocol (
1275                   DeviceHandle,               // candidate device
1276                   &gVirtioDeviceProtocolGuid, // for generic VirtIo access
1277                   (VOID **)&VirtIo,           // handle to instantiate
1278                   This->DriverBindingHandle,  // requestor driver identity
1279                   DeviceHandle,               // ControllerHandle, according to
1280                                               // the UEFI Driver Model
1281                   EFI_OPEN_PROTOCOL_BY_DRIVER // get exclusive VirtIo access to
1282                                               // the device; to be released
1283                   );
1284   if (EFI_ERROR (Status)) {
1285     return Status;
1286   }
1287
1288   if (VirtIo->SubSystemDeviceId != VIRTIO_SUBSYSTEM_SCSI_HOST) {
1289     Status = EFI_UNSUPPORTED;
1290   }
1291
1292   //
1293   // We needed VirtIo access only transitorily, to see whether we support the
1294   // device or not.
1295   //
1296   gBS->CloseProtocol (DeviceHandle, &gVirtioDeviceProtocolGuid,
1297          This->DriverBindingHandle, DeviceHandle);
1298   return Status;
1299 }
1300
1301
1302 EFI_STATUS
1303 EFIAPI
1304 VirtioScsiDriverBindingStart (
1305   IN EFI_DRIVER_BINDING_PROTOCOL *This,
1306   IN EFI_HANDLE                  DeviceHandle,
1307   IN EFI_DEVICE_PATH_PROTOCOL    *RemainingDevicePath
1308   )
1309 {
1310   VSCSI_DEV  *Dev;
1311   EFI_STATUS Status;
1312
1313   Dev = (VSCSI_DEV *) AllocateZeroPool (sizeof *Dev);
1314   if (Dev == NULL) {
1315     return EFI_OUT_OF_RESOURCES;
1316   }
1317
1318   Status = gBS->OpenProtocol (DeviceHandle, &gVirtioDeviceProtocolGuid,
1319                   (VOID **)&Dev->VirtIo, This->DriverBindingHandle,
1320                   DeviceHandle, EFI_OPEN_PROTOCOL_BY_DRIVER);
1321   if (EFI_ERROR (Status)) {
1322     goto FreeVirtioScsi;
1323   }
1324
1325   //
1326   // VirtIo access granted, configure virtio-scsi device.
1327   //
1328   Status = VirtioScsiInit (Dev);
1329   if (EFI_ERROR (Status)) {
1330     goto CloseVirtIo;
1331   }
1332
1333   Status = gBS->CreateEvent (EVT_SIGNAL_EXIT_BOOT_SERVICES, TPL_CALLBACK,
1334                   &VirtioScsiExitBoot, Dev, &Dev->ExitBoot);
1335   if (EFI_ERROR (Status)) {
1336     goto UninitDev;
1337   }
1338
1339   //
1340   // Setup complete, attempt to export the driver instance's PassThru
1341   // interface.
1342   //
1343   Dev->Signature = VSCSI_SIG;
1344   Status = gBS->InstallProtocolInterface (&DeviceHandle,
1345                   &gEfiExtScsiPassThruProtocolGuid, EFI_NATIVE_INTERFACE,
1346                   &Dev->PassThru);
1347   if (EFI_ERROR (Status)) {
1348     goto CloseExitBoot;
1349   }
1350
1351   return EFI_SUCCESS;
1352
1353 CloseExitBoot:
1354   gBS->CloseEvent (Dev->ExitBoot);
1355
1356 UninitDev:
1357   VirtioScsiUninit (Dev);
1358
1359 CloseVirtIo:
1360   gBS->CloseProtocol (DeviceHandle, &gVirtioDeviceProtocolGuid,
1361          This->DriverBindingHandle, DeviceHandle);
1362
1363 FreeVirtioScsi:
1364   FreePool (Dev);
1365
1366   return Status;
1367 }
1368
1369
1370 EFI_STATUS
1371 EFIAPI
1372 VirtioScsiDriverBindingStop (
1373   IN EFI_DRIVER_BINDING_PROTOCOL *This,
1374   IN EFI_HANDLE                  DeviceHandle,
1375   IN UINTN                       NumberOfChildren,
1376   IN EFI_HANDLE                  *ChildHandleBuffer
1377   )
1378 {
1379   EFI_STATUS                      Status;
1380   EFI_EXT_SCSI_PASS_THRU_PROTOCOL *PassThru;
1381   VSCSI_DEV                       *Dev;
1382
1383   Status = gBS->OpenProtocol (
1384                   DeviceHandle,                     // candidate device
1385                   &gEfiExtScsiPassThruProtocolGuid, // retrieve the SCSI iface
1386                   (VOID **)&PassThru,               // target pointer
1387                   This->DriverBindingHandle,        // requestor driver ident.
1388                   DeviceHandle,                     // lookup req. for dev.
1389                   EFI_OPEN_PROTOCOL_GET_PROTOCOL    // lookup only, no new ref.
1390                   );
1391   if (EFI_ERROR (Status)) {
1392     return Status;
1393   }
1394
1395   Dev = VIRTIO_SCSI_FROM_PASS_THRU (PassThru);
1396
1397   //
1398   // Handle Stop() requests for in-use driver instances gracefully.
1399   //
1400   Status = gBS->UninstallProtocolInterface (DeviceHandle,
1401                   &gEfiExtScsiPassThruProtocolGuid, &Dev->PassThru);
1402   if (EFI_ERROR (Status)) {
1403     return Status;
1404   }
1405
1406   gBS->CloseEvent (Dev->ExitBoot);
1407
1408   VirtioScsiUninit (Dev);
1409
1410   gBS->CloseProtocol (DeviceHandle, &gVirtioDeviceProtocolGuid,
1411          This->DriverBindingHandle, DeviceHandle);
1412
1413   FreePool (Dev);
1414
1415   return EFI_SUCCESS;
1416 }
1417
1418
1419 //
1420 // The static object that groups the Supported() (ie. probe), Start() and
1421 // Stop() functions of the driver together. Refer to UEFI Spec 2.3.1 + Errata
1422 // C, 10.1 EFI Driver Binding Protocol.
1423 //
1424 STATIC EFI_DRIVER_BINDING_PROTOCOL gDriverBinding = {
1425   &VirtioScsiDriverBindingSupported,
1426   &VirtioScsiDriverBindingStart,
1427   &VirtioScsiDriverBindingStop,
1428   0x10, // Version, must be in [0x10 .. 0xFFFFFFEF] for IHV-developed drivers
1429   NULL, // ImageHandle, to be overwritten by
1430         // EfiLibInstallDriverBindingComponentName2() in VirtioScsiEntryPoint()
1431   NULL  // DriverBindingHandle, ditto
1432 };
1433
1434
1435 //
1436 // The purpose of the following scaffolding (EFI_COMPONENT_NAME_PROTOCOL and
1437 // EFI_COMPONENT_NAME2_PROTOCOL implementation) is to format the driver's name
1438 // in English, for display on standard console devices. This is recommended for
1439 // UEFI drivers that follow the UEFI Driver Model. Refer to the Driver Writer's
1440 // Guide for UEFI 2.3.1 v1.01, 11 UEFI Driver and Controller Names.
1441 //
1442 // Device type names ("Virtio SCSI Host Device") are not formatted because the
1443 // driver supports only that device type. Therefore the driver name suffices
1444 // for unambiguous identification.
1445 //
1446
1447 STATIC
1448 EFI_UNICODE_STRING_TABLE mDriverNameTable[] = {
1449   { "eng;en", L"Virtio SCSI Host Driver" },
1450   { NULL,     NULL                   }
1451 };
1452
1453 STATIC
1454 EFI_COMPONENT_NAME_PROTOCOL gComponentName;
1455
1456 EFI_STATUS
1457 EFIAPI
1458 VirtioScsiGetDriverName (
1459   IN  EFI_COMPONENT_NAME_PROTOCOL *This,
1460   IN  CHAR8                       *Language,
1461   OUT CHAR16                      **DriverName
1462   )
1463 {
1464   return LookupUnicodeString2 (
1465            Language,
1466            This->SupportedLanguages,
1467            mDriverNameTable,
1468            DriverName,
1469            (BOOLEAN)(This == &gComponentName) // Iso639Language
1470            );
1471 }
1472
1473 EFI_STATUS
1474 EFIAPI
1475 VirtioScsiGetDeviceName (
1476   IN  EFI_COMPONENT_NAME_PROTOCOL *This,
1477   IN  EFI_HANDLE                  DeviceHandle,
1478   IN  EFI_HANDLE                  ChildHandle,
1479   IN  CHAR8                       *Language,
1480   OUT CHAR16                      **ControllerName
1481   )
1482 {
1483   return EFI_UNSUPPORTED;
1484 }
1485
1486 STATIC
1487 EFI_COMPONENT_NAME_PROTOCOL gComponentName = {
1488   &VirtioScsiGetDriverName,
1489   &VirtioScsiGetDeviceName,
1490   "eng" // SupportedLanguages, ISO 639-2 language codes
1491 };
1492
1493 STATIC
1494 EFI_COMPONENT_NAME2_PROTOCOL gComponentName2 = {
1495   (EFI_COMPONENT_NAME2_GET_DRIVER_NAME)     &VirtioScsiGetDriverName,
1496   (EFI_COMPONENT_NAME2_GET_CONTROLLER_NAME) &VirtioScsiGetDeviceName,
1497   "en" // SupportedLanguages, RFC 4646 language codes
1498 };
1499
1500
1501 //
1502 // Entry point of this driver.
1503 //
1504 EFI_STATUS
1505 EFIAPI
1506 VirtioScsiEntryPoint (
1507   IN EFI_HANDLE       ImageHandle,
1508   IN EFI_SYSTEM_TABLE *SystemTable
1509   )
1510 {
1511   return EfiLibInstallDriverBindingComponentName2 (
1512            ImageHandle,
1513            SystemTable,
1514            &gDriverBinding,
1515            ImageHandle,
1516            &gComponentName,
1517            &gComponentName2
1518            );
1519 }