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 - 2018, Intel Corporation. All rights reserved.<BR>
30 Copyright (c) 2017, AMD Inc, All rights reserved.<BR>
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
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.
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 configuration elements of the
55 virtio-scsi VirtIo device.
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.
63 @param[in] Field A field name from VSCSI_HDR, identifying the virtio-scsi
64 configuration item to access.
66 @param[in] Value (VIRTIO_CFG_WRITE() only.) The value to write to the
67 selected configuration item.
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.
74 @return Status codes returned by Virtio->WriteDevice() / Virtio->ReadDevice().
78 #define VIRTIO_CFG_WRITE(Dev, Field, Value) ((Dev)->VirtIo->WriteDevice ( \
80 OFFSET_OF_VSCSI (Field), \
81 SIZE_OF_VSCSI (Field), \
85 #define VIRTIO_CFG_READ(Dev, Field, Pointer) ((Dev)->VirtIo->ReadDevice ( \
87 OFFSET_OF_VSCSI (Field), \
88 SIZE_OF_VSCSI (Field), \
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.
102 // - InTransferLength
103 // - OutTransferLength
104 // - HostAdapterStatus
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.)
117 Populate a virtio-scsi request from the Extended SCSI Pass Thru Protocol
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.
124 @param[in] Dev The virtio-scsi host device the packet targets.
126 @param[in] Target The SCSI target controlled by the virtio-scsi host
129 @param[in] Lun The Logical Unit Number under the SCSI target.
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.
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
142 @retval EFI_SUCCESS The Extended SCSI Pass Thru Protocol packet was valid,
143 Request has been populated.
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()
155 IN CONST VSCSI_DEV
*Dev
,
158 IN OUT EFI_EXT_SCSI_PASS_THRU_SCSI_REQUEST_PACKET
*Packet
,
159 OUT
volatile VIRTIO_SCSI_REQ
*Request
166 // bidirectional transfer was requested, but the host doesn't support it
168 (Packet
->InTransferLength
> 0 && Packet
->OutTransferLength
> 0 &&
169 !Dev
->InOutSupported
) ||
172 // a target / LUN was addressed that's impossible to encode for the host
174 Target
> 0xFF || Lun
>= 0x4000 ||
177 // Command Descriptor Block bigger than VIRTIO_SCSI_CDB_SIZE
179 Packet
->CdbLength
> VIRTIO_SCSI_CDB_SIZE
||
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".
185 (UINT64
) Packet
->InTransferLength
+ Packet
->OutTransferLength
> SIZE_1GB
189 // this error code doesn't require updates to the Packet output fields
191 return EFI_UNSUPPORTED
;
196 // addressed invalid device
198 Target
> Dev
->MaxTarget
|| Lun
> Dev
->MaxLun
||
201 // invalid direction (there doesn't seem to be a macro for the "no data
202 // transferred" "direction", eg. for TEST UNIT READY)
204 Packet
->DataDirection
> EFI_EXT_SCSI_DATA_DIRECTION_BIDIRECTIONAL
||
207 // trying to receive, but destination pointer is NULL, or contradicting
208 // transfer direction
210 (Packet
->InTransferLength
> 0 &&
211 (Packet
->InDataBuffer
== NULL
||
212 Packet
->DataDirection
== EFI_EXT_SCSI_DATA_DIRECTION_WRITE
217 // trying to send, but source pointer is NULL, or contradicting transfer
220 (Packet
->OutTransferLength
> 0 &&
221 (Packet
->OutDataBuffer
== NULL
||
222 Packet
->DataDirection
== EFI_EXT_SCSI_DATA_DIRECTION_READ
228 // this error code doesn't require updates to the Packet output fields
230 return EFI_INVALID_PARAMETER
;
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.
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
;
252 // target & LUN encoding: see virtio-0.9.5, Appendix I: SCSI Host Device,
253 // Device Operation: request queues
256 Request
->Lun
[1] = (UINT8
) Target
;
257 Request
->Lun
[2] = (UINT8
) (((UINT32
)Lun
>> 8) | 0x40);
258 Request
->Lun
[3] = (UINT8
) Lun
;
261 // CopyMem() would cast away the "volatile" qualifier before access, which is
262 // undefined behavior (ISO C99 6.7.3p5)
264 for (Idx
= 0; Idx
< Packet
->CdbLength
; ++Idx
) {
265 Request
->Cdb
[Idx
] = ((UINT8
*) Packet
->Cdb
)[Idx
];
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.
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
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
289 @return PassThru() status codes mandated by UEFI Spec 2.3.1 + Errata C, 14.7
290 Extended SCSI Pass Thru Protocol.
297 IN OUT EFI_EXT_SCSI_PASS_THRU_SCSI_REQUEST_PACKET
*Packet
,
298 IN CONST
volatile VIRTIO_SCSI_RESP
*Response
301 UINTN ResponseSenseLen
;
305 // return sense data (length and contents) in all cases, truncated if needed
307 ResponseSenseLen
= MIN (Response
->SenseLen
, VIRTIO_SCSI_SENSE_SIZE
);
308 if (Packet
->SenseDataLength
> ResponseSenseLen
) {
309 Packet
->SenseDataLength
= (UINT8
) ResponseSenseLen
;
311 for (Idx
= 0; Idx
< Packet
->SenseDataLength
; ++Idx
) {
312 ((UINT8
*) Packet
->SenseData
)[Idx
] = Response
->Sense
[Idx
];
316 // Report actual transfer lengths. The logic below covers all three
317 // DataDirections (read, write, bidirectional).
321 // | write ^ @ Residual (unprocessed)
323 // -+- @ OutTransferLength -+- @ InTransferLength
327 // V @ OutTransferLength + InTransferLength -+- @ 0
329 if (Response
->Residual
<= Packet
->InTransferLength
) {
330 Packet
->InTransferLength
-= Response
->Residual
;
333 Packet
->OutTransferLength
-= Response
->Residual
- Packet
->InTransferLength
;
334 Packet
->InTransferLength
= 0;
338 // report target status in all cases
340 Packet
->TargetStatus
= Response
->Status
;
343 // host adapter status and function return value depend on virtio-scsi
346 switch (Response
->Response
) {
347 case VIRTIO_SCSI_S_OK
:
348 Packet
->HostAdapterStatus
= EFI_EXT_SCSI_STATUS_HOST_ADAPTER_OK
;
351 case VIRTIO_SCSI_S_OVERRUN
:
352 Packet
->HostAdapterStatus
=
353 EFI_EXT_SCSI_STATUS_HOST_ADAPTER_DATA_OVERRUN_UNDERRUN
;
356 case VIRTIO_SCSI_S_BAD_TARGET
:
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.
362 Packet
->HostAdapterStatus
=
363 EFI_EXT_SCSI_STATUS_HOST_ADAPTER_TIMEOUT_COMMAND
;
366 case VIRTIO_SCSI_S_RESET
:
367 Packet
->HostAdapterStatus
= EFI_EXT_SCSI_STATUS_HOST_ADAPTER_BUS_RESET
;
370 case VIRTIO_SCSI_S_BUSY
:
371 Packet
->HostAdapterStatus
= EFI_EXT_SCSI_STATUS_HOST_ADAPTER_OK
;
372 return EFI_NOT_READY
;
375 // Lump together the rest. The mapping for VIRTIO_SCSI_S_ABORTED is
376 // intentional as well, not an oversight.
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
:
384 Packet
->HostAdapterStatus
= EFI_EXT_SCSI_STATUS_HOST_ADAPTER_OTHER
;
387 return EFI_DEVICE_ERROR
;
393 The function can be used to create a fake host adapter error.
395 When VirtioScsiPassThru() is failed due to some reasons then this function
396 can be called to construct a host adapter error.
398 @param[out] Packet The Extended SCSI Pass Thru Protocol packet that the host
399 adapter error shall be placed in.
402 @retval EFI_DEVICE_ERROR The function returns this status code
403 unconditionally, to be propagated by
404 VirtioScsiPassThru().
409 ReportHostAdapterError (
410 OUT EFI_EXT_SCSI_PASS_THRU_SCSI_REQUEST_PACKET
*Packet
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
;
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.
432 IN EFI_EXT_SCSI_PASS_THRU_PROTOCOL
*This
,
435 IN OUT EFI_EXT_SCSI_PASS_THRU_SCSI_REQUEST_PACKET
*Packet
,
436 IN EFI_EVENT Event OPTIONAL
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
;
449 VOID
*OutDataMapping
;
450 EFI_PHYSICAL_ADDRESS RequestDeviceAddress
;
451 EFI_PHYSICAL_ADDRESS ResponseDeviceAddress
;
452 EFI_PHYSICAL_ADDRESS InDataDeviceAddress
;
453 EFI_PHYSICAL_ADDRESS OutDataDeviceAddress
;
455 UINTN InDataNumPages
;
456 BOOLEAN OutDataBufferIsMapped
;
459 // Set InDataMapping,OutDataMapping,InDataDeviceAddress and OutDataDeviceAddress to
460 // suppress incorrect compiler/analyzer warnings.
462 InDataMapping
= NULL
;
463 OutDataMapping
= NULL
;
464 InDataDeviceAddress
= 0;
465 OutDataDeviceAddress
= 0;
467 ZeroMem ((VOID
*) &Request
, sizeof (Request
));
469 Dev
= VIRTIO_SCSI_FROM_PASS_THRU (This
);
470 CopyMem (&TargetValue
, Target
, sizeof TargetValue
);
473 OutDataBufferIsMapped
= FALSE
;
476 Status
= PopulateRequest (Dev
, TargetValue
, Lun
, Packet
, &Request
);
477 if (EFI_ERROR (Status
)) {
482 // Map the virtio-scsi Request header buffer
484 Status
= VirtioMapAllBytesInSharedBuffer (
486 VirtioOperationBusMasterRead
,
489 &RequestDeviceAddress
,
491 if (EFI_ERROR (Status
)) {
492 return ReportHostAdapterError (Packet
);
496 // Map the input buffer
498 if (Packet
->InTransferLength
> 0) {
500 // Allocate a intermediate input buffer. This is mainly to handle the
502 // * caller submits a bi-directional request
503 // * we perform the request fine
504 // * but we fail to unmap the "InDataMapping"
506 // In that case simply returing the EFI_DEVICE_ERROR is not sufficient. In
507 // addition to the error code we also need to update Packet fields
508 // accordingly so that we report the full loss of the incoming transfer.
510 // We allocate a temporary buffer and map it with BusMasterCommonBuffer. If
511 // the Virtio request is successful then we copy the data from temporary
512 // buffer into Packet->InDataBuffer.
514 InDataNumPages
= EFI_SIZE_TO_PAGES ((UINTN
)Packet
->InTransferLength
);
515 Status
= Dev
->VirtIo
->AllocateSharedPages (
520 if (EFI_ERROR (Status
)) {
521 Status
= ReportHostAdapterError (Packet
);
522 goto UnmapRequestBuffer
;
525 ZeroMem (InDataBuffer
, Packet
->InTransferLength
);
527 Status
= VirtioMapAllBytesInSharedBuffer (
529 VirtioOperationBusMasterCommonBuffer
,
531 Packet
->InTransferLength
,
532 &InDataDeviceAddress
,
535 if (EFI_ERROR (Status
)) {
536 Status
= ReportHostAdapterError (Packet
);
537 goto FreeInDataBuffer
;
542 // Map the output buffer
544 if (Packet
->OutTransferLength
> 0) {
545 Status
= VirtioMapAllBytesInSharedBuffer (
547 VirtioOperationBusMasterRead
,
548 Packet
->OutDataBuffer
,
549 Packet
->OutTransferLength
,
550 &OutDataDeviceAddress
,
553 if (EFI_ERROR (Status
)) {
554 Status
= ReportHostAdapterError (Packet
);
555 goto UnmapInDataBuffer
;
558 OutDataBufferIsMapped
= TRUE
;
562 // Response header is bi-direction (we preset with host status and expect
563 // the device to update it). Allocate a response buffer which can be mapped
564 // to access equally by both processor and device.
566 Status
= Dev
->VirtIo
->AllocateSharedPages (
568 EFI_SIZE_TO_PAGES (sizeof *Response
),
571 if (EFI_ERROR (Status
)) {
572 Status
= ReportHostAdapterError (Packet
);
573 goto UnmapOutDataBuffer
;
576 Response
= ResponseBuffer
;
578 ZeroMem ((VOID
*)Response
, sizeof (*Response
));
581 // preset a host status for ourselves that we do not accept as success
583 Response
->Response
= VIRTIO_SCSI_S_FAILURE
;
586 // Map the response buffer with BusMasterCommonBuffer so that response
587 // buffer can be accessed by both host and device.
589 Status
= VirtioMapAllBytesInSharedBuffer (
591 VirtioOperationBusMasterCommonBuffer
,
594 &ResponseDeviceAddress
,
597 if (EFI_ERROR (Status
)) {
598 Status
= ReportHostAdapterError (Packet
);
599 goto FreeResponseBuffer
;
602 VirtioPrepare (&Dev
->Ring
, &Indices
);
605 // ensured by VirtioScsiInit() -- this predicate, in combination with the
606 // lock-step progress, ensures we don't have to track free descriptors.
608 ASSERT (Dev
->Ring
.QueueSize
>= 4);
615 RequestDeviceAddress
,
622 // enqueue "dataout" if any
624 if (Packet
->OutTransferLength
> 0) {
627 OutDataDeviceAddress
,
628 Packet
->OutTransferLength
,
635 // enqueue Response, to be written by the host
639 ResponseDeviceAddress
,
641 VRING_DESC_F_WRITE
| (Packet
->InTransferLength
> 0 ? VRING_DESC_F_NEXT
: 0),
646 // enqueue "datain" if any, to be written by the host
648 if (Packet
->InTransferLength
> 0) {
652 Packet
->InTransferLength
,
658 // If kicking the host fails, we must fake a host adapter error.
659 // EFI_NOT_READY would save us the effort, but it would also suggest that the
662 if (VirtioFlush (Dev
->VirtIo
, VIRTIO_SCSI_REQUEST_QUEUE
, &Dev
->Ring
,
663 &Indices
, NULL
) != EFI_SUCCESS
) {
664 Status
= ReportHostAdapterError (Packet
);
665 goto UnmapResponseBuffer
;
668 Status
= ParseResponse (Packet
, Response
);
671 // If virtio request was successful and it was a CPU read request then we
672 // have used an intermediate buffer. Copy the data from intermediate buffer
673 // to the final buffer.
675 if (InDataBuffer
!= NULL
) {
676 CopyMem (Packet
->InDataBuffer
, InDataBuffer
, Packet
->InTransferLength
);
680 Dev
->VirtIo
->UnmapSharedBuffer (Dev
->VirtIo
, ResponseMapping
);
683 Dev
->VirtIo
->FreeSharedPages (
685 EFI_SIZE_TO_PAGES (sizeof *Response
),
690 if (OutDataBufferIsMapped
) {
691 Dev
->VirtIo
->UnmapSharedBuffer (Dev
->VirtIo
, OutDataMapping
);
695 if (InDataBuffer
!= NULL
) {
696 Dev
->VirtIo
->UnmapSharedBuffer (Dev
->VirtIo
, InDataMapping
);
700 if (InDataBuffer
!= NULL
) {
701 Dev
->VirtIo
->FreeSharedPages (Dev
->VirtIo
, InDataNumPages
, InDataBuffer
);
705 Dev
->VirtIo
->UnmapSharedBuffer (Dev
->VirtIo
, RequestMapping
);
713 VirtioScsiGetNextTargetLun (
714 IN EFI_EXT_SCSI_PASS_THRU_PROTOCOL
*This
,
715 IN OUT UINT8
**TargetPointer
,
725 // the TargetPointer input parameter is unnecessarily a pointer-to-pointer
727 Target
= *TargetPointer
;
730 // Search for first non-0xFF byte. If not found, return first target & LUN.
732 for (Idx
= 0; Idx
< TARGET_MAX_BYTES
&& Target
[Idx
] == 0xFF; ++Idx
)
734 if (Idx
== TARGET_MAX_BYTES
) {
735 SetMem (Target
, TARGET_MAX_BYTES
, 0x00);
741 // see the TARGET_MAX_BYTES check in "VirtioScsi.h"
743 CopyMem (&LastTarget
, Target
, sizeof LastTarget
);
746 // increment (target, LUN) pair if valid on input
748 Dev
= VIRTIO_SCSI_FROM_PASS_THRU (This
);
749 if (LastTarget
> Dev
->MaxTarget
|| *Lun
> Dev
->MaxLun
) {
750 return EFI_INVALID_PARAMETER
;
753 if (*Lun
< Dev
->MaxLun
) {
758 if (LastTarget
< Dev
->MaxTarget
) {
761 CopyMem (Target
, &LastTarget
, sizeof LastTarget
);
765 return EFI_NOT_FOUND
;
771 VirtioScsiBuildDevicePath (
772 IN EFI_EXT_SCSI_PASS_THRU_PROTOCOL
*This
,
775 IN OUT EFI_DEVICE_PATH_PROTOCOL
**DevicePath
780 SCSI_DEVICE_PATH
*ScsiDevicePath
;
782 if (DevicePath
== NULL
) {
783 return EFI_INVALID_PARAMETER
;
786 CopyMem (&TargetValue
, Target
, sizeof TargetValue
);
787 Dev
= VIRTIO_SCSI_FROM_PASS_THRU (This
);
788 if (TargetValue
> Dev
->MaxTarget
|| Lun
> Dev
->MaxLun
|| Lun
> 0xFFFF) {
789 return EFI_NOT_FOUND
;
792 ScsiDevicePath
= AllocatePool (sizeof *ScsiDevicePath
);
793 if (ScsiDevicePath
== NULL
) {
794 return EFI_OUT_OF_RESOURCES
;
797 ScsiDevicePath
->Header
.Type
= MESSAGING_DEVICE_PATH
;
798 ScsiDevicePath
->Header
.SubType
= MSG_SCSI_DP
;
799 ScsiDevicePath
->Header
.Length
[0] = (UINT8
) sizeof *ScsiDevicePath
;
800 ScsiDevicePath
->Header
.Length
[1] = (UINT8
) (sizeof *ScsiDevicePath
>> 8);
801 ScsiDevicePath
->Pun
= TargetValue
;
802 ScsiDevicePath
->Lun
= (UINT16
) Lun
;
804 *DevicePath
= &ScsiDevicePath
->Header
;
811 VirtioScsiGetTargetLun (
812 IN EFI_EXT_SCSI_PASS_THRU_PROTOCOL
*This
,
813 IN EFI_DEVICE_PATH_PROTOCOL
*DevicePath
,
814 OUT UINT8
**TargetPointer
,
818 SCSI_DEVICE_PATH
*ScsiDevicePath
;
822 if (DevicePath
== NULL
|| TargetPointer
== NULL
|| *TargetPointer
== NULL
||
824 return EFI_INVALID_PARAMETER
;
827 if (DevicePath
->Type
!= MESSAGING_DEVICE_PATH
||
828 DevicePath
->SubType
!= MSG_SCSI_DP
) {
829 return EFI_UNSUPPORTED
;
832 ScsiDevicePath
= (SCSI_DEVICE_PATH
*) DevicePath
;
833 Dev
= VIRTIO_SCSI_FROM_PASS_THRU (This
);
834 if (ScsiDevicePath
->Pun
> Dev
->MaxTarget
||
835 ScsiDevicePath
->Lun
> Dev
->MaxLun
) {
836 return EFI_NOT_FOUND
;
840 // a) the TargetPointer input parameter is unnecessarily a pointer-to-pointer
841 // b) see the TARGET_MAX_BYTES check in "VirtioScsi.h"
842 // c) ScsiDevicePath->Pun is an UINT16
844 Target
= *TargetPointer
;
845 CopyMem (Target
, &ScsiDevicePath
->Pun
, 2);
846 SetMem (Target
+ 2, TARGET_MAX_BYTES
- 2, 0x00);
848 *Lun
= ScsiDevicePath
->Lun
;
855 VirtioScsiResetChannel (
856 IN EFI_EXT_SCSI_PASS_THRU_PROTOCOL
*This
859 return EFI_UNSUPPORTED
;
865 VirtioScsiResetTargetLun (
866 IN EFI_EXT_SCSI_PASS_THRU_PROTOCOL
*This
,
871 return EFI_UNSUPPORTED
;
877 VirtioScsiGetNextTarget (
878 IN EFI_EXT_SCSI_PASS_THRU_PROTOCOL
*This
,
879 IN OUT UINT8
**TargetPointer
888 // the TargetPointer input parameter is unnecessarily a pointer-to-pointer
890 Target
= *TargetPointer
;
893 // Search for first non-0xFF byte. If not found, return first target.
895 for (Idx
= 0; Idx
< TARGET_MAX_BYTES
&& Target
[Idx
] == 0xFF; ++Idx
)
897 if (Idx
== TARGET_MAX_BYTES
) {
898 SetMem (Target
, TARGET_MAX_BYTES
, 0x00);
903 // see the TARGET_MAX_BYTES check in "VirtioScsi.h"
905 CopyMem (&LastTarget
, Target
, sizeof LastTarget
);
908 // increment target if valid on input
910 Dev
= VIRTIO_SCSI_FROM_PASS_THRU (This
);
911 if (LastTarget
> Dev
->MaxTarget
) {
912 return EFI_INVALID_PARAMETER
;
915 if (LastTarget
< Dev
->MaxTarget
) {
917 CopyMem (Target
, &LastTarget
, sizeof LastTarget
);
921 return EFI_NOT_FOUND
;
929 IN OUT VSCSI_DEV
*Dev
934 UINT64 RingBaseShift
;
936 UINT16 MaxChannel
; // for validation only
937 UINT32 NumQueues
; // for validation only
941 // Execute virtio-0.9.5, 2.2.1 Device Initialization Sequence.
943 NextDevStat
= 0; // step 1 -- reset device
944 Status
= Dev
->VirtIo
->SetDeviceStatus (Dev
->VirtIo
, NextDevStat
);
945 if (EFI_ERROR (Status
)) {
949 NextDevStat
|= VSTAT_ACK
; // step 2 -- acknowledge device presence
950 Status
= Dev
->VirtIo
->SetDeviceStatus (Dev
->VirtIo
, NextDevStat
);
951 if (EFI_ERROR (Status
)) {
955 NextDevStat
|= VSTAT_DRIVER
; // step 3 -- we know how to drive it
956 Status
= Dev
->VirtIo
->SetDeviceStatus (Dev
->VirtIo
, NextDevStat
);
957 if (EFI_ERROR (Status
)) {
962 // Set Page Size - MMIO VirtIo Specific
964 Status
= Dev
->VirtIo
->SetPageSize (Dev
->VirtIo
, EFI_PAGE_SIZE
);
965 if (EFI_ERROR (Status
)) {
970 // step 4a -- retrieve and validate features
972 Status
= Dev
->VirtIo
->GetDeviceFeatures (Dev
->VirtIo
, &Features
);
973 if (EFI_ERROR (Status
)) {
976 Dev
->InOutSupported
= (BOOLEAN
) ((Features
& VIRTIO_SCSI_F_INOUT
) != 0);
978 Status
= VIRTIO_CFG_READ (Dev
, MaxChannel
, &MaxChannel
);
979 if (EFI_ERROR (Status
)) {
982 if (MaxChannel
!= 0) {
984 // this driver is for a single-channel virtio-scsi HBA
986 Status
= EFI_UNSUPPORTED
;
990 Status
= VIRTIO_CFG_READ (Dev
, NumQueues
, &NumQueues
);
991 if (EFI_ERROR (Status
)) {
995 Status
= EFI_UNSUPPORTED
;
999 Status
= VIRTIO_CFG_READ (Dev
, MaxTarget
, &Dev
->MaxTarget
);
1000 if (EFI_ERROR (Status
)) {
1003 if (Dev
->MaxTarget
> PcdGet16 (PcdVirtioScsiMaxTargetLimit
)) {
1004 Dev
->MaxTarget
= PcdGet16 (PcdVirtioScsiMaxTargetLimit
);
1007 Status
= VIRTIO_CFG_READ (Dev
, MaxLun
, &Dev
->MaxLun
);
1008 if (EFI_ERROR (Status
)) {
1011 if (Dev
->MaxLun
> PcdGet32 (PcdVirtioScsiMaxLunLimit
)) {
1012 Dev
->MaxLun
= PcdGet32 (PcdVirtioScsiMaxLunLimit
);
1015 Status
= VIRTIO_CFG_READ (Dev
, MaxSectors
, &Dev
->MaxSectors
);
1016 if (EFI_ERROR (Status
)) {
1019 if (Dev
->MaxSectors
< 2) {
1021 // We must be able to halve it for bidirectional transfers
1022 // (see EFI_BAD_BUFFER_SIZE in PopulateRequest()).
1024 Status
= EFI_UNSUPPORTED
;
1028 Features
&= VIRTIO_SCSI_F_INOUT
| VIRTIO_F_VERSION_1
|
1029 VIRTIO_F_IOMMU_PLATFORM
;
1032 // In virtio-1.0, feature negotiation is expected to complete before queue
1033 // discovery, and the device can also reject the selected set of features.
1035 if (Dev
->VirtIo
->Revision
>= VIRTIO_SPEC_REVISION (1, 0, 0)) {
1036 Status
= Virtio10WriteFeatures (Dev
->VirtIo
, Features
, &NextDevStat
);
1037 if (EFI_ERROR (Status
)) {
1043 // step 4b -- allocate request virtqueue
1045 Status
= Dev
->VirtIo
->SetQueueSel (Dev
->VirtIo
, VIRTIO_SCSI_REQUEST_QUEUE
);
1046 if (EFI_ERROR (Status
)) {
1049 Status
= Dev
->VirtIo
->GetQueueNumMax (Dev
->VirtIo
, &QueueSize
);
1050 if (EFI_ERROR (Status
)) {
1054 // VirtioScsiPassThru() uses at most four descriptors
1056 if (QueueSize
< 4) {
1057 Status
= EFI_UNSUPPORTED
;
1061 Status
= VirtioRingInit (Dev
->VirtIo
, QueueSize
, &Dev
->Ring
);
1062 if (EFI_ERROR (Status
)) {
1067 // If anything fails from here on, we must release the ring resources
1069 Status
= VirtioRingMap (
1075 if (EFI_ERROR (Status
)) {
1080 // Additional steps for MMIO: align the queue appropriately, and set the
1081 // size. If anything fails from here on, we must unmap the ring resources.
1083 Status
= Dev
->VirtIo
->SetQueueNum (Dev
->VirtIo
, QueueSize
);
1084 if (EFI_ERROR (Status
)) {
1088 Status
= Dev
->VirtIo
->SetQueueAlign (Dev
->VirtIo
, EFI_PAGE_SIZE
);
1089 if (EFI_ERROR (Status
)) {
1094 // step 4c -- Report GPFN (guest-physical frame number) of queue.
1096 Status
= Dev
->VirtIo
->SetQueueAddress (
1101 if (EFI_ERROR (Status
)) {
1106 // step 5 -- Report understood features and guest-tuneables.
1108 if (Dev
->VirtIo
->Revision
< VIRTIO_SPEC_REVISION (1, 0, 0)) {
1109 Features
&= ~(UINT64
)(VIRTIO_F_VERSION_1
| VIRTIO_F_IOMMU_PLATFORM
);
1110 Status
= Dev
->VirtIo
->SetGuestFeatures (Dev
->VirtIo
, Features
);
1111 if (EFI_ERROR (Status
)) {
1117 // We expect these maximum sizes from the host. Since they are
1118 // guest-negotiable, ask for them rather than just checking them.
1120 Status
= VIRTIO_CFG_WRITE (Dev
, CdbSize
, VIRTIO_SCSI_CDB_SIZE
);
1121 if (EFI_ERROR (Status
)) {
1124 Status
= VIRTIO_CFG_WRITE (Dev
, SenseSize
, VIRTIO_SCSI_SENSE_SIZE
);
1125 if (EFI_ERROR (Status
)) {
1130 // step 6 -- initialization complete
1132 NextDevStat
|= VSTAT_DRIVER_OK
;
1133 Status
= Dev
->VirtIo
->SetDeviceStatus (Dev
->VirtIo
, NextDevStat
);
1134 if (EFI_ERROR (Status
)) {
1139 // populate the exported interface's attributes
1141 Dev
->PassThru
.Mode
= &Dev
->PassThruMode
;
1142 Dev
->PassThru
.PassThru
= &VirtioScsiPassThru
;
1143 Dev
->PassThru
.GetNextTargetLun
= &VirtioScsiGetNextTargetLun
;
1144 Dev
->PassThru
.BuildDevicePath
= &VirtioScsiBuildDevicePath
;
1145 Dev
->PassThru
.GetTargetLun
= &VirtioScsiGetTargetLun
;
1146 Dev
->PassThru
.ResetChannel
= &VirtioScsiResetChannel
;
1147 Dev
->PassThru
.ResetTargetLun
= &VirtioScsiResetTargetLun
;
1148 Dev
->PassThru
.GetNextTarget
= &VirtioScsiGetNextTarget
;
1151 // AdapterId is a target for which no handle will be created during bus scan.
1152 // Prevent any conflict with real devices.
1154 Dev
->PassThruMode
.AdapterId
= 0xFFFFFFFF;
1157 // Set both physical and logical attributes for non-RAID SCSI channel. See
1158 // Driver Writer's Guide for UEFI 2.3.1 v1.01, 20.1.5 Implementing Extended
1159 // SCSI Pass Thru Protocol.
1161 Dev
->PassThruMode
.Attributes
= EFI_EXT_SCSI_PASS_THRU_ATTRIBUTES_PHYSICAL
|
1162 EFI_EXT_SCSI_PASS_THRU_ATTRIBUTES_LOGICAL
;
1165 // no restriction on transfer buffer alignment
1167 Dev
->PassThruMode
.IoAlign
= 0;
1172 Dev
->VirtIo
->UnmapSharedBuffer (Dev
->VirtIo
, Dev
->RingMap
);
1175 VirtioRingUninit (Dev
->VirtIo
, &Dev
->Ring
);
1179 // Notify the host about our failure to setup: virtio-0.9.5, 2.2.2.1 Device
1180 // Status. VirtIo access failure here should not mask the original error.
1182 NextDevStat
|= VSTAT_FAILED
;
1183 Dev
->VirtIo
->SetDeviceStatus (Dev
->VirtIo
, NextDevStat
);
1185 Dev
->InOutSupported
= FALSE
;
1188 Dev
->MaxSectors
= 0;
1190 return Status
; // reached only via Failed above
1198 IN OUT VSCSI_DEV
*Dev
1202 // Reset the virtual device -- see virtio-0.9.5, 2.2.2.1 Device Status. When
1203 // VIRTIO_CFG_WRITE() returns, the host will have learned to stay away from
1204 // the old comms area.
1206 Dev
->VirtIo
->SetDeviceStatus (Dev
->VirtIo
, 0);
1208 Dev
->InOutSupported
= FALSE
;
1211 Dev
->MaxSectors
= 0;
1213 Dev
->VirtIo
->UnmapSharedBuffer (Dev
->VirtIo
, Dev
->RingMap
);
1214 VirtioRingUninit (Dev
->VirtIo
, &Dev
->Ring
);
1216 SetMem (&Dev
->PassThru
, sizeof Dev
->PassThru
, 0x00);
1217 SetMem (&Dev
->PassThruMode
, sizeof Dev
->PassThruMode
, 0x00);
1222 // Event notification function enqueued by ExitBootServices().
1228 VirtioScsiExitBoot (
1235 DEBUG ((DEBUG_VERBOSE
, "%a: Context=0x%p\n", __FUNCTION__
, Context
));
1237 // Reset the device. This causes the hypervisor to forget about the virtio
1240 // We allocated said ring in EfiBootServicesData type memory, and code
1241 // executing after ExitBootServices() is permitted to overwrite it.
1244 Dev
->VirtIo
->SetDeviceStatus (Dev
->VirtIo
, 0);
1249 // Probe, start and stop functions of this driver, called by the DXE core for
1250 // specific devices.
1252 // The following specifications document these interfaces:
1253 // - Driver Writer's Guide for UEFI 2.3.1 v1.01, 9 Driver Binding Protocol
1254 // - UEFI Spec 2.3.1 + Errata C, 10.1 EFI Driver Binding Protocol
1256 // The implementation follows:
1257 // - Driver Writer's Guide for UEFI 2.3.1 v1.01
1258 // - 5.1.3.4 OpenProtocol() and CloseProtocol()
1259 // - UEFI Spec 2.3.1 + Errata C
1260 // - 6.3 Protocol Handler Services
1265 VirtioScsiDriverBindingSupported (
1266 IN EFI_DRIVER_BINDING_PROTOCOL
*This
,
1267 IN EFI_HANDLE DeviceHandle
,
1268 IN EFI_DEVICE_PATH_PROTOCOL
*RemainingDevicePath
1272 VIRTIO_DEVICE_PROTOCOL
*VirtIo
;
1275 // Attempt to open the device with the VirtIo set of interfaces. On success,
1276 // the protocol is "instantiated" for the VirtIo device. Covers duplicate open
1277 // attempts (EFI_ALREADY_STARTED).
1279 Status
= gBS
->OpenProtocol (
1280 DeviceHandle
, // candidate device
1281 &gVirtioDeviceProtocolGuid
, // for generic VirtIo access
1282 (VOID
**)&VirtIo
, // handle to instantiate
1283 This
->DriverBindingHandle
, // requestor driver identity
1284 DeviceHandle
, // ControllerHandle, according to
1285 // the UEFI Driver Model
1286 EFI_OPEN_PROTOCOL_BY_DRIVER
// get exclusive VirtIo access to
1287 // the device; to be released
1289 if (EFI_ERROR (Status
)) {
1293 if (VirtIo
->SubSystemDeviceId
!= VIRTIO_SUBSYSTEM_SCSI_HOST
) {
1294 Status
= EFI_UNSUPPORTED
;
1298 // We needed VirtIo access only transitorily, to see whether we support the
1301 gBS
->CloseProtocol (DeviceHandle
, &gVirtioDeviceProtocolGuid
,
1302 This
->DriverBindingHandle
, DeviceHandle
);
1309 VirtioScsiDriverBindingStart (
1310 IN EFI_DRIVER_BINDING_PROTOCOL
*This
,
1311 IN EFI_HANDLE DeviceHandle
,
1312 IN EFI_DEVICE_PATH_PROTOCOL
*RemainingDevicePath
1318 Dev
= (VSCSI_DEV
*) AllocateZeroPool (sizeof *Dev
);
1320 return EFI_OUT_OF_RESOURCES
;
1323 Status
= gBS
->OpenProtocol (DeviceHandle
, &gVirtioDeviceProtocolGuid
,
1324 (VOID
**)&Dev
->VirtIo
, This
->DriverBindingHandle
,
1325 DeviceHandle
, EFI_OPEN_PROTOCOL_BY_DRIVER
);
1326 if (EFI_ERROR (Status
)) {
1327 goto FreeVirtioScsi
;
1331 // VirtIo access granted, configure virtio-scsi device.
1333 Status
= VirtioScsiInit (Dev
);
1334 if (EFI_ERROR (Status
)) {
1338 Status
= gBS
->CreateEvent (EVT_SIGNAL_EXIT_BOOT_SERVICES
, TPL_CALLBACK
,
1339 &VirtioScsiExitBoot
, Dev
, &Dev
->ExitBoot
);
1340 if (EFI_ERROR (Status
)) {
1345 // Setup complete, attempt to export the driver instance's PassThru
1348 Dev
->Signature
= VSCSI_SIG
;
1349 Status
= gBS
->InstallProtocolInterface (&DeviceHandle
,
1350 &gEfiExtScsiPassThruProtocolGuid
, EFI_NATIVE_INTERFACE
,
1352 if (EFI_ERROR (Status
)) {
1359 gBS
->CloseEvent (Dev
->ExitBoot
);
1362 VirtioScsiUninit (Dev
);
1365 gBS
->CloseProtocol (DeviceHandle
, &gVirtioDeviceProtocolGuid
,
1366 This
->DriverBindingHandle
, DeviceHandle
);
1377 VirtioScsiDriverBindingStop (
1378 IN EFI_DRIVER_BINDING_PROTOCOL
*This
,
1379 IN EFI_HANDLE DeviceHandle
,
1380 IN UINTN NumberOfChildren
,
1381 IN EFI_HANDLE
*ChildHandleBuffer
1385 EFI_EXT_SCSI_PASS_THRU_PROTOCOL
*PassThru
;
1388 Status
= gBS
->OpenProtocol (
1389 DeviceHandle
, // candidate device
1390 &gEfiExtScsiPassThruProtocolGuid
, // retrieve the SCSI iface
1391 (VOID
**)&PassThru
, // target pointer
1392 This
->DriverBindingHandle
, // requestor driver ident.
1393 DeviceHandle
, // lookup req. for dev.
1394 EFI_OPEN_PROTOCOL_GET_PROTOCOL
// lookup only, no new ref.
1396 if (EFI_ERROR (Status
)) {
1400 Dev
= VIRTIO_SCSI_FROM_PASS_THRU (PassThru
);
1403 // Handle Stop() requests for in-use driver instances gracefully.
1405 Status
= gBS
->UninstallProtocolInterface (DeviceHandle
,
1406 &gEfiExtScsiPassThruProtocolGuid
, &Dev
->PassThru
);
1407 if (EFI_ERROR (Status
)) {
1411 gBS
->CloseEvent (Dev
->ExitBoot
);
1413 VirtioScsiUninit (Dev
);
1415 gBS
->CloseProtocol (DeviceHandle
, &gVirtioDeviceProtocolGuid
,
1416 This
->DriverBindingHandle
, DeviceHandle
);
1425 // The static object that groups the Supported() (ie. probe), Start() and
1426 // Stop() functions of the driver together. Refer to UEFI Spec 2.3.1 + Errata
1427 // C, 10.1 EFI Driver Binding Protocol.
1429 STATIC EFI_DRIVER_BINDING_PROTOCOL gDriverBinding
= {
1430 &VirtioScsiDriverBindingSupported
,
1431 &VirtioScsiDriverBindingStart
,
1432 &VirtioScsiDriverBindingStop
,
1433 0x10, // Version, must be in [0x10 .. 0xFFFFFFEF] for IHV-developed drivers
1434 NULL
, // ImageHandle, to be overwritten by
1435 // EfiLibInstallDriverBindingComponentName2() in VirtioScsiEntryPoint()
1436 NULL
// DriverBindingHandle, ditto
1441 // The purpose of the following scaffolding (EFI_COMPONENT_NAME_PROTOCOL and
1442 // EFI_COMPONENT_NAME2_PROTOCOL implementation) is to format the driver's name
1443 // in English, for display on standard console devices. This is recommended for
1444 // UEFI drivers that follow the UEFI Driver Model. Refer to the Driver Writer's
1445 // Guide for UEFI 2.3.1 v1.01, 11 UEFI Driver and Controller Names.
1447 // Device type names ("Virtio SCSI Host Device") are not formatted because the
1448 // driver supports only that device type. Therefore the driver name suffices
1449 // for unambiguous identification.
1453 EFI_UNICODE_STRING_TABLE mDriverNameTable
[] = {
1454 { "eng;en", L
"Virtio SCSI Host Driver" },
1459 EFI_COMPONENT_NAME_PROTOCOL gComponentName
;
1463 VirtioScsiGetDriverName (
1464 IN EFI_COMPONENT_NAME_PROTOCOL
*This
,
1466 OUT CHAR16
**DriverName
1469 return LookupUnicodeString2 (
1471 This
->SupportedLanguages
,
1474 (BOOLEAN
)(This
== &gComponentName
) // Iso639Language
1480 VirtioScsiGetDeviceName (
1481 IN EFI_COMPONENT_NAME_PROTOCOL
*This
,
1482 IN EFI_HANDLE DeviceHandle
,
1483 IN EFI_HANDLE ChildHandle
,
1485 OUT CHAR16
**ControllerName
1488 return EFI_UNSUPPORTED
;
1492 EFI_COMPONENT_NAME_PROTOCOL gComponentName
= {
1493 &VirtioScsiGetDriverName
,
1494 &VirtioScsiGetDeviceName
,
1495 "eng" // SupportedLanguages, ISO 639-2 language codes
1499 EFI_COMPONENT_NAME2_PROTOCOL gComponentName2
= {
1500 (EFI_COMPONENT_NAME2_GET_DRIVER_NAME
) &VirtioScsiGetDriverName
,
1501 (EFI_COMPONENT_NAME2_GET_CONTROLLER_NAME
) &VirtioScsiGetDeviceName
,
1502 "en" // SupportedLanguages, RFC 4646 language codes
1507 // Entry point of this driver.
1511 VirtioScsiEntryPoint (
1512 IN EFI_HANDLE ImageHandle
,
1513 IN EFI_SYSTEM_TABLE
*SystemTable
1516 return EfiLibInstallDriverBindingComponentName2 (