MdeModulePkg/Bus/Ata/AhciPei/AhciPeiStorageSecurity.h

   1 /** @file
   2   The AhciPei driver is used to manage ATA hard disk device working under AHCI
   3   mode at PEI phase.
   4
   5   Copyright (c) 2019, Intel Corporation. All rights reserved.<BR>
   6
   7   SPDX-License-Identifier: BSD-2-Clause-Patent
   8
   9 **/
  10
  11 #ifndef _AHCI_PEI_STORAGE_SECURITY_H_
  12 #define _AHCI_PEI_STORAGE_SECURITY_H_
  13
  14 /**
  15   Gets the count of storage security devices that one specific driver detects.
  16
  17   @param[in]  This               The PPI instance pointer.
  18   @param[out] NumberofDevices    The number of storage security devices discovered.
  19
  20   @retval EFI_SUCCESS              The operation performed successfully.
  21   @retval EFI_INVALID_PARAMETER    The parameters are invalid.
  22
  23 **/
  24 EFI_STATUS
  25 EFIAPI
  26 AhciStorageSecurityGetDeviceNo (
  27   IN  EDKII_PEI_STORAGE_SECURITY_CMD_PPI    *This,
  28   OUT UINTN                                 *NumberofDevices
  29   );
  30
  31 /**
  32   Gets the device path of a specific storage security device.
  33
  34   @param[in]  This                 The PPI instance pointer.
  35   @param[in]  DeviceIndex          Specifies the storage security device to which
  36                                    the function wants to talk. Because the driver
  37                                    that implements Storage Security Command PPIs
  38                                    will manage multiple storage devices, the PPIs
  39                                    that want to talk to a single device must specify
  40                                    the device index that was assigned during the
  41                                    enumeration process. This index is a number from
  42                                    one to NumberofDevices.
  43   @param[out] DevicePathLength     The length of the device path in bytes specified
  44                                    by DevicePath.
  45   @param[out] DevicePath           The device path of storage security device.
  46                                    This field re-uses EFI Device Path Protocol as
  47                                    defined by Section 10.2 EFI Device Path Protocol
  48                                    of UEFI 2.7 Specification.
  49
  50   @retval EFI_SUCCESS              The operation succeeds.
  51   @retval EFI_INVALID_PARAMETER    DevicePathLength or DevicePath is NULL.
  52   @retval EFI_NOT_FOUND            The specified storage security device not found.
  53   @retval EFI_OUT_OF_RESOURCES     The operation fails due to lack of resources.
  54
  55 **/
  56 EFI_STATUS
  57 EFIAPI
  58 AhciStorageSecurityGetDevicePath (
  59   IN  EDKII_PEI_STORAGE_SECURITY_CMD_PPI    *This,
  60   IN  UINTN                                 DeviceIndex,
  61   OUT UINTN                                 *DevicePathLength,
  62   OUT EFI_DEVICE_PATH_PROTOCOL              **DevicePath
  63   );
  64
  65 /**
  66   Send a security protocol command to a device that receives data and/or the result
  67   of one or more commands sent by SendData.
  68
  69   The ReceiveData function sends a security protocol command to the given DeviceIndex.
  70   The security protocol command sent is defined by SecurityProtocolId and contains
  71   the security protocol specific data SecurityProtocolSpecificData. The function
  72   returns the data from the security protocol command in PayloadBuffer.
  73
  74   For devices supporting the SCSI command set, the security protocol command is sent
  75   using the SECURITY PROTOCOL IN command defined in SPC-4.
  76
  77   For devices supporting the ATA command set, the security protocol command is sent
  78   using one of the TRUSTED RECEIVE commands defined in ATA8-ACS if PayloadBufferSize
  79   is non-zero.
  80
  81   If the PayloadBufferSize is zero, the security protocol command is sent using the
  82   Trusted Non-Data command defined in ATA8-ACS.
  83
  84   If PayloadBufferSize is too small to store the available data from the security
  85   protocol command, the function shall copy PayloadBufferSize bytes into the
  86   PayloadBuffer and return EFI_WARN_BUFFER_TOO_SMALL.
  87
  88   If PayloadBuffer or PayloadTransferSize is NULL and PayloadBufferSize is non-zero,
  89   the function shall return EFI_INVALID_PARAMETER.
  90
  91   If the given DeviceIndex does not support security protocol commands, the function
  92   shall return EFI_UNSUPPORTED.
  93
  94   If the security protocol fails to complete within the Timeout period, the function
  95   shall return EFI_TIMEOUT.
  96
  97   If the security protocol command completes without an error, the function shall
  98   return EFI_SUCCESS. If the security protocol command completes with an error, the
  99   function shall return EFI_DEVICE_ERROR.
 100
 101   @param[in]  This             The PPI instance pointer.
 102   @param[in]  DeviceIndex      Specifies the storage security device to which the
 103                                function wants to talk. Because the driver that
 104                                implements Storage Security Command PPIs will manage
 105                                multiple storage devices, the PPIs that want to talk
 106                                to a single device must specify the device index
 107                                that was assigned during the enumeration process.
 108                                This index is a number from one to NumberofDevices.
 109   @param[in]  Timeout          The timeout, in 100ns units, to use for the execution
 110                                of the security protocol command. A Timeout value
 111                                of 0 means that this function will wait indefinitely
 112                                for the security protocol command to execute. If
 113                                Timeout is greater than zero, then this function
 114                                will return EFI_TIMEOUT if the time required to
 115                                execute the receive data command is greater than
 116                                Timeout.
 117   @param[in]  SecurityProtocolId
 118                                The value of the "Security Protocol" parameter of
 119                                the security protocol command to be sent.
 120   @param[in]  SecurityProtocolSpecificData
 121                                The value of the "Security Protocol Specific"
 122                                parameter of the security protocol command to be
 123                                sent.
 124   @param[in]  PayloadBufferSize
 125                                Size in bytes of the payload data buffer.
 126   @param[out] PayloadBuffer    A pointer to a destination buffer to store the
 127                                security protocol command specific payload data
 128                                for the security protocol command. The caller is
 129                                responsible for having either implicit or explicit
 130                                ownership of the buffer.
 131   @param[out] PayloadTransferSize
 132                                A pointer to a buffer to store the size in bytes
 133                                of the data written to the payload data buffer.
 134
 135   @retval EFI_SUCCESS                  The security protocol command completed
 136                                        successfully.
 137   @retval EFI_WARN_BUFFER_TOO_SMALL    The PayloadBufferSize was too small to
 138                                        store the available data from the device.
 139                                        The PayloadBuffer contains the truncated
 140                                        data.
 141   @retval EFI_UNSUPPORTED              The given DeviceIndex does not support
 142                                        security protocol commands.
 143   @retval EFI_DEVICE_ERROR             The security protocol command completed
 144                                        with an error.
 145   @retval EFI_INVALID_PARAMETER        The PayloadBuffer or PayloadTransferSize
 146                                        is NULL and PayloadBufferSize is non-zero.
 147   @retval EFI_TIMEOUT                  A timeout occurred while waiting for the
 148                                        security protocol command to execute.
 149
 150 **/
 151 EFI_STATUS
 152 EFIAPI
 153 AhciStorageSecurityReceiveData (
 154   IN  EDKII_PEI_STORAGE_SECURITY_CMD_PPI    *This,
 155   IN  UINTN                                 DeviceIndex,
 156   IN  UINT64                                Timeout,
 157   IN  UINT8                                 SecurityProtocolId,
 158   IN  UINT16                                SecurityProtocolSpecificData,
 159   IN  UINTN                                 PayloadBufferSize,
 160   OUT VOID                                  *PayloadBuffer,
 161   OUT UINTN                                 *PayloadTransferSize
 162   );
 163
 164 /**
 165   Send a security protocol command to a device.
 166
 167   The SendData function sends a security protocol command containing the payload
 168   PayloadBuffer to the given DeviceIndex. The security protocol command sent is
 169   defined by SecurityProtocolId and contains the security protocol specific data
 170   SecurityProtocolSpecificData. If the underlying protocol command requires a
 171   specific padding for the command payload, the SendData function shall add padding
 172   bytes to the command payload to satisfy the padding requirements.
 173
 174   For devices supporting the SCSI command set, the security protocol command is
 175   sent using the SECURITY PROTOCOL OUT command defined in SPC-4.
 176
 177   For devices supporting the ATA command set, the security protocol command is
 178   sent using one of the TRUSTED SEND commands defined in ATA8-ACS if PayloadBufferSize
 179   is non-zero. If the PayloadBufferSize is zero, the security protocol command
 180   is sent using the Trusted Non-Data command defined in ATA8-ACS.
 181
 182   If PayloadBuffer is NULL and PayloadBufferSize is non-zero, the function shall
 183   return EFI_INVALID_PARAMETER.
 184
 185   If the given DeviceIndex does not support security protocol commands, the function
 186   shall return EFI_UNSUPPORTED.
 187
 188   If the security protocol fails to complete within the Timeout period, the function
 189   shall return EFI_TIMEOUT.
 190
 191   If the security protocol command completes without an error, the function shall
 192   return EFI_SUCCESS. If the security protocol command completes with an error,
 193   the functio shall return EFI_DEVICE_ERROR.
 194
 195   @param[in] This              The PPI instance pointer.
 196   @param[in] DeviceIndex       The ID of the device.
 197   @param[in] Timeout           The timeout, in 100ns units, to use for the execution
 198                                of the security protocol command. A Timeout value
 199                                of 0 means that this function will wait indefinitely
 200                                for the security protocol command to execute. If
 201                                Timeout is greater than zero, then this function
 202                                will return EFI_TIMEOUT if the time required to
 203                                execute the receive data command is greater than
 204                                Timeout.
 205   @param[in] SecurityProtocolId
 206                                The value of the "Security Protocol" parameter of
 207                                the security protocol command to be sent.
 208   @param[in] SecurityProtocolSpecificData
 209                                The value of the "Security Protocol Specific"
 210                                parameter of the security protocol command to be
 211                                sent.
 212   @param[in] PayloadBufferSize Size in bytes of the payload data buffer.
 213   @param[in] PayloadBuffer     A pointer to a destination buffer to store the
 214                                security protocol command specific payload data
 215                                for the security protocol command.
 216
 217   @retval EFI_SUCCESS              The security protocol command completed successfully.
 218   @retval EFI_UNSUPPORTED          The given DeviceIndex does not support security
 219                                    protocol commands.
 220   @retval EFI_DEVICE_ERROR         The security protocol command completed with
 221                                    an error.
 222   @retval EFI_INVALID_PARAMETER    The PayloadBuffer is NULL and PayloadBufferSize
 223                                    is non-zero.
 224   @retval EFI_TIMEOUT              A timeout occurred while waiting for the security
 225                                    protocol command to execute.
 226
 227 **/
 228 EFI_STATUS
 229 EFIAPI
 230 AhciStorageSecuritySendData (
 231   IN EDKII_PEI_STORAGE_SECURITY_CMD_PPI  *This,
 232   IN UINTN                               DeviceIndex,
 233   IN UINT64                              Timeout,
 234   IN UINT8                               SecurityProtocolId,
 235   IN UINT16                              SecurityProtocolSpecificData,
 236   IN UINTN                               PayloadBufferSize,
 237   IN VOID                                *PayloadBuffer
 238   );
 239
 240 #endif