README.md
1# Hello World
2
3Building embedded applications is tricky in part because of the huge
4number of configuration settings necessary to get something that
5works. This example shows how to use the installed version of
6picolibc, and uses 'make' instead of 'meson' to try and make the
7operations as clear as possible.
8
9## Selecting picolibc headers and C library
10
11Picolibc provides a GCC '.specs' file _(generated from
12picolibc.specs.in)_ which sets the search path for
13header files and picolibc libraries.
14
15 gcc --specs=picolibc.specs
16
17## Semihosting
18
19Our example program wants to display a string to stdout; because there
20aren't drivers for the serial ports emulated by qemu provided, the
21example uses Picolibc's semihosting support
22
23 gcc --specs=picolibc.specs --oslib=semihost
24
25## Target processor
26
27For RISC-V, QEMU offers the same emulation as the "spike" simulator,
28which looks like a SiFive E31 chip (sifive-e31). That's a 32-bit
29processor with the 'imac' options (integer, multiply, atomics,
30compressed) and uses the 'ilp32' ABI (32-bit integer, long and
31pointer):
32
33 riscv64-unknown-elf-gcc --specs=picolibc.specs --oslib-semihost -march=rv32imac -mabi=ilp32
34
35For ARM, QEMU emulates a "mps2-an385" board which has a Cortex-M3
36processor:
37
38 arm-none-eabi-gcc --specs=picolibc.specs --oslib=semihost -mcpu=cortex-m3
39
40## Target Memory Layout
41
42The application needs to be linked at addresses which correspond to
43where the target memories are addressed. The default linker script
44provided with picolibc, `picolibc.ld`, assumes that the target device
45will have two kinds of memory, one for code and read-only data and
46another kind for read-write data. However, the linker script has no
47idea where those memories are placed in the address space. The example
48specifies those by setting a few values before including
49`picolibc.ld`.
50
51For 'spike', you can have as much memory as you like, but execution
52starts at 0x80000000 so the first instruction in the application needs
53to land there. Picolibc on RISC-V puts _start at the first location in
54read-only memory, so we set things up like this (this is
55hello-world-riscv.ld):
56
57 __flash = 0x80000000;
58 __flash_size = 0x00080000;
59 __ram = 0x80080000;
60 __ram_size = 0x40000;
61 __stack_size = 1k;
62
63 INCLUDE picolibc.ld
64
65The mps2-an385 has at least 16kB of flash starting at 0. Picolibc
66places a small interrupt vector there which points at the first
67instruction of _start. The mps2-an385 also has 64kB of RAM starting
68at 0x20000000, so hello-world-arm.ld looks like this:
69
70 __flash = 0x00000000;
71 __flash_size = 0x00004000;
72 __ram = 0x20000000;
73 __ram_size = 0x00010000;
74 __stack_size = 1k;
75
76 INCLUDE picolibc.ld
77
78The `-T` flag is used to specify the linker script in the compile
79line:
80
81 riscv64-unknown-elf-gcc --specs=picolibc.specs --oslib=semihost -march=rv32imac -mabi=ilp32 -Thello-world-riscv.ld
82
83 arm-none-eabi-gcc --specs=picolibc.specs --oslib=semihost -mcpu=cortex-m3 -Thello-world-arm.ld
84
85## Final Commands
86
87The rest of the command line tells GCC what file to compile
88(hello-world.c) and where to put the output (hello-world-riscv.elf and
89hello-world-arm.elf):
90
91 riscv64-unknown-elf-gcc --specs=picolibc.specs --oslib=semihost
92 -march=rv32imac -mabi=ilp32 -Thello-world-riscv.ld -o
93 hello-world-riscv.elf hello-world.c
94
95 arm-none-eabi-gcc --specs=picolibc.specs --oslib=semihost
96 -mcpu=cortex-m3 -Thello-world-arm.ld -o hello-world-arm.elf
97 hello-world.c
98