Skip to content

Commit

Permalink
[libc][docs] codify Policy on Assembler Sources
Browse files Browse the repository at this point in the history
It would be helpful in future code reviews to document a policy with regards to
where and when Assembler sources are appropriate. That way when reviewers point
out infractions, they can point to this written policy, which may help
contributors understand that it's not the solely personal preferences of
reviewers but rather a previously agreed upon rule by maintainers.

Link: llvm#87837
Link: llvm#88157
Link: https://discourse.llvm.org/t/hand-written-in-assembly-in-libc-setjmp-longjmp/73249/12
  • Loading branch information
nickdesaulniers committed Apr 9, 2024
1 parent e127997 commit 7b562fa
Showing 1 changed file with 29 additions and 0 deletions.
29 changes: 29 additions & 0 deletions libc/docs/dev/code_style.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
should strive to stick with C++ for as long as it remains reasonable to do so.
llvm-libc maintainers reserve the right to reject Assembler contributions that
could they feel could be better maintained if rewritten in C++, and to revisit
this policy in the future.

0 comments on commit 7b562fa

Please sign in to comment.