RFC: EL3 RMM IDE KM Interface
Note
The RFC has been implemented in TF-A. The EL3-RMM communication interface document specifies the SMCs as mentioned here.
This document captures the requirements and the design of the programming interface exposed by EL3 to program and manage IDE keys at the PCIe Root Port (RP). The RME System Architecture document defines that an RME-DA RP must implement the defined DVSEC registers and exposes an IDE key programming interface for IDE Key Management (IDE_KM). The current proposal is that RMM directly access the DVSEC registers and do any required programming and EL3 provides an SMC interface for IDE_KM operations.
RMM needs to be know the location of DVSEC and IDE Capabilities of the Root port in PCIe ECAM space in a Secure way from EL3. This can be done by passing this info in the Boot Manifest to RMM as part of Root Complex PCIe topology info as described here.
The following diagram shows the overall sequence for setting up IDE Selective stream for an offchip PCIe device. RCiEP and integrated platform devices are not considered for the sequence as NS Host will not be involved in the communication flow for such devices. The below sequence also assumes that EL3 implements blocking semantics for the SMC calls. Note that every communication by RMM to the Device via SPDM session involves a switch back to NS Host and another invocation of RMI_PDEV_COMMUNICATE() API from Host but, for simplicity, the sequence shows direct message from RMM to Device.
Once an IDE Stream is setup and running, it would be needed to update the keys used for the IDE Connection. The following diagram shows the overall sequence for IDE Key refresh. The below sequence assumes that EL3 implements blocking semantics for the SMC calls.
The RME System Architecture mandates the requirements for the IDE Key management (IDE-KM) interface hardware. For the purpose of defining an EL3 ABI for programming this hardware, the following assumptions are made:
- Several Streams can be setup using a single IDE-KM interface for a Root Port. It is up to EL3 to ensure that suitable exclusives are in place to access this interface from multiple CPUs.
- A single Stream ID is associated with one physical device. It is up to the caller to ensure that IDE-KM requests to a Stream ID follow the proper sequence as mandated by the PCIe specification.
- We expect most platforms to implement MMIO based IDE-KM interface. But it is possible for the IDE-KM interface to be over a transport that involve request and response messages and this could have some inherent delays involved. This would mean that the EL3 SMC interface may need to support returning early prior to completion back to caller. Hence it is expected that the interface need to support returning early prior to completion back to caller (non-blocking).
- If an IDE-KM interface is busy, or the IDE-KM transport queue is full, then it is not possible to send a request on this interface. EL3 can return busy error code
E_RMM_AGAINin these cases and RMM needs to retry and this is expected to be needed only for non-blocking mode.
The EL3 IDE Key mgmt SMCs can blocking (run to completion) or non-blocking (return prior to completion). It is upto the platform to choose the required behavior based on delays expected for IDE-KM interface requests. In the blocking mode, once the request is programmed, then the request SMCs return E_RMM_OK or other error code based on the status of the request.
In the non-blocking mode, EL3 can queue the request SMC and return back to the caller with in-progress error code E_RMM_INPROGRESS. The caller needs to pull the response using RMM_IDE_KM_PULL_RESPONSE SMC and this response could correspond to the request from current caller or a request from another caller. It is upto the caller to do the necessary to populate the response to the correct request. To facilitate this, callers can make use of 2 arguments {request_id, cookie} as part of the request and this will be passed through to the corresponding response when pulled. Note that E_RMM_AGAIN error can be returned if EL3 finds that the request-response queue is full and needs the caller to retry the request again. The caller can issue RMM_IDE_KM_PULL_RESPONSE SMC to free up the EL3 queue and it is recommended to pull a response before re-trying the same request again.
Set the key/IV info for a stream. The key is 256 bits and IV is 96 bits. The caller needs to call this SMC to program this key to the {Rx, Tx} ports and for each sub-stream corresponding to a single keyset.
| Reg | Name | Type | Desc |
|---|---|---|---|
| X0 | FID | ||
| X1 | ECAM address | ulong | Identify the root complex (RC). |
| X2 | RP ID | ulong | Identify the RP within the RC |
| X3 | Keyset [12]: Dir[11]: Substream[10:8]: Stream ID [7:0] | ulong | IDE selective stream informationKey set: can be 0 or 1unused bits MBZ. |
| X4 | KeqQW0 | ulong | Quad word of key [63:0] |
| X5 | KeyQW1 | ulong | Quad word of key [127:64] |
| X6 | KeyQW2 | ulong | Quad word of key [191:128] |
| X7 | KeyQW3 | ulong | Quad word of key [255:192] |
| X8 | IFVQW0 | ulong | Quad word of IV [63:0] |
| X9 | IFVQW1 | ulong | Quad word of IV [95:64] |
| X10 | request_id | ulong | Used only in non-blocking mode. Ignored in blocking mode |
| X11 | cookie | ulong | Used only in non-blocking mode. Ignored in blocking mode |
Return values
E_RMM_OK - The key programming is successful.
E_RMM_FAULT - The key programming is not successful.
E_RMM_INVAL - Arguments are not correct.
E_RMM_UNK - Unknown error.
E_RMM_AGAIN - Returned only for non-blocking mode. IDE-KM interface is busy or the request queue is full. The caller needs to retry again.
E_RMM_INPROGRESS - Returned only for non-blocking mode. The caller must issue RMM_IDE_KM_PULL_RESPONSE SMC to pull the response.
Activate the IDE stream once all the keys have been programmed. The caller needs to ensure that the corresponding EL3_IDE_KEY_PROG() has succeeded prior to this call.
| Reg | Name | Type | Desc |
|---|---|---|---|
| X0 | FID | ||
| X1 | ECAM address | ulong | Identify the root complex (RC). |
| X2 | RP ID | ulong | Identify the RP within the RC |
| X3 | Keyset [12]: Dir[11]: Substream[10:8]: Stream ID [7:0] | ulong | IDE selective stream information |
| X4 | request_id | ulong | Used only in non-blocking mode. Ignored in blocking mode |
| X5 | cookie | ulong | Used only in non-blocking mode. Ignored in blocking mode |
Return values
E_RMM_OK - The key set go is successful.
E_RMM_FAULT - The key set go is not successful.
E_RMM_INVAL - Arguments are not correct.
E_RMM_UNK - Unknown error.
E_RMM_AGAIN - Returned only for non-blocking mode. IDE-KM interface is busy or the request queue is full. The caller needs to retry again.
E_RMM_INPROGRESS - Returned only for non-blocking mode. The caller must issue RMM_IDE_KM_PULL_RESPONSE SMC to pull the response.
Stop the IDE stream. This SMC is typically only used in tear down of the IDE Stream.
| Reg | Name | Type | Desc |
|---|---|---|---|
| X0 | FID | ||
| X1 | ECAM address | ulong | Identify the root complex (RC). |
| X2 | RP ID | ulong | Identify the RP within the RC |
| X3 | Keyset [12]: Dir[11]: Substream[10:8]: Stream ID [7:0] | ulong | IDE selective stream information |
| X4 | request_id | ulong | Used only in non-blocking mode. Ignored in blocking mode |
| X5 | cookie | ulong | Used only in non-blocking mode. Ignored in blocking mode |
Return values
E_RMM_OK - The key set stop is successful.
E_RMM_FAULT - The key set stop is not successful.
E_RMM_INVAL - Arguments are not correct.
E_RMM_UNK - Unknown error.
E_RMM_AGAIN - Returned only for non-blocking mode. IDE-KM interface is busy or the request queue is full. The caller needs to retry again.
E_RMM_INPROGRESS - Returned only for non-blocking mode. The caller must issue RMM_IDE_KM_PULL_RESPONSE SMC to pull the response.
Retrieve a response for a non-blocking IDE-KM SMC request. The response may correspond to the any of last pending request SMCs. It is upto the caller to identify the corresponding request and populate the response.
The RP ID parameter is used only to identify the IDE_KM interface and the response pulled may not correspond the root port in case there are multiple Root ports sharing the IDE_KM interface.
For blocking semantics, this SMC always returns E_RMM_UNK.
| Reg | Name | Type | Desc |
|---|---|---|---|
| X0 | FID | ||
| X1 | ECAM address | ulong | Identify the root complex (RC). |
| X2 | RP ID | ulong | Identify the RP within the RC |
Return values
Note that return values in X1, X2 and X3 are only valid if X0 is E_RMM_OK.
| Reg | Name | Type | Desc |
|---|---|---|---|
| X0 | result | ulong |
E_RMM_OK - The response is retrieved successfully. E_RMM_INVAL - Arguments to pull response SMC is not correct.E_RMM_UNK - Pull response SMC encountered unknown error.E_RMM_AGAIN - IDE-KM response queue is empty. No response available. |
| X1 | req_result | ulong | Retrieved Response corresponding to previous IDE_KM request. E_RMM_OK - The previous request was successful. E_RMM_FAULT - The previous request was not successful.E_RMM_INVAL - Arguments to previous request were incorrect.E_RMM_UNK - Previous request returned Unknown error. |
| X2 | request_id | ulong | Passthrough from request SMC |
| X3 | cookie | ulong | Passthrough from request SMC |