Skip to content

Commit 0336116

Browse files
[libc][docs] codify Policy on Assembler Sources (#88185)
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 solely the personal preferences of individual reviewers but instead rather a previously agreed upon rule by maintainers. Link: #87837 Link: #88157 Link: https://discourse.llvm.org/t/hand-written-in-assembly-in-libc-setjmp-longjmp/73249/12
1 parent a54102a commit 0336116

File tree

1 file changed

+41
-0
lines changed

1 file changed

+41
-0
lines changed

libc/docs/dev/code_style.rst

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -219,3 +219,44 @@ defines. Code under ``libc/src/`` should ``#include`` a proxy header from
219219
``hdr/``, which contains a guard on ``LLVM_LIBC_FULL_BUILD`` to either include
220220
our header from ``libc/include/`` (fullbuild) or the corresponding underlying
221221
system header (overlay).
222+
223+
Policy on Assembly sources
224+
==========================
225+
226+
Coding in high level languages such as C++ provides benefits relative to low
227+
level languages like Assembly, such as:
228+
229+
* Improved safety
230+
* Compile time diagnostics
231+
* Instrumentation
232+
233+
* Code coverage
234+
* Profile collection
235+
* Sanitization
236+
* Automatic generation of debug info
237+
238+
While it's not impossible to have Assembly code that correctly provides all of
239+
the above, we do not wish to maintain such Assembly sources in llvm-libc.
240+
241+
That said, there are a few functions provided by llvm-libc that are impossible
242+
to reliably implement in C++ for all compilers supported for building
243+
llvm-libc.
244+
245+
We do use inline or out-of-line Assembly in an intentionally minimal set of
246+
places; typically places where the stack or individual register state must be
247+
manipulated very carefully for correctness, or instances where a specific
248+
instruction sequence does not have a corresponding compiler builtin function
249+
today.
250+
251+
Contributions adding functions implemented purely in Assembly for performance
252+
are not welcome.
253+
254+
Contributors should strive to stick with C++ for as long as it remains
255+
reasonable to do so. Ideally, bugs should be filed against compiler vendors,
256+
and links to those bug reports should appear in commit messages or comments
257+
that seek to add Assembly to llvm-libc.
258+
259+
Patches containing any amount of Assembly ideally should be approved by 2
260+
maintainers. llvm-libc maintainers reserve the right to reject Assembly
261+
contributions that they feel could be better maintained if rewritten in C++,
262+
and to revisit this policy in the future.

0 commit comments

Comments
 (0)