[PATCH 10/12] doc: arm64: document FF-A runtime path for EFI variables

[Simon Glass]

Hi Harsimran,

On 2026-04-24T17:31:50, Harsimran Singh Tungal
<harsimransingh.tungal at arm.com> wrote:
> doc: arm64: document FF-A runtime path for EFI variables
>
> Document how EFI runtime variables use FF-A MM communication
>
> Describe the FF-A runtime layer on arm64 and how EFI variable
> runtime services use the FF-A transport and shared MM buffer.
> Also clarify armffa command scope and link to the FF-A doc.
>
> Signed-off-by: Harsimran Singh Tungal <harsimransingh.tungal at arm.com>
>
> doc/arch/arm64.ffa.rst   | 92 ++++++++++++++++++++++++++++++++++++++++++++----
>  doc/usage/cmd/armffa.rst | 11 ++++++
>  2 files changed, 96 insertions(+), 7 deletions(-)

> diff --git a/doc/arch/arm64.ffa.rst b/doc/arch/arm64.ffa.rst
> @@ -15,10 +15,10 @@ application in S-EL0, or a Trusted OS in S-EL1.
> +U-Boot's FF-A bus support exposes an optional transport that EFI runtime
> +services can use to communicate with Secure Partitions. Through this
> +interface, EFI services (such as variable access) can request or exchange
> +data with the Secure World using FF-A.

The rest of this file uses lower-case 'Secure world' (see lines 12 and
16). Please keep the capitalisation consistent throughout the new
prose — also at the 'Secure World' in the runtime section below.

> diff --git a/doc/arch/arm64.ffa.rst b/doc/arch/arm64.ffa.rst
> @@ -158,6 +164,77 @@ they want to use (32-bit vs 64-bit). Selecting the protocol means using
> +- The communication buffer is located at CONFIG_FFA_SHARED_MM_BUF_ADDR and
> +  sized by CONFIG_FFA_SHARED_MM_BUF_SIZE.
> +- CONFIG_FFA_SHARED_MM_BUF_OFFSET is sent in the FF-A direct message payload
> +  to indicate where the data begins.
> +- The buffer is filled by memcpy(), the cache is flushed before notifying the
> +  MM SP, and later the buffer is reused directly with only the shared-buffer
> +  range invalidated (invalidate_dcache_range()) to avoid whole-cache
> +  invalidation.

This level of cache-maintenance detail is an implementation note and
will go stale the moment the code is touched (and patch 12 is already
touching it in this very series). I'd drop the third bullet and let
the source comments have that, or move it under a clearly marked
'Implementation notes' sub-heading so readers know it is informative
rather than contractual.

> diff --git a/doc/arch/arm64.ffa.rst b/doc/arch/arm64.ffa.rst
> @@ -158,6 +164,77 @@ they want to use (32-bit vs 64-bit). Selecting the protocol means using
> +- get_comm_buf() switches to the static shared buffer
> +- mm_communicate_runtime() selects FF-A transport when the runtime context
> +  is enabled
> +- ffa_mm_communicate_runtime() issues FFA_MSG_SEND_DIRECT_{REQ,RESP} through
> +  ffa_sync_send_receive_runtime()

Naming specific static helpers in a public document ties the doc to
current internal names. If one is renamed or refactored later, the doc
silently lies. Please describe the flow at one level higher (e.g. 'the
runtime path uses a static shared buffer and dispatches direct FF-A
messages') and leave the function names to the source.

>
>     doc: arm64: document FF-A runtime path for EFI variables
>
>     Document how EFI runtime variables use FF-A MM communication
>
>     Describe the FF-A runtime layer on arm64 and how EFI variable
>     runtime services use the FF-A transport and shared MM buffer.
>     Also clarify armffa command scope and link to the FF-A doc.

The single-line paragraph just restates the subject and the next
paragraph. U-Boot convention is to open with the motivation/problem -
please replace this with a sentence explaining why the doc was
previously incomplete (the previous text said runtime support was a
future development) and what readers gain from the new sections.

Regards,
Simon