# Darwin Sanitizers Stable ABI
We wish to make it possible to include the AddressSanitizer (ASan) runtime implementation in OSes and for this we need a stable ASan ABI. Based on previous discussions about this topic, our understanding is that freezing the present ABI would impose an excessive burden on other sanitizer developers and for unrelated platforms. Therefore, we propose adding a secondary stable ABI for our use and anyone else in the community seeking the same. We believe that we can define a stable ABI with minimal burden on the community, expecting only to keep existing tests running and implementing stubs when new features are added. We are okay with trading performance for stability with no impact for existing users of ASan while minimizing the maintenance burden for ASan maintainers. We wish to commit this functionality to the LLVM project to maintain it there. This new and stable ABI will abstract away the implementation details allowing new and novel approaches to ASan for developers, researchers and others.
## Details
Rather than adding a lot of conditional code to the LLVM instrumentation phase, which would incur excessive complexity and maintenance cost of adding conditional code into all places that emit a runtime call, we propose a “shim” layer which will map the unstable ABI to the stable ABI:
* A static library (.a library) shim that maps the existing ASan ABI to a generalized, smaller and stable ABI. The library would implement the __asan functions and call into the new ABI. For example:
* `void __asan_load1(uptr p) { __asan_abi_loadn(p, 1, true); }`
* `void __asan_load2(uptr p) { __asan_abi_loadn(p, 2, true); }`
* `void __asan_noabort_load16(uptr p) { __asan_abi_loadn(p, 16, false); }`
* `void __asan_poison_cxx_array_cookie(uptr p) { __asan_abi_pac(p); }`
* This “shim” library would only be used by people who opt in: A compilation flag in the Clang driver will be used to gate the use of the stable ABI workflow.
* Utilize the existing ability for the ASan instrumentation to prefer runtime calls instead of inlined direct shadow memory accesses.
* Pursue (under the new driver flag) a better separation of abstraction and implementation with:
* LLVM instrumentation: Calling out for all poisoning, checking and unpoisoning.
* Runtime: Implementing the stable ABI and being responsible of implementation details of the shadow memory.
## Maintenance
Our aim is that the maintenance burden on the sanitizer developer community be negligible. Stable ABI tests will always pass for non-Darwin platforms. Changes to the existing ABI which would require a change to the shim have been infrequent as the ASan ABI is already relatively stable. Rarely, a change that impacts the contract between LLVM and the shim will occur. Among such foreseeable changes are: 1) changes to a function signature, 2) additions of new functions, or 3) deprecation of an existing function. Following are some examples of reasonable responses to those changes:
* Example: An existing ABI function is changed to return the input parameter on success or NULL on failure. In this scenario, a reasonable change to the shim would be to modify the function signature appropriately and to simply guess at a common-sense implementation.
* `uptr __asan_load1(uptr p) { __asan_abi_loadn(p, 1, true); return p; }`
* Example: An additional function is added for performance reasons. It has a very similar function signature to other similarly named functions and logically is an extension of that same pattern. In this case it would make sense to apply the same logic as the existing entry points:
* `void __asan_load128(uptr p) { __asan_abi_loadn(p, 128, true); }`
* Example: An entry point is added to the existing ABI for which there is no obvious stable ABI implementation: In this case, doing nothing in a no-op stub would be acceptable, assuming existing features of ASan can still work without an actual implementation of this new function.
* `void __asan_prefetch(uptr p) { }`
* Example: An entrypoint in the existing ABI is deprecated and/or deleted:
* (Delete the entrypoint from the shim.)
We’re looking for buy-in for this level of support.
(Note: Upon acceptance of the general concepts herein, we will add a controlling clang flag, cmake integration, contract for the stable ABI, and the appropriate test infrastructure.)
Reviewed By: eugenis, vitalybuka, MaskRay
Differential Revision: https://reviews.llvm.org/D143675
We held off on this before as `LLVM_LIBDIR_SUFFIX` conflicted with it.
Now we return this.
`LLVM_LIBDIR_SUFFIX` is kept as a deprecated way to set
`CMAKE_INSTALL_LIBDIR`. The other `*_LIBDIR_SUFFIX` are just removed
entirely.
I imagine this is too potentially-breaking to make LLVM 15. That's fine.
I have a more minimal version of this in the disto (NixOS) patches for
LLVM 15 (like previous versions). This more expansive version I will
test harder after the release is cut.
Reviewed By: sebastian-ne, ldionne, #libc, #libc_abi
Differential Revision: https://reviews.llvm.org/D130586
This is a second attempt at D101497, which landed as
9a9bc76c0eb72f0f2732c729a460abbd5239c2e3 but had to be reverted in
8cf7ddbdd4e5af966a369e170c73250f2e3920e7.
This issue was that in the case that `COMPILER_RT_INSTALL_PATH` is
empty, expressions like "${COMPILER_RT_INSTALL_PATH}/bin" evaluated to
"/bin" not "bin" as intended and as was originally.
One solution is to make `COMPILER_RT_INSTALL_PATH` always non-empty,
defaulting it to `CMAKE_INSTALL_PREFIX`. D99636 adopted that approach.
But, I think it is more ergonomic to allow those project-specific paths
to be relative the global ones. Also, making install paths absolute by
default inhibits the proper behavior of functions like
`GNUInstallDirs_get_absolute_install_dir` which make relative install
paths absolute in a more complicated way.
Given all this, I will define a function like the one asked for in
https://gitlab.kitware.com/cmake/cmake/-/issues/19568 (and needed for a
similar use-case).
---
Original message:
Instead of using `COMPILER_RT_INSTALL_PATH` through the CMake for
complier-rt, just use it to define variables for the subdirs which
themselves are used.
This preserves compatibility, but later on we might consider getting rid
of `COMPILER_RT_INSTALL_PATH` and just changing the defaults for the
subdir variables directly.
---
There was a seaming bug where the (non-Apple) per-target libdir was
`${target}` not `lib/${target}`. I suspect that has to do with the docs
on `COMPILER_RT_INSTALL_PATH` saying was the library dir when that's no
longer true, so I just went ahead and fixed it, allowing me to define
fewer and more sensible variables.
That last part should be the only behavior changes; everything else
should be a pure refactoring.
---
I added some documentation of these variables too. In particular, I
wanted to highlight the gotcha where `-DSomeCachePath=...` without the
`:PATH` will lead CMake to make the path absolute. See [1] for
discussion of the problem, and [2] for the brief official documentation
they added as a result.
[1]: https://cmake.org/pipermail/cmake/2015-March/060204.html
[2]: https://cmake.org/cmake/help/latest/manual/cmake.1.html#options
In 38b2dec37ee735d5409148e71ecba278caf0f969 the problem was somewhat
misidentified and so `:STRING` was used, but `:PATH` is better as it
sets the correct type from the get-go.
---
D99484 is the main thrust of the `GnuInstallDirs` work. Once this lands,
it should be feasible to follow both of these up with a simple patch for
compiler-rt analogous to the one for libcxx.
Reviewed By: phosek, #libc_abi, #libunwind
Differential Revision: https://reviews.llvm.org/D105765
