Awesome
libgloss-htif
This is a minimalistic libgloss port for RISC-V M-mode that implements system calls through the Berkeley Host-Target Interface (HTIF).
Installation
$ mkdir build
$ cd build
$ ../configure --prefix=${RISCV}/riscv64-unknown-elf --host=riscv64-unknown-elf
$ make
$ make install
Note: The installation prefix must be chosen such that the libdir
variable matches one of the library search paths of the RISC-V compiler.
For a typical cross-compiler toolchain, the prefix would generally be
the sysroot directory (riscv64-unknown-elf-gcc -print-sysroot
).
Use the --libdir
configure option to adjust the location if the final
directory component is not /lib
.
Test static linking with a suite of "Hello World" demonstration programs:
$ make check
$ spike hello.riscv
$ spike hello.nano.riscv
$ spike hello.pico.riscv
multilib
The --enable-multilib
or --disable-multilib
configure options
control whether both RV32 and RV64 libraries are built.
A list of ISA/ABI combinations can be passed as an argument to override
the default set:
--enable-multilib='rv32i/ilp32 rv32iac/ilp32 rv32im/ilp32 rv32imac/ilp32 rv32imafc/ilp32f rv64imac/lp64 rv64imafdc/lp64d'
If these options are omitted, configure
dynamically detects the set of
multilib mappings supported by the compiler ($CC
).
Usage
For convenience, the compiler/linker switches needed to replace the
standard -lgloss
are encapsulated in GCC spec files, along with a
bare-metal linker script.
Spec File | Description |
---|---|
htif.specs | Link with newlib |
htif_nano.specs | Link with newlib-nano |
htif_wrap.specs | Switch to minimal stdio implementation |
htif_argv.specs | Retrieve argv from fesvr |
$ riscv64-unknown-elf-gcc -O2 -specs=htif.specs -o hello tests/hello.c
htif_wrap.specs
further reduces static code size by inserting custom
implementations of common stdio.h
functions, which support only a
constrained subset of format specifiers (e.g., non-floating-point).
This depends on the --wrap
feature of GNU ld and is intended to be
used in conjuction with the other newlib spec files.
$ riscv64-unknown-elf-gcc -O2 -specs=htif_nano.specs -specs=htif_wrap.specs -o hello tests/hello.c
htif_argv.specs
adds extra initialization code to retrieve
command-line arguments from the frontend server. The program will exit
with an error (typically ENOMEM
) if the number or length of the
argument strings exceeds the fixed buffer size set by ARG_MAX
.
If this feature is omitted, argv
defaults to a static array with no
arguments.
$ riscv64-unknown-elf-gcc -O2 -specs=htif_nano.specs -specs=htif_argv.specs -o hello tests/hello.c
Local usage
For simple testing, it is possible to directly link against
libgloss_htif.a
in the build directory without installing:
- Add
-L <builddir>
to the link command. - Pass the actual path to the spec file in
-specs
argument. - Symlink
htif.ld
to the current working directory. (This bypasses a limitation where gcc searches only the default library path for the linker script, ignoring-L
.)
Stack and heap sizes
Override the __stack_size_min
symbol to change the minimum stack
size in bytes:
-Wl,--defsym=__stack_size_min=$N
.
Override the __heap_size
symbol to change the heap size in bytes:
-Wl,--defsym=__heap_size=$N
.
Multi-threading
Static TLS is supported through the Local Executable access model, which
allows the declaration of thread-local variables with the __thread
specifier.
By default, hart 0 is designated as the primary hart for handling global
initialization and executing the main()
function.
A different hart ID can be specified by redefining the __boot_hart
symbol, such as with a linker option: -Wl,--defsym=__boot_hart=$N
.
All other harts execute the secondary __main()
function, which
defaults to a busy loop.
Multi-threaded programs should either override this function or alias
__main
with main
to force a common entry point:
-Wl,--defsym=__main=main
.
Exception handling
A custom exception handler can be implemented by overriding the
handle_trap()
function, which should match the following signature:
uintptr_t handle_trap(uintptr_t epc, uintptr_t cause, uintptr_t tval, uintptr_t regs[32])
The return value sets the new mepc
for returning from the exception.