Platforms and runtime identifiers
From 0.3.0, one .asmproj builds for seven platforms, named the way .NET names them: by
runtime identifier (RID). Any build machine builds any of them. This page covers the RIDs, how
a project chooses them, how its sources and calls differ per platform, and what each platform's
output looks like. Everything here was measured with the 0.3.0 targets, NASM 3.02 and LLVM
23.1.5.
| RID | Object format, linker | Shared library | Static library | Executable | C library (libc) |
|---|---|---|---|---|---|
win-x64 |
PE/COFF, lld-link | name.dll (+ name.dll.lib, name.pdb) |
name.lib |
name.exe |
Universal C Runtime (ucrtbase.dll) |
win-arm64 |
PE/COFF, lld-link | name.dll (+ name.dll.lib) |
name.lib |
name.exe |
Universal C Runtime |
linux-x64 |
ELF, ld.lld | libname.so |
libname.a |
name |
glibc 2.34+ (libc.so.6) |
linux-arm64 |
ELF, ld.lld | libname.so |
libname.a |
name |
glibc 2.34+ (libc.so.6) |
linux-musl-x64 |
ELF, ld.lld | libname.so |
libname.a |
name |
musl (libc.musl-x86_64.so.1): Alpine |
osx-x64 |
Mach-O, ld64.lld | libname.dylib |
libname.a |
name (libc only) |
libSystem |
osx-arm64 |
Mach-O, ld64.lld | libname.dylib |
libname.a |
name (libc only) |
libSystem |
x64 code is NASM (.asm). ARM64 code is GNU syntax (.s), which the bundled llvm-mc
assembles. The two can live side by side in one project.
Note
Not released yet: the main branch adds an eighth RID, linux-musl-arm64: musl on ARM64,
such as Alpine on Graviton. It behaves like linux-musl-x64, with libc.musl-aarch64.so.1
and the loader /lib/ld-musl-aarch64.so.1. AsmFoundation.Sdk 0.3.0 on nuget.org builds the
seven RIDs above. See the changelog.
Choosing the RIDs
A project lists the RIDs its code supports, with .NET's property:
<PropertyGroup>
<RuntimeIdentifiers>win-x64;linux-x64;linux-arm64;osx-arm64</RuntimeIdentifiers>
</PropertyGroup>
There is no default: a project that names no RID, and that nothing asks to build for a RID, stops with ASM0010. A project gets its RIDs in one of three ways:
- Its own
RuntimeIdentifiers(or a singleRuntimeIdentifier):dotnet buildbuilds each one. - Its referencing project. An asm project that references a RID-less one builds it for
its own RID, one inner build at a time. A .NET project can name the RIDs on the
reference:
<ProjectReference Include="../Crc32C/Crc32C.asmproj" RuntimeIdentifiers="linux-x64;win-x64" /> - The command line:
dotnet build -r linux-arm64builds exactly that RID. It must be one the project lists (ASM0012), and one AsmSdk builds (ASM0011).
A solution build is the one exception to ASM0010. A solution builds each project by itself, with no RID, besides building it through its referencing projects. A project that lists no RID on purpose prints "builds nothing for it by itself" there instead of failing.
How the build runs
Each RID is an inner build with the standard RuntimeIdentifier global property, exactly
like dotnet build -r. So $(RuntimeIdentifier) conditions work in an .asmproj as in a
.csproj, and outputs land in bin/<Configuration>/<TargetFramework>/<rid>/:
bin/Release/freestanding/win-x64/crc32c.dll
bin/Release/freestanding/linux-arm64/libcrc32c.so
bin/Release/freestanding/osx-arm64/libcrc32c.dylib
Without RuntimeIdentifier, the build is the RID outer build. It builds each RID in turn,
in parallel when the build is, and links nothing itself, just as the outer build of a
multi-targeted project (TargetFrameworks) builds each framework. TargetFrameworks
and RuntimeIdentifiers combine. A project may list different RIDs per framework:
<TargetFrameworks>freestanding;libc</TargetFrameworks>
<RuntimeIdentifiers>linux-x64;win-x64</RuntimeIdentifiers>
<RuntimeIdentifiers Condition="'$(TargetFramework)' == 'libc'">linux-x64</RuntimeIdentifiers>
dotnet clean cleans every RID; IDEs see each RID's output in their up-to-date checks.
Sources per platform
Every *.asm and *.s file of the project is a source. Which of them builds a RID is decided
by the file name:
- The extension is the language.
.asmis NASM, which assembles x86-64 only..sis GNU syntax forllvm-mc, which assembles ARM64 (and x86-64 in AT&T syntax). - An unqualified file builds its CPU's RIDs.
crc32c.asmbuilds every x64 RID, andcrc32c.severy ARM64 RID. - A qualifier before the extension narrows the targets. It is a RID (
crc32c.win-x64.asm), an OS family (win,linux,linux-musl,osx),unix(Linux and macOS), or a CPU (x64,arm64).crc32c.linux.asmbuilds every Linux x64 RID. - The closest file wins. Files of one name in one folder compete per RID: a RID qualifier
beats
linux-musl, which beats an OS family, which beatsunix, which beats a CPU, which beats no qualifier. A generic file can thus be overridden for one platform without excluding anything by hand:
| Files | win-x64 | linux-x64 | linux-musl-x64 | osx-x64 | ARM64 RIDs |
|---|---|---|---|---|---|
io.asm, io.win.asm, io.linux.asm, io.linux-musl.asm |
io.win.asm |
io.linux.asm |
io.linux-musl.asm |
io.asm |
(none) |
io.s, io.win-arm64.s |
(none) | (none) | (none) | (none) | io.win-arm64.s on win-arm64, io.s elsewhere |
Objects keep the qualifier (io.linux.o), so variants never share an object. The rules have
their own errors:
- ASM0020: two files of one name apply equally to a RID (
x.linux.asmandx.linux.s). - ASM0021: a
.asmqualified for ARM64 only, which NASM cannot assemble. - ASM0023: a listed RID that no source builds (typically ARM64 with only
.asmfiles). - ASM0024: one file listed twice as an
AsmSource(the default glob plus an explicit item), as .NET reportsNETSDK1022forCompileitems.
Writing code that runs everywhere
The three OSes agree on little below C: Windows and System V pass arguments in different registers, and the three object formats name, export and address symbols differently. The SDK puts a platform layer on every include path, and defines the platform's symbols.
Defines
Every assembler run receives:
WINDOWS,LINUXorMACOS, plusMUSLonlinux-musl-x64(withLINUX);X64orARM64;FREESTANDINGorLIBC, andDEBUGorRELEASE, as before.
NASM gets them with -D, llvm-mc with --defsym NAME=1, so %ifdef MACOS in NASM and
.ifdef MACOS in GNU syntax test the same thing. DisableImplicitFrameworkDefines=true
turns off all but the configuration's, as in .NET.
x64: asmsdk.inc
default rel
%include "asmsdk.inc"
section .text
FUNCTION crc32c_append, 3, rbx ; exported; 3 integer arguments; changes rbx
mov eax, ARG1d ; ecx on Windows, edi elsewhere
mov rbx, ARG2 ; rdx / rsi
; ...
RETURN ; restores rbx, then ret
ENDFUNCTION
| Name | Windows (Microsoft x64) | Linux, macOS (System V) |
|---|---|---|
ARG1 .. ARG4 |
rcx, rdx, r8, r9 |
rdi, rsi, rdx, rcx |
ARG5, ARG6 |
r10, r11, loaded from the stack by FUNCTION when nargs says 5 or 6 |
r8, r9 |
ARG1d, ARG1w, ARG1b, … |
the 32-, 16- and 8-bit forms | |
SHADOW_SPACE |
32 (a caller reserves it above the return address) | 0 |
PLT |
empty | wrt ..plt (calls into another module) |
FUNCTION name [, nargs [, registers]]starts a global, exported function:global name:functionfor ELF, plainglobalfor Mach-O (the SDK passes NASM--gprefix _, so every global and extern gets Mach-O's underscore), and on Windows also an-export:namedirective in.drectve, which is what__declspec(dllexport)does. The registers listed are the ones the body changes.FUNCTIONsaves those the caller expects back on this OS:rbx,rbp,r12-r15everywhere, andrdi,rsi,xmm6-xmm15on Windows only. Listingrsicosts nothing on Linux and keeps Windows correct.LOCAL_FUNCTIONis the same, not global.HIDDEN_FUNCTIONis global but exported from no image:hiddenon ELF,private_externon Mach-O, no directive on Windows. Use it for what the library's other files, or a static library's users, call.RETURNrestores and returns, and may appear more than once.ENDFUNCTIONcloses the function.In a program,
FUNCTIONexports nothing. The SDK definesASMSDK_EXECUTABLEthere, andmainand_startare no exports (see Programs export nothing by default).section .rodataworks on every OS: macho64 maps it to__TEXT,__const. On Windows the SDK passes-D.rodata=.rdata, because NASM's win64 output makes a section name it does not know executable code. In Debug builds (CodeView), NASM 3.02 also crashed on such a section..note.GNU-stackis Linux-only: wrap it in%ifdef LINUX. For macho64 the line is an error (unknown section name .note.GNU-stack). win64 makes it one more empty, executable code section.%ifdef LINUX section .note.GNU-stack noalloc noexec nowrite progbits %endifIn a
.sfile, the same guard is.ifdef LINUXand.section .note.GNU-stack,"",%progbits. The SDK's own Linux links never need the note, because they pass-z noexecstack. It matters for a static library that someone else links with GNUld.
Stack alignment is still yours: rsp is 16n+8 at entry, and each saved register moves it by
8. A Windows function that calls another reserves SHADOW_SPACE below its own data.
Floating-point arguments are positional on Windows (xmm0-xmm3 together with the integer
ones), but sequential on System V. The macros name integer arguments only.
ARM64: asmsdk-gnu.inc
AAPCS64 is the same calling convention on Linux, Windows and macOS: arguments in x0-x7,
the result in x0, with x19-x28 and d8-d15 callee-saved. So no argument macros are
needed. What differs is how symbols are named, declared, exported and addressed:
.include "asmsdk-gnu.inc"
RODATA // .rodata, .rdata or __TEXT,__const
table: .word 10, 20, 30
FUNCTION lookup // global, exported, in .text, aligned
stp x29, x30, [sp, #-16]!
mov x29, sp
ADDRESS x1, table // adrp + :lo12:, or @PAGE / @PAGEOFF on Mach-O
CALL helper // bl helper, or bl _helper on Mach-O
ldp x29, x30, [sp], #16
ret
ENDFUNCTION lookup
| Macro | What it does |
|---|---|
FUNCTION name |
Global, exported function: .type %function and .size on ELF; .def/.scl/.type 32 and the -export: directive on COFF; _name on Mach-O, plus the plain name as a local label so that ADDRESS takes one spelling. |
LOCAL_FUNCTION name |
The same, not global. |
HIDDEN_FUNCTION name |
The same, global but exported from no image: .hidden on ELF, .private_extern on Mach-O, no directive on COFF. |
ENDFUNCTION name |
Closes it (records the ELF size). |
CALL name / TAILCALL name |
bl / b with the OS's name for a C symbol: one of this module, of a linked static library, or of the C library (the linker routes it through a stub). On x86-64 GNU syntax: call / jmp, through @PLT on Linux. |
ADDRESS reg, label |
The position-independent address of a label of this file. |
RODATA |
Switches to read-only data, which each format names differently (.section .rodata is an error on Mach-O). |
x18 is the platform register on Windows (the TEB) and macOS: never use it.
On macOS every variadic argument goes on the stack (Apple's ARM64 convention), while Windows
and Linux pass them in x1-x7 like the others. printf from ARM64 assembly is therefore
written per OS.
Exports
On Linux and macOS every global symbol of a shared library is exported. On Windows, only what
the DLL lists is: FUNCTION lists itself through its .drectve directive. An
ExportsFile (a linker version script) decides the exports on every OS:
- Linux:
--version-script. The names are versioned (crc32c_append@@CRC32C_1.0), andlocal: *hides the rest. - Windows:
-export:for each global name. The SDK definesASMSDK_EXPORTS_FILE, andFUNCTIONthen writes no directive of its own. - macOS:
-exported_symbol _namefor each global name. Patterns are kept, and ld64.lld matches them itself.
A version script with extern "C++", or a pattern on Windows, is ASM0030. One leak
remains on Windows: a referenced static library's FUNCTIONs keep their directives and
are exported from the DLL that links them. lld-link cannot drop a directive. Keep a static
library's FUNCTIONs to its public API. Use HIDDEN_FUNCTION for what its users call
internally, and LOCAL_FUNCTION for what one file uses alone. Linux and macOS export a
static library's globals from every shared library that links it too, unless an
ExportsFile or HIDDEN_FUNCTION hides them.
Linux shared libraries are linked -Bsymbolic, so a library's references to its own global
symbols bind to the library, as on Windows and macOS. Without it, lea [rel global] or an
adrp to a global symbol failed to link ("recompile with -fPIC"). A library that wants ELF's
interposition back adds <LinkerArg Include="-Bno-symbolic" />.
The C library per platform
<TargetFramework>libc</TargetFramework> links the platform's C library, with an ordinary
int main(int argc, char **argv) for a program. The SDK links against stand-ins it writes
itself from its symbol lists, so no build machine needs the target's sysroot or SDK:
| Platform | Linked against | A program starts in | Notes |
|---|---|---|---|
| Linux glibc (x64, ARM64) | a stub libc.so.6 |
the SDK's crt1 → __libc_start_main |
glibc 2.34+; loader /lib64/ld-linux-x86-64.so.2 or /lib/ld-linux-aarch64.so.1 |
| Linux musl (x64) | a stub libc.musl-x86_64.so.1 |
the same crt1 (musl's __libc_start_main takes the same arguments) |
loader /lib/ld-musl-x86_64.so.1 |
| macOS | libSystem.tbd (install name /usr/lib/libSystem.B.dylib) |
main, called by dyld (LC_MAIN) |
macOS 11+ (AsmMacOSMinimumVersion) |
| Windows | ucrtbase.lib (the Universal C Runtime, part of Windows 10+) |
the SDK's mainCRTStartup |
printf, fprintf, sprintf, snprintf, their v forms, sscanf and atexit come from the SDK's wrappers |
What a C compiler would take from static runtime archives, the SDK provides itself:
atexiton glibc, which keeps it inlibc_nonshared.a. In 0.2.0 a program that called it linked but did not start.- The
printffamily on Windows. The UCRT headers define those functions inline, over__stdio_common_vfprintf, soucrtbase.dllexports none of them.
A function missing from the SDK's list fails the link with "undefined symbol". Add it with
<AsmLibcSymbol Include="name" /> (a C name; macOS gets the underscore). The lists, and what
the SDK writes from them, are in
Runtimes and linking.
kernel32 on every Windows output. Windows system call numbers change between releases, so
kernel32 is a Windows program's way to the OS. A freestanding Windows program may call
GetStdHandle, WriteFile and ExitProcess. The import library adds an import only for the
names a program uses. Freestanding programs
has a complete one.
Programs export nothing by default. FUNCTION writes no export directive in an executable
(the SDK defines ASMSDK_EXECUTABLE there), so main and _start are no exports. The .exe
gets no import library either. A program that exports, such as a plugin host, names its
exports in an ExportsFile. On Windows it then also gets <name>.lib, for its plugins to
link against.
macOS has no freestanding programs: Apple supports no static executables, and dyld starts every program, with libSystem (ASM0015). Freestanding libraries are fine.
Some differences remain the code's to handle:
- errno is
__error()on macOS,__errno_location()on glibc,_errno()on Windows. stdoutis the data objectstdouton Linux,__stdoutpon macOS, and__acrt_iob_func(1)on Windows.- On osx-x64,
statand friends are the old 32-bit-inode versions unless the code callsstat$INODE64.
Build machines
The bundled toolchain (AsmFoundation.Toolchain.<host>) exists for the machines LLVM publishes
release binaries for:
| Build machine | Toolchain package | Notes |
|---|---|---|
| Windows x64 | AsmFoundation.Toolchain.win-x64 |
|
| Windows on Arm | AsmFoundation.Toolchain.win-arm64 |
native LLVM tools; NASM's x64 build runs under Windows' x64 emulation |
| Linux x64 (glibc) | AsmFoundation.Toolchain.linux-x64 |
|
| Linux ARM64 (glibc) | AsmFoundation.Toolchain.linux-arm64 |
|
| Apple silicon Mac | AsmFoundation.Toolchain.osx-arm64 |
|
| Intel Mac, Alpine | none (ASM0006) | <AsmToolchain>System</AsmToolchain> with Homebrew's or Alpine's nasm, llvm and lld; or AsmHostRid to a toolchain that runs there |
Every toolchain builds every RID. llvm-mc arrived in toolchain 0.2.0; with an older one, a
.s source stops with ASM0004. The System toolchain links with GNU ld by default,
which links ELF of the build machine's own architecture only. Windows and macOS RIDs need
AsmLinkerCommand set to lld-link or ld64.lld, and the Linux RID of the other
architecture ld.lld (ASM0005).