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