3 Copyright (c) 2019, Intel Corporation. All rights reserved.<BR>
4 SPDX-License-Identifier: BSD-2-Clause-Patent
8 #ifndef _EDKII_STORAGE_SECURITY_COMMAND_PPI_H_
9 #define _EDKII_STORAGE_SECURITY_COMMAND_PPI_H_
11 #include <Protocol/DevicePath.h>
14 /// Global ID for the EDKII_PEI_STORAGE_SECURITY_CMD_PPI.
16 #define EDKII_PEI_STORAGE_SECURITY_CMD_PPI_GUID \
18 0x35de0b4e, 0x30fb, 0x46c3, { 0xbd, 0x84, 0x1f, 0xdb, 0xa1, 0x58, 0xbb, 0x56 } \
22 // Forward declaration for the EDKII_PEI_STORAGE_SECURITY_CMD_PPI.
24 typedef struct _EDKII_PEI_STORAGE_SECURITY_CMD_PPI EDKII_PEI_STORAGE_SECURITY_CMD_PPI
;
27 // Revision The revision to which the Storage Security Command interface adheres.
28 // All future revisions must be backwards compatible.
29 // If a future version is not back wards compatible it is not the same GUID.
31 #define EDKII_STORAGE_SECURITY_PPI_REVISION 0x00010000
34 Gets the count of storage security devices that one specific driver detects.
36 @param[in] This The PPI instance pointer.
37 @param[out] NumberofDevices The number of storage security devices discovered.
39 @retval EFI_SUCCESS The operation performed successfully.
40 @retval EFI_INVALID_PARAMETER The parameters are invalid.
45 (EFIAPI
*EDKII_PEI_STORAGE_SECURITY_GET_NUMBER_DEVICES
)(
46 IN EDKII_PEI_STORAGE_SECURITY_CMD_PPI
*This
,
47 OUT UINTN
*NumberofDevices
51 Gets the device path of a specific storage security device.
53 @param[in] This The PPI instance pointer.
54 @param[in] DeviceIndex Specifies the storage security device to which
55 the function wants to talk. Because the driver
56 that implements Storage Security Command PPIs
57 will manage multiple storage devices, the PPIs
58 that want to talk to a single device must specify
59 the device index that was assigned during the
60 enumeration process. This index is a number from
61 one to NumberofDevices.
62 @param[out] DevicePathLength The length of the device path in bytes specified
64 @param[out] DevicePath The device path of storage security device.
65 This field re-uses EFI Device Path Protocol as
66 defined by Section 10.2 EFI Device Path Protocol
67 of UEFI 2.7 Specification.
69 @retval EFI_SUCCESS The operation succeeds.
70 @retval EFI_INVALID_PARAMETER DevicePathLength or DevicePath is NULL.
71 @retval EFI_NOT_FOUND The specified storage security device not found.
72 @retval EFI_OUT_OF_RESOURCES The operation fails due to lack of resources.
77 (EFIAPI
*EDKII_PEI_STORAGE_SECURITY_GET_DEVICE_PATH
)(
78 IN EDKII_PEI_STORAGE_SECURITY_CMD_PPI
*This
,
80 OUT UINTN
*DevicePathLength
,
81 OUT EFI_DEVICE_PATH_PROTOCOL
**DevicePath
85 Send a security protocol command to a device that receives data and/or the result
86 of one or more commands sent by SendData.
88 The ReceiveData function sends a security protocol command to the given DeviceIndex.
89 The security protocol command sent is defined by SecurityProtocolId and contains
90 the security protocol specific data SecurityProtocolSpecificData. The function
91 returns the data from the security protocol command in PayloadBuffer.
93 For devices supporting the SCSI command set, the security protocol command is sent
94 using the SECURITY PROTOCOL IN command defined in SPC-4.
96 For devices supporting the ATA command set, the security protocol command is sent
97 using one of the TRUSTED RECEIVE commands defined in ATA8-ACS if PayloadBufferSize
100 If the PayloadBufferSize is zero, the security protocol command is sent using the
101 Trusted Non-Data command defined in ATA8-ACS.
103 If PayloadBufferSize is too small to store the available data from the security
104 protocol command, the function shall copy PayloadBufferSize bytes into the
105 PayloadBuffer and return EFI_WARN_BUFFER_TOO_SMALL.
107 If PayloadBuffer or PayloadTransferSize is NULL and PayloadBufferSize is non-zero,
108 the function shall return EFI_INVALID_PARAMETER.
110 If the given DeviceIndex does not support security protocol commands, the function
111 shall return EFI_UNSUPPORTED.
113 If the security protocol fails to complete within the Timeout period, the function
114 shall return EFI_TIMEOUT.
116 If the security protocol command completes without an error, the function shall
117 return EFI_SUCCESS. If the security protocol command completes with an error, the
118 function shall return EFI_DEVICE_ERROR.
120 @param[in] This The PPI instance pointer.
121 @param[in] DeviceIndex Specifies the storage security device to which the
122 function wants to talk. Because the driver that
123 implements Storage Security Command PPIs will manage
124 multiple storage devices, the PPIs that want to talk
125 to a single device must specify the device index
126 that was assigned during the enumeration process.
127 This index is a number from one to NumberofDevices.
128 @param[in] Timeout The timeout, in 100ns units, to use for the execution
129 of the security protocol command. A Timeout value
130 of 0 means that this function will wait indefinitely
131 for the security protocol command to execute. If
132 Timeout is greater than zero, then this function
133 will return EFI_TIMEOUT if the time required to
134 execute the receive data command is greater than
136 @param[in] SecurityProtocolId
137 The value of the "Security Protocol" parameter of
138 the security protocol command to be sent.
139 @param[in] SecurityProtocolSpecificData
140 The value of the "Security Protocol Specific"
141 parameter of the security protocol command to be
143 @param[in] PayloadBufferSize
144 Size in bytes of the payload data buffer.
145 @param[out] PayloadBuffer A pointer to a destination buffer to store the
146 security protocol command specific payload data
147 for the security protocol command. The caller is
148 responsible for having either implicit or explicit
149 ownership of the buffer.
150 @param[out] PayloadTransferSize
151 A pointer to a buffer to store the size in bytes
152 of the data written to the payload data buffer.
154 @retval EFI_SUCCESS The security protocol command completed
156 @retval EFI_WARN_BUFFER_TOO_SMALL The PayloadBufferSize was too small to
157 store the available data from the device.
158 The PayloadBuffer contains the truncated
160 @retval EFI_UNSUPPORTED The given DeviceIndex does not support
161 security protocol commands.
162 @retval EFI_DEVICE_ERROR The security protocol command completed
164 @retval EFI_INVALID_PARAMETER The PayloadBuffer or PayloadTransferSize
165 is NULL and PayloadBufferSize is non-zero.
166 @retval EFI_TIMEOUT A timeout occurred while waiting for the
167 security protocol command to execute.
172 (EFIAPI
*EDKII_PEI_STORAGE_SECURITY_RECEIVE_DATA
)(
173 IN EDKII_PEI_STORAGE_SECURITY_CMD_PPI
*This
,
174 IN UINTN DeviceIndex
,
176 IN UINT8 SecurityProtocolId
,
177 IN UINT16 SecurityProtocolSpecificData
,
178 IN UINTN PayloadBufferSize
,
179 OUT VOID
*PayloadBuffer
,
180 OUT UINTN
*PayloadTransferSize
184 Send a security protocol command to a device.
186 The SendData function sends a security protocol command containing the payload
187 PayloadBuffer to the given DeviceIndex. The security protocol command sent is
188 defined by SecurityProtocolId and contains the security protocol specific data
189 SecurityProtocolSpecificData. If the underlying protocol command requires a
190 specific padding for the command payload, the SendData function shall add padding
191 bytes to the command payload to satisfy the padding requirements.
193 For devices supporting the SCSI command set, the security protocol command is
194 sent using the SECURITY PROTOCOL OUT command defined in SPC-4.
196 For devices supporting the ATA command set, the security protocol command is
197 sent using one of the TRUSTED SEND commands defined in ATA8-ACS if PayloadBufferSize
198 is non-zero. If the PayloadBufferSize is zero, the security protocol command
199 is sent using the Trusted Non-Data command defined in ATA8-ACS.
201 If PayloadBuffer is NULL and PayloadBufferSize is non-zero, the function shall
202 return EFI_INVALID_PARAMETER.
204 If the given DeviceIndex does not support security protocol commands, the function
205 shall return EFI_UNSUPPORTED.
207 If the security protocol fails to complete within the Timeout period, the function
208 shall return EFI_TIMEOUT.
210 If the security protocol command completes without an error, the function shall
211 return EFI_SUCCESS. If the security protocol command completes with an error,
212 the functio shall return EFI_DEVICE_ERROR.
214 @param[in] This The PPI instance pointer.
215 @param[in] DeviceIndex The ID of the device.
216 @param[in] Timeout The timeout, in 100ns units, to use for the execution
217 of the security protocol command. A Timeout value
218 of 0 means that this function will wait indefinitely
219 for the security protocol command to execute. If
220 Timeout is greater than zero, then this function
221 will return EFI_TIMEOUT if the time required to
222 execute the receive data command is greater than
224 @param[in] SecurityProtocolId
225 The value of the "Security Protocol" parameter of
226 the security protocol command to be sent.
227 @param[in] SecurityProtocolSpecificData
228 The value of the "Security Protocol Specific"
229 parameter of the security protocol command to be
231 @param[in] PayloadBufferSize Size in bytes of the payload data buffer.
232 @param[in] PayloadBuffer A pointer to a destination buffer to store the
233 security protocol command specific payload data
234 for the security protocol command.
236 @retval EFI_SUCCESS The security protocol command completed successfully.
237 @retval EFI_UNSUPPORTED The given DeviceIndex does not support security
239 @retval EFI_DEVICE_ERROR The security protocol command completed with
241 @retval EFI_INVALID_PARAMETER The PayloadBuffer is NULL and PayloadBufferSize
243 @retval EFI_TIMEOUT A timeout occurred while waiting for the security
244 protocol command to execute.
249 (EFIAPI
*EDKII_PEI_STORAGE_SECURITY_SEND_DATA
)(
250 IN EDKII_PEI_STORAGE_SECURITY_CMD_PPI
*This
,
251 IN UINTN DeviceIndex
,
253 IN UINT8 SecurityProtocolId
,
254 IN UINT16 SecurityProtocolSpecificData
,
255 IN UINTN PayloadBufferSize
,
256 IN VOID
*PayloadBuffer
260 // EDKII_PEI_STORAGE_SECURITY_CMD_PPI contains a set of services to send security
261 // protocol commands to a mass storage device. Two types of security protocol
262 // commands are supported. SendData sends a command with data to a device.
263 // ReceiveData sends a command that receives data and/or the result of one or
264 // more commands sent by SendData.
266 struct _EDKII_PEI_STORAGE_SECURITY_CMD_PPI
{
268 EDKII_PEI_STORAGE_SECURITY_GET_NUMBER_DEVICES GetNumberofDevices
;
269 EDKII_PEI_STORAGE_SECURITY_GET_DEVICE_PATH GetDevicePath
;
270 EDKII_PEI_STORAGE_SECURITY_RECEIVE_DATA ReceiveData
;
271 EDKII_PEI_STORAGE_SECURITY_SEND_DATA SendData
;
274 extern EFI_GUID gEdkiiPeiStorageSecurityCommandPpiGuid
;