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 241