[PATCH v2 2/3] Documentation: user: optee: bring up-to-date

[Ahmad Fatoum <a.fatoum@pengutronix.de>]

Most platforms now use OP-TEE early loading and we have gained support
to communicate with OP-TEE and not only loading it.

Reflect that in the docs.

Reviewed-by: Marco Felsch <m.felsch@pengutronix.de>
Signed-off-by: Ahmad Fatoum <a.fatoum@pengutronix.de>
---
v1 -> v2:
  - Add Marco's R-b
---
 Documentation/user/optee.rst | 45 +++++++++++++++++++++++++++---------
 1 file changed, 34 insertions(+), 11 deletions(-)

diff --git a/Documentation/user/optee.rst b/Documentation/user/optee.rst
index 950917b446ad..2729d21d2e44 100644
--- a/Documentation/user/optee.rst
+++ b/Documentation/user/optee.rst
@@ -4,20 +4,20 @@
 OP-TEE
 ======
 
-Barebox is able to start the Open Portable Trusted Execution Environment
-(OP-TEE) either before starting the linux kernel or during lowlevel board
-initialization in the Pre Bootloader ``PBL``.
+barebox has support for loading and communicating with the Open Portable Trusted
+Execution Environment (OP-TEE).
 
-Before Linux start
-------------------
-Enable the `CONFIG_BOOTM_OPTEE` configuration variable and configure the
-`CONFIG_OPTEE_SIZE` variable. This will reserve a memory area at the end
-of memory for OP-TEE to run, usually Barebox would relocate itself there. To
-load OP-TEE before the kernel is started, configure the global ``bootm.tee``
-variable to point to a valid OPTEE v1 binary.
+Loading OP-TEE
+--------------
+
+barebox can start OP-TEE either during lowlevel board initialization
+in the :ref:`prebootloader <pbl>` or prior to starting the linux kernel.
+
+.. _optee_early_loading:
 
 During the PBL
---------------
+^^^^^^^^^^^^^^
+
 To start OP-TEE during the lowlevel initialization of your board in the ``PBL``,
 enable the ``CONFIG_PBL_OPTEE`` configuration variable. your board should then
 call the function ``start_optee_early(void* tee, void* fdt)`` with a valid tee
@@ -27,3 +27,26 @@ Since OP-TEE in the default configuration also modifies the device tree, don't
 pass the barebox internal device tree, instead copy it into a different memory
 location and pass it to OP-TEE afterwards.
 The modified device tree can then be passed to the main barebox start function.
+
+Before Linux start
+^^^^^^^^^^^^^^^^^^
+
+.. warning:: Late loading of OP-TEE is deprecated, greatly increases the
+   attack surface and is only supported on 32-bit ARM systems.
+   Systems should prefer early loading OP-TEE whenever possible.
+
+Enable the `CONFIG_BOOTM_OPTEE` configuration variable and configure the
+`CONFIG_OPTEE_SIZE` variable. This will reserve a memory area at the end
+of memory for OP-TEE to run, usually Barebox would relocate itself there. To
+load OP-TEE before the kernel is started, configure the global ``bootm.tee``
+variable to point to a valid OPTEE v1 binary.
+
+Communication with OP-TEE
+-------------------------
+
+Controlled by the ``CONFIG_OPTEE`` option, barebox has support for
+communicating with OP-TEE via secure monitor calls and dynamic shared memory.
+This is possible independently of whether OP-TEE was loaded by barebox or not.
+
+The primary use cases currently is SCMI-over-OP-TEE, which is required on
+the STM32MP13.
-- 
2.39.5