Building a program

A Terse32 program is one image file, .terse: a 32-byte header (SPEC §image) and the ROM, RV32IMC machine code and constants loaded at 0001_0000h. RAM starts at 0010_0000h; devices are reached with ecall. terse build makes an image from C, assembly or Rust. This article is the reference for it: what you need, every option, what it runs and why each flag is there, and the devices an image lists. The C library describes the library and the hello program, Rust programs the Rust runtime, and Building by hand, and other languages the same build without terse build and what any other compiler must do.

What you need

Nothing else. The C library, the start-up code, the linker script and the Rust runtime are built into terse, and terse build takes the ROM out of the linked ELF file itself, so llvm-objcopy is not needed. When a tool is missing, terse build says in one sentence what to install. The compiler's own errors and warnings are shown as it prints them.

The commands

terse new <file.c|file.rs|file.S>
terse build <source>... [-o <out.terse>] [--title <t>]
    [--ram-pages <n>] [--device <slot:version>]...
    [--optional <slot:version>]... [--cflag <flag>]...
    [--clang <path>] [--lld <path>] [--rustc <path>]
    [--show] [--run [the options of terse run]...]
terse build --write-lib <dir>

terse build prints the image's size, its RAM and its ID on standard error:

hello.terse: 386 bytes (ROM 350), RAM 2 pages
    (4 bytes of data, the rest stack), id 54c6bd79...

(one line). The same sources and the same compiler give the same image, byte for byte.

What it runs for C and assembly

clang $CFLAGS -I <lib> -c <lib>/crt0.S -o 0.o
clang $CFLAGS -I <lib> -c hello.c -o 1.o
clang $CFLAGS -I <lib> -c <lib>/terse.c -o 2.o
ld.lld -T <lib>/terse.ld --gc-sections 0.o 1.o 2.o \
    -o out.elf
terse pack --rom rom.bin --title hello --ram-pages 2 \
    --device 2:0 --device 3:0 -o hello.terse

crt0.S is compiled only when there is C, and each source in its turn as 1.o; rom.bin is the ELF file's loaded bytes (below). $CFLAGS is

--target=riscv32-unknown-elf -march=rv32imc -mabi=ilp32
-Os -ffreestanding -nostdlib -fno-builtin
-ffunction-sections -fdata-sections

the flags of every programs/*/build.sh: built with its build.sh's header options, each program of programs/ that uses programs/lib comes out byte for byte as its checked-in image (crates/terse-cli/tests/build.rs checks it).

FlagWhy
--target=riscv32-unknown-elf32-bit RISC-V, no operating system: no system headers or libraries
-march=rv32imcexactly the CPU (SPEC §cpu): integers, multiply and divide, compressed instructions; no atomics, no floating-point registers
-mabi=ilp32the calling convention without floating-point registers
-Ossmall code: ROM is at most 128 KiB and every instruction costs budget
-ffreestandingno hosted C library: only freestanding headers such as stdint.h
-nostdliblink no C library or start files
-fno-builtinmemcpy and the like are not known functions; terse.c provides memcpy, memmove, memset and memcmp
-ffunction-sections -fdata-sectionseach function and variable in its own section, so --gc-sections drops what a program does not use
-I <lib>finds terse.h
-T terse.ldthe memory map (below)
--gc-sectionsdrop every section nothing refers to

crt0.S comes first and terse.c last. crt0.S holds _start, in the section .text.start, which the linker script puts at the first byte of ROM, where the machine starts (SPEC §reset). It copies .data from ROM to RAM, calls main and exits with its return value; RAM is zero at reset, so .bss needs nothing. A program only in assembly starts itself: it defines _start in .text.start (see programs/hello/hello.S or terse new x.S). terse.c is always linked; --gc-sections drops it from a program that calls nothing in it. There is no C library beyond terse.c and no compiler runtime: avoid 64-bit division and floating point in C, or bring the routines.

The linker script, terse.ld

ROM (rx) : ORIGIN = 0x00010000, LENGTH = 128K
RAM (rw) : ORIGIN = 0x00100000, LENGTH = 1M
.text   : KEEP(*(.text.start)), then *(.text .text.*)  > ROM
.rodata : constants                                     > ROM
.data   : __data_start .. __data_end  > RAM, at __data_load
.bss    : (NOLOAD) up to __bss_end                      > RAM
/DISCARD/ : .comment, .note*, .riscv.attributes, .eh_frame*

.data is loaded in ROM at __data_load, after .rodata, and copied to RAM by the start code. The image's RAM is set by its header, not by the script (which allows the largest, 1 MiB); terse build reads where .bss ends from the ELF file to choose the default RAM and to refuse a count too small.

The ROM from the ELF file

The ROM is the bytes of each loadable segment (program header PT_LOAD with a file size) placed at its load address (p_paddr) from 0001_0000h, with the gaps between segments zero: what llvm-objcopy -O binary writes for these files. terse build refuses an ELF file whose entry point is not 0001_0000h (no _start in .text.start) or which loads anything outside the 128 KiB of ROM.

The devices an image lists

terse pack --rom <raw.bin> --title <t> --ram-pages <n> [--device <slot:version>]... [--optional <slot:version>]... -o <out.terse> writes the header before a raw ROM and checks the result as a host would; terse build takes the same --device and --optional. The title is at most 16 bytes; RAM is 1 to 128 pages of 8 KiB; at most 16 devices. It prints the file's size and its image ID.

SlotDevice--device
1Systemalways present, need not be listed
2Terminal2:0
32D vector display3:0
4Content4:0
5Messagesreserved
6Sound6:0
7Page7:0
8Machines8:0; only the shell of a system gets it
93D vector display9:0
10Full text10:0

A device the image does not list is absent: its calls return FFFF_FFFFh. A host refuses an image that requires (--device) a device version it does not have. A device the program can do without is listed with --optional instead (any slot but 1 and 8): the image runs on hosts without it, where the device is absent, and asks at start whether it has it, with terse_has_device(slot) in C, the system device's device call; the answer never changes while the machine runs.

A program that prints characters outside the basic repertoire (ASCII, Latin-1, dashes, quotes, •, …, −, box drawing and blocks) lists device 10, full text: --optional 10:0 if a placeholder box will do on a host without it, --device 10:0 if not (see the terminal's article). Full text promises the full repertoire (Latin, Greek, Cyrillic, punctuation and common symbols); other scripts show only where the user added a font. A program meant to run on every host requires only the program profile, devices 2 and 3 (terse run --profile program runs it with exactly those), and lists the rest as optional. terse info shows both lists.

Next: The C library.