VirtualBox

source: vbox/trunk/src/VBox/Devices/EFI/Firmware/MdeModulePkg/Bus/Scsi/ScsiBusDxe/ScsiBus.h

Last change on this file was 99404, checked in by vboxsync, 2 years ago

Devices/EFI/FirmwareNew: Update to edk2-stable202302 and make it build, bugref:4643
  • Property svn:eol-style set to native
File size: 19.1 KB
Line 
1/** @file
2 Header file for SCSI Bus Driver.
3
4Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
5SPDX-License-Identifier: BSD-2-Clause-Patent
6
7**/
8
9#ifndef _SCSI_BUS_H_
10#define _SCSI_BUS_H_
11
12#include <Uefi.h>
13
14#include <Protocol/ScsiPassThru.h>
15#include <Protocol/ScsiPassThruExt.h>
16#include <Protocol/ScsiIo.h>
17#include <Protocol/ComponentName.h>
18#include <Protocol/DriverBinding.h>
19#include <Protocol/DevicePath.h>
20
21#include <Library/DebugLib.h>
22#include <Library/UefiDriverEntryPoint.h>
23#include <Library/UefiLib.h>
24#include <Library/BaseMemoryLib.h>
25#include <Library/MemoryAllocationLib.h>
26#include <Library/UefiScsiLib.h>
27#include <Library/UefiBootServicesTableLib.h>
28#include <Library/DevicePathLib.h>
29#include <Library/ReportStatusCodeLib.h>
30
31#include <IndustryStandard/Scsi.h>
32
33#define SCSI_IO_DEV_SIGNATURE SIGNATURE_32 ('s', 'c', 'i', 'o')
34
35typedef union {
36 UINT32 Scsi;
37 UINT8 ExtScsi[4];
38} SCSI_ID;
39
40typedef struct _SCSI_TARGET_ID {
41 SCSI_ID ScsiId;
42 UINT8 ExtScsiId[12];
43} SCSI_TARGET_ID;
44
45typedef struct {
46 VOID *Data1;
47 VOID *Data2;
48} SCSI_EVENT_DATA;
49
50//
51// SCSI Bus Controller device structure
52//
53#define SCSI_BUS_DEVICE_SIGNATURE SIGNATURE_32 ('s', 'c', 's', 'i')
54
55//
56// SCSI Bus Timeout Experience Value
57//
58#define SCSI_BUS_TIMEOUT EFI_TIMER_PERIOD_SECONDS (3)
59
60//
61// The ScsiBusProtocol is just used to locate ScsiBusDev
62// structure in the SCSIBusDriverBindingStop(). Then we can
63// Close all opened protocols and release this structure.
64// ScsiBusProtocol is the private protocol.
65// gEfiCallerIdGuid will be used as its protocol guid.
66//
67typedef struct _EFI_SCSI_BUS_PROTOCOL {
68 UINT64 Reserved;
69} EFI_SCSI_BUS_PROTOCOL;
70
71typedef struct _SCSI_BUS_DEVICE {
72 UINTN Signature;
73 EFI_SCSI_BUS_PROTOCOL BusIdentify;
74 BOOLEAN ExtScsiSupport;
75 EFI_SCSI_PASS_THRU_PROTOCOL *ScsiInterface;
76 EFI_EXT_SCSI_PASS_THRU_PROTOCOL *ExtScsiInterface;
77 EFI_DEVICE_PATH_PROTOCOL *DevicePath;
78} SCSI_BUS_DEVICE;
79
80#define SCSI_BUS_CONTROLLER_DEVICE_FROM_THIS(a) CR (a, SCSI_BUS_DEVICE, BusIdentify, SCSI_BUS_DEVICE_SIGNATURE)
81
82typedef struct {
83 UINT32 Signature;
84 EFI_HANDLE Handle;
85 EFI_SCSI_IO_PROTOCOL ScsiIo;
86 EFI_DEVICE_PATH_PROTOCOL *DevicePath;
87 BOOLEAN ExtScsiSupport;
88 EFI_SCSI_PASS_THRU_PROTOCOL *ScsiPassThru;
89 EFI_EXT_SCSI_PASS_THRU_PROTOCOL *ExtScsiPassThru;
90 SCSI_BUS_DEVICE *ScsiBusDeviceData;
91 SCSI_TARGET_ID Pun;
92 UINT64 Lun;
93 UINT8 ScsiDeviceType;
94 UINT8 ScsiVersion;
95 BOOLEAN RemovableDevice;
96} SCSI_IO_DEV;
97
98#define SCSI_IO_DEV_FROM_THIS(a) CR (a, SCSI_IO_DEV, ScsiIo, SCSI_IO_DEV_SIGNATURE)
99
100//
101// Global Variables
102//
103extern EFI_DRIVER_BINDING_PROTOCOL gScsiBusDriverBinding;
104extern EFI_COMPONENT_NAME_PROTOCOL gScsiBusComponentName;
105extern EFI_COMPONENT_NAME2_PROTOCOL gScsiBusComponentName2;
106
107/**
108 Test to see if this driver supports ControllerHandle.
109
110 This service is called by the EFI boot service ConnectController(). In order
111 to make drivers as small as possible, there are a few calling restrictions for
112 this service. ConnectController() must follow these calling restrictions. If
113 any other agent wishes to call Supported() it must also follow these calling
114 restrictions.
115
116 @param This Protocol instance pointer.
117 @param ControllerHandle Handle of device to test
118 @param RemainingDevicePath Optional parameter use to pick a specific child
119 device to start.
120
121 @retval EFI_SUCCESS This driver supports this device
122 @retval EFI_ALREADY_STARTED This driver is already running on this device
123 @retval other This driver does not support this device
124
125**/
126EFI_STATUS
127EFIAPI
128SCSIBusDriverBindingSupported (
129 IN EFI_DRIVER_BINDING_PROTOCOL *This,
130 IN EFI_HANDLE Controller,
131 IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath
132 );
133
134/**
135 Start this driver on ControllerHandle.
136
137 This service is called by the EFI boot service ConnectController(). In order
138 to make drivers as small as possible, there are a few calling restrictions for
139 this service. ConnectController() must follow these calling restrictions. If
140 any other agent wishes to call Start() it must also follow these calling
141 restrictions.
142
143 @param This Protocol instance pointer.
144 @param ControllerHandle Handle of device to bind driver to
145 @param RemainingDevicePath Optional parameter use to pick a specific child
146 device to start.
147
148 @retval EFI_SUCCESS This driver is added to ControllerHandle
149 @retval EFI_ALREADY_STARTED This driver is already running on ControllerHandle
150 @retval other This driver does not support this device
151
152**/
153EFI_STATUS
154EFIAPI
155SCSIBusDriverBindingStart (
156 IN EFI_DRIVER_BINDING_PROTOCOL *This,
157 IN EFI_HANDLE Controller,
158 IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath
159 );
160
161/**
162 Stop this driver on ControllerHandle.
163
164 This service is called by the EFI boot service DisconnectController().
165 In order to make drivers as small as possible, there are a few calling
166 restrictions for this service. DisconnectController() must follow these
167 calling restrictions. If any other agent wishes to call Stop() it must also
168 follow these calling restrictions.
169
170 @param This Protocol instance pointer.
171 @param ControllerHandle Handle of device to stop driver on
172 @param NumberOfChildren Number of Handles in ChildHandleBuffer. If number of
173 children is zero stop the entire bus driver.
174 @param ChildHandleBuffer List of Child Handles to Stop.
175
176 @retval EFI_SUCCESS This driver is removed ControllerHandle
177 @retval other This driver was not removed from this device
178
179**/
180EFI_STATUS
181EFIAPI
182SCSIBusDriverBindingStop (
183 IN EFI_DRIVER_BINDING_PROTOCOL *This,
184 IN EFI_HANDLE Controller,
185 IN UINTN NumberOfChildren,
186 IN EFI_HANDLE *ChildHandleBuffer
187 );
188
189//
190// EFI Component Name Functions
191//
192
193/**
194 Retrieves a Unicode string that is the user readable name of the driver.
195
196 This function retrieves the user readable name of a driver in the form of a
197 Unicode string. If the driver specified by This has a user readable name in
198 the language specified by Language, then a pointer to the driver name is
199 returned in DriverName, and EFI_SUCCESS is returned. If the driver specified
200 by This does not support the language specified by Language,
201 then EFI_UNSUPPORTED is returned.
202
203 @param This A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or
204 EFI_COMPONENT_NAME_PROTOCOL instance.
205
206 @param Language A pointer to a Null-terminated ASCII string
207 array indicating the language. This is the
208 language of the driver name that the caller is
209 requesting, and it must match one of the
210 languages specified in SupportedLanguages. The
211 number of languages supported by a driver is up
212 to the driver writer. Language is specified
213 in RFC 4646 or ISO 639-2 language code format.
214
215 @param DriverName A pointer to the Unicode string to return.
216 This Unicode string is the name of the
217 driver specified by This in the language
218 specified by Language.
219
220 @retval EFI_SUCCESS The Unicode string for the Driver specified by
221 This and the language specified by Language was
222 returned in DriverName.
223
224 @retval EFI_INVALID_PARAMETER Language is NULL.
225
226 @retval EFI_INVALID_PARAMETER DriverName is NULL.
227
228 @retval EFI_UNSUPPORTED The driver specified by This does not support
229 the language specified by Language.
230
231**/
232EFI_STATUS
233EFIAPI
234ScsiBusComponentNameGetDriverName (
235 IN EFI_COMPONENT_NAME_PROTOCOL *This,
236 IN CHAR8 *Language,
237 OUT CHAR16 **DriverName
238 );
239
240/**
241 Retrieves a Unicode string that is the user readable name of the controller
242 that is being managed by a driver.
243
244 This function retrieves the user readable name of the controller specified by
245 ControllerHandle and ChildHandle in the form of a Unicode string. If the
246 driver specified by This has a user readable name in the language specified by
247 Language, then a pointer to the controller name is returned in ControllerName,
248 and EFI_SUCCESS is returned. If the driver specified by This is not currently
249 managing the controller specified by ControllerHandle and ChildHandle,
250 then EFI_UNSUPPORTED is returned. If the driver specified by This does not
251 support the language specified by Language, then EFI_UNSUPPORTED is returned.
252
253 @param This A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or
254 EFI_COMPONENT_NAME_PROTOCOL instance.
255
256 @param ControllerHandle The handle of a controller that the driver
257 specified by This is managing. This handle
258 specifies the controller whose name is to be
259 returned.
260
261 @param ChildHandle The handle of the child controller to retrieve
262 the name of. This is an optional parameter that
263 may be NULL. It will be NULL for device
264 drivers. It will also be NULL for a bus drivers
265 that wish to retrieve the name of the bus
266 controller. It will not be NULL for a bus
267 driver that wishes to retrieve the name of a
268 child controller.
269
270 @param Language A pointer to a Null-terminated ASCII string
271 array indicating the language. This is the
272 language of the driver name that the caller is
273 requesting, and it must match one of the
274 languages specified in SupportedLanguages. The
275 number of languages supported by a driver is up
276 to the driver writer. Language is specified in
277 RFC 4646 or ISO 639-2 language code format.
278
279 @param ControllerName A pointer to the Unicode string to return.
280 This Unicode string is the name of the
281 controller specified by ControllerHandle and
282 ChildHandle in the language specified by
283 Language from the point of view of the driver
284 specified by This.
285
286 @retval EFI_SUCCESS The Unicode string for the user readable name in
287 the language specified by Language for the
288 driver specified by This was returned in
289 DriverName.
290
291 @retval EFI_INVALID_PARAMETER ControllerHandle is NULL.
292
293 @retval EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a valid
294 EFI_HANDLE.
295
296 @retval EFI_INVALID_PARAMETER Language is NULL.
297
298 @retval EFI_INVALID_PARAMETER ControllerName is NULL.
299
300 @retval EFI_UNSUPPORTED The driver specified by This is not currently
301 managing the controller specified by
302 ControllerHandle and ChildHandle.
303
304 @retval EFI_UNSUPPORTED The driver specified by This does not support
305 the language specified by Language.
306
307**/
308EFI_STATUS
309EFIAPI
310ScsiBusComponentNameGetControllerName (
311 IN EFI_COMPONENT_NAME_PROTOCOL *This,
312 IN EFI_HANDLE ControllerHandle,
313 IN EFI_HANDLE ChildHandle OPTIONAL,
314 IN CHAR8 *Language,
315 OUT CHAR16 **ControllerName
316 );
317
318/**
319 Retrieves the device type information of the SCSI Controller.
320
321 @param This Protocol instance pointer.
322 @param DeviceType A pointer to the device type information retrieved from
323 the SCSI Controller.
324
325 @retval EFI_SUCCESS Retrieves the device type information successfully.
326 @retval EFI_INVALID_PARAMETER The DeviceType is NULL.
327
328**/
329EFI_STATUS
330EFIAPI
331ScsiGetDeviceType (
332 IN EFI_SCSI_IO_PROTOCOL *This,
333 OUT UINT8 *DeviceType
334 );
335
336/**
337 Retrieves the device location in the SCSI channel.
338
339 @param This Protocol instance pointer.
340 @param Target A pointer to the Target ID of a SCSI device
341 on the SCSI channel.
342 @param Lun A pointer to the LUN of the SCSI device on
343 the SCSI channel.
344
345 @retval EFI_SUCCESS Retrieves the device location successfully.
346 @retval EFI_INVALID_PARAMETER The Target or Lun is NULL.
347
348**/
349EFI_STATUS
350EFIAPI
351ScsiGetDeviceLocation (
352 IN EFI_SCSI_IO_PROTOCOL *This,
353 IN OUT UINT8 **Target,
354 OUT UINT64 *Lun
355 );
356
357/**
358 Resets the SCSI Bus that the SCSI Controller is attached to.
359
360 @param This Protocol instance pointer.
361
362 @retval EFI_SUCCESS The SCSI bus is reset successfully.
363 @retval EFI_DEVICE_ERROR Errors encountered when resetting the SCSI bus.
364 @retval EFI_UNSUPPORTED The bus reset operation is not supported by the
365 SCSI Host Controller.
366 @retval EFI_TIMEOUT A timeout occurred while attempting to reset
367 the SCSI bus.
368**/
369EFI_STATUS
370EFIAPI
371ScsiResetBus (
372 IN EFI_SCSI_IO_PROTOCOL *This
373 );
374
375/**
376 Resets the SCSI Controller that the device handle specifies.
377
378 @param This Protocol instance pointer.
379
380 @retval EFI_SUCCESS Reset the SCSI controller successfully.
381 @retval EFI_DEVICE_ERROR Errors are encountered when resetting the SCSI Controller.
382 @retval EFI_UNSUPPORTED The SCSI bus does not support a device reset operation.
383 @retval EFI_TIMEOUT A timeout occurred while attempting to reset the
384 SCSI Controller.
385**/
386EFI_STATUS
387EFIAPI
388ScsiResetDevice (
389 IN EFI_SCSI_IO_PROTOCOL *This
390 );
391
392/**
393 Sends a SCSI Request Packet to the SCSI Controller for execution.
394
395 @param This Protocol instance pointer.
396 @param CommandPacket The SCSI request packet to send to the SCSI
397 Controller specified by the device handle.
398 @param Event If the SCSI bus where the SCSI device is attached
399 does not support non-blocking I/O, then Event is
400 ignored, and blocking I/O is performed.
401 If Event is NULL, then blocking I/O is performed.
402 If Event is not NULL and non-blocking I/O is
403 supported, then non-blocking I/O is performed,
404 and Event will be signaled when the SCSI Request
405 Packet completes.
406
407 @retval EFI_SUCCESS The SCSI Request Packet was sent by the host
408 successfully, and TransferLength bytes were
409 transferred to/from DataBuffer.See
410 HostAdapterStatus, TargetStatus,
411 SenseDataLength, and SenseData in that order
412 for additional status information.
413 @retval EFI_BAD_BUFFER_SIZE The SCSI Request Packet was executed,
414 but the entire DataBuffer could not be transferred.
415 The actual number of bytes transferred is returned
416 in TransferLength. See HostAdapterStatus,
417 TargetStatus, SenseDataLength, and SenseData in
418 that order for additional status information.
419 @retval EFI_NOT_READY The SCSI Request Packet could not be sent because
420 there are too many SCSI Command Packets already
421 queued.The caller may retry again later.
422 @retval EFI_DEVICE_ERROR A device error occurred while attempting to send
423 the SCSI Request Packet. See HostAdapterStatus,
424 TargetStatus, SenseDataLength, and SenseData in
425 that order for additional status information.
426 @retval EFI_INVALID_PARAMETER The contents of CommandPacket are invalid.
427 The SCSI Request Packet was not sent, so no
428 additional status information is available.
429 @retval EFI_UNSUPPORTED The command described by the SCSI Request Packet
430 is not supported by the SCSI initiator(i.e., SCSI
431 Host Controller). The SCSI Request Packet was not
432 sent, so no additional status information is
433 available.
434 @retval EFI_TIMEOUT A timeout occurred while waiting for the SCSI
435 Request Packet to execute. See HostAdapterStatus,
436 TargetStatus, SenseDataLength, and SenseData in
437 that order for additional status information.
438**/
439EFI_STATUS
440EFIAPI
441ScsiExecuteSCSICommand (
442 IN EFI_SCSI_IO_PROTOCOL *This,
443 IN OUT EFI_SCSI_IO_SCSI_REQUEST_PACKET *CommandPacket,
444 IN EFI_EVENT Event OPTIONAL
445 );
446
447/**
448 Scan SCSI Bus to discover the device, and attach ScsiIoProtocol to it.
449
450 @param This Protocol instance pointer
451 @param Controller Controller handle
452 @param TargetId Target to be scanned
453 @param Lun The Lun of the SCSI device on the SCSI channel.
454 @param ScsiBusDev The pointer of SCSI_BUS_DEVICE
455
456 @retval EFI_SUCCESS Successfully to discover the device and attach
457 ScsiIoProtocol to it.
458 @retval EFI_NOT_FOUND Fail to discover the device.
459 @retval EFI_OUT_OF_RESOURCES Fail to allocate memory resources.
460
461**/
462EFI_STATUS
463EFIAPI
464ScsiScanCreateDevice (
465 IN EFI_DRIVER_BINDING_PROTOCOL *This,
466 IN EFI_HANDLE Controller,
467 IN SCSI_TARGET_ID *TargetId,
468 IN UINT64 Lun,
469 IN OUT SCSI_BUS_DEVICE *ScsiBusDev
470 );
471
472/**
473 Discovery SCSI Device
474
475 @param ScsiIoDevice The pointer of SCSI_IO_DEV
476
477 @retval EFI_SUCCESS Find SCSI Device and verify it.
478 @retval EFI_NOT_FOUND Unable to find SCSI Device.
479 @retval EFI_OUT_OF_RESOURCES Fail to allocate memory resources.
480
481**/
482EFI_STATUS
483DiscoverScsiDevice (
484 IN OUT SCSI_IO_DEV *ScsiIoDevice
485 );
486
487#endif
Note: See TracBrowser for help on using the repository browser.

© 2025 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette