picolibc - a C library designed for embedded 32- and 64- bit systems.
picolibc - a C library designed for embedded 32- and 64- bit systems.
Copyright © 2018-2023 Keith Packard
Picolibc is library offering standard C library APIs that targets small embedded systems with limited RAM. Picolibc was formed by blending code from Newlib and AVR Libc.
Build status:
Picolibc source comes from a variety of places and has a huge variety of copyright holders and license texts. While much of the code comes from Newlib, none of the GPL-related bits used to build the library are left in the repository, so all of the source code uses BSD-like licenses, a mixture of 2- and 3- clause BSD itself and a variety of other (mostly older) licenses with similar terms.
There are two files used for testing printf, test/printf-tests.c and test/testcases.c which are licensed under the GPL version 2 or later. There is also a shell script, GeneratePicolibcCrossFile.sh which is licensed under the AGPL version 3 or later which is provided as a helper for people building the library, but not used by picolibc otherwise.
The file COPYING.picolibc contains all of the current copyright and license information in the Debian standard machine-readable format. It was generated using the make-copyrights and find-copyright scripts.
Picolibc has integrated testing support for many architectures which is used to validate the code for all patch integration:
There is also build infrastructure and continuous build validation, but no integrated testing available for additional architectures:
Supporting new architectures requires:
Add libc/machine/architecture for architecture-specific libc bits. This should at least include setjmp/longjmp support as these cannot be performed in architecture independent code and are needed by libstdc++. If available, it should also include thread local storage setup code as libc/machine/architecture/tls.c; the build system looks for that file by name when determining if TLS is available.
Checking for atomic support for stdio. Picolibc requires atomics for ungetc to work correctly in a reentrant environment. By default, it stores them in 16-bit values, but some architectures only have 32-bit atomics. To avoid ABI issues, the size selected isn't detected automatically, instead it must be configured in libc/include/stdio.h.
If necessary, add libm/machine/architecture for any architecture-specific math bits
picocrt/machine/architecture source code and build bits for startup code needed for the architecture. Useful in all cases, but this is necessary to run tests under emulation if your platform can do that.
cross-gcc-triple.txt to configure the meson cross-compilation mechanism to use the right tools
do-architecture-configure to make testing the cross-compilation setup easier.
run-architecture script to run tests under QEMU. Look at the ARM and RISC-V examples to get a sense of what this needs to do and how it gets invoked from the cross-gcc-triple.txt configuration file.
Picolibc includes a lot of code originally from newlib. However, it has been reformatted and restructured to make it easier to read and maintain going forward.
Here's a list of some differences between picolibc and newlib:
Designed for and tested on 32- and 64- bit embedded systems. Newlib (and newlib-nano) are used on both embedded systems and Cygwin, with the bulk of the development focused on improving the Cygwin support. Because the Cygwin version needs to be very careful about ABI stability, many parts of the newlib code base are very difficult to change. Picolibc has no such constraints, so much work has been done to improve the ABI and API for use in embedded systems.
Stdio. Picolibc's stdio implementation borrows some code from AVR-Libc along with substantial new code. The goal is to remain compatible with relevant C and POSIX standards while using a very narrow API to the underlying system (it only requires getc and putc) along with doing no internal allocation and using a minimal amount of RAM.
Thread-local-storage support. Instead of creating a large data structure containing all possible thread-specific data, Picolibc uses the underlying TLS support from the compiler which only allocates the amount of per-thread storage needed to support the API called by the application. Typically, this means you use only 4 bytes for errno.
Integrated test suite. Along with dozens of new tests, picolibc includes tests from newlib and musl. These tests are run as a part of the patch review process and new code or bugfixes are expected to include tests that verify functionality and keep bugs from recurring.
Bare-metal startup code and linker scripts for many architectures. These may not support precisely what your application requires, but these provide a good basis for writing your own startup code and linker scripts. These are used to create bare-metal versions of the test suite which can then be run using QEMU.
Meson-based build system. This is largely used to avoid conflicts with the newlib autotools build system files, but a side effect is that the library builds very quickly.
Narrow and well-defined POSIX OS requirements. Portions of Picolibc which require underlying OS support are documented so that you will know which functions are necessary based on the API in use. In particular, picolibc requires no POSIX functions to support stdin/stdout/stderr, and instead requires only functions to get and put single characters to the target device.
Built-in semihosting support for many architectures. This allows you to take advantage of existing gdb, openocd and qemu semihosting support for things like debugging output even before you have a serial port working.
Clear BSD licensing. All non-BSD compatible library source code has been removed so that the status of the resulting library is not in question.
Introductory documentation. Read these first:
Detailed documentation. Use these to learn more details about how to use Picolibc:
Native Linux support on a couple of architectures. This allows building of numerous Linux applications and test cases.
Clean up some picolibc structs that attempted to match native Linux layout. Instead, map the contents at runtime, just like the new native linux syscall support does.
Eliminate off64_t type; off_t is always 64 bits.
Fix iconv to not write partial codepoints to conform to the spec.
vfprintf("%lc") takes a wint_t parameter, not int. This only matters when int is smaller than 32 bits (as on msp430). Make %lc work with a L'\0' value and ignore any specified precision.
Fix some corner cases in vfprintf when wchar_t is 16 bits.
Use an array for strerror instead of a switch statement.
In ARM semihosting, preserve LR register and add an option to use hlt instead of svc for arm arch >= 8 as that's the new recommendation. Thanks to Simi Pallipurath.
Add POSIX group file functions (getgrname et al).
Add vectorized memset, memcpy and memmove for RISC-V. Thanks to Pincheng Wang.
Eliminate recursive locking of libc lock.
Simplify arc4random state and fork detection logic.
Fix possible NULL pointer dereference in the mbrtoc functions. Thanks to Gergely Futo.
Provide semihosting calls for Hexagon. Thanks to Kushal Pal and Zain Siddavatam.
Fix vfprintf_s thread safety analysis warning. Thanks to Brian Cain.
Add clang thread safety analysis annotations for functions which change lock state. Thanks to Brian Cain.
Fix strerror_r to handle missing entries in errnames array. Thanks to mrashad.
Remove --gc-sections from picolibc.specs. This was more important when the vfprintf and vfscanf variants were tied together to avoid pulling in a vfscanf implementation.
Make CI report the detected code formatting errors. Thanks to Kushal Pal.
Add 32-bit vector implementations for memmove, memcpy and memset. Thanks to Abdallah Abdelhafeez.
Fix generic C version of riscv memcpy so the loop only copies 8 elements rather than 9. Thanks to Abdallah Abdelhafeez.
Add fopencookie and open_memstream. Thanks to Alexey Lapshin.
Improve performance of riscv strcmp function by re-ordering instructions. Thanks to Abdallah Abdelhafeez.
Add Hexagon floating point environment support. Thanks to Zain Siddavatam.
Fix bufio lazy lock initialization race. Thanks to Kushal Pal.
Add support for riscv Zcmt extension. Thanks to Sam Elliott.
Fix fflush(NULL) when -Dstdio-exit-flush=true. Thanks to Kushal Pal for finding this bug.
Test arm code using FVP. Thanks to Mark Murray.
Add Hexagon assembly for various memory/string operations. Thanks to Kushal Pal.
Make directory used by various temporary file functions configurable. Use /tmp for the native Linux ports. Thanks to Zain Siddavatam.
Add Hexagon optimized math functions. Thanks to Zain Siddavatam.
Initialize AArch64 SME in picocrt. Thanks to Mark Murray.
Add crt variant that enables riscv zicfilp/zicfiss features. Thanks to Ahmed Shehab.
Add dynamic linking support for Hexagon. Thanks to Kushal Pal.
Add quick_exit and at_quick_exit. Thanks to Kushal Pal.
Fix undefined behavior in floating point printf. Thanks to Alberto Escolar Piedras.
Use __math_inexact to generate FE_INEXACT in several math functions. Thanks to Gergely Futo.
Support riscv '-mlarge' model in asm code.
Initialize riscv vector unit in startup code when present.
Improve arm32 A-profile operation in Thumb state. Thanks to Victor Campos.
Remove duplicate isinf and isnan declarations that were visible even when building with C++. Thanks to Mostafa Salman.
Improve accuracy of cacoshf for real inputs. Thanks to Ahmed Shehab.
Avoid use of float types in vfprintf to avoid unnecessary fpu register use.
Add missing pid_t and getdate_err declarations to time.h.
Implement getdate and getdate_r as required by POSI
No open issues yet, or sync has not completed.