MdePkg/Include/Library/UefiScsiLib.h

   1 /** @file
   2
   3   Provides the functions to submit Scsi commands defined in SCSI-2 specification for scsi device.
   4
   5 Copyright (c) 2006 - 2008, Intel Corporation
   6 All rights reserved. This program and the accompanying materials
   7 are licensed and made available under the terms and conditions of the BSD License
   8 which accompanies this distribution.  The full text of the license may be found at
   9 http://opensource.org/licenses/bsd-license.php
  10
  11 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  12 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  13
  14 **/
  15
  16 #ifndef _SCSI_LIB_H_
  17 #define _SCSI_LIB_H_
  18
  19 #include <Protocol/ScsiIo.h>
  20
  21 //
  22 // the time unit is 100ns, since the SCSI I/O defines timeout in 100ns unit.
  23 //
  24 #define EFI_SCSI_STALL_1_MICROSECOND  10
  25 #define EFI_SCSI_STALL_1_MILLISECOND  10000
  26 #define EFI_SCSI_STALL_1_SECOND       10000000
  27
  28 ///
  29 /// this macro cannot be directly used by the gBS->Stall(),
  30 /// since the value output by this macro is in 100ns unit,
  31 /// not 1us unit (1us = 1000ns)
  32 ///
  33 #define EFI_SCSI_STALL_SECONDS(a)  ((a) * EFI_SCSI_STALL_1_SECOND)
  34
  35
  36 /**
  37   Function test the ready status of the SCSI unit.
  38
  39   Submit SCSI test unit ready command with SCSI request packet specified by this scsi command, TimeOut
  40   and SenseData, then get the status of the target Scsi unit.
  41
  42   If SenseDataLength is NULL, then ASSERT().
  43
  44   If HostAdapterStatus is NULL, then ASSERT().
  45
  46   If TargetStatus is NULL, then ASSERT().
  47
  48   @param[in]     ScsiIo             A pointer to SCSI IO protocol.
  49   @param[in]     Timeout            The length of timeout period.
  50   @param[in]     SenseData          A pointer to output sense data.
  51   @param[out]    SenseDataLength    The length of output sense data.
  52   @param[out]    HostAdapterStatus  The status of Host Adapter.
  53   @param[out]    TargetStatus       The status of the target.
  54
  55   @retval EFI_SUCCESS           The status of the unit is tested successfully.
  56   @retval EFI_BAD_BUFFER_SIZE   The SCSI Request Packet was executed,
  57                                 but the entire DataBuffer could not be transferred.
  58                                 The actual number of bytes transferred is returned
  59                                 in InTransferLength.
  60   @retval EFI_NOT_READY         The SCSI Request Packet could not be sent because
  61                                 there are too many SCSI Command Packets already
  62                                 queued.
  63   @retval EFI_DEVICE_ERROR      A device error occurred while attempting to send
  64                                 the SCSI Request Packet.
  65   @retval EFI_INVALID_PARAMETER ScsiIo is NULL.
  66   @retval EFI_UNSUPPORTED       The command described by the SCSI Request Packet
  67                                 is not supported by the SCSI initiator(i.e., SCSI
  68                                 Host Controller).
  69   @retval EFI_TIMEOUT           A timeout occurred while waiting for the SCSI
  70                                 Request Packet to execute.
  71
  72 **/
  73 EFI_STATUS
  74 EFIAPI
  75 ScsiTestUnitReadyCommand (
  76   IN  EFI_SCSI_IO_PROTOCOL  *ScsiIo,
  77   IN  UINT64                Timeout,
  78   IN  VOID                  *SenseData,
  79   OUT UINT8                 *SenseDataLength,
  80   OUT UINT8                 *HostAdapterStatus,
  81   OUT UINT8                 *TargetStatus
  82   );
  83
  84
  85 /**
  86   Function to submit SCSI inquiry command.
  87
  88   Submit SCSI inquiry command with the SCSI request packet specified by this SCSI command and input
  89   parameters, then return the status of Scsi unit execution.
  90
  91   If SenseDataLength is NULL, then ASSERT().
  92
  93   If HostAdapterStatus is NULL, then ASSERT().
  94
  95   If TargetStatus is NULL, then ASSERT().
  96
  97   If InquiryDataLength is NULL, then ASSERT().
  98
  99   @param[in]     ScsiIo             SCSI IO Protocol to use
 100   @param[in]     Timeout            The length of timeout period.
 101   @param[in]     SenseData          A pointer to output sense data.
 102   @param[in, out] SenseDataLength    The length of output sense data.
 103   @param[out]    HostAdapterStatus  The status of Host Adapter.
 104   @param[out]    TargetStatus       The status of the target.
 105   @param[in, out] InquiryDataBuffer  A pointer to inquiry data buffer.
 106   @param[in, out] InquiryDataLength  The length of inquiry data buffer.
 107   @param[in]     EnableVitalProductData  Boolean to enable Vital Product Data.
 108
 109   @retval EFI_SUCCESS                Command is executed successfully.
 110   @retval EFI_BAD_BUFFER_SIZE        The SCSI Request Packet was executed,
 111                                      but the entire DataBuffer could not be transferred.
 112                                      The actual number of bytes transferred is returned
 113                                      in TransferLength.
 114   @retval EFI_NOT_READY              The SCSI Request Packet could not be sent because
 115                                      there are too many SCSI Command Packets already
 116                                      queued.
 117   @retval EFI_DEVICE_ERROR           A device error occurred while attempting to send
 118                                      the SCSI Request Packet.
 119   @retval EFI_INVALID_PARAMETER      ScsiIo is NULL.
 120   @retval EFI_UNSUPPORTED            The command described by the SCSI Request Packet
 121                                      is not supported by the SCSI initiator(i.e., SCSI
 122                                      Host Controller).
 123   @retval EFI_TIMEOUT                A timeout occurred while waiting for the SCSI
 124                                      Request Packet to execute.
 125
 126 **/
 127 EFI_STATUS
 128 EFIAPI
 129 ScsiInquiryCommand (
 130   IN  EFI_SCSI_IO_PROTOCOL  *ScsiIo,
 131   IN  UINT64                Timeout,
 132   IN  VOID                  *SenseData,
 133   IN OUT UINT8              *SenseDataLength,
 134   OUT UINT8                 *HostAdapterStatus,
 135   OUT UINT8                 *TargetStatus,
 136   IN OUT VOID               *InquiryDataBuffer,
 137   IN OUT UINT32             *InquiryDataLength,
 138   IN  BOOLEAN               EnableVitalProductData
 139   );
 140
 141
 142 /**
 143   Function to submit SCSI mode sense 10 command.
 144
 145   Submit SCSI Mode Sense (10) command with the SCSI request packet specified by this SCSI command and
 146   the input parameters, then return the status of Scsi unit execution.
 147
 148   If SenseDataLength is NULL, then ASSERT().
 149
 150   If HostAdapterStatus is NULL, then ASSERT().
 151
 152   If TargetStatus is NULL, then ASSERT().
 153
 154   If DataLength is NULL, then ASSERT().
 155
 156   @param[in]     ScsiIo             A pointer to SCSI IO protocol.
 157   @param[in]     Timeout            The length of timeout period.
 158   @param[in]     SenseData          A pointer to output sense data.
 159   @param[in, out] SenseDataLength    The length of output sense data.
 160   @param[out]    HostAdapterStatus  The status of Host Adapter.
 161   @param[out]    TargetStatus       The status of the target.
 162   @param[in]     DataBuffer         A pointer to input data buffer.
 163   @param[in, out] DataLength         The length of input data buffer.
 164   @param[in]     DBDField           The DBD Field (Optional).
 165   @param[in]     PageControl        Page Control.
 166   @param[in]     PageCode           Page code.
 167
 168   @retval EFI_SUCCESS               The status of the unit is tested successfully.
 169   @retval EFI_BAD_BUFFER_SIZE       The SCSI Request Packet was executed,
 170                                     but the entire DataBuffer could not be transferred.
 171                                     The actual number of bytes transferred is returned
 172                                     in TransferLength.
 173   @retval EFI_NOT_READY             The SCSI Request Packet could not be sent because
 174                                     there are too many SCSI Command Packets already
 175                                     queued.
 176   @retval EFI_DEVICE_ERROR          A device error occurred while attempting to send
 177                                     the SCSI Request Packet.
 178   @retval EFI_INVALID_PARAMETER     ScsiIo is NULL.
 179   @retval EFI_UNSUPPORTED           The command described by the SCSI Request Packet
 180                                     is not supported by the SCSI initiator(i.e., SCSI
 181                                     Host Controller).
 182   @retval EFI_TIMEOUT               A timeout occurred while waiting for the SCSI
 183                                     Request Packet to execute.
 184
 185 **/
 186 EFI_STATUS
 187 EFIAPI
 188 ScsiModeSense10Command (
 189   IN  EFI_SCSI_IO_PROTOCOL    *ScsiIo,
 190   IN  UINT64                  Timeout,
 191   IN  VOID                    *SenseData,
 192   IN OUT UINT8                *SenseDataLength,
 193   OUT UINT8                   *HostAdapterStatus,
 194   OUT UINT8                   *TargetStatus,
 195   IN  VOID                    *DataBuffer,
 196   IN OUT UINT32               *DataLength,
 197   IN  UINT8                   DBDField, OPTIONAL
 198   IN  UINT8                   PageControl,
 199   IN  UINT8                   PageCode
 200   );
 201
 202
 203
 204 /**
 205   Function to submit SCSI request sense command.
 206
 207   Submit SCSI request sense command with the SCSI requested packet specified by this
 208   SCSI command, TimeOut and SenseData, and then return the status of scsi unit execution.
 209
 210   If SenseDataLength is NULL, then ASSERT().
 211
 212   If HostAdapterStatus is NULL, then ASSERT().
 213
 214   If TargetStatus is NULL, then ASSERT().
 215
 216   @param[in]       ScsiIo               A pointer to SCSI IO protocol.
 217   @param[in]       Timeout              The length of timeout period.
 218   @param[in]       SenseData            A pointer to output sense data.
 219   @param[in, out]   SenseDataLength      The length of output sense data.
 220   @param[out]      HostAdapterStatus    The status of Host Adapter.
 221   @param[out]      TargetStatus         The status of the target.
 222
 223   @retval EFI_SUCCESS                   Command is executed successfully.
 224   @retval EFI_NOT_READY                 The SCSI Request Packet could not be sent because there are
 225                                         too many SCSI Command Packets already queued.
 226   @retval EFI_DEVICE_ERROR              A device error occurred while attempting to send SCSI Request Packet.
 227   @retval EFI_UNSUPPORTED               The command described by the SCSI Request Packet is not supported by
 228                                         the SCSI initiator(i.e., SCSI  Host Controller)
 229   @retval EFI_TIMEOUT                   A timeout occurred while waiting for the SCSI Request Packet to execute.
 230   @retval EFI_INVALID_PARAMETER         ScsiIo is NULL.
 231
 232 **/
 233 EFI_STATUS
 234 EFIAPI
 235 ScsiRequestSenseCommand (
 236   IN  EFI_SCSI_IO_PROTOCOL  *ScsiIo,
 237   IN  UINT64                Timeout,
 238   IN  VOID                  *SenseData,
 239   IN OUT UINT8              *SenseDataLength,
 240   OUT UINT8                 *HostAdapterStatus,
 241   OUT UINT8                 *TargetStatus
 242   );
 243
 244
 245 /**
 246   Function to submit read capacity command.
 247
 248   Submit SCSI read capacity command with the SCSI request packet specified by this SCSI
 249   command and the input parameters, and then return the status of Scsi unit execution.
 250
 251   If SenseDataLength is NULL, then ASSERT().
 252
 253   If HostAdapterStatus is NULL, then ASSERT().
 254
 255   If TargetStatus is NULL, then ASSERT().
 256
 257   If DataLength is NULL, then ASSERT().
 258
 259   @param[in]     ScsiIo               A pointer to SCSI IO protocol.
 260   @param[in]     Timeout              The length of timeout period.
 261   @param[in]     SenseData            A pointer to output sense data.
 262   @param[in, out] SenseDataLength      The length of output sense data.
 263   @param[out]    HostAdapterStatus    The status of Host Adapter.
 264   @param[out]    TargetStatus         The status of the target.
 265   @param[out]    DataBuffer           A pointer to a data buffer.
 266   @param[in, out] DataLength           The length of data buffer.
 267   @param[in]     PMI                  Partial medium indicator.
 268
 269   @retval  EFI_SUCCESS                Command is executed successfully.
 270   @retval  EFI_WARN_BUFFER_TOO_SMALL  The SCSI Request Packet was executed, but the entire DataBuffer could
 271                                       not be transferred. The actual number of bytes transferred is returned in DataLength.
 272   @retval  EFI_NOT_READY              The SCSI Request Packet could not be sent because there are too many
 273                                       SCSI Command Packets already queued.
 274   @retval  EFI_DEVICE_ERROR           A device error occurred while attempting to send SCSI Request Packet.
 275   @retval  EFI_UNSUPPORTED            The command described by the SCSI Request Packet is not supported by
 276                                       the SCSI initiator(i.e., SCSI  Host Controller)
 277   @retval  EFI_TIMEOUT                A timeout occurred while waiting for the SCSI Request Packet to execute.
 278   @retval  EFI_INVALID_PARAMETER      ScsiIo is NULL.
 279
 280 **/
 281 EFI_STATUS
 282 EFIAPI
 283 ScsiReadCapacityCommand (
 284   IN  EFI_SCSI_IO_PROTOCOL  *ScsiIo,
 285   IN  UINT64                Timeout,
 286   IN  VOID                  *SenseData,
 287   IN OUT UINT8              *SenseDataLength,
 288   OUT UINT8                 *HostAdapterStatus,
 289   OUT UINT8                 *TargetStatus,
 290   OUT VOID                  *DataBuffer,
 291   IN OUT UINT32             *DataLength,
 292   IN  BOOLEAN               PMI
 293   );
 294
 295
 296 /**
 297   Function to submit read 10 command.
 298
 299   Submit SCSI read (10) command with the SCSI request packet specified by this SCSI command
 300   and the input parameters, and then return the status of Scsi unit execution.
 301
 302   If SenseDataLength is NULL, then ASSERT().
 303
 304   If HostAdapterStatus is NULL, then ASSERT().
 305
 306   If TargetStatus is NULL, then ASSERT().
 307
 308   If DataLength is NULL, then ASSERT().
 309
 310   @param[in]     ScsiIo               A pointer to SCSI IO protocol.
 311   @param[in]     Timeout              The length of timeout period.
 312   @param[in]     SenseData            A pointer to output sense data.
 313   @param[in, out] SenseDataLength      The length of output sense data.
 314   @param[out]    HostAdapterStatus    The status of Host Adapter.
 315   @param[out]    TargetStatus         The status of the target.
 316   @param[out]    DataBuffer           Read 10 command data.
 317   @param[in, out] DataLength           The length of data buffer.
 318   @param[in]     StartLba             The start address of LBA.
 319   @param[in]     SectorSize           The sector size.
 320
 321   @retval  EFI_SUCCESS                Command is executed successfully.
 322   @retval  EFI_WARN_BUFFER_TOO_SMALL  The SCSI Request Packet was executed, but the entire DataBuffer could
 323                                       not be transferred. The actual number of bytes transferred is returned in DataLength.
 324   @retval  EFI_NOT_READY              The SCSI Request Packet could not be sent because there are too many
 325                                       SCSI Command Packets already queued.
 326   @retval  EFI_DEVICE_ERROR           A device error occurred while attempting to send SCSI Request Packet.
 327   @retval  EFI_UNSUPPORTED            The command described by the SCSI Request Packet is not supported by
 328                                       the SCSI initiator(i.e., SCSI  Host Controller)
 329   @retval  EFI_TIMEOUT                A timeout occurred while waiting for the SCSI Request Packet to execute.
 330   @retval  EFI_INVALID_PARAMETER      ScsiIo is NULL.
 331
 332 **/
 333 EFI_STATUS
 334 EFIAPI
 335 ScsiRead10Command (
 336   IN  EFI_SCSI_IO_PROTOCOL  *ScsiIo,
 337   IN  UINT64                Timeout,
 338   IN  VOID                  *SenseData,
 339   IN OUT UINT8              *SenseDataLength,
 340   OUT UINT8                 *HostAdapterStatus,
 341   OUT UINT8                 *TargetStatus,
 342   OUT VOID                  *DataBuffer,
 343   IN OUT UINT32             *DataLength,
 344   IN  UINT32                StartLba,
 345   IN  UINT32                SectorSize
 346   );
 347
 348
 349 /**
 350   Function to submit SCSI write 10 command.
 351
 352   Submit SCSI write (10) command with the SCSI request packet specified by this SCSI command and the
 353   input parameters, and then return the status of Scsi unit execution.
 354
 355   If SenseDataLength is NULL, then ASSERT().
 356
 357   If HostAdapterStatus is NULL, then ASSERT().
 358
 359   If TargetStatus is NULL, then ASSERT().
 360
 361   If DataLength is NULL, then ASSERT().
 362
 363   @param[in]     ScsiIo               SCSI IO Protocol to use
 364   @param[in]     Timeout              The length of timeout period.
 365   @param[in]     SenseData            A pointer to output sense data.
 366   @param[in, out] SenseDataLength      The length of output sense data.
 367   @param[out]    HostAdapterStatus    The status of Host Adapter.
 368   @param[out]    TargetStatus         The status of the target.
 369   @param[out]    DataBuffer           A pointer to a data buffer.
 370   @param[in, out] DataLength           The length of data buffer.
 371   @param[in]     StartLba             The start address of LBA.
 372   @param[in]     SectorSize           The sector size.
 373
 374   @retval  EFI_SUCCESS                Command is executed successfully.
 375   @retval  EFI_WARN_BUFFER_TOO_SMALL  The SCSI Request Packet was executed, but the entire DataBuffer could
 376                                       not be transferred. The actual number of bytes transferred is returned in DataLength.
 377   @retval  EFI_NOT_READY              The SCSI Request Packet could not be sent because there are too many
 378                                       SCSI Command Packets already queued.
 379   @retval  EFI_DEVICE_ERROR           A device error occurred while attempting to send SCSI Request Packet.
 380   @retval  EFI_UNSUPPORTED            The command described by the SCSI Request Packet is not supported by
 381                                       the SCSI initiator(i.e., SCSI  Host Controller)
 382   @retval  EFI_TIMEOUT                A timeout occurred while waiting for the SCSI Request Packet to execute.
 383   @retval  EFI_INVALID_PARAMETER      ScsiIo is NULL.
 384
 385 **/
 386 EFI_STATUS
 387 EFIAPI
 388 ScsiWrite10Command (
 389   IN  EFI_SCSI_IO_PROTOCOL  *ScsiIo,
 390   IN  UINT64                Timeout,
 391   IN  VOID                  *SenseData,
 392   IN OUT UINT8              *SenseDataLength,
 393   OUT UINT8                 *HostAdapterStatus,
 394   OUT UINT8                 *TargetStatus,
 395   OUT VOID                  *DataBuffer,
 396   IN OUT UINT32             *DataLength,
 397   IN  UINT32                StartLba,
 398   IN  UINT32                SectorSize
 399   );
 400
 401
 402 #endif