ScsiIo.h revision 99e8ed219f48b82694424e46c9512d4929d9d54e 
1/** @file
2  EFI_SCSI_IO_PROTOCOL as defined in UEFI 2.0.
3  This protocol is used by code, typically drivers, running in the EFI boot
4  services environment to access SCSI devices. In particular, functions for
5  managing devices on SCSI buses are defined here.
6
7  Copyright (c) 2006 - 2008, Intel Corporation
8  All rights reserved. This program and the accompanying materials
9  are licensed and made available under the terms and conditions of the BSD License
10  which accompanies this distribution.  The full text of the license may be found at
11  http://opensource.org/licenses/bsd-license.php
12
13  THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
14  WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
15
16**/
17
18#ifndef __EFI_SCSI_IO_PROTOCOL_H__
19#define __EFI_SCSI_IO_PROTOCOL_H__
20
21#define EFI_SCSI_IO_PROTOCOL_GUID \
22  { \
23    0x932f4736, 0x2362, 0x4002, {0x80, 0x3e, 0x3c, 0xd5, 0x4b, 0x13, 0x8f, 0x85 } \
24  }
25
26///
27/// Forward reference for pure ANSI compatability
28///
29typedef struct _EFI_SCSI_IO_PROTOCOL EFI_SCSI_IO_PROTOCOL;
30
31//
32// SCSI Data Direction definition
33//
34#define EFI_SCSI_IO_DATA_DIRECTION_READ                        0
35#define EFI_SCSI_IO_DATA_DIRECTION_WRITE                       1
36#define EFI_SCSI_IO_DATA_DIRECTION_BIDIRECTIONAL               2
37
38//
39// SCSI Host Adapter Status definition
40//
41#define EFI_SCSI_IO_STATUS_HOST_ADAPTER_OK                     0x00
42#define EFI_SCSI_IO_STATUS_HOST_ADAPTER_TIMEOUT_COMMAND        0x09    // timeout when processing the command
43#define EFI_SCSI_IO_STATUS_HOST_ADAPTER_TIMEOUT                0x0b    // timeout when waiting for the command processing
44#define EFI_SCSI_IO_STATUS_HOST_ADAPTER_MESSAGE_REJECT         0x0d    // a message reject was received when processing command
45#define EFI_SCSI_IO_STATUS_HOST_ADAPTER_BUS_RESET              0x0e    // a bus reset was detected
46#define EFI_SCSI_IO_STATUS_HOST_ADAPTER_PARITY_ERROR           0x0f
47#define EFI_SCSI_IO_STATUS_HOST_ADAPTER_REQUEST_SENSE_FAILED   0x10    // the adapter failed in issuing request sense command
48#define EFI_SCSI_IO_STATUS_HOST_ADAPTER_SELECTION_TIMEOUT      0x11    // selection timeout
49#define EFI_SCSI_IO_STATUS_HOST_ADAPTER_DATA_OVERRUN_UNDERRUN  0x12    // data overrun or data underrun
50#define EFI_SCSI_IO_STATUS_HOST_ADAPTER_BUS_FREE               0x13    // Unexepected bus free
51#define EFI_SCSI_IO_STATUS_HOST_ADAPTER_PHASE_ERROR            0x14    // Target bus phase sequence failure
52#define EFI_SCSI_IO_STATUS_HOST_ADAPTER_OTHER                  0x7f
53
54
55//
56// SCSI Target Status definition
57//
58#define EFI_SCSI_IO_STATUS_TARGET_GOOD                         0x00
59#define EFI_SCSI_IO_STATUS_TARGET_CHECK_CONDITION              0x02    // check condition
60#define EFI_SCSI_IO_STATUS_TARGET_CONDITION_MET                0x04    // condition met
61#define EFI_SCSI_IO_STATUS_TARGET_BUSY                         0x08    // busy
62#define EFI_SCSI_IO_STATUS_TARGET_INTERMEDIATE                 0x10    // intermediate
63#define EFI_SCSI_IO_STATUS_TARGET_INTERMEDIATE_CONDITION_MET   0x14    // intermediate-condition met
64#define EFI_SCSI_IO_STATUS_TARGET_RESERVATION_CONFLICT         0x18    // reservation conflict
65#define EFI_SCSI_IO_STATUS_TARGET_COMMOND_TERMINATED           0x22    // command terminated
66#define EFI_SCSI_IO_STATUS_TARGET_QUEUE_FULL                   0x28    // queue full
67
68typedef struct {
69  UINT64                              Timeout;
70  VOID                                *InDataBuffer;
71  VOID                                *OutDataBuffer;
72  VOID                                *SenseData;
73  VOID                                *Cdb;
74  UINT32                              InTransferLength;
75  UINT32                              OutTransferLength;
76  UINT8                               CdbLength;
77  UINT8                               DataDirection;
78  UINT8                               HostAdapterStatus;
79  UINT8                               TargetStatus;
80  UINT8                               SenseDataLength;
81} EFI_SCSI_IO_SCSI_REQUEST_PACKET;
82
83/**
84  Retrieves the device type information of the SCSI Controller.
85
86  @param  This       Protocol instance pointer.
87  @param  DeviceType A pointer to the device type information
88                     retrieved from the SCSI Controller.
89
90  @retval EFI_SUCCESS           Retrieves the device type information successfully.
91  @retval EFI_INVALID_PARAMETER The DeviceType is NULL.
92
93**/
94typedef
95EFI_STATUS
96(EFIAPI *EFI_SCSI_IO_PROTOCOL_GET_DEVICE_TYPE)(
97  IN  EFI_SCSI_IO_PROTOCOL            *This,
98  OUT UINT8                           *DeviceType
99  )
100;
101
102/**
103  Retrieves the device location in the SCSI channel.
104
105  @param  This   Protocol instance pointer.
106  @param  Target A pointer to the Target ID of a SCSI device
107                 on the SCSI channel.
108  @param  Lun    A pointer to the LUN of the SCSI device on
109                 the SCSI channel.
110
111  @retval EFI_SUCCESS           Retrieves the device location successfully.
112  @retval EFI_INVALID_PARAMETER The Target or Lun is NULL.
113
114**/
115typedef
116EFI_STATUS
117(EFIAPI *EFI_SCSI_IO_PROTOCOL_GET_DEVICE_LOCATION)(
118  IN EFI_SCSI_IO_PROTOCOL           *This,
119  IN OUT UINT8                      **Target,
120  OUT UINT64                        *Lun
121  )
122;
123
124/**
125  Resets the SCSI Bus that the SCSI Controller is attached to.
126
127  @param  This Protocol instance pointer.
128
129  @retval EFI_SUCCESS      The SCSI bus is reset successfully.
130  @retval EFI_DEVICE_ERROR Errors encountered when resetting the SCSI bus.
131  @retval EFI_UNSUPPORTED  The bus reset operation is not supported by the
132                           SCSI Host Controller.
133  @retval EFI_TIMEOUT      A timeout occurred while attempting to reset
134                            the SCSI bus.
135
136**/
137typedef
138EFI_STATUS
139(EFIAPI *EFI_SCSI_IO_PROTOCOL_RESET_BUS)(
140  IN EFI_SCSI_IO_PROTOCOL     *This
141  )
142;
143
144/**
145  Resets the SCSI Controller that the device handle specifies.
146
147  @param  This Protocol instance pointer.
148
149  @retval EFI_SUCCESS      Reset the SCSI controller successfully.
150  @retval EFI_DEVICE_ERROR Errors are encountered when resetting the
151                           SCSI Controller.
152  @retval EFI_UNSUPPORTED  The SCSI bus does not support a device
153                           reset operation.
154  @retval EFI_TIMEOUT      A timeout occurred while attempting to
155                           reset the SCSI Controller.
156
157**/
158typedef
159EFI_STATUS
160(EFIAPI *EFI_SCSI_IO_PROTOCOL_RESET_DEVICE)(
161  IN EFI_SCSI_IO_PROTOCOL     *This
162  )
163;
164
165
166/**
167  Sends a SCSI Request Packet to the SCSI Controller for execution.
168
169  @param  This    Protocol instance pointer.
170  @param  Packet  The SCSI request packet to send to the SCSI
171                  Controller specified by the device handle.
172  @param  Event   If the SCSI bus where the SCSI device is attached
173                  does not support non-blocking I/O, then Event is
174                  ignored, and blocking I/O is performed.
175                  If Event is NULL, then blocking I/O is performed.
176                  If Event is not NULL and non-blocking I/O is
177                  supported, then non-blocking I/O is performed,
178                  and Event will be signaled when the SCSI Request
179                  Packet completes.
180
181  @retval EFI_SUCCESS               The SCSI Request Packet was sent by the host
182                                    successfully, and TransferLength bytes were
183                                    transferred to/from DataBuffer.See
184                                    HostAdapterStatus, TargetStatus,
185                                    SenseDataLength, and SenseData in that order
186                                    for additional status information.
187  @retval EFI_BAD_BUFFER_SIZE       The SCSI Request Packet was executed,
188                                    but the entire DataBuffer could not be transferred.
189                                    The actual number of bytes transferred is returned
190                                    in TransferLength. See HostAdapterStatus,
191                                    TargetStatus, SenseDataLength, and SenseData in
192                                    that order for additional status information.
193  @retval EFI_NOT_READY             The SCSI Request Packet could not be sent because
194                                    there are too many SCSI Command Packets already
195                                    queued.The caller may retry again later.
196  @retval EFI_DEVICE_ERROR          A device error occurred while attempting to send
197                                    the SCSI Request Packet. See HostAdapterStatus,
198                                    TargetStatus, SenseDataLength, and SenseData in
199                                    that order for additional status information.
200  @retval EFI_INVALID_PARAMETER     The contents of CommandPacket are invalid.
201                                    The SCSI Request Packet was not sent, so no
202                                    additional status information is available.
203  @retval EFI_UNSUPPORTED           The command described by the SCSI Request Packet
204                                    is not supported by the SCSI initiator(i.e., SCSI
205                                    Host Controller). The SCSI Request Packet was not
206                                    sent, so no additional status information is
207                                    available.
208  @retval EFI_TIMEOUT               A timeout occurred while waiting for the SCSI
209                                    Request Packet to execute. See HostAdapterStatus,
210                                    TargetStatus, SenseDataLength, and SenseData in
211                                    that order for additional status information.
212
213**/
214typedef
215EFI_STATUS
216(EFIAPI *EFI_SCSI_IO_PROTOCOL_EXEC_SCSI_COMMAND)(
217  IN EFI_SCSI_IO_PROTOCOL                   *This,
218  IN OUT  EFI_SCSI_IO_SCSI_REQUEST_PACKET   *Packet,
219  IN EFI_EVENT                              Event  OPTIONAL
220  )
221;
222
223/**
224  @par Protocol Description:
225  Provides services to manage and communicate with SCSI devices.
226
227  @param GetDeviceType
228  Retrieves the information of the device type which the SCSI device belongs to.
229
230  @param GetDeviceLocation
231  Retrieves the device location information in the SCSI bus.
232
233  @param ResetBus
234  Resets the entire SCSI bus the SCSI device attaches to.
235
236  @param ResetDevice
237  Resets the SCSI Device that is specified by the device handle the SCSI I/O
238  protocol attaches.
239
240  @param ExecuteScsiCommand
241  Sends a SCSI command to the SCSI device and waits for the execution completion
242  until an exit condition is met, or a timeout occurs.
243
244  @param IoAlign
245  Supplies the alignment requirement for any buffer used in a data transfer.
246  IoAlign values of 0 and 1 mean that the buffer can be placed anywhere in memory.
247  Otherwise, IoAlign must be a power of 2, and the requirement is that the
248  start address of a buffer must be evenly divisible by IoAlign with no remainder.
249
250**/
251struct _EFI_SCSI_IO_PROTOCOL {
252  EFI_SCSI_IO_PROTOCOL_GET_DEVICE_TYPE      GetDeviceType;
253  EFI_SCSI_IO_PROTOCOL_GET_DEVICE_LOCATION  GetDeviceLocation;
254  EFI_SCSI_IO_PROTOCOL_RESET_BUS            ResetBus;
255  EFI_SCSI_IO_PROTOCOL_RESET_DEVICE         ResetDevice;
256  EFI_SCSI_IO_PROTOCOL_EXEC_SCSI_COMMAND    ExecuteScsiCommand;
257  UINT32                                    IoAlign;
258};
259
260extern EFI_GUID gEfiScsiIoProtocolGuid;
261
262#endif
263