[PATCH] Documentation/firmware: clean up other_interfaces.rst

[PATCH] Documentation/firmware: clean up other_interfaces.rst

[Randy Dunlap]

Fix bullet lists, grammar, punctuation, spelling, and literal block
formatting. These changes eliminate several documentation build warnings
make the documentation more readable, and render it cleanly.

Documentation/driver-api/firmware/other_interfaces.rst:60: ERROR: Unexpected indentation. [docutils]
Documentation/driver-api/firmware/other_interfaces.rst:103: ERROR: Unexpected indentation. [docutils]
Documentation/driver-api/firmware/other_interfaces.rst:115: ERROR: Unexpected indentation. [docutils]
Documentation/driver-api/firmware/other_interfaces.rst:116: WARNING: Blank line required after table. [docutils]
Documentation/driver-api/firmware/other_interfaces.rst:140: WARNING: Bullet list ends without a blank line; unexpected unindent. [docutils]

Fixes: 3b4531c6e0f4 ("Documentation/firmware: add imx/se to other_interfaces")
Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
---
Cc: Pankaj Gupta <pankaj.gupta@nxp.com>
Cc: Frank Li <Frank.Li@nxp.com>
Cc: imx@lists.linux.dev
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Shuah Khan <skhan@linuxfoundation.org>
Cc: linux-doc@vger.kernel.org

 Documentation/driver-api/firmware/other_interfaces.rst |   40 +++++-----
 1 file changed, 21 insertions(+), 19 deletions(-)

--- linux-next-20260506.orig/Documentation/driver-api/firmware/other_interfaces.rst
+++ linux-next-20260506/Documentation/driver-api/firmware/other_interfaces.rst
@@ -56,12 +56,13 @@ NXP Secure Enclave Firmware Interface
 Introduction
 ------------
 The NXP's i.MX HW IP like EdgeLock Enclave, V2X etc., creates an embedded secure
-enclave within the SoC boundary to enable features like
- - Hardware Security Module (HSM)
- - Security Hardware Extension (SHE)
- - Vehicular to Anything (V2X)
+enclave within the SoC boundary to enable features like:
 
-Each of the above feature is enabled through dedicated NXP H/W IP on the SoC.
+- Hardware Security Module (HSM)
+- Security Hardware Extension (SHE)
+- Vehicular to Anything (V2X)
+
+Each of the above features is enabled through dedicated NXP H/W IP on the SoC.
 On a single SoC, multiple hardware IP (or can say more than one secure enclave)
 can exist.
 
@@ -74,25 +75,27 @@ MUs, dedicated to itself. None of the MU
 of the MU is realized using the mailbox driver. Each secure enclave can cater to
 multiple clients by virtue of these exclusive MUs. Also, they can distinguish
 transactions originating from these clients based on the MU used and core security
-state. The communication between the clients and secure enclaves is in form of
-command/response mechanism. Each client could expose specific set of secure enclave
+state. The communication between the clients and secure enclaves is in the form of
+a command/response mechanism. Each client could expose a specific set of secure enclave
 features to the higher layers, based on the commands supported by that client. For
 example, the secure enclave could simultaneously support an OPTEE TA and Linux
-middleware as clients. Each of these clients can expose specific set of secure
+middleware as clients. Each of these clients can expose a specific set of secure
 enclave features based on the command set supported by them.
 
 NXP Secure Enclave(SE) Interface
 --------------------------------
-Although MU(s) is/are not shared between SE(s). But for SoC like i.MX95 which has
-multiple SE(s) like HSM, V2X-HSM, V2X-SHE; all the SE(s) and their interfaces 'se-if'
+MU(s) is/are not shared between SE(s). But for an SoC like i.MX95 which has
+multiple SE(s) like HSM, V2X-HSM, V2X-SHE, all the SE(s) and their interfaces 'se-if'
 that is/are dedicated to a particular SE will be enumerated and provisioned using the
 single compatible node("fsl,imx95-se").
 
-Each 'se-if' comprise of twp layers:
+Each 'se-if' comprises two layers:
+
 - (C_DEV Layer) User-Space software-access interface.
 - (Service Layer) OS-level software-access interface.
 
 ::
+
    +--------------------------------------------+
    |            Character Device(C_DEV)         |
    |                                            |
@@ -124,20 +127,19 @@ Each 'se-if' comprise of twp layers:
   for communication with firmware.
 
   FW Communication protocol ensures two things:
-  - Serializing the messages to be sent over an MU.
 
+  - Serializing the messages to be sent over an MU.
   - FW can handle one command message at a time.
 
 - c_dev:
   This layer offers character device contexts, created as '/dev/<se>_mux_chx'.
-  Using these multiple device contexts that are getting multiplexed over a single MU,
+  Using these multiple device contexts that are multiplexed over a single MU,
   userspace application(s) can call fops like write/read to send the command message,
   and read back the command response message to/from Firmware.
   fops like read & write use the above defined service layer API(s) to communicate with
   Firmware.
 
-  Misc-device(/dev/<se>_mux_chn) synchronization protocol:
-::
+  Misc-device(/dev/<se>_mux_chn) synchronization protocol::
 
                                 Non-Secure               +   Secure
                                                          |
@@ -163,11 +165,11 @@ Each 'se-if' comprise of twp layers:
                 User 0        User 1       User Y        |
                 +------+      +------+     +------+      |
                 |misc.c|      |misc.c|     |misc.c|      |
- kernel space   +------+      +------+     +------+      |
+   kernel space +------+      +------+     +------+      |
                                                          |
- +------------------------------------------------------ |
+   +---------------------------------------------------- |
                     |             |           |          |
- userspace     /dev/ele_muXch0    |           |          |
+   userspace   /dev/ele_muXch0    |           |          |
                           /dev/ele_muXch1     |          |
                                         /dev/ele_muXchY  |
                                                          |
@@ -175,7 +177,7 @@ Each 'se-if' comprise of twp layers:
 When a user sends a command to the firmware, it registers its device_ctx
 as waiter of a response from firmware.
 
-Enclave's Firmware owns the storage management, over Linux filesystem.
+Enclave's Firmware owns the storage management over a Linux filesystem.
 For this c_dev provisions a dedicated slave device called "receiver".
 
 .. kernel-doc:: drivers/firmware/imx/se_ctrl.c

Re: [PATCH] Documentation/firmware: clean up other_interfaces.rst

[Frank Li]

On Wed, 06 May 2026 19:04:46 -0700, Randy Dunlap wrote:
> Fix bullet lists, grammar, punctuation, spelling, and literal block
> formatting. These changes eliminate several documentation build warnings
> make the documentation more readable, and render it cleanly.
>
> Documentation/driver-api/firmware/other_interfaces.rst:60: ERROR: Unexpected indentation. [docutils]
> Documentation/driver-api/firmware/other_interfaces.rst:103: ERROR: Unexpected indentation. [docutils]
> Documentation/driver-api/firmware/other_interfaces.rst:115: ERROR: Unexpected indentation. [docutils]
> Documentation/driver-api/firmware/other_interfaces.rst:116: WARNING: Blank line required after table. [docutils]
> Documentation/driver-api/firmware/other_interfaces.rst:140: WARNING: Bullet list ends without a blank line; unexpected unindent. [docutils]
>
> [...]

Applied, thanks!

[1/1] Documentation/firmware: clean up other_interfaces.rst

squash to 3b4531c6e0f4 ("Documentation/firmware: add imx/se to other_interfaces")
any concern let me known.

Best regards,
--
Frank Li <Frank.Li@nxp.com>