On 2026-04-28 12:08 -0600, Simon Glass wrote: > Hi Harsimran, > > On 2026-04-24T17:31:50, Harsimran Singh Tungal > <[email protected]> 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 <[email protected]> > > > > 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. >
Thanks, I fixed the capitalization in v2. Link to v2: https://lore.kernel.org/u-boot/[email protected]/ > > 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. > Thanks, agreed. In v2, I dropped that cache-maintenance bullet and kept the section focused on the FF-A runtime/MM buffer interface rather than implementation detail. > > 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. > Thanks, this makes sense to me. In v2, I removed the internal helper names from that section and rewrote it at a higher level in terms of the FF-A runtime transport, the shared MM buffer, and direct FF-A messaging after ExitBootServices(). > > > > 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 > This has been updated in v2. Thanks Regards Harsimran Singh Tungal
