Repository navigation
[libc] Major docs refresh - #241609
[libc] Major docs refresh#241609michaelrj-google wants to merge 3 commits into
Conversation
This was made as an attempt to write down as much of what I know about LLVM-libc as possible. The process involved using an LLM agent to interview me about what wasn't clear from the codebase and then write docs based on my answers. After that were several rounds of revisions where I tweaked phrasing and corrected more issues. The final documents are an accurate reflection of my understanding of the state of LLVM-libc. Assisted-by: Automated tooling, human reviewed.
| ```{admonition} Open questions for the math maintainers | ||
| :class: important | ||
|
|
||
| - Is the multiple-implementation scheme (`LIBC_MATH_<FUNC>_IMPL` selecting |
There was a problem hiding this comment.
Yes, the multiple-implementation scheme will be the intended structure for every function.
| - Is the multiple-implementation scheme (`LIBC_MATH_<FUNC>_IMPL` selecting | ||
| among `double_eval`, `float_eval`, and `integer_eval` variants) the intended | ||
| structure for every function? What does each variant promise for accuracy, | ||
| `errno`, exceptions, and signaling NaNs? |
There was a problem hiding this comment.
Once we have more variants implemented, we will have explicit table to document these behaviors from math homepage. OTOH, the default implementations for all math functions are expected to be correctly rounded, and support all errno + exceptions + sNaNs behaviors.
| among `double_eval`, `float_eval`, and `integer_eval` variants) the intended | ||
| structure for every function? What does each variant promise for accuracy, | ||
| `errno`, exceptions, and signaling NaNs? | ||
| - Is `math::static_rounding` the future primary implementation, with the |
There was a problem hiding this comment.
static rounding is only for static rounding use cases like compilers. The primary implementation will be whatever best for that context / config.
| `errno`, exceptions, and signaling NaNs? | ||
| - Is `math::static_rounding` the future primary implementation, with the | ||
| dynamic rounding mode as a wrapper, or a parallel API for compiler use only? | ||
| - Must a new single precision or half precision function pass an exhaustive |
There was a problem hiding this comment.
Yes, implementers are supposed to run all the unit + smoke + exhaustive tests, at least default configurations on their machine (preferably before sending out PRs), and reviewers will need to double check that. Our CIs will try to cover most of the tests and some configs. It's totally ok for implementers to reach out for help if they have problems running or making the tests passed.
| dynamic rounding mode as a wrapper, or a parallel API for compiler use only? | ||
| - Must a new single precision or half precision function pass an exhaustive | ||
| test in all four rounding modes before it is merged, and who runs it? | ||
| - The status tables list double precision `atan` and `atan2` at 1 ULP. Is |
| test in all four rounding modes before it is merged, and who runs it? | ||
| - The status tables list double precision `atan` and `atan2` at 1 ULP. Is | ||
| that an accepted bound or a gap to close? | ||
| - What are the rules for the test data under |
There was a problem hiding this comment.
Those are hard to round cases from the CORE-MATH projects. I'll set up a CI to guarantee the consistency between textual data file and the compact binary file.
There was a problem hiding this comment.
together with instruction when we want to add more hard-to-round cases.
| - **The `File` abstraction.** The Linux implementation is in | ||
| `src/__support/File/`, while the baremetal and GPU implementations are in | ||
| `src/stdio/baremetal/` and `src/stdio/gpu/`. These should share one design. | ||
| - **`src/__support/HashTable/`** needs a cleanup. |
There was a problem hiding this comment.
Besides the implementation style, HashTable's header inclusion and arch specific dispatch should also be cleaned up.
| text and should be renamed for what it contains. | ||
| - **Separation by OS dependence.** See {ref}`code_organization`. | ||
| - **`libc/benchmarks/`** is unmaintained, apart from the GPU benchmarks in | ||
| `libc/benchmarks/gpu/`, and will be removed or rewritten. |
There was a problem hiding this comment.
I remember there is a plan to restructure benchmark parts after @lntue's cmake refactor.
| - **Separation by OS dependence.** See {ref}`code_organization`. | ||
| - **`libc/benchmarks/`** is unmaintained, apart from the GPU benchmarks in | ||
| `libc/benchmarks/gpu/`, and will be removed or rewritten. | ||
| - **`libc/fuzzing/`** is in use but covers less than it should. |
There was a problem hiding this comment.
is centipede/fuzztest like structural mutation still a goal to chase after?
There was a problem hiding this comment.
Also, I think we should default build with sancov for fuzzers. Not sure about internal running ones.
This was made as an attempt to write down as much of what I know about
LLVM-libc as possible. The process involved using an LLM agent to
interview me about what wasn't clear from the codebase and then write
docs based on my answers. After that were several rounds of revisions
where I tweaked phrasing and corrected more issues. The final documents
are an accurate reflection of my understanding of the state of
LLVM-libc.
Assisted-by: Automated tooling, human reviewed.