xref: /illumos-gate/usr/src/boot/efi/include/Protocol/ScsiPassThru.h (revision f334afcfaebea1b7dc3430015651d8d748fa8a3e)
1 /** @file
2   SCSI Pass Through protocol as defined in EFI 1.1.
3   This protocol allows information about a SCSI channel to be collected,
4   and allows SCSI Request Packets to be sent to any SCSI devices on a SCSI
5   channel even if those devices are not boot devices. This protocol is attached
6   to the device handle of each SCSI channel in a system that the protocol
7   supports, and can be used for diagnostics. It may also be used to build
8   a Block I/O driver for SCSI hard drives and SCSI CD-ROM or DVD drives to
9   allow those devices to become boot devices.
10 
11   Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
12   SPDX-License-Identifier: BSD-2-Clause-Patent
13 
14 **/
15 
16 #ifndef __SCSI_PASS_THROUGH_H__
17 #define __SCSI_PASS_THROUGH_H__
18 
19 #define EFI_SCSI_PASS_THRU_PROTOCOL_GUID \
20   { \
21     0xa59e8fcf, 0xbda0, 0x43bb, {0x90, 0xb1, 0xd3, 0x73, 0x2e, 0xca, 0xa8, 0x77 } \
22   }
23 
24 ///
25 /// Forward reference for pure ANSI compatability
26 ///
27 typedef struct _EFI_SCSI_PASS_THRU_PROTOCOL EFI_SCSI_PASS_THRU_PROTOCOL;
28 
29 #define EFI_SCSI_PASS_THRU_ATTRIBUTES_PHYSICAL    0x0001
30 #define EFI_SCSI_PASS_THRU_ATTRIBUTES_LOGICAL     0x0002
31 #define EFI_SCSI_PASS_THRU_ATTRIBUTES_NONBLOCKIO  0x0004
32 
33 //
34 // SCSI Host Adapter Status definition
35 //
36 #define EFI_SCSI_STATUS_HOST_ADAPTER_OK                     0x00
37 #define EFI_SCSI_STATUS_HOST_ADAPTER_TIMEOUT_COMMAND        0x09  // timeout when processing the command
38 #define EFI_SCSI_STATUS_HOST_ADAPTER_TIMEOUT                0x0b  // timeout when waiting for the command processing
39 #define EFI_SCSI_STATUS_HOST_ADAPTER_MESSAGE_REJECT         0x0d  // a message reject was received when processing command
40 #define EFI_SCSI_STATUS_HOST_ADAPTER_BUS_RESET              0x0e  // a bus reset was detected
41 #define EFI_SCSI_STATUS_HOST_ADAPTER_PARITY_ERROR           0x0f
42 #define EFI_SCSI_STATUS_HOST_ADAPTER_REQUEST_SENSE_FAILED   0x10  // the adapter failed in issuing request sense command
43 #define EFI_SCSI_STATUS_HOST_ADAPTER_SELECTION_TIMEOUT      0x11  // selection timeout
44 #define EFI_SCSI_STATUS_HOST_ADAPTER_DATA_OVERRUN_UNDERRUN  0x12  // data overrun or data underrun
45 #define EFI_SCSI_STATUS_HOST_ADAPTER_BUS_FREE               0x13  // Unexepected bus free
46 #define EFI_SCSI_STATUS_HOST_ADAPTER_PHASE_ERROR            0x14  // Target bus phase sequence failure
47 #define EFI_SCSI_STATUS_HOST_ADAPTER_OTHER                  0x7f
48 
49 //
50 // SCSI Target Status definition
51 //
52 #define EFI_SCSI_STATUS_TARGET_GOOD                        0x00
53 #define EFI_SCSI_STATUS_TARGET_CHECK_CONDITION             0x02 // check condition
54 #define EFI_SCSI_STATUS_TARGET_CONDITION_MET               0x04 // condition met
55 #define EFI_SCSI_STATUS_TARGET_BUSY                        0x08 // busy
56 #define EFI_SCSI_STATUS_TARGET_INTERMEDIATE                0x10 // intermediate
57 #define EFI_SCSI_STATUS_TARGET_INTERMEDIATE_CONDITION_MET  0x14 // intermediate-condition met
58 #define EFI_SCSI_STATUS_TARGET_RESERVATION_CONFLICT        0x18 // reservation conflict
59 #define EFI_SCSI_STATUS_TARGET_COMMOND_TERMINATED          0x22 // command terminated
60 #define EFI_SCSI_STATUS_TARGET_QUEUE_FULL                  0x28 // queue full
61 
62 typedef struct {
63   ///
64   /// The timeout, in 100 ns units, to use for the execution of this SCSI
65   /// Request Packet. A Timeout value of 0 means that this function
66   /// will wait indefinitely for the SCSI Request Packet to execute. If
67   /// Timeout is greater than zero, then this function will return
68   /// EFI_TIMEOUT if the time required to execute the SCSI Request
69   /// Packet is greater than Timeout.
70   ///
71   UINT64    Timeout;
72   ///
73   /// A pointer to the data buffer to transfer between the SCSI
74   /// controller and the SCSI device. Must be aligned to the boundary
75   /// specified in the IoAlign field of the
76   /// EFI_SCSI_PASS_THRU_MODE structure.
77   ///
78   VOID      *DataBuffer;
79   ///
80   /// A pointer to the sense data that was generated by the execution of
81   /// the SCSI Request Packet.
82   ///
83   VOID      *SenseData;
84   ///
85   /// A pointer to buffer that contains the Command Data Block to
86   /// send to the SCSI device.
87   ///
88   VOID      *Cdb;
89   ///
90   /// On Input, the size, in bytes, of InDataBuffer. On output, the
91   /// number of bytes transferred between the SCSI controller and the SCSI device.
92   ///
93   UINT32    TransferLength;
94   ///
95   /// The length, in bytes, of the buffer Cdb. The standard values are
96   /// 6, 10, 12, and 16, but other values are possible if a variable length CDB is used.
97   ///
98   UINT8     CdbLength;
99   ///
100   /// The direction of the data transfer. 0 for reads, 1 for writes. A
101   /// value of 2 is Reserved for Bi-Directional SCSI commands.
102   ///
103   UINT8     DataDirection;
104   ///
105   /// The status of the SCSI Host Controller that produces the SCSI
106   /// bus where the SCSI device attached when the SCSI Request
107   /// Packet was executed on the SCSI Controller.
108   ///
109   UINT8     HostAdapterStatus;
110   ///
111   /// The status returned by the SCSI device when the SCSI Request
112   /// Packet was executed.
113   ///
114   UINT8     TargetStatus;
115   ///
116   /// On input, the length in bytes of the SenseData buffer. On
117   /// output, the number of bytes written to the SenseData buffer.
118   ///
119   UINT8     SenseDataLength;
120 } EFI_SCSI_PASS_THRU_SCSI_REQUEST_PACKET;
121 
122 typedef struct {
123   ///
124   /// A Null-terminated Unicode string that represents the printable name of the SCSI controller.
125   ///
126   CHAR16    *ControllerName;
127   ///
128   /// A Null-terminated Unicode string that represents the printable name of the SCSI channel.
129   ///
130   CHAR16    *ChannelName;
131   ///
132   /// The Target ID of the host adapter on the SCSI channel.
133   ///
134   UINT32    AdapterId;
135   ///
136   /// Additional information on the attributes of the SCSI channel.
137   ///
138   UINT32    Attributes;
139   ///
140   /// Supplies the alignment requirement for any buffer used in a data transfer.
141   ///
142   UINT32    IoAlign;
143 } EFI_SCSI_PASS_THRU_MODE;
144 
145 /**
146   Sends a SCSI Request Packet to a SCSI device that is attached to
147   the SCSI channel. This function supports both blocking I/O and
148   non-blocking I/O.  The blocking I/O functionality is required,
149   and the non-blocking I/O functionality is optional.
150 
151   @param  This   Protocol instance pointer.
152   @param  Target The Target ID of the SCSI device to
153                  send the SCSI Request Packet.
154   @param  Lun    The LUN of the SCSI device to send the
155                  SCSI Request Packet.
156   @param  Packet A pointer to the SCSI Request Packet to send
157                  to the SCSI device specified by Target and Lun.
158   @param  Event  If non-blocking I/O is not supported then Event
159                  is ignored, and blocking I/O is performed.
160                  If Event is NULL, then blocking I/O is performed.
161                  If Event is not NULL and non blocking I/O is
162                  supported, then non-blocking I/O is performed,
163                  and Event will be signaled when the SCSI Request
164                  Packet completes
165 
166   @retval EFI_SUCCESS               The SCSI Request Packet was sent by the host, and
167                                     TransferLength bytes were transferred to/from
168                                     DataBuffer. See HostAdapterStatus, TargetStatus,
169                                     SenseDataLength, and SenseData in that order
170                                     for additional status information.
171   @retval EFI_BAD_BUFFER_SIZE       The SCSI Request Packet was executed, but the
172                                     entire DataBuffer could not be transferred.
173                                     The actual number of bytes transferred is returned
174                                     in TransferLength. See HostAdapterStatus,
175                                     TargetStatus, SenseDataLength, and SenseData in
176                                     that order for additional status information.
177   @retval EFI_NOT_READY             The SCSI Request Packet could not be sent because
178                                     there are too many SCSI Request Packets already
179                                     queued.  The caller may retry again later.
180   @retval EFI_DEVICE_ERROR          A device error occurred while attempting to send
181                                     the SCSI Request Packet. See HostAdapterStatus,
182                                     TargetStatus, SenseDataLength, and SenseData in
183                                     that order for additional status information.
184   @retval EFI_INVALID_PARAMETER     Target, Lun, or the contents of ScsiRequestPacket
185                                     are invalid. The SCSI Request Packet was not sent,
186                                     so no additional status information is available.
187   @retval EFI_UNSUPPORTED           The command described by the SCSI Request Packet
188                                     is not supported by the host adapter. The SCSI
189                                     Request Packet was not sent, so no additional
190                                     status information is available.
191   @retval EFI_TIMEOUT               A timeout occurred while waiting for the SCSI
192                                     Request Packet to execute. See HostAdapterStatus,
193                                     TargetStatus, SenseDataLength, and SenseData in
194                                     that order for additional status information.
195 
196 **/
197 typedef
198 EFI_STATUS
199 (EFIAPI *EFI_SCSI_PASS_THRU_PASSTHRU)(
200   IN EFI_SCSI_PASS_THRU_PROTOCOL                          *This,
201   IN UINT32                                               Target,
202   IN UINT64                                               Lun,
203   IN OUT EFI_SCSI_PASS_THRU_SCSI_REQUEST_PACKET           *Packet,
204   IN EFI_EVENT                                            Event   OPTIONAL
205   );
206 
207 /**
208   Used to retrieve the list of legal Target IDs for SCSI devices
209   on a SCSI channel.
210 
211   @param  This   Protocol instance pointer.
212   @param  Target On input, a pointer to the Target ID of a
213                  SCSI device present on the SCSI channel.
214                  On output, a pointer to the Target ID of
215                  the next SCSI device present on a SCSI channel.
216                  An input value of 0xFFFFFFFF retrieves the
217                  Target ID of the first SCSI device present on
218                  a SCSI channel.
219   @param  Lun    On input, a pointer to the LUN of a SCSI device
220                  present on the SCSI channel. On output, a pointer
221                  to the LUN of the next SCSI device present on a
222                  SCSI channel.
223 
224   @retval EFI_SUCCESS           The Target ID of the next SCSI device on the SCSI
225                                 channel was returned in Target and Lun.
226   @retval EFI_NOT_FOUND         There are no more SCSI devices on this SCSI channel.
227   @retval EFI_INVALID_PARAMETER Target is not 0xFFFFFFFF, and Target and Lun were
228                                  not returned on a previous call to GetNextDevice().
229 
230 **/
231 typedef
232 EFI_STATUS
233 (EFIAPI *EFI_SCSI_PASS_THRU_GET_NEXT_DEVICE)(
234   IN EFI_SCSI_PASS_THRU_PROTOCOL            *This,
235   IN OUT UINT32                             *Target,
236   IN OUT UINT64                             *Lun
237   );
238 
239 /**
240   Used to allocate and build a device path node for a SCSI device
241   on a SCSI channel.
242 
243   @param  This       Protocol instance pointer.
244   @param  Target     The Target ID of the SCSI device for which
245                      a device path node is to be allocated and built.
246   @param  Lun        The LUN of the SCSI device for which a device
247                      path node is to be allocated and built.
248   @param  DevicePath A pointer to a single device path node that
249                      describes the SCSI device specified by
250                      Target and Lun. This function is responsible
251                      for allocating the buffer DevicePath with the boot
252                      service AllocatePool().  It is the caller's
253                      responsibility to free DevicePath when the caller
254                      is finished with DevicePath.
255 
256   @retval EFI_SUCCESS           The device path node that describes the SCSI device
257                                 specified by Target and Lun was allocated and
258                                 returned in DevicePath.
259   @retval EFI_NOT_FOUND         The SCSI devices specified by Target and Lun does
260                                 not exist on the SCSI channel.
261   @retval EFI_INVALID_PARAMETER DevicePath is NULL.
262   @retval EFI_OUT_OF_RESOURCES  There are not enough resources to allocate
263                                 DevicePath.
264 
265 **/
266 typedef
267 EFI_STATUS
268 (EFIAPI *EFI_SCSI_PASS_THRU_BUILD_DEVICE_PATH)(
269   IN EFI_SCSI_PASS_THRU_PROTOCOL            *This,
270   IN     UINT32                             Target,
271   IN     UINT64                             Lun,
272   IN OUT EFI_DEVICE_PATH_PROTOCOL           **DevicePath
273   );
274 
275 /**
276   Used to translate a device path node to a Target ID and LUN.
277 
278   @param  This       Protocol instance pointer.
279   @param  DevicePath A pointer to the device path node that
280                      describes a SCSI device on the SCSI channel.
281   @param  Target     A pointer to the Target ID of a SCSI device
282                      on the SCSI channel.
283   @param  Lun        A pointer to the LUN of a SCSI device on
284                      the SCSI channel.
285 
286   @retval EFI_SUCCESS           DevicePath was successfully translated to a
287                                 Target ID and LUN, and they were returned
288                                 in Target and Lun.
289   @retval EFI_INVALID_PARAMETER DevicePath is NULL.
290   @retval EFI_INVALID_PARAMETER Target is NULL.
291   @retval EFI_INVALID_PARAMETER Lun is NULL.
292   @retval EFI_UNSUPPORTED       This driver does not support the device path
293                                 node type in DevicePath.
294   @retval EFI_NOT_FOUND         A valid translation from DevicePath to a
295                                 Target ID and LUN does not exist.
296 
297 **/
298 typedef
299 EFI_STATUS
300 (EFIAPI *EFI_SCSI_PASS_THRU_GET_TARGET_LUN)(
301   IN EFI_SCSI_PASS_THRU_PROTOCOL            *This,
302   IN  EFI_DEVICE_PATH_PROTOCOL              *DevicePath,
303   OUT UINT32                                *Target,
304   OUT UINT64                                *Lun
305   );
306 
307 /**
308   Resets a SCSI channel.This operation resets all the
309   SCSI devices connected to the SCSI channel.
310 
311   @param  This Protocol instance pointer.
312 
313   @retval EFI_SUCCESS      The SCSI channel was reset.
314   @retval EFI_UNSUPPORTED  The SCSI channel does not support
315                            a channel reset operation.
316   @retval EFI_DEVICE_ERROR A device error occurred while
317                            attempting to reset the SCSI channel.
318   @retval EFI_TIMEOUT      A timeout occurred while attempting
319                            to reset the SCSI channel.
320 
321 **/
322 typedef
323 EFI_STATUS
324 (EFIAPI *EFI_SCSI_PASS_THRU_RESET_CHANNEL)(
325   IN EFI_SCSI_PASS_THRU_PROTOCOL             *This
326   );
327 
328 /**
329   Resets a SCSI device that is connected to a SCSI channel.
330 
331   @param  This   Protocol instance pointer.
332   @param  Target The Target ID of the SCSI device to reset.
333   @param  Lun    The LUN of the SCSI device to reset.
334 
335   @retval EFI_SUCCESS           The SCSI device specified by Target and
336                                 Lun was reset.
337   @retval EFI_UNSUPPORTED       The SCSI channel does not support a target
338                                 reset operation.
339   @retval EFI_INVALID_PARAMETER Target or Lun are invalid.
340   @retval EFI_DEVICE_ERROR      A device error occurred while attempting
341                                 to reset the SCSI device specified by Target
342                                 and Lun.
343   @retval EFI_TIMEOUT           A timeout occurred while attempting to reset
344                                 the SCSI device specified by Target and Lun.
345 
346 **/
347 typedef
348 EFI_STATUS
349 (EFIAPI *EFI_SCSI_PASS_THRU_RESET_TARGET)(
350   IN EFI_SCSI_PASS_THRU_PROTOCOL             *This,
351   IN UINT32                                  Target,
352   IN UINT64                                  Lun
353   );
354 
355 ///
356 /// The EFI_SCSI_PASS_THRU_PROTOCOL provides information about a SCSI channel and
357 /// the ability to send SCSI Request Packets to any SCSI device attached to that SCSI channel. The
358 /// information includes the Target ID of the host controller on the SCSI channel, the attributes of
359 /// the SCSI channel, the printable name for the SCSI controller, and the printable name of the
360 /// SCSI channel.
361 ///
362 struct _EFI_SCSI_PASS_THRU_PROTOCOL {
363   ///
364   /// A pointer to the EFI_SCSI_PASS_THRU_MODE data for this SCSI channel.
365   ///
366   EFI_SCSI_PASS_THRU_MODE                 *Mode;
367   EFI_SCSI_PASS_THRU_PASSTHRU             PassThru;
368   EFI_SCSI_PASS_THRU_GET_NEXT_DEVICE      GetNextDevice;
369   EFI_SCSI_PASS_THRU_BUILD_DEVICE_PATH    BuildDevicePath;
370   EFI_SCSI_PASS_THRU_GET_TARGET_LUN       GetTargetLun;
371   EFI_SCSI_PASS_THRU_RESET_CHANNEL        ResetChannel;
372   EFI_SCSI_PASS_THRU_RESET_TARGET         ResetTarget;
373 };
374 
375 extern EFI_GUID  gEfiScsiPassThruProtocolGuid;
376 
377 #endif
378