Skip to content

Commit 7b562fa

Browse files
[libc][docs] codify Policy on Assembler Sources
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
1 parent e127997 commit 7b562fa

File tree

1 file changed

+29
-0
lines changed

1 file changed

+29
-0
lines changed

libc/docs/dev/code_style.rst

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -186,3 +186,32 @@ We expect contributions to be free of warnings from the `minimum supported
186186
compiler versions`__ (and newer).
187187

188188
.. __: https://libc.llvm.org/compiler_support.html#minimum-supported-versions
189+
190+
Policy on Assembler sources
191+
===========================
192+
193+
Coding in high level languages such as C++ provides benefits relative to low
194+
level languages like Assembler, such as:
195+
196+
* Improved safety
197+
* Instrumentation
198+
199+
* Code coverage
200+
* Profile collection
201+
* Sanitization
202+
* Debug info
203+
204+
While its not impossible to have Assembler code that correctly provides all of
205+
the above, we do not wish to maintain such Assembler sources in llvm-libc.
206+
207+
That said, there a few functions provided by llvm-libc that are more difficult
208+
to implement or maintain in C++ than Assembler. We do use inline or out-of-line
209+
Assembler in an intentionally minimal set of places; typically places where the
210+
stack or individual register state must be manipulated very carefully for
211+
correctness.
212+
213+
Contributions adding Assembler for performance are not welcome. Contributors
214+
should strive to stick with C++ for as long as it remains reasonable to do so.
215+
llvm-libc maintainers reserve the right to reject Assembler contributions that
216+
could they feel could be better maintained if rewritten in C++, and to revisit
217+
this policy in the future.

0 commit comments

Comments
 (0)