docs(rmmd): document the EL3-RMM IDE KM Interface
This patch documents the EL3-RMM IDE KM interface.
Four IDE Key management smc calls have been added:
- RMM_IDE_KEY_PROG()
- RMM_IDE_KEY_SET_GO()
- RMM_IDE_KEY_SET_STOP()
- RMM_IDE_KM_PULL_RESPONSE()
Change-Id: Iea357ec16a2bee88573266c7a5c9fb36025f15f1
Signed-off-by: Sona Mathew <sonarebecca.mathew@arm.com>
diff --git a/docs/components/rmm-el3-comms-spec.rst b/docs/components/rmm-el3-comms-spec.rst
index 2693e58..1ff2037 100644
--- a/docs/components/rmm-el3-comms-spec.rst
+++ b/docs/components/rmm-el3-comms-spec.rst
@@ -52,7 +52,7 @@
- ``RES0``: Bit 31 of the version number is reserved 0 as to maintain
consistency with the versioning schemes used in other parts of RMM.
-This document specifies the 0.5 version of Boot Interface ABI and RMM-EL3
+This document specifies the 0.6 version of Boot Interface ABI and RMM-EL3
services specification and the 0.5 version of the Boot Manifest.
.. _rmm_el3_boot_interface:
@@ -719,6 +719,247 @@
``E_RMM_OK``,No errors detected
+RMM_IDE_KEY_PROG command
+=========================
+
+Set the key/IV info at Root port for an IDE stream as part of Device Assignment flow. This
+command is available from v0.6 of the RMM-EL3 interface.
+
+Please refer to `IDE-KM RFC <https://github.com/TF-RMM/tf-rmm/wiki/RFC:-EL3-RMM-IDE-KM-Interface>`_
+for description of the IDE setup sequence and how this will be invoked by RMM.
+
+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.
+
+FID
+---
+
+``0xC40001B7``
+
+Input values
+------------
+
+.. csv-table:: Input values for RMM_IDE_KEY_PROG
+ :header: "Name", "Register", "Field", "Type", "Description"
+ :widths: 1 1 1 1 5
+
+ fid,x0,[63:0],UInt64,Command FID
+ ecam_address,x1,[63:0],UInt64,Used to identify the root complex(RC)
+ rp_id,x2,[63:0],UInt64,Used to identify the root port within the root complex(RC)
+ Keyset[12]:Dir[11]:Substream[10:8]:StreamID[7:0],x3,[63:0],UInt64,IDE selective stream informationKey set: can be 0 or 1unused bits MBZ.
+ KeqQW0,x4,[63:0],UInt64,Quad word of key [63:0]
+ KeqQW1,x5,[63:0],UInt64,Quad word of key [127:64]
+ KeqQW2,x6,[63:0],UInt64,Quad word of key [191:128]
+ KeqQW3,x7,[63:0],UInt64,Quad word of key [255:192]
+ IFVQW0,x8,[63:0],UInt64,Quad word of IV [63:0]
+ IFVQW1,x9,[63:0],UInt64,Quad word of IV [95:64]
+ request_id,x10,[63:0],UInt64,Used only in non-blocking mode. Ignored in blocking mode.
+ cookie,x11,[63:0],UInt64,Used only in non-blocking mode. Ignored in blocking mode.
+
+
+Output values
+-------------
+
+.. csv-table:: Output values for RMM_IDE_KEY_PROG
+ :header: "Name", "Register", "Field", "Type", "Description"
+ :widths: 1 1 1 2 4
+
+ Result,x0,[63:0],Error Code,Command return status
+
+Failure conditions
+------------------
+
+The table below shows all the possible error codes returned in ``Result`` upon
+a failure. The errors are ordered by condition check.
+
+.. csv-table:: Failure conditions for RMM_IDE_KEY_PROG
+ :header: "ID", "Condition"
+ :widths: 1 5
+
+ ``E_RMM_OK``,Key programming is successful.
+ ``E_RMM_FAULT``,Key programming is not successful.
+ ``E_RMM_INVAL``,Key programming arguments are incorrect.
+ ``E_RMM_UNK``,Unknown error or the SMC is not present if the version is < 0.6
+ ``E_RMM_AGAIN``,Returned only for non-blocking mode. IDE-KM interface is busy or request is full. Retry required.
+ ``E_RMM_INPROGRESS``,Returned only for non-blocking mode. The caller must issue RMM_IDE_KM_PULL_RESPONSE SMC to pull the response.
+
+
+RMM_IDE_KEY_SET_GO command
+==========================
+
+Activate the IDE stream at Root Port once the keys have been programmed as part of
+Device Assignment flow. This command is available from v0.6 of the RMM-EL3 interface.
+
+Please refer to `IDE-KM RFC <https://github.com/TF-RMM/tf-rmm/wiki/RFC:-EL3-RMM-IDE-KM-Interface>`_
+for description of the IDE setup sequence and info on how this will be invoked by RMM.
+
+The caller(RMM) needs to ensure the EL3_IDE_KEY_PROG() call had succeeded prior to this call.
+
+FID
+---
+
+``0xC40001B8``
+
+Input values
+------------
+
+.. csv-table:: Input values for RMM_IDE_KEY_SET_GO
+ :header: "Name", "Register", "Field", "Type", "Description"
+ :widths: 1 1 1 1 5
+
+ fid,x0,[63:0],UInt64,Command FID
+ ecam_address,x1,[63:0],UInt64,Used to identify the root complex(RC)
+ rp_id,x2,[63:0],UInt64,Used to identify the root port within the root complex(RC)
+ Keyset[12]:Dir[11]:Substream[10:8]:StreamID[7:0],x3,[63:0],UInt64,IDE selective stream information. Key set can be 0 or 1. Unused bits MBZ.
+ request_id,x4,[63:0],UInt64,Used only in non-blocking mode. Ignored in blocking mode.
+ cookie,x5,[63:0],UInt64,Used only in non-blocking mode. Ignored in blocking mode.
+
+
+Output values
+-------------
+
+.. csv-table:: Output values for RMM_IDE_KEY_SET_GO
+ :header: "Name", "Register", "Field", "Type", "Description"
+ :widths: 1 1 1 2 4
+
+ Result,x0,[63:0],Error Code,Command return status
+
+Failure conditions
+------------------
+
+The table below shows all the possible error codes returned in ``Result`` upon
+a failure. The errors are ordered by condition check.
+
+.. csv-table:: Failure conditions for RMM_IDE_KEY_SET_GO
+ :header: "ID", "Condition"
+ :widths: 1 5
+
+ ``E_RMM_OK``,Key set go is successful.
+ ``E_RMM_FAULT``,Key set go is not successful.
+ ``E_RMM_INVAL``,incorrect arguments.
+ ``E_RMM_UNK``,Unknown error or the SMC is not present if the version is < 0.6.
+ ``E_RMM_AGAIN``,Returned only for non-blocking mode. IDE-KM interface is busy or request is full. Retry required.
+ ``E_RMM_INPROGRESS``,Returned only for non-blocking mode. The caller must issue RMM_IDE_KM_PULL_RESPONSE SMC to pull the response.
+
+
+RMM_IDE_KEY_SET_STOP command
+============================
+
+Deactivate the IDE stream at Root Port as part of Device Assignment flow. This command is
+available from v0.6 of the RMM-EL3 interface.
+
+Please refer to `IDE-KM RFC <https://github.com/TF-RMM/tf-rmm/wiki/RFC:-EL3-RMM-IDE-KM-Interface>`_
+for description of the IDE setup sequence and info on how this will be invoked by RMM.
+
+This SMC is used to tear down an IDE Stream.
+
+FID
+---
+
+``0xC40001B9``
+
+Input values
+------------
+
+.. csv-table:: Input values for RMM_IDE_KEY_SET_STOP
+ :header: "Name", "Register", "Field", "Type", "Description"
+ :widths: 1 1 1 1 5
+
+ fid,x0,[63:0],UInt64,Command FID
+ ecam_address,x1,[63:0],UInt64,Used to identify the root complex(RC)
+ rp_id,x2,[63:0],UInt64,Used to identify the root port within the root complex(RC)
+ Keyset[12]:Dir[11]:Substream[10:8]:StreamID[7:0],x3,[63:0],UInt64,IDE selective stream information. Key set can be 0 or 1. Unused bits MBZ.
+ request_id,x4,[63:0],UInt64,Used only in non-blocking mode. Ignored in blocking mode.
+ cookie,x5,[63:0],UInt64,Used only in non-blocking mode. Ignored in blocking mode.
+
+
+Output values
+-------------
+
+.. csv-table:: Output values for RMM_IDE_KEY_SET_STOP
+ :header: "Name", "Register", "Field", "Type", "Description"
+ :widths: 1 1 1 2 4
+
+ Result,x0,[63:0],Error Code,Command return status
+
+Failure conditions
+------------------
+
+The table below shows all the possible error codes returned in ``Result`` upon
+a failure. The errors are ordered by condition check.
+
+.. csv-table:: Failure conditions for RMM_IDE_KEY_SET_STOP
+ :header: "ID", "Condition"
+ :widths: 1 5
+
+ ``E_RMM_OK``,Key set go is successful.
+ ``E_RMM_FAULT``,Key set go is not successful.
+ ``E_RMM_INVAL``,incorrect arguments.
+ ``E_RMM_UNK``,Unknown error or the SMC is not present if the version is < 0.6.
+ ``E_RMM_AGAIN``,Returned only for non-blocking mode. IDE-KM interface is busy or request is full. Retry required.
+ ``E_RMM_INPROGRESS``,Returned only for non-blocking mode. The caller must issue RMM_IDE_KM_PULL_RESPONSE SMC to pull the response.
+
+
+RMM_IDE_KM_PULL_RESPONSE command
+================================
+
+Retrieve the response from Root Port to a previous non-blocking IDE-KM SMC request as part of
+Device Assignment flow. This command is available from v0.6 of the RMM-EL3 interface.
+
+Please refer to `IDE-KM RFC <https://github.com/TF-RMM/tf-rmm/wiki/RFC:-EL3-RMM-IDE-KM-Interface>`_
+for description of the IDE setup sequence and info on how this will be invoked by RMM.
+
+The response from this call could correspond to any of the last pending requests and the
+RMM needs to identify the request and populate the response. For blocking calls, this SMC
+always returns E_RMM_UNK.
+
+FID
+---
+
+``0xC40001BA``
+
+Input values
+------------
+
+.. csv-table:: Input values for RMM_IDE_KM_PULL_RESPONSE
+ :header: "Name", "Register", "Field", "Type", "Description"
+ :widths: 1 1 1 1 5
+
+ fid,x0,[63:0],UInt64,Command FID
+ ecam_address,x1,[63:0],UInt64,Used to identify the root complex(RC)
+ rp_id,x2,[63:0],UInt64,Used to identify the root port within the root complex(RC)
+
+
+Output values
+-------------
+
+.. csv-table:: Output values for RMM_IDE_KM_PULL_RESPONSE
+ :header: "Name", "Register", "Field", "Type", "Description"
+ :widths: 1 1 1 2 4
+
+ Result,x0,[63:0],Error Code,Command return status
+ Result,x1,[63:0],Error Code,Retrieved response corresponding to previous IDE_KM requests.
+ Result,x2,[63:0],value,passthrough from requested SMC
+ Result,x3,[63:0],value,passthrough from requested SMC
+
+Failure conditions
+------------------
+
+The table below shows all the possible error codes returned in ``Result`` upon
+a failure. The errors are ordered by condition check.
+
+.. csv-table:: Failure conditions for RMM_IDE_KM_PULL_RESPONSE
+ :header: "ID", "Condition"
+ :widths: 1 5
+
+ ``E_RMM_OK``,Key set go is successful.
+ ``E_RMM_FAULT``,Key set go is not successful.
+ ``E_RMM_INVAL``,incorrect arguments.
+ ``E_RMM_UNK``,Unknown error or the SMC is not present if the version is < 0.6.
+ ``E_RMM_AGAIN``,KM request is empty and no response if available.
+
+
RMM-EL3 world switch register save restore convention
_____________________________________________________
diff --git a/docs/porting-guide.rst b/docs/porting-guide.rst
index 327c67b..7e40e47 100644
--- a/docs/porting-guide.rst
+++ b/docs/porting-guide.rst
@@ -2460,6 +2460,163 @@
The function returns E_RMM_OK on success, RMM_E_INVAL if arguments are invalid and
E_RMM_UNK if the SMC is not implemented or if interface version is < 0.4.
+Function : plat_rmmd_el3_ide_key_program() [mandatory when RMMD_ENABLE_IDE_KEY_PROG == 1]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : uint64_t, uint64_t, uint64_t, struct rp_ide_key_info_t *, uint64_t, uint64_t
+ Return : int
+
+This function sets the key/IV info for an IDE stream at the Root port. The key is 256 bits
+and IV is 96 bits. The caller calls this SMC to program this key to the Rx and Tx ports
+and for each substream corresponding to a single keyset. The platform should validate
+the arguments `Ecam address` and `Rootport ID` before acting on it. The arguments `request ID`
+and `cookie` are to be ignored for blocking mode and are pass-through to the response for
+non-blocking mode.
+
+The platform needs to ensure proper exclusives are in place when accessed from multiple CPUs.
+Depending on the expected latency for IDE-KM interface, the platform should choose blocking
+or non-blocking semantics. More details about IDE Setup flow can be found
+in this `RFC <https://github.com/TF-RMM/tf-rmm/wiki/RFC:-EL3-RMM-IDE-KM-Interface>`_.
+
+The parameters of the function are:
+
+ arg0 - The ecam address, to access and configure PCI devices in a system.
+
+ arg1 - The rootport ID used to identify the PCIe rootport of a connected device.
+
+ arg2 - The IDE stream info associated with a physical device, this parameter packs the
+ the keyset, direction, substream and stream ID info.
+
+ arg3 - Structure with key and IV info.
+
+ arg4 - The request ID, is used in non-blocking mode only and can be ignored in blocking mode.
+
+ arg5 - The cookie variable, is used in non-blocking mode only and can be ignored in blocking
+ mode.
+
+The function returns E_RMM_OK on success, E_RMM_INVAL if arguments are invalid, E_RMM_FAULT
+if the key programming is unsuccesful, E_RMM_UNK for an unknown error, E_RMM_AGAIN returned
+only for non-blocking mode if the IDE-KM interface is busy or the request queue is full.
+E_RMM_INPROGRESS returned if the request is queued successfully and used only in non-blocking
+mode.
+
+Function : plat_rmmd_el3_ide_key_set_go() [mandatory when RMMD_ENABLE_IDE_KEY_PROG == 1]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : uint64_t, uint64_t, uint64_t, uint64_t, uint64_t
+ Return : int
+
+This function activates the IDE stream at the Root Port once all the keys have been
+programmed. The platform should validate the arguments `Ecam address` and `Rootport ID`
+before acting on it. The arguments `request ID` and `cookie` are to be ignored for blocking
+mode and are pass-through to the response for non-blocking mode.
+
+The platform needs to ensure proper exclusives are in place when accessed from multiple CPUs.
+Depending on the expected latency for IDE-KM interface, the platform should choose blocking
+or non-blocking semantics. More details about IDE Setup flow can be found
+in this `RFC <https://github.com/TF-RMM/tf-rmm/wiki/RFC:-EL3-RMM-IDE-KM-Interface>`_.
+
+The parameters of the function are:
+
+ arg0 - The ecam address, to access and configure PCI devices in a system.
+
+ arg1 - The rootport ID used to identify the PCIe rootport of a connected device.
+
+ arg2 - The IDE stream info associated with a physical device, this parameter packs the
+ the keyset, direction, substream and stream ID info.
+
+ arg3 - The request ID, is used in non-blocking mode only and can be ignored in blocking mode.
+
+ arg4 - The cookie variable, is used in non-blocking mode only and can be ignored in blocking
+ mode.
+
+The function returns E_RMM_OK on success, E_RMM_INVAL if arguments are invalid, E_RMM_FAULT
+if the key programming is unsuccesful, E_RMM_UNK for an unknown error, E_RMM_AGAIN returned
+only for non-blocking mode if the IDE-KM interface is busy or the request queue is full.
+E_RMM_INPROGRESS returned if the request is queued successfully and used only in non-blocking
+mode.
+
+Function : plat_rmmd_el3_ide_key_set_stop() [mandatory when RMMD_ENABLE_IDE_KEY_PROG == 1]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : uint64_t, uint64_t, uint64_t, uint64_t, uint64_t
+ Return : int
+
+This function stops the IDE stream and is used to tear down the IDE stream at Root Port.
+The platform should validate the arguments `Ecam address` and `Rootport ID` before acting
+on it. The arguments `request ID` and `cookie` are to be ignored for blocking
+mode and are pass-through to the response for non-blocking mode.
+
+The platform needs to ensure proper exclusives are in place when accessed from multiple CPUs.
+Depending on the expected latency for IDE-KM interface, the platform should choose blocking
+or non-blocking semantics. More details about IDE Setup flow can be found
+in this `RFC <https://github.com/TF-RMM/tf-rmm/wiki/RFC:-EL3-RMM-IDE-KM-Interface>`_.
+
+The parameters of the function are:
+
+ arg0 - The ecam address, to access and configure PCI devices in a system.
+
+ arg1 - The rootport ID used to identify the PCIe rootport of a connected device.
+
+ arg2 - The IDE stream info associated with a physical device, this parameter packs the
+ the keyset, direction, substream and stream ID info.
+
+ arg3 - The request ID, is used in non-blocking mode only and can be ignored in blocking mode.
+
+ arg4 - The cookie variable, is used in non-blocking mode only and can be ignored in blocking
+ mode.
+
+The function returns E_RMM_OK on success, E_RMM_INVAL if arguments are invalid, E_RMM_FAULT
+if the key programming is unsuccesful, E_RMM_UNK for an unknown error, E_RMM_AGAIN returned
+only for non-blocking mode if the IDE-KM interface is busy or the request queue is full.
+E_RMM_INPROGRESS returned if the request is queued successfully and used only in non-blocking
+mode.
+
+Function : plat_rmmd_el3_ide_km_pull_response() [mandatory when RMMD_ENABLE_IDE_KEY_PROG == 1]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : uint64_t, uint64_t, uint64_t *, uint64_t *, uint64_t *
+ Return : int
+
+This function retrieves a reponse for any of the prior non-blocking IDE-KM requests. The
+caller has to identify the request and populate the accurate response. For blocking calls,
+this function always returns E_RMM_UNK.
+
+The platform needs to ensure proper exclusives are in place when accessed from multiple CPUs.
+Depending on the expected latency for IDE-KM interface, the platform should choose blocking
+or non-blocking semantics. More details about IDE Setup flow can be found
+in this `RFC <https://github.com/TF-RMM/tf-rmm/wiki/RFC:-EL3-RMM-IDE-KM-Interface>`_.
+
+The parameters of the function are:
+
+ arg0 - The ecam address, to access and configure PCI devices in a system.
+
+ arg1 - The rootport ID used to identify the PCIe rootport of a connected device.
+
+ arg2 - Retrieved response corresponding to the previous IDE_KM request.
+
+ arg3 - returns the passthrough request ID of the retrieved response.
+
+ arg4 - returns the passthrough cookie of the retrieved response.
+
+The function returns E_RMM_OK if response is retrieved successfully, E_RMM_INVAL if arguments
+to this function are invalid, E_RMM_UNK if response retrieval failed for an unknown error or
+IDE-KM interface is having blocking semantics, E_RMM_AGAIN if the response queue is empty.
+
+The `arg2` return parameter can return the following values:
+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.
+
Function : bl31_plat_enable_mmu [optional]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~