MdeModulePkg/Bus/Pci/NvmExpressPei/NvmExpressPeiStorageSecurity.h

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