One step to a board: zeno build --board
zeno build --board boards/qemu-cortex-m3 examples/blink.zeno
Wrote blink.c
Built blink.elf for the board in `boards/qemu-cortex-m3`.
Run it with: qemu-system-arm -M lm3s6965evb -nographic -semihosting -kernel blink.elf
blink.elf is a program for an ARM Cortex-M3: the code for its flash,
with the table of vectors at the front. One command made it from a
.zeno file. This page says what that command does, what a board's
folder holds, how to try it with no hardware, and how to write the
folder for a board of your own. The reasons are in chapter 51 of
decisions.md.
Until now zeno build wrote C and compiled it for the computer it ran
on. Building the same C for a chip was a second command, typed by
hand, with the chip's compiler, a dozen flags, a startup file and a
linker script on it (board.md). Those four things are
the same for every program on one board. So they are written down
once, in a folder, and --board names the folder.
What the command does
- It reads
zeno.boardin the folder, and says what is wrong with it before anything else happens. - It checks the program and writes its C, exactly as
zeno build --no-collectordoes: the C for a chip, with a pool of a fixed size and no garbage collector (no-collector.md).--boardchanges nothing in the C. It changes who compiles it. - It runs the board's compiler once, on the program's C and the
board's own files, with the board's flags and linker script. Out
comes
<name>.elf. - It shows the command that runs the program, if the board gives one.
--minimal, --release, --fast and --memory go with it and mean
what they always mean. --collector, --llvm, --web and --target
are refused, each with its reason.
A board is a folder
boards/qemu-cortex-m3/
zeno.board what the compiler is asked
startup.c what runs before `main`, and the clock
system.c what the C library asks of a system
link.ld where the chip's flash and RAM are
zeno.board is read as a zeno.package is: a # starts a comment,
and text is in quotes. This is the whole file of the emulated board,
without its comments:
about "An ARM Cortex-M3 that QEMU emulates (its machine lm3s6965evb)"
compiler "arm-none-eabi-gcc"
flags "-mcpu=cortex-m3" "-mthumb"
flags "-ffunction-sections" "-fdata-sections"
flags "-D_POSIX_TIMERS=1" "-D_POSIX_MONOTONIC_CLOCK=1"
sources "startup.c" "system.c"
script "link.ld"
link "-nostartfiles" "-Wl,--gc-sections"
run "qemu-system-arm" "-M" "lm3s6965evb" "-nographic" "-semihosting" "-kernel"
| Line | What it says | How often |
|---|---|---|
compiler "arm-none-eabi-gcc" |
The C compiler for the board's processor | once, and it must be there |
flags "..." "..." |
What the compiler is told every time: which processor, which floating point | any number of lines |
header "board.h" |
The header with the board's own functions (board.md). With none, the program gets the simulated board |
once at most |
sources "startup.c" |
Files of C that are built with every program | any number of lines |
script "link.ld" |
The linker script | once at most |
link "..." |
What the compiler is told only when it links | any number of lines |
run "..." "..." |
The command that runs a built program, or loads it onto the board | once at most |
about "..." |
Which board this is, in one line | once at most |
Each word in quotes is one word of the command, so a path with a
space in it needs nothing special. A file (header, sources,
script) is named as it is in the board's folder, wherever the
command is typed. A file that is named and is not there is said before
anything is built.
From that file and blink.zeno, the compiler is asked this:
arm-none-eabi-gcc -O2 \
-mcpu=cortex-m3 -mthumb -ffunction-sections -fdata-sections \
-D_POSIX_TIMERS=1 -D_POSIX_MONOTONIC_CLOCK=1 \
-Iboards/qemu-cortex-m3 \
-o blink.elf blink.c \
boards/qemu-cortex-m3/startup.c boards/qemu-cortex-m3/system.c \
-T boards/qemu-cortex-m3/link.ld \
-nostartfiles -Wl,--gc-sections \
-I. -lm
The order gives the board the last word. Zeno's own flag comes first
(-O2, or -Os with --minimal), so a board that says flags "-Os"
gets -Os. The board's folder is on the path of headers (-I), so
its header and its sources can include what lies beside them. With a
header line, -DZENO_BOARD="board.h" is there too. What the program
itself brings comes last: the libraries of C it declares with
import c (c.md), and -lm.
The last word of the run line's command is the program. A tool that
wants it elsewhere says where with {program}:
run "openocd" "-f" "board/st_nucleo_f1.cfg" "-c" "program {program} verify reset exit"
zeno build shows that command and does not run it. Loading a
program onto a board changes the board, and that stays a step you
take.
Try it with no hardware
QEMU emulates a whole board with a Cortex-M3 on it, the Stellaris
LM3S6965 evaluation board: 256 KB of flash, 64 KB of RAM, serial
ports, timers. Zeno's folder for it is
boards/qemu-cortex-m3. It needs the
compiler for ARM chips and QEMU. On Debian and Ubuntu:
sudo apt-get install gcc-arm-none-eabi libnewlib-arm-none-eabi qemu-system-arm
Then, in a copy of Zeno's repository, or in the folder an archive of a
release unpacks to, which has boards/ since 0.7.0 (install.sh puts
it in ~/.zeno/boards; the setup program for Windows and the packages
of apt, pacman, snap, flatpak and Homebrew do not carry it yet):
zeno build --board boards/qemu-cortex-m3 examples/signal.zeno
qemu-system-arm -M lm3s6965evb -nographic -semihosting -kernel signal.elf
pin 2 on
led on
pin 2 off
pin 4 on
led off
...
(Ctrl-A, then X, leaves QEMU when a program runs for ever.)
This board has no header line, so its pins are the simulated ones: a
line of text for each change, as under zeno run
(board.md). The text comes out of the chip's first
serial port, which QEMU joins to the terminal. Everything else is
real: the code is ARM code, an int of the program is 64 bits on a
processor of 32, there is no floating point in the processor, the
clock is the chip's SysTick timer counting milliseconds from an
interrupt, and the memory is 64 KB.
What the three files of C and the script do:
link.ldsays where the flash and the RAM are, puts the table of vectors first in the flash, and gives names to the ends of the variables so that the other two files can find them.startup.cis what the processor runs first. It copies the first values of the variables from flash to RAM, clears the rest, starts the timer, and callsmain. Whenmainreturns it callsexit.system.chas the few functions the C library (newlib) leaves to a system: write these bytes (to the serial port), read a byte (from it), givemallocmore memory, and stop. On this board "stop" tells the debugger that holds the chip, which is QEMU, and QEMU ends with the program's own answer: 0, or 1 after an error nothing caught. The message of such an error goes to the debugger too, and QEMU writes it to the terminal's error stream.
How much of the chip a program takes, in bytes, as
python3 tools/board.py --sizes measures it:
| program | flash | flash, --minimal |
RAM | RAM, --minimal |
|---|---|---|---|---|
hello.zeno |
9,472 | 9,432 | 1,756 | 1,756 |
buffer.zeno |
15,888 | 13,776 | 35,700 | 35,692 |
primes.zeno |
16,172 | 14,876 | 35,684 | 2,800 |
thermostat.zeno |
17,760 | 15,516 | 35,704 | 35,676 |
tour.zeno |
22,000 | 19,648 | 35,724 | 35,716 |
blink.zeno |
29,984 | 29,904 | 2,184 | 2,184 |
signal.zeno |
31,016 | 30,800 | 2,240 | 2,240 |
doorbell.zeno |
32,280 | 31,464 | 36,144 | 3,260 |
tachometer.zeno |
33,488 | 32,144 | 36,896 | 4,012 |
A program that makes a list or an object, or builds text, has the pool
and the room for text in its RAM, about 34 KB together, whose sizes
are fixed when the program is built (pool.md). Since
0.8.0 --pool and --text-room choose them, as in zeno build --board
boards/qemu-cortex-m3 --pool 4096 examples/primes.zeno
(pool-size.md). A program with neither, like blink.zeno, takes 2 KB. Most of the flash of a
small program on this board is the C library: its streams are 8 KB of
hello.zeno, and printf is 20 KB more for a program that drives a
simulated pin (blink.zeno and the three after it: a simulated pin
prints with printf). Zeno's own print does not call printf, in
the minimal build for a board either, and a number with a fraction is
made into text by the runtime itself (decision 53): primes.zeno,
which shows one, was 33,032 bytes when snprintf did that.
The same chip, on its own registers
boards/qemu-cortex-m3 leans on two things a real board may not
have: a whole C library under the program, and pins that are only
text. boards/lm3s6965evb is the same chip
without either. It has a header line, and its board.h is the board
layer written for real (board.md):
zeno build --board boards/lm3s6965evb examples/hello.zeno
qemu-system-arm -M lm3s6965evb -nographic -semihosting -kernel hello.elf
- A pin is a bit of one of the chip's seven ports. Pins 0 to 7 are
PA0 to PA7, and so on to 48 to 55 for port G.
ledis PF0, where the board's LED is.pin(3).on()gives port A its clock, makes PA3 an output and writes its bit, through the registers the data sheet names. - The clock is the SysTick timer, and
sleepputs the processor to sleep between its ticks. serial(0, ...)toserial(2, ...)are UART0 to UART2.printgoes out of UART0, and the header does it: the line#define ZENO_BOARD_PRINTSand four functions (decision 52). A warning and the message of an error go to the debugger, and so does the end of the program. There is noprintf, no stream and noexitanywhere in the program, andstartup.chas nosystem.cbeside it.
QEMU emulates those registers, so the program runs with no hardware, and that is the only place this folder has run. It has never run on the chip itself. What QEMU does not emulate (a pull-up, the speed of a UART, the clocks of the ports) is written from the data sheet and has been tried nowhere.
What that buys, in bytes of flash and of RAM, for the build that checks:
| program | flash on qemu-cortex-m3 |
flash on lm3s6965evb |
RAM on lm3s6965evb |
|---|---|---|---|
hello.zeno |
9,472 | 936 | 20 |
blink.zeno |
29,984 | 3,996 | 20 |
signal.zeno |
31,016 | 4,844 | 76 |
buffer.zeno |
15,888 | 7,464 | 33,968 |
primes.zeno |
16,172 | 7,884 | 33,952 |
modbus.zeno |
14,452 | 9,720 | 35,656 |
words.zeno |
18,704 | 10,408 | 33,980 |
tour.zeno |
22,000 | 14,032 | 34,608 |
A program carries of the C library memcpy, memset, strlen and
their like, and the functions of math it calls. A number with a
fraction is made into text, and read out of text, by Zeno's own
runtime with whole numbers (decision 53): that is 1 to 4 KB of flash,
where the C library's snprintf and strtod were 28 KB. primes.zeno
shows one such number and was 25,360 bytes on lm3s6965evb before.
The sums on floats themselves are the compiler's, some 3 KB on a chip
with no floating point of its own.
A folder for your own board
- Start from the vendor's project. The compiler, the flags, the
startup file and the linker script of a chip come with its vendor's
package (STM32Cube, the nRF SDK, MCUXpresso), or from a project
that already builds for the board. Copy the startup file and the
linker script into a new folder, and copy the flags from the
project's build line into
flagsandlink. - Say where
printgoes. Either give the C library its few functions, assystem.cofboards/qemu-cortex-m3does, unless the vendor's package has them (often a file calledsyscalls.c):printthen goes wherever_writesends it. Or let the board print by itself, asboard.hofboards/lm3s6965evbdoes: one line and four functions in the header, and noprintfin the program (board.md). The second is far smaller. - Write the header with the board's functions, four for pins and
a clock and more for what the program uses
(
board.md, and the pages of each part:inputs.md,serial.md,analog.md,pwm.md,interrupts.md). Name it withheader "board.h". The vendor's own C can be listed undersources. - Say how a program is loaded, in
run. - If the compiler is neither GCC nor Clang, the C still builds:
it is given its checks in plain C without being asked
(
plain-c.md).zeno build --boardtypes a command of the shape GCC takes, so for a compiler with another shape name a script of your own as thecompiler. That has not been tried.
A zeno.board for an ST Nucleo-F103RB would look like this. It is
a sketch: it has not been run on hardware, as nothing in Zeno has
yet (missing.md).
about "ST Nucleo-F103RB (STM32F103RB, Cortex-M3)"
compiler "arm-none-eabi-gcc"
flags "-mcpu=cortex-m3" "-mthumb" "-DSTM32F103xB" "-Os"
flags "-ffunction-sections" "-fdata-sections"
header "board.h"
sources "startup_stm32f103xb.s" "system_stm32f1xx.c" "syscalls.c"
script "STM32F103RBTx_FLASH.ld"
link "--specs=nano.specs" "-u" "_printf_float" "-Wl,--gc-sections"
run "openocd" "-f" "board/st_nucleo_f1.cfg" "-c" "program {program} verify reset exit"
A board need not be a chip. The smallest zeno.board is one line,
compiler "cc", and builds the program for the computer itself, with
no collector, as program.elf.
What a board does not have
A program is built for a board with no collector, so it is held to
the rules of no-collector.md: every list and
object has one owner. The garbage collector takes its memory from the
system 64 KB at a time, which is right for a computer and wrong for a
chip with 64 KB in all, so --collector is refused with --board.
The emulated board has no files, nobody types words after a program's
name, and a serial port has no end: a program that reads what is
typed until there is no more waits there for ever. Zeno does not
refuse such a program. files.read raises its FileError, as for a
file that is not there.
A board that prints by itself (ZENO_BOARD_PRINTS) has no printf
and no exit under the program, and no snprintf under a float.
--memory does not go with such a board yet: the report is written
as the C library ends a program (missing.md). The
text of one statement has 1,024 bytes in a build with no collector,
unless --text-room says otherwise
(pool-size.md), and the largest float written
with decimals, f"{x:.2f}" of 1e308, is 312 of them.
How it is checked
cargo test board_buildreadszeno.boardfiles, right and wrong.cargo test cortex_m3builds one program with every part of a board in it for the emulated board, as--boarddoes, runs it in QEMU and compares what it prints withzeno run, for the build that checks and the minimal one. It skips the run where the compiler for ARM or QEMU is not installed.cargo test registers_of_a_cortex_m3does the same onboards/lm3s6965evb: pins driven and read back through the chip's registers, the clock, a serial port, a line typed toinput, a warning, and an error that stops the program.python3 tools/board.pybuilds every example, every sample of the book and the corner programs intools/targets/for the computer and for both boards, and compares what they do. When this page was written, 228 of 228 programs did the same onqemu-cortex-m3and 208 of 208 onlm3s6965evbin the build that checks, and 212 of 212 and 193 of 193 in the minimal one. The rest are left out, and counted: a build with no collector refuses them (176), or they need files, words on their line, or an end to what is typed, or, for the minimal build, a check stops them, or, on the board with pins of its own, they use theboardmodule (a simulated pin prints a line when it changes, and a real one does not). A number with a fraction may differ after its fifteenth digit, becausecoshand its like come from another C library on the board.- The workflow
boardruns all of it on a push that changes the C backend, the runtime or a board.
That check found a mistake the first time it ran, which was not about boards at all: a class whose list field has a default was built wrong with no collector (decision 51.8). A second processor is a second opinion on the same C.
Exercises
- Build
examples/blink.zenofor the emulated board with and without--minimal, and compare the two witharm-none-eabi-size. Which of text, data and bss changed, and why not the others? - Copy
boards/qemu-cortex-m3and give the copyflags "-Os". Is the program smaller than with--minimalalone? Now-O0: by how much does it grow? link.ldgives the chip 64 KB of RAM. Change it to 16 KB in your copy and buildexamples/signal.zeno. Read what the linker says. Which two sizes would you make smaller to fit (pool.md)?- In your copy's
system.c, make_writesend the error stream to the serial port too. What does a program that stops with an error print now, and in what order? - Build
examples/primes.zenoforboards/lm3s6965evband look at the largest functions witharm-none-eabi-nm --size-sort. Which of them make a float into text, and which line of the program brings them in? Take that line out and build again. - Copy
boards/lm3s6965evband makezeno_board_warnin itsboard.hsend its bytes out of UART0, aszeno_board_printdoes. That is a board with one wire and no debugger. What is lost? - Write a
board.hfor your copy with the four functions, wherezeno_board_writeprints all pins as one line of0and1. Add theheaderline and take the two-D_POSIXflags out. Why are they no longer needed? - QEMU's
lm3s6965evbhas real pins too: the LM3S6965's GPIO ports are emulated. Its status LED is on pin 0 of port F (data register at0x400253FC, direction at0x40025400, digital enable at0x4002551C). Makeled.on()write that register. How can a program tell that it worked? (On the real chip the port's clock must be switched on first, in the register at0x400FE108.)
This page is docs/board-build.md in the language repository.