3 This driver produces Extended SCSI Pass Thru Protocol instances for
6 The implementation is basic:
8 - No hotplug / hot-unplug.
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
14 - Timeouts are not supported for EFI_EXT_SCSI_PASS_THRU_PROTOCOL.PassThru().
16 - Only one channel is supported. (At the time of this writing, host-side
17 virtio-scsi supports a single channel too.)
19 - Only one request queue is used (for the one synchronous request).
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
28 Copyright (C) 2012, Red Hat, Inc.
29 Copyright (c) 2012, Intel Corporation. All rights reserved.<BR>
31 This program and the accompanying materials are licensed and made available
32 under the terms and conditions of the BSD License which accompanies this
33 distribution. The full text of the license may be found at
34 http://opensource.org/licenses/bsd-license.php
36 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, WITHOUT
37 WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
41 #include <IndustryStandard/Pci.h>
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>
50 #include "VirtioScsi.h"
54 Convenience macros to read and write region 0 IO space elements of the
55 virtio-scsi PCI device, for configuration purposes.
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.
61 @param[in] Dev Pointer to the VSCSI_DEV structure whose PCI IO space
62 we're accessing. Dev->PciIo must be valid.
64 @param[in] Field A field name from VSCSI_HDR, identifying the virtio-scsi
65 configuration item to access.
67 @param[in] Value (VIRTIO_CFG_WRITE() only.) The value to write to the
68 selected configuration item.
70 @param[out] Pointer (VIRTIO_CFG_READ() only.) The object to receive the
71 value read from the configuration item. Its type must be
72 one of UINT8, UINT16, UINT32, UINT64.
75 @return Status codes returned by VirtioWrite() / VirtioRead().
79 #define VIRTIO_CFG_WRITE(Dev, Field, Value) (VirtioWrite ( \
81 OFFSET_OF_VSCSI (Field), \
82 SIZE_OF_VSCSI (Field), \
86 #define VIRTIO_CFG_READ(Dev, Field, Pointer) (VirtioRead ( \
88 OFFSET_OF_VSCSI (Field), \
89 SIZE_OF_VSCSI (Field), \
96 // UEFI Spec 2.3.1 + Errata C, 14.7 Extended SCSI Pass Thru Protocol specifies
97 // the PassThru() interface. Beside returning a status code, the function must
98 // set some fields in the EFI_EXT_SCSI_PASS_THRU_SCSI_REQUEST_PACKET in/out
99 // parameter on return. The following is a full list of those fields, for
100 // easier validation of PopulateRequest(), ParseResponse(), and
101 // VirtioScsiPassThru() below.
103 // - InTransferLength
104 // - OutTransferLength
105 // - HostAdapterStatus
110 // On any return from the PassThru() interface, these fields must be set,
111 // except if the returned status code is explicitly exempt. (Actually the
112 // implementation here conservatively sets these fields even in case not all
113 // of them would be required by the specification.)
118 Populate a virtio-scsi request from the Extended SCSI Pass Thru Protocol
121 The caller is responsible for pre-zeroing the virtio-scsi request. The
122 Extended SCSI Pass Thru Protocol packet is modified, to be forwarded outwards
123 by VirtioScsiPassThru(), if invalid or unsupported parameters are detected.
125 @param[in] Dev The virtio-scsi host device the packet targets.
127 @param[in] Target The SCSI target controlled by the virtio-scsi host
130 @param[in] Lun The Logical Unit Number under the SCSI target.
132 @param[in out] Packet The Extended SCSI Pass Thru Protocol packet the
133 function translates to a virtio-scsi request. On
134 failure this parameter relays error contents.
136 @param[out] Request The pre-zeroed virtio-scsi request to populate. This
137 parameter is volatile-qualified because we expect the
138 caller to append it to a virtio ring, thus
139 assignments to Request must be visible when the
143 @retval EFI_SUCCESS The Extended SCSI Pass Thru Protocol packet was valid,
144 Request has been populated.
146 @return Otherwise, invalid or unsupported parameters were
147 detected. Status codes are meant for direct forwarding
148 by the EFI_EXT_SCSI_PASS_THRU_PROTOCOL.PassThru()
156 IN CONST VSCSI_DEV
*Dev
,
159 IN OUT EFI_EXT_SCSI_PASS_THRU_SCSI_REQUEST_PACKET
*Packet
,
160 OUT
volatile VIRTIO_SCSI_REQ
*Request
167 // bidirectional transfer was requested, but the host doesn't support it
169 (Packet
->InTransferLength
> 0 && Packet
->OutTransferLength
> 0 &&
170 !Dev
->InOutSupported
) ||
173 // a target / LUN was addressed that's impossible to encode for the host
175 Target
> 0xFF || Lun
>= 0x4000 ||
178 // Command Descriptor Block bigger than VIRTIO_SCSI_CDB_SIZE
180 Packet
->CdbLength
> VIRTIO_SCSI_CDB_SIZE
||
183 // From virtio-0.9.5, 2.3.2 Descriptor Table:
184 // "no descriptor chain may be more than 2^32 bytes long in total".
186 (UINT64
) Packet
->InTransferLength
+ Packet
->OutTransferLength
> SIZE_1GB
190 // this error code doesn't require updates to the Packet output fields
192 return EFI_UNSUPPORTED
;
197 // addressed invalid device
199 Target
> Dev
->MaxTarget
|| Lun
> Dev
->MaxLun
||
202 // invalid direction (there doesn't seem to be a macro for the "no data
203 // transferred" "direction", eg. for TEST UNIT READY)
205 Packet
->DataDirection
> EFI_EXT_SCSI_DATA_DIRECTION_BIDIRECTIONAL
||
208 // trying to receive, but destination pointer is NULL, or contradicting
209 // transfer direction
211 (Packet
->InTransferLength
> 0 &&
212 (Packet
->InDataBuffer
== NULL
||
213 Packet
->DataDirection
== EFI_EXT_SCSI_DATA_DIRECTION_WRITE
218 // trying to send, but source pointer is NULL, or contradicting transfer
221 (Packet
->OutTransferLength
> 0 &&
222 (Packet
->OutDataBuffer
== NULL
||
223 Packet
->DataDirection
== EFI_EXT_SCSI_DATA_DIRECTION_READ
229 // this error code doesn't require updates to the Packet output fields
231 return EFI_INVALID_PARAMETER
;
235 // Catch oversized requests eagerly. If this condition evaluates to false,
236 // then the combined size of a bidirectional request will not exceed the
237 // virtio-scsi device's transfer limit either.
239 if (ALIGN_VALUE (Packet
->OutTransferLength
, 512) / 512
240 > Dev
->MaxSectors
/ 2 ||
241 ALIGN_VALUE (Packet
->InTransferLength
, 512) / 512
242 > Dev
->MaxSectors
/ 2) {
243 Packet
->InTransferLength
= (Dev
->MaxSectors
/ 2) * 512;
244 Packet
->OutTransferLength
= (Dev
->MaxSectors
/ 2) * 512;
245 Packet
->HostAdapterStatus
=
246 EFI_EXT_SCSI_STATUS_HOST_ADAPTER_DATA_OVERRUN_UNDERRUN
;
247 Packet
->TargetStatus
= EFI_EXT_SCSI_STATUS_TARGET_GOOD
;
248 Packet
->SenseDataLength
= 0;
249 return EFI_BAD_BUFFER_SIZE
;
253 // target & LUN encoding: see virtio-0.9.5, Appendix I: SCSI Host Device,
254 // Device Operation: request queues
257 Request
->Lun
[1] = (UINT8
) Target
;
258 Request
->Lun
[2] = (UINT8
) ((Lun
>> 8) | 0x40);
259 Request
->Lun
[3] = (UINT8
) Lun
;
262 // CopyMem() would cast away the "volatile" qualifier before access, which is
263 // undefined behavior (ISO C99 6.7.3p5)
265 for (Idx
= 0; Idx
< Packet
->CdbLength
; ++Idx
) {
266 Request
->Cdb
[Idx
] = ((UINT8
*) Packet
->Cdb
)[Idx
];
275 Parse the virtio-scsi device's response, translate it to an EFI status code,
276 and update the Extended SCSI Pass Thru Protocol packet, to be returned by
277 the EFI_EXT_SCSI_PASS_THRU_PROTOCOL.PassThru() implementation.
279 @param[in out] Packet The Extended SCSI Pass Thru Protocol packet that has
280 been translated to a virtio-scsi request with
281 PopulateRequest(), and processed by the host. On
282 output this parameter is updated with response or
285 @param[in] Response The virtio-scsi response structure to parse. We expect
286 it to come from a virtio ring, thus it is qualified
290 @return PassThru() status codes mandated by UEFI Spec 2.3.1 + Errata C, 14.7
291 Extended SCSI Pass Thru Protocol.
298 IN OUT EFI_EXT_SCSI_PASS_THRU_SCSI_REQUEST_PACKET
*Packet
,
299 IN CONST
volatile VIRTIO_SCSI_RESP
*Response
302 UINTN ResponseSenseLen
;
306 // return sense data (length and contents) in all cases, truncated if needed
308 ResponseSenseLen
= MIN (Response
->SenseLen
, VIRTIO_SCSI_SENSE_SIZE
);
309 if (Packet
->SenseDataLength
> ResponseSenseLen
) {
310 Packet
->SenseDataLength
= (UINT8
) ResponseSenseLen
;
312 for (Idx
= 0; Idx
< Packet
->SenseDataLength
; ++Idx
) {
313 ((UINT8
*) Packet
->SenseData
)[Idx
] = Response
->Sense
[Idx
];
317 // Report actual transfer lengths. The logic below covers all three
318 // DataDirections (read, write, bidirectional).
322 // | write ^ @ Residual (unprocessed)
324 // -+- @ OutTransferLength -+- @ InTransferLength
328 // V @ OutTransferLength + InTransferLength -+- @ 0
330 if (Response
->Residual
<= Packet
->InTransferLength
) {
331 Packet
->InTransferLength
-= Response
->Residual
;
334 Packet
->OutTransferLength
-= Response
->Residual
- Packet
->InTransferLength
;
335 Packet
->InTransferLength
= 0;
339 // report target status in all cases
341 Packet
->TargetStatus
= Response
->Status
;
344 // host adapter status and function return value depend on virtio-scsi
347 switch (Response
->Response
) {
348 case VIRTIO_SCSI_S_OK
:
349 Packet
->HostAdapterStatus
= EFI_EXT_SCSI_STATUS_HOST_ADAPTER_OK
;
352 case VIRTIO_SCSI_S_OVERRUN
:
353 Packet
->HostAdapterStatus
=
354 EFI_EXT_SCSI_STATUS_HOST_ADAPTER_DATA_OVERRUN_UNDERRUN
;
357 case VIRTIO_SCSI_S_BAD_TARGET
:
359 // This is non-intuitive but explicitly required by the
360 // EFI_EXT_SCSI_PASS_THRU_PROTOCOL.PassThru() specification for
361 // disconnected (but otherwise valid) target / LUN addresses.
363 Packet
->HostAdapterStatus
=
364 EFI_EXT_SCSI_STATUS_HOST_ADAPTER_TIMEOUT_COMMAND
;
367 case VIRTIO_SCSI_S_RESET
:
368 Packet
->HostAdapterStatus
= EFI_EXT_SCSI_STATUS_HOST_ADAPTER_BUS_RESET
;
371 case VIRTIO_SCSI_S_BUSY
:
372 Packet
->HostAdapterStatus
= EFI_EXT_SCSI_STATUS_HOST_ADAPTER_OK
;
373 return EFI_NOT_READY
;
376 // Lump together the rest. The mapping for VIRTIO_SCSI_S_ABORTED is
377 // intentional as well, not an oversight.
379 case VIRTIO_SCSI_S_ABORTED
:
380 case VIRTIO_SCSI_S_TRANSPORT_FAILURE
:
381 case VIRTIO_SCSI_S_TARGET_FAILURE
:
382 case VIRTIO_SCSI_S_NEXUS_FAILURE
:
383 case VIRTIO_SCSI_S_FAILURE
:
385 Packet
->HostAdapterStatus
= EFI_EXT_SCSI_STATUS_HOST_ADAPTER_OTHER
;
388 return EFI_DEVICE_ERROR
;
393 // The next seven functions implement EFI_EXT_SCSI_PASS_THRU_PROTOCOL
394 // for the virtio-scsi HBA. Refer to UEFI Spec 2.3.1 + Errata C, sections
395 // - 14.1 SCSI Driver Model Overview,
396 // - 14.7 Extended SCSI Pass Thru Protocol.
402 IN EFI_EXT_SCSI_PASS_THRU_PROTOCOL
*This
,
405 IN OUT EFI_EXT_SCSI_PASS_THRU_SCSI_REQUEST_PACKET
*Packet
,
406 IN EFI_EVENT Event OPTIONAL
412 volatile VIRTIO_SCSI_REQ Request
;
413 volatile VIRTIO_SCSI_RESP Response
;
414 DESC_INDICES Indices
;
416 ZeroMem ((VOID
*) &Request
, sizeof (Request
));
417 ZeroMem ((VOID
*) &Response
, sizeof (Response
));
419 Dev
= VIRTIO_SCSI_FROM_PASS_THRU (This
);
420 CopyMem (&TargetValue
, Target
, sizeof TargetValue
);
422 Status
= PopulateRequest (Dev
, TargetValue
, Lun
, Packet
, &Request
);
423 if (EFI_ERROR (Status
)) {
427 VirtioPrepare (&Dev
->Ring
, &Indices
);
430 // preset a host status for ourselves that we do not accept as success
432 Response
.Response
= VIRTIO_SCSI_S_FAILURE
;
435 // ensured by VirtioScsiInit() -- this predicate, in combination with the
436 // lock-step progress, ensures we don't have to track free descriptors.
438 ASSERT (Dev
->Ring
.QueueSize
>= 4);
443 VirtioAppendDesc (&Dev
->Ring
, (UINTN
) &Request
, sizeof Request
,
444 VRING_DESC_F_NEXT
, &Indices
);
447 // enqueue "dataout" if any
449 if (Packet
->OutTransferLength
> 0) {
450 VirtioAppendDesc (&Dev
->Ring
, (UINTN
) Packet
->OutDataBuffer
,
451 Packet
->OutTransferLength
, VRING_DESC_F_NEXT
, &Indices
);
455 // enqueue Response, to be written by the host
457 VirtioAppendDesc (&Dev
->Ring
, (UINTN
) &Response
, sizeof Response
,
458 VRING_DESC_F_WRITE
| (Packet
->InTransferLength
> 0 ?
459 VRING_DESC_F_NEXT
: 0),
463 // enqueue "datain" if any, to be written by the host
465 if (Packet
->InTransferLength
> 0) {
466 VirtioAppendDesc (&Dev
->Ring
, (UINTN
) Packet
->InDataBuffer
,
467 Packet
->InTransferLength
, VRING_DESC_F_WRITE
, &Indices
);
470 // If kicking the host fails, we must fake a host adapter error.
471 // EFI_NOT_READY would save us the effort, but it would also suggest that the
474 if (VirtioFlush (Dev
->PciIo
, VIRTIO_SCSI_REQUEST_QUEUE
, &Dev
->Ring
,
475 &Indices
) != EFI_SUCCESS
) {
476 Packet
->InTransferLength
= 0;
477 Packet
->OutTransferLength
= 0;
478 Packet
->HostAdapterStatus
= EFI_EXT_SCSI_STATUS_HOST_ADAPTER_OTHER
;
479 Packet
->TargetStatus
= EFI_EXT_SCSI_STATUS_TARGET_GOOD
;
480 Packet
->SenseDataLength
= 0;
481 return EFI_DEVICE_ERROR
;
484 return ParseResponse (Packet
, &Response
);
490 VirtioScsiGetNextTargetLun (
491 IN EFI_EXT_SCSI_PASS_THRU_PROTOCOL
*This
,
492 IN OUT UINT8
**TargetPointer
,
502 // the TargetPointer input parameter is unnecessarily a pointer-to-pointer
504 Target
= *TargetPointer
;
507 // Search for first non-0xFF byte. If not found, return first target & LUN.
509 for (Idx
= 0; Idx
< TARGET_MAX_BYTES
&& Target
[Idx
] == 0xFF; ++Idx
)
511 if (Idx
== TARGET_MAX_BYTES
) {
512 SetMem (Target
, TARGET_MAX_BYTES
, 0x00);
518 // see the TARGET_MAX_BYTES check in "VirtioScsi.h"
520 CopyMem (&LastTarget
, Target
, sizeof LastTarget
);
523 // increment (target, LUN) pair if valid on input
525 Dev
= VIRTIO_SCSI_FROM_PASS_THRU (This
);
526 if (LastTarget
> Dev
->MaxTarget
|| *Lun
> Dev
->MaxLun
) {
527 return EFI_INVALID_PARAMETER
;
530 if (*Lun
< Dev
->MaxLun
) {
535 if (LastTarget
< Dev
->MaxTarget
) {
538 CopyMem (Target
, &LastTarget
, sizeof LastTarget
);
542 return EFI_NOT_FOUND
;
548 VirtioScsiBuildDevicePath (
549 IN EFI_EXT_SCSI_PASS_THRU_PROTOCOL
*This
,
552 IN OUT EFI_DEVICE_PATH_PROTOCOL
**DevicePath
557 SCSI_DEVICE_PATH
*ScsiDevicePath
;
559 if (DevicePath
== NULL
) {
560 return EFI_INVALID_PARAMETER
;
563 CopyMem (&TargetValue
, Target
, sizeof TargetValue
);
564 Dev
= VIRTIO_SCSI_FROM_PASS_THRU (This
);
565 if (TargetValue
> Dev
->MaxTarget
|| Lun
> Dev
->MaxLun
|| Lun
> 0xFFFF) {
566 return EFI_NOT_FOUND
;
569 ScsiDevicePath
= AllocatePool (sizeof *ScsiDevicePath
);
570 if (ScsiDevicePath
== NULL
) {
571 return EFI_OUT_OF_RESOURCES
;
574 ScsiDevicePath
->Header
.Type
= MESSAGING_DEVICE_PATH
;
575 ScsiDevicePath
->Header
.SubType
= MSG_SCSI_DP
;
576 ScsiDevicePath
->Header
.Length
[0] = (UINT8
) sizeof *ScsiDevicePath
;
577 ScsiDevicePath
->Header
.Length
[1] = (UINT8
) (sizeof *ScsiDevicePath
>> 8);
578 ScsiDevicePath
->Pun
= TargetValue
;
579 ScsiDevicePath
->Lun
= (UINT16
) Lun
;
581 *DevicePath
= &ScsiDevicePath
->Header
;
588 VirtioScsiGetTargetLun (
589 IN EFI_EXT_SCSI_PASS_THRU_PROTOCOL
*This
,
590 IN EFI_DEVICE_PATH_PROTOCOL
*DevicePath
,
591 OUT UINT8
**TargetPointer
,
595 SCSI_DEVICE_PATH
*ScsiDevicePath
;
599 if (DevicePath
== NULL
|| TargetPointer
== NULL
|| *TargetPointer
== NULL
||
601 return EFI_INVALID_PARAMETER
;
604 if (DevicePath
->Type
!= MESSAGING_DEVICE_PATH
||
605 DevicePath
->SubType
!= MSG_SCSI_DP
) {
606 return EFI_UNSUPPORTED
;
609 ScsiDevicePath
= (SCSI_DEVICE_PATH
*) DevicePath
;
610 Dev
= VIRTIO_SCSI_FROM_PASS_THRU (This
);
611 if (ScsiDevicePath
->Pun
> Dev
->MaxTarget
||
612 ScsiDevicePath
->Lun
> Dev
->MaxLun
) {
613 return EFI_NOT_FOUND
;
617 // a) the TargetPointer input parameter is unnecessarily a pointer-to-pointer
618 // b) see the TARGET_MAX_BYTES check in "VirtioScsi.h"
619 // c) ScsiDevicePath->Pun is an UINT16
621 Target
= *TargetPointer
;
622 CopyMem (Target
, &ScsiDevicePath
->Pun
, 2);
623 SetMem (Target
+ 2, TARGET_MAX_BYTES
- 2, 0x00);
625 *Lun
= ScsiDevicePath
->Lun
;
632 VirtioScsiResetChannel (
633 IN EFI_EXT_SCSI_PASS_THRU_PROTOCOL
*This
636 return EFI_UNSUPPORTED
;
642 VirtioScsiResetTargetLun (
643 IN EFI_EXT_SCSI_PASS_THRU_PROTOCOL
*This
,
648 return EFI_UNSUPPORTED
;
654 VirtioScsiGetNextTarget (
655 IN EFI_EXT_SCSI_PASS_THRU_PROTOCOL
*This
,
656 IN OUT UINT8
**TargetPointer
665 // the TargetPointer input parameter is unnecessarily a pointer-to-pointer
667 Target
= *TargetPointer
;
670 // Search for first non-0xFF byte. If not found, return first target.
672 for (Idx
= 0; Idx
< TARGET_MAX_BYTES
&& Target
[Idx
] == 0xFF; ++Idx
)
674 if (Idx
== TARGET_MAX_BYTES
) {
675 SetMem (Target
, TARGET_MAX_BYTES
, 0x00);
680 // see the TARGET_MAX_BYTES check in "VirtioScsi.h"
682 CopyMem (&LastTarget
, Target
, sizeof LastTarget
);
685 // increment target if valid on input
687 Dev
= VIRTIO_SCSI_FROM_PASS_THRU (This
);
688 if (LastTarget
> Dev
->MaxTarget
) {
689 return EFI_INVALID_PARAMETER
;
692 if (LastTarget
< Dev
->MaxTarget
) {
694 CopyMem (Target
, &LastTarget
, sizeof LastTarget
);
698 return EFI_NOT_FOUND
;
706 IN OUT VSCSI_DEV
*Dev
713 UINT16 MaxChannel
; // for validation only
714 UINT32 NumQueues
; // for validation only
718 // Execute virtio-0.9.5, 2.2.1 Device Initialization Sequence.
720 NextDevStat
= 0; // step 1 -- reset device
721 Status
= VIRTIO_CFG_WRITE (Dev
, Generic
.VhdrDeviceStatus
, NextDevStat
);
722 if (EFI_ERROR (Status
)) {
726 NextDevStat
|= VSTAT_ACK
; // step 2 -- acknowledge device presence
727 Status
= VIRTIO_CFG_WRITE (Dev
, Generic
.VhdrDeviceStatus
, NextDevStat
);
728 if (EFI_ERROR (Status
)) {
732 NextDevStat
|= VSTAT_DRIVER
; // step 3 -- we know how to drive it
733 Status
= VIRTIO_CFG_WRITE (Dev
, Generic
.VhdrDeviceStatus
, NextDevStat
);
734 if (EFI_ERROR (Status
)) {
739 // step 4a -- retrieve and validate features
741 Status
= VIRTIO_CFG_READ (Dev
, Generic
.VhdrDeviceFeatureBits
, &Features
);
742 if (EFI_ERROR (Status
)) {
745 Dev
->InOutSupported
= !!(Features
& VIRTIO_SCSI_F_INOUT
);
747 Status
= VIRTIO_CFG_READ (Dev
, VhdrMaxChannel
, &MaxChannel
);
748 if (EFI_ERROR (Status
)) {
751 if (MaxChannel
!= 0) {
753 // this driver is for a single-channel virtio-scsi HBA
755 Status
= EFI_UNSUPPORTED
;
759 Status
= VIRTIO_CFG_READ (Dev
, VhdrNumQueues
, &NumQueues
);
760 if (EFI_ERROR (Status
)) {
764 Status
= EFI_UNSUPPORTED
;
768 Status
= VIRTIO_CFG_READ (Dev
, VhdrMaxTarget
, &Dev
->MaxTarget
);
769 if (EFI_ERROR (Status
)) {
772 if (Dev
->MaxTarget
> PcdGet16 (PcdVirtioScsiMaxTargetLimit
)) {
773 Dev
->MaxTarget
= PcdGet16 (PcdVirtioScsiMaxTargetLimit
);
776 Status
= VIRTIO_CFG_READ (Dev
, VhdrMaxLun
, &Dev
->MaxLun
);
777 if (EFI_ERROR (Status
)) {
780 if (Dev
->MaxLun
> PcdGet32 (PcdVirtioScsiMaxLunLimit
)) {
781 Dev
->MaxLun
= PcdGet32 (PcdVirtioScsiMaxLunLimit
);
784 Status
= VIRTIO_CFG_READ (Dev
, VhdrMaxSectors
, &Dev
->MaxSectors
);
785 if (EFI_ERROR (Status
)) {
788 if (Dev
->MaxSectors
< 2) {
790 // We must be able to halve it for bidirectional transfers
791 // (see EFI_BAD_BUFFER_SIZE in PopulateRequest()).
793 Status
= EFI_UNSUPPORTED
;
798 // step 4b -- allocate request virtqueue
800 Status
= VIRTIO_CFG_WRITE (Dev
, Generic
.VhdrQueueSelect
,
801 VIRTIO_SCSI_REQUEST_QUEUE
);
802 if (EFI_ERROR (Status
)) {
805 Status
= VIRTIO_CFG_READ (Dev
, Generic
.VhdrQueueSize
, &QueueSize
);
806 if (EFI_ERROR (Status
)) {
810 // VirtioScsiPassThru() uses at most four descriptors
813 Status
= EFI_UNSUPPORTED
;
817 Status
= VirtioRingInit (QueueSize
, &Dev
->Ring
);
818 if (EFI_ERROR (Status
)) {
823 // step 4c -- Report GPFN (guest-physical frame number) of queue. If anything
824 // fails from here on, we must release the ring resources.
826 Status
= VIRTIO_CFG_WRITE (Dev
, Generic
.VhdrQueueAddress
,
827 (UINTN
) Dev
->Ring
.Base
>> EFI_PAGE_SHIFT
);
828 if (EFI_ERROR (Status
)) {
833 // step 5 -- Report understood features and guest-tuneables. We want none of
834 // the known (or unknown) VIRTIO_SCSI_F_* or VIRTIO_F_* capabilities (see
835 // virtio-0.9.5, Appendices B and I), except bidirectional transfers.
837 Status
= VIRTIO_CFG_WRITE (Dev
, Generic
.VhdrGuestFeatureBits
,
838 Features
& VIRTIO_SCSI_F_INOUT
);
839 if (EFI_ERROR (Status
)) {
844 // We expect these maximum sizes from the host. Since they are
845 // guest-negotiable, ask for them rather than just checking them.
847 Status
= VIRTIO_CFG_WRITE (Dev
, VhdrCdbSize
, VIRTIO_SCSI_CDB_SIZE
);
848 if (EFI_ERROR (Status
)) {
851 Status
= VIRTIO_CFG_WRITE (Dev
, VhdrSenseSize
, VIRTIO_SCSI_SENSE_SIZE
);
852 if (EFI_ERROR (Status
)) {
857 // step 6 -- initialization complete
859 NextDevStat
|= VSTAT_DRIVER_OK
;
860 Status
= VIRTIO_CFG_WRITE (Dev
, Generic
.VhdrDeviceStatus
, NextDevStat
);
861 if (EFI_ERROR (Status
)) {
866 // populate the exported interface's attributes
868 Dev
->PassThru
.Mode
= &Dev
->PassThruMode
;
869 Dev
->PassThru
.PassThru
= &VirtioScsiPassThru
;
870 Dev
->PassThru
.GetNextTargetLun
= &VirtioScsiGetNextTargetLun
;
871 Dev
->PassThru
.BuildDevicePath
= &VirtioScsiBuildDevicePath
;
872 Dev
->PassThru
.GetTargetLun
= &VirtioScsiGetTargetLun
;
873 Dev
->PassThru
.ResetChannel
= &VirtioScsiResetChannel
;
874 Dev
->PassThru
.ResetTargetLun
= &VirtioScsiResetTargetLun
;
875 Dev
->PassThru
.GetNextTarget
= &VirtioScsiGetNextTarget
;
878 // AdapterId is a target for which no handle will be created during bus scan.
879 // Prevent any conflict with real devices.
881 Dev
->PassThruMode
.AdapterId
= 0xFFFFFFFF;
884 // Set both physical and logical attributes for non-RAID SCSI channel. See
885 // Driver Writer's Guide for UEFI 2.3.1 v1.01, 20.1.5 Implementing Extended
886 // SCSI Pass Thru Protocol.
888 Dev
->PassThruMode
.Attributes
= EFI_EXT_SCSI_PASS_THRU_ATTRIBUTES_PHYSICAL
|
889 EFI_EXT_SCSI_PASS_THRU_ATTRIBUTES_LOGICAL
;
892 // no restriction on transfer buffer alignment
894 Dev
->PassThruMode
.IoAlign
= 0;
899 VirtioRingUninit (&Dev
->Ring
);
903 // Notify the host about our failure to setup: virtio-0.9.5, 2.2.2.1 Device
904 // Status. PCI IO access failure here should not mask the original error.
906 NextDevStat
|= VSTAT_FAILED
;
907 VIRTIO_CFG_WRITE (Dev
, Generic
.VhdrDeviceStatus
, NextDevStat
);
909 Dev
->InOutSupported
= FALSE
;
914 return Status
; // reached only via Failed above
923 IN OUT VSCSI_DEV
*Dev
927 // Reset the virtual device -- see virtio-0.9.5, 2.2.2.1 Device Status. When
928 // VIRTIO_CFG_WRITE() returns, the host will have learned to stay away from
929 // the old comms area.
931 VIRTIO_CFG_WRITE (Dev
, Generic
.VhdrDeviceStatus
, 0);
933 Dev
->InOutSupported
= FALSE
;
938 VirtioRingUninit (&Dev
->Ring
);
940 SetMem (&Dev
->PassThru
, sizeof Dev
->PassThru
, 0x00);
941 SetMem (&Dev
->PassThruMode
, sizeof Dev
->PassThruMode
, 0x00);
946 // Probe, start and stop functions of this driver, called by the DXE core for
949 // The following specifications document these interfaces:
950 // - Driver Writer's Guide for UEFI 2.3.1 v1.01, 9 Driver Binding Protocol
951 // - UEFI Spec 2.3.1 + Errata C, 10.1 EFI Driver Binding Protocol
953 // The implementation follows:
954 // - Driver Writer's Guide for UEFI 2.3.1 v1.01
955 // - 5.1.3.4 OpenProtocol() and CloseProtocol()
956 // - 18 PCI Driver Design Guidelines
957 // - 18.3 PCI drivers
958 // - UEFI Spec 2.3.1 + Errata C
959 // - 6.3 Protocol Handler Services
960 // - 13.4 EFI PCI I/O Protocol
965 VirtioScsiDriverBindingSupported (
966 IN EFI_DRIVER_BINDING_PROTOCOL
*This
,
967 IN EFI_HANDLE DeviceHandle
,
968 IN EFI_DEVICE_PATH_PROTOCOL
*RemainingDevicePath
972 EFI_PCI_IO_PROTOCOL
*PciIo
;
976 // Attempt to open the device with the PciIo set of interfaces. On success,
977 // the protocol is "instantiated" for the PCI device. Covers duplicate open
978 // attempts (EFI_ALREADY_STARTED).
980 Status
= gBS
->OpenProtocol (
981 DeviceHandle
, // candidate device
982 &gEfiPciIoProtocolGuid
, // for generic PCI access
983 (VOID
**)&PciIo
, // handle to instantiate
984 This
->DriverBindingHandle
, // requestor driver identity
985 DeviceHandle
, // ControllerHandle, according to
986 // the UEFI Driver Model
987 EFI_OPEN_PROTOCOL_BY_DRIVER
// get exclusive PciIo access to
988 // the device; to be released
990 if (EFI_ERROR (Status
)) {
995 // Read entire PCI configuration header for more extensive check ahead.
997 Status
= PciIo
->Pci
.Read (
998 PciIo
, // (protocol, device)
1000 EfiPciIoWidthUint32
, // access width & copy
1003 sizeof Pci
/ sizeof (UINT32
), // Count
1004 &Pci
// target buffer
1007 if (Status
== EFI_SUCCESS
) {
1009 // virtio-0.9.5, 2.1 PCI Discovery
1011 Status
= (Pci
.Hdr
.VendorId
== 0x1AF4 &&
1012 Pci
.Hdr
.DeviceId
>= 0x1000 && Pci
.Hdr
.DeviceId
<= 0x103F &&
1013 Pci
.Hdr
.RevisionID
== 0x00 &&
1014 Pci
.Device
.SubsystemID
== VIRTIO_SUBSYSTEM_SCSI_HOST
) ? EFI_SUCCESS
: EFI_UNSUPPORTED
;
1018 // We needed PCI IO access only transitorily, to see whether we support the
1021 gBS
->CloseProtocol (DeviceHandle
, &gEfiPciIoProtocolGuid
,
1022 This
->DriverBindingHandle
, DeviceHandle
);
1029 VirtioScsiDriverBindingStart (
1030 IN EFI_DRIVER_BINDING_PROTOCOL
*This
,
1031 IN EFI_HANDLE DeviceHandle
,
1032 IN EFI_DEVICE_PATH_PROTOCOL
*RemainingDevicePath
1038 Dev
= (VSCSI_DEV
*) AllocateZeroPool (sizeof *Dev
);
1040 return EFI_OUT_OF_RESOURCES
;
1043 Status
= gBS
->OpenProtocol (DeviceHandle
, &gEfiPciIoProtocolGuid
,
1044 (VOID
**)&Dev
->PciIo
, This
->DriverBindingHandle
,
1045 DeviceHandle
, EFI_OPEN_PROTOCOL_BY_DRIVER
);
1046 if (EFI_ERROR (Status
)) {
1047 goto FreeVirtioScsi
;
1051 // We must retain and ultimately restore the original PCI attributes of the
1052 // device. See Driver Writer's Guide for UEFI 2.3.1 v1.01, 18.3 PCI drivers /
1053 // 18.3.2 Start() and Stop().
1055 // The third parameter ("Attributes", input) is ignored by the Get operation.
1056 // The fourth parameter ("Result", output) is ignored by the Enable and Set
1059 // For virtio-scsi we only need IO space access.
1061 Status
= Dev
->PciIo
->Attributes (Dev
->PciIo
, EfiPciIoAttributeOperationGet
,
1062 0, &Dev
->OriginalPciAttributes
);
1063 if (EFI_ERROR (Status
)) {
1067 Status
= Dev
->PciIo
->Attributes (Dev
->PciIo
,
1068 EfiPciIoAttributeOperationEnable
,
1069 EFI_PCI_IO_ATTRIBUTE_IO
, NULL
);
1070 if (EFI_ERROR (Status
)) {
1075 // PCI IO access granted, configure virtio-scsi device.
1077 Status
= VirtioScsiInit (Dev
);
1078 if (EFI_ERROR (Status
)) {
1079 goto RestorePciAttributes
;
1083 // Setup complete, attempt to export the driver instance's PassThru
1086 Dev
->Signature
= VSCSI_SIG
;
1087 Status
= gBS
->InstallProtocolInterface (&DeviceHandle
,
1088 &gEfiExtScsiPassThruProtocolGuid
, EFI_NATIVE_INTERFACE
,
1090 if (EFI_ERROR (Status
)) {
1097 VirtioScsiUninit (Dev
);
1099 RestorePciAttributes
:
1100 Dev
->PciIo
->Attributes (Dev
->PciIo
, EfiPciIoAttributeOperationSet
,
1101 Dev
->OriginalPciAttributes
, NULL
);
1104 gBS
->CloseProtocol (DeviceHandle
, &gEfiPciIoProtocolGuid
,
1105 This
->DriverBindingHandle
, DeviceHandle
);
1116 VirtioScsiDriverBindingStop (
1117 IN EFI_DRIVER_BINDING_PROTOCOL
*This
,
1118 IN EFI_HANDLE DeviceHandle
,
1119 IN UINTN NumberOfChildren
,
1120 IN EFI_HANDLE
*ChildHandleBuffer
1124 EFI_EXT_SCSI_PASS_THRU_PROTOCOL
*PassThru
;
1127 Status
= gBS
->OpenProtocol (
1128 DeviceHandle
, // candidate device
1129 &gEfiExtScsiPassThruProtocolGuid
, // retrieve the SCSI iface
1130 (VOID
**)&PassThru
, // target pointer
1131 This
->DriverBindingHandle
, // requestor driver ident.
1132 DeviceHandle
, // lookup req. for dev.
1133 EFI_OPEN_PROTOCOL_GET_PROTOCOL
// lookup only, no new ref.
1135 if (EFI_ERROR (Status
)) {
1139 Dev
= VIRTIO_SCSI_FROM_PASS_THRU (PassThru
);
1142 // Handle Stop() requests for in-use driver instances gracefully.
1144 Status
= gBS
->UninstallProtocolInterface (DeviceHandle
,
1145 &gEfiExtScsiPassThruProtocolGuid
, &Dev
->PassThru
);
1146 if (EFI_ERROR (Status
)) {
1150 VirtioScsiUninit (Dev
);
1152 Dev
->PciIo
->Attributes (Dev
->PciIo
, EfiPciIoAttributeOperationSet
,
1153 Dev
->OriginalPciAttributes
, NULL
);
1155 gBS
->CloseProtocol (DeviceHandle
, &gEfiPciIoProtocolGuid
,
1156 This
->DriverBindingHandle
, DeviceHandle
);
1165 // The static object that groups the Supported() (ie. probe), Start() and
1166 // Stop() functions of the driver together. Refer to UEFI Spec 2.3.1 + Errata
1167 // C, 10.1 EFI Driver Binding Protocol.
1169 STATIC EFI_DRIVER_BINDING_PROTOCOL gDriverBinding
= {
1170 &VirtioScsiDriverBindingSupported
,
1171 &VirtioScsiDriverBindingStart
,
1172 &VirtioScsiDriverBindingStop
,
1173 0x10, // Version, must be in [0x10 .. 0xFFFFFFEF] for IHV-developed drivers
1174 NULL
, // ImageHandle, to be overwritten by
1175 // EfiLibInstallDriverBindingComponentName2() in VirtioScsiEntryPoint()
1176 NULL
// DriverBindingHandle, ditto
1181 // The purpose of the following scaffolding (EFI_COMPONENT_NAME_PROTOCOL and
1182 // EFI_COMPONENT_NAME2_PROTOCOL implementation) is to format the driver's name
1183 // in English, for display on standard console devices. This is recommended for
1184 // UEFI drivers that follow the UEFI Driver Model. Refer to the Driver Writer's
1185 // Guide for UEFI 2.3.1 v1.01, 11 UEFI Driver and Controller Names.
1187 // Device type names ("Virtio SCSI Host Device") are not formatted because the
1188 // driver supports only that device type. Therefore the driver name suffices
1189 // for unambiguous identification.
1193 EFI_UNICODE_STRING_TABLE mDriverNameTable
[] = {
1194 { "eng;en", L
"Virtio SCSI Host Driver" },
1199 EFI_COMPONENT_NAME_PROTOCOL gComponentName
;
1203 VirtioScsiGetDriverName (
1204 IN EFI_COMPONENT_NAME_PROTOCOL
*This
,
1206 OUT CHAR16
**DriverName
1209 return LookupUnicodeString2 (
1211 This
->SupportedLanguages
,
1214 (BOOLEAN
)(This
== &gComponentName
) // Iso639Language
1220 VirtioScsiGetDeviceName (
1221 IN EFI_COMPONENT_NAME_PROTOCOL
*This
,
1222 IN EFI_HANDLE DeviceHandle
,
1223 IN EFI_HANDLE ChildHandle
,
1225 OUT CHAR16
**ControllerName
1228 return EFI_UNSUPPORTED
;
1232 EFI_COMPONENT_NAME_PROTOCOL gComponentName
= {
1233 &VirtioScsiGetDriverName
,
1234 &VirtioScsiGetDeviceName
,
1235 "eng" // SupportedLanguages, ISO 639-2 language codes
1239 EFI_COMPONENT_NAME2_PROTOCOL gComponentName2
= {
1240 (EFI_COMPONENT_NAME2_GET_DRIVER_NAME
) &VirtioScsiGetDriverName
,
1241 (EFI_COMPONENT_NAME2_GET_CONTROLLER_NAME
) &VirtioScsiGetDeviceName
,
1242 "en" // SupportedLanguages, RFC 4646 language codes
1247 // Entry point of this driver.
1251 VirtioScsiEntryPoint (
1252 IN EFI_HANDLE ImageHandle
,
1253 IN EFI_SYSTEM_TABLE
*SystemTable
1256 return EfiLibInstallDriverBindingComponentName2 (