README.md
1# PicoLibc
2Copyright © 2018,2019 Keith Packard
3
4PicoLibc is library offering standard C library APIs that targets
5small embedded systems with limited RAM. PicoLibc was formed by blending
6code from [Newlib](http://sourceware.org/newlib/) and
7[AVR Libc](https://www.nongnu.org/avr-libc/).
8
9## License
10
11Picolibc source comes from a variety of places and has a huge variety
12of copyright holders and license texts. While much of the code comes
13from newlib, none of the GPL-related bits are left in the repository,
14so all of the source code uses BSD-like licenses, a mixture of 2- and
153- clause BSD itself and a variety of other (mostly older) licenses
16with similar terms.
17
18Please see the file COPYING.NEWLIB in this distribution for newlib
19license terms.
20
21## Supported Architectures
22
23Picolibc inherited code for a *lot* of architectures from newlib, but
24at this point only has code to build for the following targets:
25
26 * ARM (32-bit only)
27 * i386 (Linux hosted, for testing)
28 * RISC-V (both 32- and 64- bit)
29 * x86_64 (Linux hosted, for testing)
30 * PowerPC
31 * ESP8266 (xtensa-lx106-elf)
32
33Supporting architectures that already have newlib code requires:
34
35 1. newlib/libc/machine/_architecture_/meson.build to build any
36 architecture-specific libc bits
37 2. newlib/libm/machine/_architecture_/meson.build to build any
38 architecture-specific libm bits
39 3. picocrt/machine/_architecture_ source code and build bits if
40 you need custom startup code for the architecture.
41 4. cross-_gcc-triple_.txt to configure the meson cross-compilation
42 mechanism to use the right tools
43 5. do-_architecture_-configure to make testing the cross-compilation
44 setup easier.
45
46## Relation to newlib
47
48Picolibc is mostly built from pieces of newlib, and retains the
49directory structure of that project. While there have been a lot of
50changes in the build system and per-thread data storage, the bulk of
51the source code remains unchanged.
52
53To keep picolibc and newlib code in sync, newlib changes will be
54regularly incorporated. To ease integration of these changes into
55picolibc, some care needs to be taken while editing the code:
56
57 * Files should not be renamed.
58 * Fixes that also benefit users of newlib should also be sent to the
59 newlib project
60 * Changes, where possible, should be made in a way compatible with
61 newlib design. For example, instead of using 'errno' (which is
62 valid in picolibc), use __errno_r(r), even when 'r' is not defined
63 in the local context.
64
65The bulk of newlib changes over the last several years have been in
66areas unrelated to the code used by picolibc, so keeping things in
67sync has not been difficult so far.
68
69## Releases
70
71### Picolibc version 1.3
72
73This release now includes tests, and fixes bugs found by them.
74
75 1. ESP8266 support added, thanks to Jonathan McDowell.
76
77 2. Numerous test cases from newlib have been fixed, and
78 precision requirements adjusted so that the library now
79 passes its own test suite on x86, RISC-V and ARM.
80
81 3. String/number conversion bug fixes. This includes fcvt/ecvt/gcvt
82 shared with newlib and tinystdio printf/scanf
83
84 4. A few RISC-V ABI fixes, including setting the TLS base correctly,
85 compiling with -mcmodel=medany, and enabling the FPU for libraries
86 built to use it.
87
88 5. Semihosting updates, including adding unlink, kill and getpid
89 (which are used by some tests).
90
91### Picolibc version 1.2
92
93This release includes important fixes in picolibc.ld and more
94semihosting support.
95
96 1. File I/O and clock support for semihosting. This enables fopen/fdopen
97 support in tinystdio along with an API to fetch a real time clock
98 value.
99
100 2. Fix picolibc.ld to not attempt to use redefined symbols for memory
101 space definitions. These redefinitions would fail and the default
102 values be used for system memory definitions. Instead, just use
103 the ? : operators each place the values are needed. Linker scripts
104 continue to mystify.
105
106 3. Expose library definitions in 'picolibc.h', instead of 'newlib.h'
107 and '_newlib_version.h'
108
109 4. Define HAVE_SEMIHOST when semihosting support is available. This
110 lets the 'hello-world' example do some semihost specific things.
111
112### Picolibc version 1.1
113
114A minor update from 1.0, this release includes:
115
116 1. semihost support. This adds console I/O and exit(3) support on ARM
117 and RISC-V hosts using the standard semihosting interfaces.
118
119 2. Posix I/O support in tinystdio. When -Dposix-io=true is included
120 in the meson command line (which is the default), tinystdio adds
121 support for fopen and fdopen by using malloc, open, close, read,
122 write and lseek. If -Dposix-console=true is also passed to meson,
123 then picolibc will direct stdin/stdout/stderr to the posix
124 standard file descriptors (0, 1, 2).
125
126 3. Merge recent upstream newlib code. This brings picolibc up to date
127 with current newlib sources.
128
129 4. Hello world example. This uses a simple Makefile to demonstrate
130 how to us picolibc when installed for ARM and RISC-V embedded
131 processors. The resulting executables can be run under qemu.
132
133 5. Remove newlib/libm/mathfp directory. This experimental code never
134 worked correctly anyways.
135
136### Picolibc version 1.0
137
138This is the first release of picolibc. Major changes from newlib
139include:
140
141 1. Remove all non-BSD licensed code. None of it was used in building
142 the embedded library, and removing it greatly simplifies the
143 license situation.
144
145 2. Move thread-local values to native TLS mechanism
146
147 3. Add smaller stdio from avr-libc, which is enabled by default
148
149 4. Switch build system to meson. This has two notable benefits; the first
150 is that building the library is much faster, the second is that
151 it isolates build system changes from newlib making merging of
152 newlib changes much easier.
153
154 5. Add simple startup code. This can be used in environments that
155 don't have complicated requirements, allowing small applications
156 to avoid needing to figure this out.
157
158## Documentation
159
160 * [Building Picolibc](doc/build.md)
161 * [Operating System Support](doc/os.md)
162 * [Using Picolibc](doc/using.md)
163 * [Picolibc initialization](doc/init.md)
164 * [Thread Local Storage](doc/tls.md)
165 * [Linking with Picolibc.ld](doc/linking.md)
166 * [Hello World](hello-world/README.md)
167 * [Picolibc as embedded source](doc/embedsource.md)
168