Targets

sultanc targets lists the 38 registered compilation targets. This page records, for each one, which backend generates its code, what standard library support it has, how its executable is linked and how it is verified. It also describes where target-specific code lives in the repository, for contributors who add or port a target.

Backends#

SultanC has two code-generation backends, selected with --backend=native or --backend=llvm.

The native backend is SultanC's own code generator and, with the built-in linkers, needs no external toolchain. It is available for the x86_64 and aarch64 targets of Linux, Android, FreeBSD, macOS and Windows (x86_64-linux, aarch64-linux-gnu, x86_64-android, aarch64-android, x86_64-freebsd, aarch64-freebsd, arm64-darwin, x86_64-darwin, x86_64-windows-msvc, aarch64-windows-msvc) and for wasm32-wasi and wasm32-browser. Requesting it for any other target reports SULTANC-BACKEND-UNAVAILABLE.

The LLVM backend is available for every target and requires a compiler built with LLVM (./build.sh --enable-llvm). It produces objects for every target. Targets without an object format (NVPTX, XCore) are compiled with --emit=asm, which works for every target. The status of each target under the LLVM backend, with what was run and what was only built, is kept in LLVM targets progress.

The الدعم (support) column of sultanc targets carries one of three values: مضيف ذاتي (self-hosted, arm64-darwin and x86_64-linux), ترجمة متقاطعة (cross-compilation, every other target) and تجريبي (experimental, none today). The compiler also compiles itself on the Android and FreeBSD x86_64 and aarch64 targets; Self-hosting on Android and FreeBSD records how that was verified.

Target matrix#

Operating-system targets#

These targets have the full standard library, including files, processes, sockets and threads (except where noted). All of them use raw kernel calls or the platform's system interface and link no libc; Platform dependencies lists every import.

Linux and Android targets use the Linux kernel ABI directly. The 32-bit targets (i686-linux-gnu, armv7-linux-gnueabihf, armv7-android) use the time64 and large-file system calls. On them, and on every other target that lacks a divide instruction or a wide divide, the backend expands division in IR so no compiler-rt is linked (see What lives where).

The FreeBSD targets use raw system calls with no libc. They require FreeBSD 13 or later (for close_range) and are built against the 14.2 headers. The executable is static, with ELFOSABI_FREEBSD and the .note.tag ABI note, which the built-in linker keeps and covers with a PT_NOTE header.

Linking#

The compiler chooses the linker; there is no option to pick one.

A hosted ELF target the ELF linker does not lay out would be linked by ld.lld -static -e _start (compiler/driver/external_linker.sn) only when its target policy names ld.lld; none does now. ld.lld is found in this order: $SULTANC_LINKER; bin/ld.lld of the LLVM installation whose libLLVM the compiler is linked with (the directory next to its lib/); ld.lld on PATH.

A link input the target's linker does not read (no object, archive, library or linker script) is reported as SULTANC-LINK-INPUT-UNSUPPORTED with its path. For macOS and iOS a text-based dylib stub of an Apple SDK (.tbd, as MacOSX.sdk/usr/lib/libSystem.tbd) stands for the dylib its install name names, as with ld64: the image loads that dylib and binds the symbols the stub exports to it.

WebAssembly#

Freestanding and accelerator targets#

These targets have no OS layer; programs use the language core and std modules that do not depend on an operating system.

These targets cannot be linked into an executable by SultanC: requesting exe reports SULTANC-LINK-OUTPUT-UNSUPPORTED. Use -c or --emit=obj for objects and --emit=asm for assembly. tests/en/target/language_core.sn (records, tagged unions, generics, and integer arithmetic of every width) compiles for each of them. A program that uses an OS service (printing, files) is rejected for them at check with SULTANC-TARGET-FEATURE-UNSUPPORTED; the compiler itself is such a program, so sultanc check compiler/main.sn passes for the 21 hosted targets only. Function values are closures whose environment the runtime allocates, and these targets have no allocator, so a program that takes a function value is rejected for them (SULTANC-BACKEND-UNSUPPORTED-CONSTRUCT). BPF before ISA v4 has no signed division; signed division divides the magnitudes there. eBPF has no floating point, so LLVM rejects float arithmetic for it.

Cortex-M targets#

The four Arm M-profile targets are bare-metal ELF targets of the LLVM backend (the native backend has no 32-bit Arm code generator). Their target conditions are الهدف.المعمارية == "arm" with الهدف.المنصة == "freestanding", and environment eabi or eabihf.

The facts live in compiler/backend/target/target_registry.sn (the M-profile class is the target's processor, target_model.sn صنف_ذراع_إم) and are passed to LLVM as CPU and feature strings (أساس_توليد_ذراع_إم).

• ABI: AAPCS, little-endian ELF32 relocatable objects with Arm build attributes (CPU name, architecture profile M, Tag_ABI_align_preserved: the stack is 8-byte aligned at every public interface). eabi passes floats in core registers; eabihf uses AAPCS-VFP (s0-s15, d0-d7), which LLVM selects from the environment.
• No run-time library. SultanC links neither libgcc nor compiler-rt, so no object for these targets references an __aeabi_* routine. 64-bit division is expanded in IR as on every 32-bit target. On ARMv6-M, which has no divide instruction, no 32 x 32 -> 64 multiply and no 64-bit shift, 32-bit division, 64-bit multiplication and 64-bit shifts by a variable amount are expanded too (compiler/backend/provider/llvm/freestanding_routines.sn) instead of calling __aeabi_uidiv, __aeabi_lmul, __aeabi_llsl, __aeabi_llsr and __aeabi_lasr.
• Floating point. A float operation the FPU cannot do would call a soft-float routine (__aeabi_fadd, __aeabi_dmul, __aeabi_f2d, ...). It is rejected instead, with SULTANC-TARGET-FEATURE-UNSUPPORTED at the source statement that holds the operation, naming the operation, its type and the source function: every float arithmetic, comparison or conversion on the eabi targets, every f64 one on thumbv7em-none-eabihf, and frem everywhere. Loading, storing and moving floats, negation, abs and copysign are allowed. A Cortex-M7 runs thumbv7em-none-eabihf code; its double-precision FPv5-D16 needs a processor selection the registry does not offer yet.
• Atomics. ARMv6-M has no exclusive accesses (LDREX/STREX); ARMv7-M has them up to 32 bits only. On these targets std.sync.atomic declares the 32-bit atomic loads and stores and the fences (atomic_u32, atomic_u32_new, atomic_u32_load, atomic_u32_store, atomic_fence), which are LDR/STR with DMB. The 64-bit and atomic_usize forms and every read-modify-write operation are declared for other targets only (SULTANC-TARGET-FEATURE-UNSUPPORTED for the Arabic names; the English aliases report SULTANC-NAME-UNKNOWN). The target conditions the bootstrap compilers parse cannot tell ARMv6-M from ARMv7-M, so the 32-bit read-modify-write atomics of ARMv7-M are not offered yet. Any atomic wider than the target does inline is rejected by the backend.
• Like every freestanding target, these have no allocator: strings, vectors and closures are rejected.

Start-up code and linking

The compiler emits the start-up into the object of every Cortex-M program with an entry, as it emits _start for the hosted targets (compiler/backend/provider/llvm/cortex_m_entry.sn), so no assembler or C toolchain is involved:

• .vector_table: the initial stack pointer __stack_top, Reset_Handler and the 14 system exceptions, each a weak alias of a spinning Default_Handler;
• Reset_Handler copies .data from FLASH to RAM, zeroes .bss, enables the FPU on thumbv7em-none-eabihf (CPACR CP10/CP11), runs .init_array, calls main and passes the low word of its result to __sultanc_exit, whose weak default stops the core in a WFI loop;
• __sultanc_semihosting_exit (Arm semihosting SYS_EXIT_EXTENDED) and __sultanc_semihosting_fault (exit status 132; a SultanC trap is UDF, which escalates to a HardFault), for runs under QEMU or a debugger.

ARMv6-M instructions only, so one sequence serves every class. The linker scripts in library/std/os/platform/none/arm/cortex_m are data files the linker is given explicitly:

SultanC does not link these targets: requesting exe reports SULTANC-LINK-OUTPUT-UNSUPPORTED. The built-in ELF linker has no Arm relocations or linker-script support yet. Link an image with ld.lld, for example:

./build/sultanc --backend=llvm --target=thumbv7m-none-eabi --emit=obj program.sn -o program.o
D=library/std/os/platform/none/arm/cortex_m
ld.lld -T $D/board_mps2.ld -L $D --gc-sections program.o $D/semihosting.ld -o program.elf
qemu-system-arm -M mps2-an385 -nographic -monitor none -serial none \
  -semihosting-config enable=on,target=native -kernel program.elf; echo $?

tools/tests/cortex_m_tests.sh does this for every test in tests/{en,ar}/target that names a Cortex-M target and runs each image on the target's QEMU boards.

Not yet supported: ve-linux-gnu#

ve-linux-gnu (NEC Vector Engine) compiles to objects and assembly but has no std OS layer. VE has no kernel trap: a system call is a request to the VEOS daemon. The number and arguments are stored in a per-thread shared-memory area whose address the VEOS and glibc start-up places in the thread control block (tcbhead_t.shm_offset, glibc-ve sysdeps/unix/sysv/linux/ve/sysdep.h), and then monc is issued. Porting needs that start-up protocol and VE hardware or an emulator to verify it.

What lives where#

A native backend for a new architecture needs only the kernel entry and _start; the std layer is shared with the LLVM backend.

Verification#

Each target is verified at the strongest level its environment allows.

tools/tests/target_tests.sh runs tests/{en,ar}/target on every target their // أهداف: header names: check, then an executable (or an object or assembly), then a run where the host can run it, comparing the exit status and standard output. On an x86_64 Linux host with qemu-user, wasmtime, node and Wine, it runs 192 of the 296 test-target pairs and builds the other 104.

Every program in examples/en (90 of the 93 files; the other three are two module helpers and a C-library FFI example) gives the same output and exit status as on x86_64 Linux under qemu-user on every Linux and Android architecture, under wasmtime (except the examples that need processes or the host environment), and on the FreeBSD x86_64, aarch64 and riscv64 VMs together with the target tests. The per-target counts are in LLVM targets progress. tools/tests/freebsd_examples.sh runs the x86_64 examples on a Linux host through a ptrace system-call translator (tools/tests/freebsd_abi_emulator.c).

Cross-checking a Linux target#

./build/sultanc --backend=llvm --target=riscv64-linux-gnu examples/en/fs/files.sn -o files
qemu-riscv64 ./files

Regenerating the FreeBSD tables#

The generators read only the sys/ and include/ headers of a FreeBSD source tree.

git clone --depth 1 -b releng/14.2 https://github.com/freebsd/freebsd-src
python3 tools/generate/generate_freebsd_syscalls.py --src freebsd-src
python3 tools/generate/generate_freebsd_uapi.py --src freebsd-src

Running FreeBSD under qemu#

The official VM images run under qemu's system emulation (TCG; no KVM needed). On Ubuntu 24.04 the packages are qemu-system-arm qemu-system-misc qemu-efi-aarch64 u-boot-qemu opensbi. The images are in https://download.freebsd.org/releases/VM-IMAGES/14.5-RELEASE/{aarch64,riscv64}/Latest/: FreeBSD-14.5-RELEASE-arm64-aarch64-ufs.qcow2.xz and FreeBSD-14.5-RELEASE-riscv-riscv64-ufs.qcow2.xz. Check them against CHECKSUM.SHA256. The 14.2 release is no longer on the mirror; 14.5 runs binaries built against the 14.2 headers. Converting an image with qemu-img convert -c -O qcow2 halves its size.

# aarch64: UEFI firmware, virtio PCI devices, SSH on host port 2223
qemu-system-aarch64 -M virt -cpu cortex-a72 -smp 4 -m 2048 -display none \
  -bios /usr/share/qemu-efi-aarch64/QEMU_EFI.fd \
  -drive file=arm64-aarch64.qcow2,if=none,id=hd0,format=qcow2 -device virtio-blk-pci,drive=hd0 \
  -netdev user,id=n0,hostfwd=tcp:127.0.0.1:2223-:22 -device virtio-net-pci,netdev=n0 \
  -serial unix:ser-aarch64.sock,server,nowait -monitor none

# riscv64: OpenSBI, then U-Boot (S-mode), which boots the image's EFI loader; SSH on 2224
qemu-system-riscv64 -M virt -smp 4 -m 2048 -display none \
  -bios /usr/lib/riscv64-linux-gnu/opensbi/generic/fw_jump.bin \
  -kernel /usr/lib/u-boot/qemu-riscv64_smode/u-boot.bin \
  -drive file=riscv-riscv64.qcow2,if=none,id=hd0,format=qcow2 -device virtio-blk-device,drive=hd0 \
  -netdev user,id=n0,hostfwd=tcp:127.0.0.1:2224-:22 -device virtio-net-device,netdev=n0 \
  -serial unix:ser-riscv64.sock,server,nowait -monitor none

The images log root in on the serial console without a password. Over the console socket, install a key in /root/.ssh/authorized_keys, add PermitRootLogin prohibit-password to /etc/ssh/sshd_config, then run sysrc sshd_enable=YES; service sshd keygen; service sshd start (sshd is off in the images, and generating the host keys takes several minutes on riscv64 under TCG). Copy a program with scp -P 2223 (or 2224) and run it over ssh. Under TCG on a 4-core host the aarch64 VM boots in about 3 minutes and the riscv64 VM in about 10, and riscv64 programs run roughly ten times slower than aarch64 ones.

The amd64 image prints only to the video console. Without a network, a run can still be driven from the host: QEMU's monitor sendkey types at the console (root, then a command line), screendump shows the screen, and the guest writes its results to the serial port (... > /dev/cuau0), which -serial unix:... hands to the host. The programs reach the guest on an ISO image (genisoimage -R) mounted with mount_cd9660 (-cdrom on amd64, virtio-scsi on aarch64, and a read-only virtio-blk-device on riscv64, where it is /dev/vtbd1).

Self-hosting on Android and FreeBSD#

A compiler built for x86_64-android, aarch64-android, x86_64-freebsd or aarch64-freebsd runs there, compiles programs for its own platform by default and compiles itself. Build one from an x86_64 Linux host with the native backend (the module source below leaves out the LLVM provider, as ./build.sh does for a compiler without LLVM):

./build/sultanc --target=x86_64-freebsd \
  --module-source=compiler.backend.provider.llvm.llvm_codegen=compiler/backend/provider/llvm/unavailable.sn \
  compiler/main.sn -o sultanc

On the target, run it from a directory that holds compiler/ and library/ (or set SULTANC_STD). The compiler learns where it runs from the host-environment identity in compiler/runtime/host_environment_model.sn, whose platform codes include Android (6) and FreeBSD (7); compiler/backend/target/target_registry.sn maps them to the registered targets, so sultanc program.sn with no --target builds for the platform it runs on.

A compiler records the absolute paths of its sources, so two builds compare equal only when they are compiled from the same directory.

On these targets (and on Linux and Windows) aarch64 code uses ARMv8.0 atomics, LDAXR/STLXR loops, from both the native and the LLVM backend (see Concurrency), so the executables run on ARMv8.0 cores such as the Cortex-A53, A57 and A72 (Raspberry Pi 3 and 4) as well as on later ones: an aarch64-linux-gnu compiler checks compiler/main.sn and compiles hello under qemu-aarch64 -cpu cortex-a57. Only arm64-darwin uses the ARMv8.1 LSE atomics (LDADDAL, CASAL and the rest), which every Apple Silicon core has. sultanc run is not available on these hosts: the interpreter's host kernel bridge exists for Linux only, and the run reports SULTANC-INTERPRETER-UNSUPPORTED-MACHINE-PRIMITIVE. Compile the program and run the executable instead.

Limitations#

• The native backend covers the x86_64 and aarch64 operating-system targets and wasm32; every other target needs the LLVM backend.
• sultanc run is not available on Android and FreeBSD hosts.
• ve-linux-gnu has no std OS layer.
• Freestanding and accelerator targets produce objects or assembly only; Cortex-M images are linked with ld.lld outside the compiler.
• Cortex-M: no soft-float routines (float operations without FPU support are rejected), no Cortex-M7 double-precision FPU selection, and only 32-bit atomic loads, stores and fences in std.
• x86_64-darwin and aarch64-windows-msvc are built but not run.
• wasm64-unknown-unknown produces objects only.
• sultanc check compiler/main.sn passes for the hosted targets only: the compiler uses files and processes.
• wasm32-wasi has no processes, threads or file locks, and its sockets are limited to preopened ones.

See also#

• Platform dependencies: every system interface std imports, per platform.
• Concurrency: thread support per OS.
• MSIR and code generation: how backends and linkers fit together.
• Bootstrap: building the compiler with or without LLVM.