[libc-commits] [libc] [libc][docs] codify Policy on Assembler Sources (PR #88185)

[James Y Knight via libc-commits]

================
@@ -186,3 +186,32 @@ We expect contributions to be free of warnings from the `minimum supported
 compiler versions`__ (and newer).
 
 .. __: https://libc.llvm.org/compiler_support.html#minimum-supported-versions
+
+Policy on Assembler sources
+===========================
+
+Coding in high level languages such as C++ provides benefits relative to low
+level languages like Assembler, such as:
+
+* Improved safety
+* Instrumentation
+
+  * Code coverage
+  * Profile collection
+* Sanitization
+* Debug info
+
+While its not impossible to have Assembler code that correctly provides all of
+the above, we do not wish to maintain such Assembler sources in llvm-libc.
+
+That said, there a few functions provided by llvm-libc that are more difficult
+to implement or maintain in C++ than Assembler. We do use inline or out-of-line
+Assembler in an intentionally minimal set of places; typically places where the
+stack or individual register state must be manipulated very carefully for
+correctness.
+
+Contributions adding Assembler for performance are not welcome. Contributors
----------------
jyknight wrote:

The document as it stands sounds like it prohibits the existing op_x86.h's usage,
```
  LIBC_INLINE static void repmovsb(void *dst, const void *src, size_t count) {
    asm volatile("rep movsb" : "+D"(dst), "+S"(src), "+c"(count) : : "memory");
  }
```

Is that the intent? IMO that's too strict.

I'd say there's 3 levels:
1. Very short, targeted, inline-asm statements (only a couple of instructions).
2. Longer inline-asm statements.
3. Functions written entirely in asm (whether standalone asm files or "naked" function).

All levels should require some justification, but each should requires substantially greater justification than the previous. Level 3, I think is widely agreed, should be outright prohibited except when it's required for correctness.

More flexibility might be reasonable for the others: e.g. level 1 should perhaps be acceptable simply if the desired instruction is not readily accessible as an intrinsic today (e.g. `rep movsb`, cacheline management, potentially things like specialized math instructions).

https://github.com/llvm/llvm-project/pull/88185