linux-kernel - [PATCH 5/9] CodingStyle: institute better inline assembly formatting

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <20250509203430.3448-5-adobriyan@gmail.com>
Date: Fri,  9 May 2025 23:34:26 +0300
From: Alexey Dobriyan <adobriyan@...il.com>
To: corbet@....net
Cc: workflows@...r.kernel.org,
	linux-kernel@...r.kernel.org,
	Alexey Dobriyan <adobriyan@...il.com>
Subject: [PATCH 5/9] CodingStyle: institute better inline assembly formatting

Signed-off-by: Alexey Dobriyan <adobriyan@...il.com>
---
 Documentation/process/coding-style.rst | 40 +++++++++++++++++++++-----
 1 file changed, 33 insertions(+), 7 deletions(-)

diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst
index 5c5902a0f897..63c41125e713 100644
--- a/Documentation/process/coding-style.rst
+++ b/Documentation/process/coding-style.rst
@@ -1159,16 +1159,42 @@ You may need to mark your asm statement as volatile, to prevent GCC from
 removing it if GCC doesn't notice any side effects.  You don't always need to
 do so, though, and doing so unnecessarily can limit optimization.
 
-When writing a single inline assembly statement containing multiple
-instructions, put each instruction on a separate line in a separate quoted
-string, and end each string except the last with ``\n\t`` to properly indent
-the next instruction in the assembly output:
+Inline assembly statements are formatted as follows:
 
 .. code-block:: c
 
-	asm ("magic %reg1, #42\n\t"
-	     "more_magic %reg2, %reg3"
-	     : /* outputs */ : /* inputs */ : /* clobbers */);
+	asm [volatile] (
+		"insn1 r0, r1, r2\n\t"
+		"insn2 r0, 1\n\t"
+		: /* possibly empty output list */
+		: /* possibly empty input list */
+		: /* possibly empty clobber list */
+		[: goto label list]
+	);
+
+All keywords are placed on a single line.
+There is a space between ``asm``/``volatile`` and ``(`` so it looks nicer.
+
+Each assembly instruction is placed on a separate line as does
+output/input/clobber/label lists even if they are empty. This is done to
+a) prevent unnecessary reformatting if ``volatile`` is added/removed and
+b) to visually separate outputs from inputs from clobbers, so it's easier
+to understand what's going on.
+
+Each line of inline assembly statement except the first and the last is
+indented by 1 tab relative to the initial ``asm`` keyword.
+
+Each assembly instruction is ended by ``"\n\t"``. It looks ugly and distracting
+in the source code but keeps formatting of ``-S`` output consistent.
+
+Very short and simple inline assembly statements are permitted to be one-liners:
+
+.. code-block:: c
+
+	asm ("movdqa %%xmm0, %0" : "=m" (*buf));
+
+Those are usually 1:1 wrappers around single CPU instruction.
+``"\n\t"`` suffix is unnecessary in this case as the compiler will insert it anyway.
 
 
 Conditional Compilation
-- 
2.49.0