This is an archive of the discontinued LLVM Phabricator instance.

Differential D136016

[libc][cleanup] Docs clean up
ClosedPublic

Authored by jeffbailey on Oct 15 2022, 5:34 AM.

Details

Reviewers
sivachandra
Commits
rG998d1ebb2754: [libc][cleanup] Docs clean up
Summary
  • Make consistent heading names
  • Factor out |check| into an include for reuse
  • Use it everywhere (No more YES or UTF-8)
  • Remove unneeded summary from pages. People know why they're there.
  • Ensure source location headers everywhere.

Diff Detail

Event Timeline

jeffbailey created this revision.Oct 15 2022, 5:34 AM
Herald added projects: Restricted Project, Restricted Project. · View Herald TranscriptOct 15 2022, 5:34 AM
Herald added subscribers: libc-commits, ecnelises, tschuett. · View Herald Transcript
jeffbailey requested review of this revision.Oct 15 2022, 5:34 AM
jeffbailey added a reviewer: sivachandra.Oct 15 2022, 5:35 AM
Harbormaster completed remote builds in B192343: Diff 468011.Oct 15 2022, 5:39 AM
This revision was not accepted when it landed; it landed in state Needs Review.Oct 15 2022, 8:30 AM
Closed by commit rG998d1ebb2754: [libc][cleanup] Docs clean up (authored by jeffbailey). · Explain Why
This revision was automatically updated to reflect the committed changes.
jeffbailey added a commit: rG998d1ebb2754: [libc][cleanup] Docs clean up.

Revision Contents

PathSize
libc/
docs/
6 lines
63 lines
27 lines
39 lines
100 lines

Diff 468011

libc/docs/check.rst

  • This file was added.
.. role:: raw-html(raw)
:format: html
.. |check| replace:: :raw-html:`&#x2705`

libc/docs/date_and_time.rst

============= =======================
Date and Time Date and Time Functions
============= =======================
============= === .. include:: check.rst
---------------
Source location
---------------
- The main source for string functions is located at:
``libc/src/time``
---------------------
Implementation Status
---------------------
============= =======
Function_Name C99 Function_Name C99
============= === ============= =======
clock clock
mktime ✅ mktime |check|
time time
asctime ✅ asctime |check|
ctime ctime
gmtime ✅ gmtime |check|
localtime localtime
strftime strftime
============= === ============= =======
=================== ===== =================== =======
Function_Name POSIX Function_Name POSIX
=================== ===== =================== =======
asctime ✅ asctime |check|
asctime_r ✅ asctime_r |check|
clock clock
clock_getcpuclockid clock_getcpuclockid
clock_getres clock_getres
clock_gettime ✅ clock_gettime |check|
clock_nanosleep clock_nanosleep
clock_settime clock_settime
ctime ctime
ctime_r ctime_r
difftime difftime
getdate getdate
gmtime ✅ gmtime |check|
gmtime_r ✅ gmtime_r |check|
localtime localtime
localtime_r localtime_r
mktime ✅ mktime |check|
nanosleep ✅ nanosleep |check|
strftime strftime
strptime strptime
time time
timer_create timer_create
timer_delete timer_delete
timer_gettime timer_gettime
timer_getoverrun timer_getoverrun
timer_settime timer_settime
tzset tzset
=================== ===== =================== =======

libc/docs/math.rst

=========================== ==============
Math Functions in LLVM-libc Math Functions
=========================== ==============
.. role:: raw-html(raw) .. include:: check.rst
:format: html
.. |check| replace:: :raw-html:`&#x2705`
.. contents:: Table of Contents .. contents:: Table of Contents
:depth: 4 :depth: 4
:local: :local:
Summary Source Locations
======= ================
* This document tracks the status of the implementation of math functions in - The main source is located at: `libc/src/math <https://github.com/llvm/llvm-project/tree/main/libc/src/math>`_.
LLVM libc. - The tests are located at: `libc/test/src/math <https://github.com/llvm/llvm-project/tree/main/libc/test/src/math>`_.
- The floating point utilities are located at: `libc/src/__support/FPUtil <https://github.com/llvm/llvm-project/tree/main/libc/src/__support/FPUtil>`_.
Implementation Requirements / Goals Implementation Requirements / Goals
=================================== ===================================
* The highest priority is to be as accurate as possible, according to the C and * The highest priority is to be as accurate as possible, according to the C and
IEEE 754 standards. By default, we will aim to be correctly rounded for `all rounding modes <https://en.cppreference.com/w/c/numeric/fenv/FE_round>`_. IEEE 754 standards. By default, we will aim to be correctly rounded for `all rounding modes <https://en.cppreference.com/w/c/numeric/fenv/FE_round>`_.
The current rounding mode of the floating point environment is used to perform The current rounding mode of the floating point environment is used to perform
computations and produce the final results. computations and produce the final results.
Show All 16 Lines - Platform-specific implementations or instructions could be added whenever it
makes sense and provides significant performance boost. makes sense and provides significant performance boost.
* For other use cases that have strict requirements on the code size, memory * For other use cases that have strict requirements on the code size, memory
footprint, or latency, such as embedded systems, we will aim to be as accurate footprint, or latency, such as embedded systems, we will aim to be as accurate
as possible within the memory or latency budgets, and consistent across all as possible within the memory or latency budgets, and consistent across all
platforms. platforms.
Source Locations
================
- The main source is located at: `libc/src/math <https://github.com/llvm/llvm-project/tree/main/libc/src/math>`_.
- The tests are located at: `libc/test/src/math <https://github.com/llvm/llvm-project/tree/main/libc/test/src/math>`_.
- The floating point utilities are located at: `libc/src/__support/FPUtil <https://github.com/llvm/llvm-project/tree/main/libc/src/__support/FPUtil>`_.
Add a new math function to LLVM libc Add a new math function to LLVM libc
==================================== ====================================
* To add a new math function, follow the steps at: `libc/src/math/docs/add_math_function.md <https://github.com/llvm/llvm-project/tree/main/libc/src/math/docs/add_math_function.md>`_. * To add a new math function, follow the steps at: `libc/src/math/docs/add_math_function.md <https://github.com/llvm/llvm-project/tree/main/libc/src/math/docs/add_math_function.md>`_.
Implementation Status Implementation Status
===================== =====================
▲ Show 20 Lines • Show All 202 Lines • Show Last 20 Lines

libc/docs/stdio.rst

============================= ===============
StdIO Functions in LLVM-libc StdIO Functions
============================= ===============
-------
Summary
-------
This document tracks the status of the implementation of stdio functions in LLVM .. include:: check.rst
Libc.
--------------- ---------------
Source location Source location
--------------- ---------------
- The main source for string functions is located at: - The main source for string functions is located at:
``libc/src/stdio`` with subdirectories for internal implementations. ``libc/src/stdio`` with subdirectories for internal implementations.
Show All 20 Lines
These functions are used to interact with the ``FILE`` object type, which is an These functions are used to interact with the ``FILE`` object type, which is an
I/O stream, often used to represent a file on the host's hard drive. Currently I/O stream, often used to represent a file on the host's hard drive. Currently
the ``FILE`` object is only available on linux. the ``FILE`` object is only available on linux.
============= ========= ============= =========
Function_Name Available Function_Name Available
============= ========= ============= =========
fopen YES fopen |check|
freopen freopen
fclose YES fclose |check|
fflush YES fflush |check|
setbuf setbuf
setvbuf setvbuf
ftell ftell
fgetpos fgetpos
fseek YES fseek |check|
fsetpos fsetpos
rewind rewind
tmpfile tmpfile
clearerr YES clearerr |check|
feof YES feof |check|
ferror YES ferror |check|
flockfile YES flockfile |check|
funlockfile YES funlockfile |check|
============= ========= ============= =========
Operations on system files Operations on system files
========================== ==========================
These functions operate on files on the host's system, without using the These functions operate on files on the host's system, without using the
``FILE`` object type. They only take the name of the file being operated on. ``FILE`` object type. They only take the name of the file being operated on.
============= ========= ============= =========
Function_Name Available Function_Name Available
============= ========= ============= =========
remove YES remove |check|
rename rename
tmpnam tmpnam
============= ========= ============= =========
Unformatted ``FILE`` Input/Output Functions Unformatted ``FILE`` Input/Output Functions
=========================================== ===========================================
The ``gets`` function was removed in C11 for having no bounds checking and The ``gets`` function was removed in C11 for having no bounds checking and
therefor being impossible to use safely. therefor being impossible to use safely.
============= ========= ============= =========
Function_Name Available Function_Name Available
============= ========= ============= =========
(f)getc (f)getc
fgets fgets
getchar getchar
fread YES fread |check|
(f)putc (f)putc
(f)puts YES (f)puts |check|
putchar putchar
fwrite YES fwrite |check|
ungetc ungetc
============= ========= ============= =========

libc/docs/strings.rst

============================= ================
String Functions in LLVM-libc String Functions
============================= ================
------- .. include:: check.rst
Summary
-------
This site tracks the status of the implementation of string functions in LLVM
Libc. This includes a few extra functions that are not in string.h, such as
functions converting strings to numbers.
--------------- ---------------
Source location Source location
--------------- ---------------
- The main source for string functions is located at: - The main source for string functions is located at:
``libc/src/string``. ``libc/src/string``.
Show All 15 Lines
======================== ========================
.. TODO(gchatelet): add details about the memory functions. .. TODO(gchatelet): add details about the memory functions.
============= ========= ============= =========
Function Name Available Function Name Available
============= ========= ============= =========
bzero YES bzero |check|
bcmp YES bcmp |check|
memcpy YES memcpy |check|
memset YES memset |check|
memcmp YES memcmp |check|
memmove YES memmove |check|
============= ========= ============= =========
Other Raw Memory Functions Other Raw Memory Functions
========================== ==========================
============= ========= ============= =========
Function Name Available Function Name Available
============= ========= ============= =========
memchr YES memchr |check|
memrchr YES memrchr |check|
memccpy YES memccpy |check|
mempcpy YES mempcpy |check|
============= ========= ============= =========
String Memory Functions String Memory Functions
======================= =======================
============= ========= ============= =========
Function Name Available Function Name Available
============= ========= ============= =========
stpcpy YES stpcpy |check|
stpncpy YES stpncpy |check|
strcpy YES strcpy |check|
strncpy YES strncpy |check|
strcat YES strcat |check|
strncat YES strncat |check|
strdup YES strdup |check|
strndup YES strndup |check|
============= ========= ============= =========
String Examination Functions String Examination Functions
============================ ============================
============= ========= ============= =========
Function Name Available Function Name Available
============= ========= ============= =========
strlen YES strlen |check|
strnlen YES strnlen |check|
strcmp YES strcmp |check|
strncmp YES strncmp |check|
strchr YES strchr |check|
strrchr YES strrchr |check|
strspn YES strspn |check|
strcspn YES strcspn |check|
strpbrk YES strpbrk |check|
strstr YES strstr |check|
strtok YES strtok |check|
strtok_r YES strtok_r |check|
============= ========= ============= =========
String Conversion Functions String Conversion Functions
============================ ============================
These functions are not in strings.h, but are still primarily string These functions are not in strings.h, but are still primarily string
functions, and are therefore tracked along with the rest of the string functions, and are therefore tracked along with the rest of the string
functions. functions.
The String to float functions were implemented using the Eisel-Lemire algorithm The String to float functions were implemented using the Eisel-Lemire algorithm
(read more about the algorithm here: `The Eisel-Lemire ParseNumberF64 Algorithm (read more about the algorithm here: `The Eisel-Lemire ParseNumberF64 Algorithm
<https://nigeltao.github.io/blog/2020/eisel-lemire.html>`_). This improved <https://nigeltao.github.io/blog/2020/eisel-lemire.html>`_). This improved
the performance of string to float and double, and allowed it to complete this the performance of string to float and double, and allowed it to complete this
comprehensive test 15% faster than glibc: `Parse Number FXX Test Data comprehensive test 15% faster than glibc: `Parse Number FXX Test Data
<https://github.com/nigeltao/parse-number-fxx-test-data>`_. The test was done <https://github.com/nigeltao/parse-number-fxx-test-data>`_. The test was done
with LLVM-libc built on 2022-04-14 and Debian GLibc version 2.33-6. The targets with LLVM-libc built on 2022-04-14 and Debian GLibc version 2.33-6. The targets
``libc_str_to_float_comparison_test`` and ``libc_str_to_float_comparison_test`` and
``libc_system_str_to_float_comparison_test`` were built and run on the test data ``libc_system_str_to_float_comparison_test`` were built and run on the test data
10 times each, skipping the first run since it was an outlier. 10 times each, skipping the first run since it was an outlier.
============= ========= ============= =========
Function Name Available Function Name Available
============= ========= ============= =========
atof YES atof |check|
atoi YES atoi |check|
atol YES atol |check|
atoll YES atoll |check|
strtol YES strtol |check|
strtoll YES strtoll |check|
strtoul YES strtoul |check|
strtoull YES strtoull |check|
strtof YES strtof |check|
strtod YES strtod |check|
strtold YES strtold |check|
strtoimax YES strtoimax |check|
strtoumax YES strtoumax |check|
============= ========= ============= =========
String Error Functions String Error Functions
====================== ======================
============= ========= ============= =========
Function Name Available Function Name Available
============= ========= ============= =========
Show All 30 Lines