Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

RFC Index

  1. Lilium knums IDL
  2. RFC Policy
  3. x86_64 System ABI

This document is Copyright (C) 2025 Lilium Project (See Contributrors file for full details).

It is released under the terms of the CC-BY 4.0 License. Any Code Snippet or example provided is released under the terms of the MIT license.

Lilium knums IDL

Summary

The knums Language is a simple Interface Description Language that allows describing system interfaces in a uniform, human-readable and human-writable, and machine-readable manner. The language is may be written by users, in the course of writing RFCs, to describe the expected interface of a subsystem.

Motivation

Several Languages are anticipated to compile to Lilium, including C, C++, and Rust. Additionally, it is anticipated that the Lilium SCI will be implemented in multiple forms, including from emulation/compatibility layer projects like winter-lily, and the official kernel. To ensure cross-contextual agreement of the API-level definitions of system calls, structures, important constants, and other metadata, it is useful to have a single "source of truth". Where other operating systems rely on C headers for this purpose, the Lilium OS instead uses a simplistic IDL.

Informative Explanation

The knums language is defined with a syntax similar to Rust. The language is token-based, whitespace insensitive (other than to delimit tokens). Line comments begin with //, documentation line comments begin with ///, and file documentation comments begin with //!

knum files are structured into folders and files, with each hierarchy level from the build root forming part of the file path (for use declarations).

The knums language is used both for consumption by automated tools, and also to be used as a common vocabulary for defining Lilium interfaces in a language-neutral manner. Thus, future RFCs may use the language to define interfaces.

Items

The language has 5 main top-level constructs (items):

  • use declarations, which bring the contents of a specified module into scope,
  • const items defining constant values of various types
  • fn items defining system calls
  • struct and union items defining custom types, and
  • type alias items that allow naming an existing type in a different way.

Additionally, there are "directive" items (led by a % sign on their own line). These directives are not intended to be consumed by users, only for automated tooling (for example, %define_int_types is used in types/int.knum to instruct definition generators to provide support for using integer types).

Each item, other than a directive, may have any number of documentation lines immediately preceeding it. Before any item, including use declarations and directives, (but not necessarily before any comments), any number of "file" documentation lines may appear.

Types

There are several kinds of types:

  • Integer types, which may be either signed or unsigned, and has a width in bits,
  • The Char type, which is an 8-bit element of a string,
  • The Byte type, which is a raw byte,
  • The Void type, which denotes a function that returns no value,
  • The Never type, which denotes a function that does not return,
  • Named types, which refer to a struct, union, or type definition,
  • Array types, which contain a number of another type
  • Function Pointer types, which denote a function that can be called with a particular signature
  • Data Pointer types. which have a pointee, and denotes an object of the pointee type.

Normative Text

Lexical Grammar

The following formal grammar, described in a simplified version of ABNF, defines the lexical format of the knums language

; Whitespace Sensitive Grammer

file := [<whitespace>] *(<token> [<whitespace>])
    ; Every file must match the lexical file non-terminal

whitespace := 1*(<White_Space> / <comment>)

newline := %x0A
comment-begin := %x00-09 / %x0B-20 / %x22-2E / %x30-x10FFFF
comment-char := <comment-begin> / "!" / "/"

comment := "//" [<comment-begin> [*<comment-char>]] <newline>

doc-comment := "///" *<comment-char> <newline>
inner-doc-comment := "//!" *<comment-char> <newline>

ident := <XID_Start> *<XID_Continue> ; Except <keyword>

keyword := "use" / "type" / "const" / "mut" / "handle" / "shared_handle" / "struct" / "union" 

octal-digit := %x30-37

digit := %x30-39

hex-digit := <digit> / %x41-46 / %x61-66

uuid := "U{" 8<hex-digit> "-" 4<hex-digit> "-" 4<hex-digit> "-" 4<hex-digit> "-" 12<hex-digit> "}

hex-literal = "0" ("x" / "X") *(<hex-digit> ["_"]) <hex-digit>

dec-literal = *(<digit> ["_"]) <digit>

oct-literal = "0 ("o" / "O") *(<octal-digit> ["_"]) <octal-digit>

int-literal = <hex-literal> / <dec-literal> / <oct-literal>

punct := "=" / "*" / "+" / "-" / "^" / "&" / "|" / "<<" / ">>" / "<" / ">" / "->" / "{" / "}" / "[" / "]" / "(" / ")" / "/"

ascii-ident-begin := %x41-5A / %x61-7A / "_"

ascii-ident-continue := <ascii-ident-begin> / %x30-39

direcitve := "%" <ascii-ident-begin> *<ascii-ident-continue> 
    ; Must only be followed by `<White_Space>` or `<comment>` before first `<newline>`

token := <int-literal> / <uuid> / <punct> / <keyword> / <ident> / <doc-comment> / <inner-doc-comment> / <directive>

The following conventions are used above:

  • The XID_Start, XID_Continue, and White_Space non-terminals each match a single character belonging to that Unicode Character Class under Unicode 16.0,
  • Whitespace characters in the input are preserved,
  • Every input file must match the <file> production to lex
  • The input is consumed such that matches are formed based on the longest and most specific rule that matches, (for example, /// <input> should be treated as a doc-comment, not a comment)
  • Any input that matches the <keyword> production is not matched by the <identifier> production (but may be matched as part of a directive)

Syntatic Grammar

The following ABNF defines the syntactic grammar:


file := *<inner-doc-comment> *<bare-item>

bare-item := <item-struct> / <item-sysfn> / <item-const> / <item-use> / <directive> 

item-struct := <struct-keyword> <ident> [<generics-def>] [":" *<struct-option>] <struct-body>

struct-body := <struct-opaque-body> / <struct-fields>

struct-opaque-body := "opaque" ["(" <type> ")"] ";"

struct-fields := "{" [<struct-field> *("," <struct-field>) ["," [<struct-padding>]]] "}"

struct-field := *<doc-comment> <ident> ":" <type>

struct-padding := "pad" "(" <type> "," <expr> ")"

item-sysfn := "fn" <ident> <fn-signature> ["=" <expr>] ";"

item-const := "const" <ident> ":" <type> "=" <expr> ";"

item-use := ["inline"] "use" <path> ";"

path := <ident> / <path> "::" <ident>

fn-signature := "(" [<fn-param> *("," <fn-param>) [","] ] ")" "->" <type>

fn-param := [<ident> ":" ] <type>

simple-type := ("(" <type> ")") / <named-type>

type := <simple-type> / <pointer-type> / <fn-pointer-type> / <array-type> / "!"

pointer-type := "*" ("const" / "mut" / "handle" / "shared_handle") <type>

fn-pointer-type := "fn" <fn-signature>

array-type := "[" <type> ";" <expr> "]"

named-type := <ident> [<generics-type>]

generics-type := <generic-list> / <alternate>

generic-list := "<" [<type> *("," <type>) ","] ">"

alternate := "!" <type>

expr := <literal-expr> / <ident> / <unary-expr> / <binary-expr>

binary-expr := <expr> <binary-op> <expr>

; Precedence Order is 
; High: `<<`, `>>`
;  | : `&`, `|`, `^`
;  v : `/`, `*`
; Low: `+`, `-`
; All operators are left-associative.
binary-op := "<<" / ">>" / "&" / "|" / "^" / "/" / "*" / "+" / "-"

unary-expr := <unary-op> <expr>

unary-op := "+" / "-" / "!"

literal-expr := <int-literal> / <uuid>

The following conventions are used:

  • All productions defined in the lexical grammar, other than the file production, may be referred to by the syntatic grammar and match the same token produced by that grammar
  • The contents of the file must match the <file> production after stripping all whitespace and comments (other than doc comments and inner doc comments)

Items

Each file is a collection of items, that represent the public api of the system. There are 6 kinds of items:

  • Directives
  • Use Definitions
  • const items
  • fn items
  • struct and union items
  • type aliases.

Directives

A directive is a % prefixed ascii identifier. It must appear on its own line and have nothing other than whitespace preceeding or following it before a newline.

A directive is a command to the processor tool, it does not form part of the public API.

Use Definitions

An item introduced by the use keyword specifies a path (a sequence of identifiers separated by ::). A use item makes the definitions in the specified path available for definitions in the current file (See below for the rules for how to find the path of a given file).

Before the use keyword, the inline contextual keyword may be present. If the inline keyword is present, the use item is part of the public api of the file, and the items of that file are accessible from any file that imports the current file. Otherwise, the items made available by the use item are not guaranteed to be available outside of the current file.

const items

A const item defines an important named constant of a specified type.

fn items

An fn item defines a system function with a specified signature. It may have an expression that represents the system function number within the subsystem it belongs to. Functions that omit the expression are defined in userspace only.

An fn item's signature contains a number of parameters (at least 0) which have a type other than void, !, or an array type. Parameters also have a name which are informative to users and documentation readers. It also has a return type which is a type other than an array type.

struct/union items

A struct item is introduced by the struct keyword, and a union item by the union keyword. Both introduce new named types.

Both types have a body which can be either a braced struct body, or for struct types only an opaque body. Prior to the body, a number of attributes

A braced struct body contains a number of fields, which have a name and a type. The fields must be initialized to a value of the type. The body may end with the keyword pad which contains a type. The type must be an integer type or an array of an integer type. Such a keyword indicates that the type is extended as though by a field of such a type, which must be initialized to 0.

An opaque body optionally specifies a type field in parenthesis. The type provides a hint about a base type. It shall be valid to cast between pointer types to the base type and the derived type. Opaque types cannot be constructed, and may not appear directly in signatures, const items, or struct fields.

Struct attributes

Prior to the body, one or more attributes may be specified. Attributes are of the form <ident>(<expr>).

The following attributes are currently recognized:

  • align(N), N must an expression of type ulong, and must be a power of two. Indicates that the type requires alignment to at least N bytes.
  • option(ID). Inserts a field at the start of the structure type ExtendedOptionHead, and provides sufficient definitions. Must appear on a struct. Both types::option and types::uuid must be used to use this attribute,
  • option_head(N): Must appear on a union. Inserts a field of an unnamed struct type, containing a field of type ExtendedOptionHead (the file types::option must be used to use this attribute), and a field of type [byte; N].

type items

A type item introduces a named alias for a specified type.

Types

Integer types

The types uN and iN are integer types (valid only for N=8, 16, 32, 64, 128, and long, all others integer values for N are reserved identifiers for type names).

An integer type uN represents a N-bit unsigned integer type with values in [0, 2^N). An integer type iN represents an N-bit signed twos-complement integer type with values in [2^(N-1), 2^(N-1)).

The type ulong and ilong represent integer types that have the same width as a pointer on the current platform. It has the same range and representation as the equivalent uN or iN type, but is a distinct type.

To use an integer type, the file types::int must be used.

byte type

The type byte is a byte type. It has the same width as u8 and can be initialized from values of type u8. byte may also contain uninitialized values.

char type

The type char is a character type. It has the same width and representation as u8, but is a distinct type.

Named types

Any identifier may be used as a type. The identifier is only valid in the type position if it refers to a struct, union, or type item in scope, or if it refers to the name of a generic parameter for a containing `struct.

Identifiers of the form uN, iN (N is an integer value), ulong, ilong, byte, char, and void do not resolve to named types and instead resolve to the specified type.

Named types may be followed by either a generic-arg-list or a replacement type. A replacement type is a hint to the type of pointee to use in a polymorphic context. Note that uN and iN match even for invalid widths of integer type.

void type

The type void is the void type. It may only appear in return types of function definitions or function pointers. It represents an empty return from a function

Array types

An array type is of the form [<elem>; <len>] where elem is the element type and len is the length of the array, an expression of type . The array is layed out with the elements contiguous in memory.

Array types cannot appear in parameters or return types directly.

Pointer types

A pointer type is of the form *<kind> <pointee> where pointee is the pointee type and kind is one of the following keywords: mut, const, handle, or shared_handle.

mut and const represents userspace pointers to mutable or immutable data respectively.

handle and shared_handle represents pointers to kernel objects. shared_handle represents a pointer to an explicitly shared resource.

handle and shared_handle pointers may only be used if the types::hdl module is used.

Pointers may be to any type, including arrays, void, !, or opaque structs. Such pointers can appear in any position.

Function Pointer Types

A function pointer type is introduced by the fn keyword, and is followed by a function signature (like for an fn item).

Function pointers can accept any function defined in userspace with the specified signature.

Expressions

Expressions are complex forms that denote values. In the knums language, expressions are constants, which means they can be computed at compile time.

Literal Expression

A Literal expressions is an integer literal or a UUID. An integer literal can be written in decimal, in hexadecimal prefixed by 0x, or in octal prefixed by 0o. Digits may be separated by _. Decimal literals may have leading 0 digits.

A UUID literal starts with U and is immediately followed by a braced UUID. Dashes in the UUID may be omitted.

Named Expressions

A const item in scope may be named by an expression. The value of the expression is the value of the const. The const value is evaluated before being substituted - in particular, the substituted expression is not reparsed.

Unary Operator Expressions

Unary Operators may prefix an expression with an integer type. - is a value-wise negation of the value mod 2^N. ! is a bitwise negation. + is an identity operation.

Binary Operator Expressions

Binary Operators may apply to two expressions with an intege type.

  • + is addition,
  • - is subtraction,
  • * is multiplication,
  • / is division,
  • & is bitwise and,
  • | is bitwise or,
  • ^ is bitwise xor,
  • << is bitwise left shift,
  • >> is bitwise right shift.

When multiple binary operators are chained, we associate them by precedence first, then group from left to right.

Parenthesis

Parenthesis may surround an expression. This provides explicit grouping for the expression.

Standard Types

The following modules are predefined:

  • types::int
  • types::hdl
  • types::option
  • types::uuid
  • types

Other than the types module, which simply acts as if it contains inline use declarations for each of the preceeding, we define the contents of each of the modules below

types::int

The types::int module contains the following definitions. Additionally, any knums module that refers to an integer type must (potentially-indirectly) contain the declaration use types::int;.

const __LILIUM_SIZEOF_POINTER__: ulong = /*see below*/;

__LILIUM_SIZEOF_POINTER__ is defined to be equal to the number of bytes in a pointer.

types::hdl

The types::hdl module contains the following definitions. Additionally, any knums module that refers to *handle T or *shared_handle T must (potentially-indirectly) contain the declaration use types::hdl;

use types::int; // Required for __LILIUM_SIZEOF_POINTER__ below
/// Base type of all handles in Lilium
struct Handle : opaque;

/// Handle Pointer that contains 16 bytes. A non-null pointer is guaranteed not to overlap in bit representation with a `Uuid`
struct WideHandle<H> : align(16) {
    hdl: *handle H!Handle,
    pad([*const void; (16 - __LILIUM_SIZEOF_POINTER__)/__LILIUM_SIZEOF_POINTER__])
}

types::option

The types::option module contains the following definitions. Additionally, any knums module that uses the option or option_head struct attributes must (potentially-indirectly) contain the declaration use types::option.

use types::int;
use types::uuid;

struct ExtendedOptionHead {
    id: Uuid,
    flags: u32,
    pad([u32; 3])
}

types::uuid

The types::uuid module contains the following definitions. Additionally, any knums module that uses the option struct attribute or a UUID literal must (potentially-indirectly) contain the declaration use types::uuid.

use types::int;
struct Uuid : align(16) {
    minor: u64,
    major: u64,
}

Security Considerations

None

ABI Considerations

The knums language allows interfaces to be described as to their language API. When combined with a future RFC defining the system calling conventions and layout definitions, this is sufficient to know the complete ABI of these interfaces as well. This RFC does not define those conventions

Note that the fact that the ABI of an interface only depends on the aforementioned calling convention RFC, and its knum API, it follows that every interface defined by a knum spec has a consistent ABI on each platform.

Prior Art

Future Directions

  • Userspace function fn items
    • Defining USI items
  • Additional items, expressions, and types may be introduced

References

Normative References

This document is Copyright (C) 2025 Lilium Project (See Contributrors file for full details).

It is released under the terms of the CC-BY 4.0 License. Any Code Snippet or example provided is released under the terms of the MIT license.

RFC Policy

Summary

The public facing portions of the Lilium OS Project will be developed through a serious of documents, called "Requests for Comment" or "RFC"s, which will provide the basis for the policies of the Lilium OS Project and the normative text for defining the public interface.

Motivation

A Community Oriented Process for creating and evolving the Lilium OS is desirable. Using a public "Request for Comments" system allows the Leads of the Lilium OS to meaningfully debate the specification while making it easy for community members with their own interests to comment on the development.

Informative Explanation

The RFC Process is the mechanism for evolution of the Lilium OS. Throughout the lifecycle of the project, documents, known as Requests for Comments or RFCs will be published for review, comment, and consensus. These documents are used to change and evolve the Lilium OS Interfaces itself, a project-level policy, or other major portions of the Lilium OS Project.

While an RFC is "Live", it is open to public review comment, not restricted to members of the project or Core Interest Groups. Likewise, anyone may open an RFC to public comment, subject to policies regarding contributions. After comment, the Lilium Leads, approve or reject the RFC, which is followed by a period for final comment, where outstanding concerns can be raised and addressed.

An RFC is proposed and becomes "Live" by opening a pull request to https://github.com/LiliumOS/rfcs with the rfc text in a new item in the src/rfcs folder.

A Template for RFCs is provided, and can be used to aid in authoring RFCs. The template sets out required, recommended, or suggested parts of the RFC and what questions an RFC should address. It includes explanations of each section.

Normative Text

Purpose of an RFC

An RFC is required if it makes any of the following changes:

  • The interacts with the primary, user-facing definitions of the Lilium Operating System (kernel or standard USI impl), including by modifying any of the following:
    • Defining a new core SCI Subsystem,
    • Defining a new standard SCI Subsystem (other than as experimental) or labeling a previously-experimental standard SCI Subsystem as no longer experimental,
    • Adding new system calls to a core SCI Subsystem or a non-experimental standard SCI subsystem,
    • Modifying the System Call ABI or the Userspace ABI,
    • Modifying, including by adding to, the Executable Format Specification used by the operating system,
    • Defining a new standard USI interface in an existing USI library or defining a new USI library,
  • It establishes a project-wide policy or charters a group within the project designed to carry out the project work in a formal manner,
  • Or otherwise if it meaningfully amends any preexisting RFC.

An RFC may also be useful, but is not necessarily required, if the change has wide impact on the project, or is important in a meaningful way.

And RFC is not required for the following:

Lifecycle of an RFC

The following is the Lifecycle of every RFC

  1. Pre-Review (Optional): The RFC is brought for informal review and drafting, in an incomplete (or Pre-RFC) form designed for drafting and initial design,
  2. Submission: The RFC is submitted to http://github.com/LiliumOS/rfcs as a Pull Request. Generally, the RFC must contain the content set forth in the content section,
  3. Review and Iteration: The Pull Request is reviewed and discussed, with appropriate concerns, design questions, proposed design changes, and appropriate changes are made to address these concerns,
  4. Approval: Once the RFC is reviewed appropriately the Lilium Leads must approve for it to be merged. Approval represents consensus to adopt the RFC.
  5. Final Comment Period: After approval the RFC must undergo a 7 day final comment period. Approval may be revoked at any point by any Lead.
  6. RFC Number Assignment: The RFC is assigned a number based on its PR Number and the document is renamed accordingly.

An RFC may be explicitly closed also by request of all of the Core Interest Groups - this indicates that there is consensus not to move forward at the current time. A Closed RFC may be reopened or refiled in the future.

After approval and the final comment period, any member of the Project may perform the RFC Number Assignment (if the Number was not previously assigned) and merge the RFC.

Content

Generally, an RFC must contain at least the following:

  • A One to two paragraph summary of the RFC,
  • Motivation for the RFC and the underlying proposal,
  • An Informative Explanation of the proposal,
  • The Normative Text of the proposal.

Additionally, an RFC should specify the following, as applicable:

  • Any Security Considerations that may apply to the RFC, both as to users and implementors,
  • Any Considerations on the System Call or Userspace Application Binary Interface,
  • A description of Prior Art that informed the proposal,
  • A description of Future Changes and Directions that can be made in respect to the RFC.

Each RFC is provided under a unified license. Everyone who submits an RFC must permit the Lilium OS Project to license the RFC under the unified license in force at the time.

The License for RFCs is currently CC-BY-4.0 and requires an RFC to change. Such a change applies to previous RFCs as well as future RFCs, though previous RFCs will remain available under the previous license as well.

Any Code submitted in an RFC is subject to the MIT License. This include examples and snipets. API Definitions are deemed by the Project to not be subject to copyright, due to their inherent functionality, If this assement is incorrect, such API signatures are also released under the terms of the MIT License.

The RFC License shall always be an Open Documentation License.

RFC Template

An RFC Template shall be provided to aid in the authoring of RFCs. The template shall provide sections for the elements of an RFC set forth in the Content section. Use of the template is not required for an RFC, however. Modifying the template is not an RFC of its own.

Security Considerations

There are no security considerations for this RFC, as it strictly defines a policy of the Project.

Prior Art

Future Direction

  • This policy does not specify the method for fixing "releases" of the Specification/OS Definition, whether the specification is simply a snapshot of the merged RFCs as a whole at any given time, or some formal stabilization process is required,
    • Likewise, it is not yet specified how or if releases will be "versioned", and how versions will be designated or discovered,
  • The Policy also Leaves Open how to modify RFCs for non-technical reasons (such as for editorial purposes),
  • While Copyright is addressed by the Policy, Patent considerations are currently omitted. This may need to be addressed at some point in the future,
  • Finally, the policy requires RFCs to be approved by the Lilium Project Leads. In the future a proper team may be chartered for this purpose, and certain kinds of RFCs may be delegated to other such teams.

Normative References

  • CC-BY-4.0 - Copyright License by Creative Commons Team

This document is Copyright (C) 2025 Lilium Project (See Contributrors file for full details).

It is released under the terms of the CC-BY 4.0 License. Any Code Snippet or example provided is released under the terms of the MIT license.

x86_64 System ABI

Summary

The Interaction with the Lilium System Calls and userspace libraries has both an API and an ABI. This document describes the ABI of those parts of Lilium on x86_64 specifically.

Motivation

Toolchains compiling to Lilium on x86_64, as well as hand-written assembly, need to be able to produce code that can interact with system libraries as well as system functions, using standardized conventions.

Informative Explanation

The x86_64 Architecture is one of the primary architectures targetted by the Lilium Operating System. To esnure compatibility of compiled programs, we define an set of conventions for the ABI, The conventions consists of the Calling Convention for both Userspace and System Calls from the Kernel, as well as layouts and representations of language types and certain vocabulary types in the standard library,

Normative Text

Userspace ABI

Except as specified below, all system libraries in userspace obey the x86-64 psABI.

The C main function, and function pointers passed to system libraries, is expected to obey this ABI, and may have the following signatures:

  • int main(void)
  • int main(int argc, char** argv) or int main(long argc, char** argv)
  • int main(int argc, char** argv, char** envp) or int main(long argc, char** argv, char** envp)

Regardless of whether argc is defined as int or long, it will contain the same value, unless the value cannot be represented as int.

(Note: Signatures using long argc are non-standard and are not portable)

(Note: It is recommended, but not strictly required, that all userspace code obey this ABI).

System Call ABI

The System Call ABI uses a modified form of the calling convention from the x86-64 psABI. It uses the same type layouts as the Userspace ABI.

System Calls (defined by the kernel) are invoked by the syscall instruction. The system function number

The following changes apply:

  • On entry, eax contains the system function number. The top 32-bits of rax must be clear.
  • On exit:
    • If the function returns void, both rax and rdx are undefined
    • If the function returns SysResult, rax contains the return value - the negative error number on error, positive or 0 if succesful, rdx is undefined.
    • If the function returns SysResult2<T> (T must be up to 8 bytes in size, and have class INTEGER), rax contains the error or 0 if successful, and rdx contains the value if successful (rdx is undefined if rax contains an error)
    • If the function returns any other type, that type must be at most one eightbyte and have class INTEGER. The value is in rax, and rdx is undefined.
  • There may be at most 6 eightbytes of parameters, each of either class MEMORY or INTEGER
  • The fourth INTEGER eightbyte for parameters (including pointers for MEMORY types) is passed in r10, not in rcx (rcx stores the return address after a syscall instruction). If the system function uses fewer than 4 eightbytes, r10 is not used for the syscall (caller saved/volatile).
  • Varargs are not supported.

System Function Number and Error Numbers

The System Function Number is a 32-bit value that describes the calling sequence. The bottom 12 bits contains the system function number within the subsystem, bits 12 through 27 (inclusive) contain the 16-bit subsystem number. Bits 28-31 (inclusive) are reserved and contain 0.

An Error Code is a negative value always (-err is the error value). -err encodes an 8-bit per-subsystem error code in the lower 8 bits and the 16-bit subsystem number. All other bits of -err are 0 (1 for err).

Lilium Specific psABI

long double

On x86_64, long double is 8-bytes in size and has an alignment of 8. It has a 53-bit Mantisa, 11-bit exponent, and an exponent bias of 10231.

When classifying parameters/return values, long double is classified as a single eightbyte of class SSE, and _Complex long double is classed as two eightbytes each with class SSE (equivalent to struct __complex_long_double { long double real; long double imm;}).

__fp80 may be defined by the toolchain, and has the standard definition and ABI. It is not Layout or ABI compatible with long double.

fenv_t

The fenv_t type defined in the header <fenv.h> is a single 32-bit value with class INTEGER. The contents of the bits are equivalent to the layout of the mxcsr register. fegetenv stores the register into the memory pointed to by its parameter, fesetenv loads the register from its parameter.

x32/ILP32

The x32 ABI defined in the x86-64 psABI is not supported by either userspace system libraries or system functions. Non-standard userspace system libraries may implement support, but require a special program loader, and may require additional support to ensure pointers (especially handles) are restricted on 32-bit. Programs written or compiled to expect x32 support cannot make use of direct system calls without adjusting ABI on the caller side.

Security Considerations

Violation of the ABI Requirements can lead to undefined behaviour, including pointer access violations that can lead to memory corruption or invalid memory leaks. Toolchains, users writing manual assembly code, and implementors of userspace system libraries must take care in matching the ABI to avoid security vulnerabilities arising due to imrpoper ABI handling.

ABI Considerations

This document defines the ABI of both System Calls and Userspace Libraries on x86_64.

Prior Art

Alternatives

  • The x86-64 psABI can be adopted verbatim without changes:
    • This would require long double to be 128-bit and use x87 ABI, which requires additional system library support without substantial benefit, conversion costs, and memory usage.
    • Additionally, the system call ABI must still be modified, as rcx (used as the 4th parameter by the psABI) is used by the syscall instruction to store the return address
  • The Win64 ABI could be used instead
    • Win64 would be more constraining, and also requires modification to the ABI for system calls (as rcx used for the first parameter needs to be switched to r10)
    • Further, the ABI would need additional parameters to support a max of 6 eightbytes of parameters, and there would be limited support for SysResult2<T>.

Future Direction

  • x32 support.

References

Normative References

Informative References

This document is Copyright (C) 2025 Lilium Project (See Contributrors file for full details).

It is released under the terms of the CC-BY 4.0 License. Any Code Snippet or example provided is released under the terms of the MIT license.

  1. This is exactly the same as the double type. long double is not equivalent to __fp80 on Lilium. ↩

Creative Commons Attribution 4.0 International

Creative Commons Corporation (“Creative Commons”) is not a law firm and does not provide legal services or legal advice. Distribution of Creative Commons public licenses does not create a lawyer-client or other relationship. Creative Commons makes its licenses and related information available on an “as-is” basis. Creative Commons gives no warranties regarding its licenses, any material licensed under their terms and conditions, or any related information. Creative Commons disclaims all liability for damages resulting from their use to the fullest extent possible.

Using Creative Commons Public Licenses

Creative Commons public licenses provide a standard set of terms and conditions that creators and other rights holders may use to share original works of authorship and other material subject to copyright and certain other rights specified in the public license below. The following considerations are for informational purposes only, are not exhaustive, and do not form part of our licenses.

  • Considerations for licensors: Our public licenses are intended for use by those authorized to give the public permission to use material in ways otherwise restricted by copyright and certain other rights. Our licenses are irrevocable. Licensors should read and understand the terms and conditions of the license they choose before applying it. Licensors should also secure all rights necessary before applying our licenses so that the public can reuse the material as expected. Licensors should clearly mark any material not subject to the license. This includes other CC-licensed material, or material used under an exception or limitation to copyright. More considerations for licensors.

  • Considerations for the public: By using one of our public licenses, a licensor grants the public permission to use the licensed material under specified terms and conditions. If the licensor’s permission is not necessary for any reason–for example, because of any applicable exception or limitation to copyright–then that use is not regulated by the license. Our licenses grant only permissions under copyright and certain other rights that a licensor has authority to grant. Use of the licensed material may still be restricted for other reasons, including because others have copyright or other rights in the material. A licensor may make special requests, such as asking that all changes be marked or described. Although not required by our licenses, you are encouraged to respect those requests where reasonable. More considerations for the public.

Creative Commons Attribution 4.0 International Public License

By exercising the Licensed Rights (defined below), You accept and agree to be bound by the terms and conditions of this Creative Commons Attribution 4.0 International Public License ("Public License"). To the extent this Public License may be interpreted as a contract, You are granted the Licensed Rights in consideration of Your acceptance of these terms and conditions, and the Licensor grants You such rights in consideration of benefits the Licensor receives from making the Licensed Material available under these terms and conditions.

Section 1 – Definitions.

a. Adapted Material means material subject to Copyright and Similar Rights that is derived from or based upon the Licensed Material and in which the Licensed Material is translated, altered, arranged, transformed, or otherwise modified in a manner requiring permission under the Copyright and Similar Rights held by the Licensor. For purposes of this Public License, where the Licensed Material is a musical work, performance, or sound recording, Adapted Material is always produced where the Licensed Material is synched in timed relation with a moving image.

b. Adapter's License means the license You apply to Your Copyright and Similar Rights in Your contributions to Adapted Material in accordance with the terms and conditions of this Public License.

c. Copyright and Similar Rights means copyright and/or similar rights closely related to copyright including, without limitation, performance, broadcast, sound recording, and Sui Generis Database Rights, without regard to how the rights are labeled or categorized. For purposes of this Public License, the rights specified in Section 2(b)(1)-(2) are not Copyright and Similar Rights.

d. Effective Technological Measures means those measures that, in the absence of proper authority, may not be circumvented under laws fulfilling obligations under Article 11 of the WIPO Copyright Treaty adopted on December 20, 1996, and/or similar international agreements.

e. Exceptions and Limitations means fair use, fair dealing, and/or any other exception or limitation to Copyright and Similar Rights that applies to Your use of the Licensed Material.

f. Licensed Material means the artistic or literary work, database, or other material to which the Licensor applied this Public License.

g. Licensed Rights means the rights granted to You subject to the terms and conditions of this Public License, which are limited to all Copyright and Similar Rights that apply to Your use of the Licensed Material and that the Licensor has authority to license.

h. Licensor means the individual(s) or entity(ies) granting rights under this Public License.

i. Share means to provide material to the public by any means or process that requires permission under the Licensed Rights, such as reproduction, public display, public performance, distribution, dissemination, communication, or importation, and to make material available to the public including in ways that members of the public may access the material from a place and at a time individually chosen by them.

j. Sui Generis Database Rights means rights other than copyright resulting from Directive 96/9/EC of the European Parliament and of the Council of 11 March 1996 on the legal protection of databases, as amended and/or succeeded, as well as other essentially equivalent rights anywhere in the world.

k. You means the individual or entity exercising the Licensed Rights under this Public License. Your has a corresponding meaning.

Section 2 – Scope.

a. License grant.

  1. Subject to the terms and conditions of this Public License, the Licensor hereby grants You a worldwide, royalty-free, non-sublicensable, non-exclusive, irrevocable license to exercise the Licensed Rights in the Licensed Material to:

    A. reproduce and Share the Licensed Material, in whole or in part; and

    B. produce, reproduce, and Share Adapted Material.

  2. Exceptions and Limitations. For the avoidance of doubt, where Exceptions and Limitations apply to Your use, this Public License does not apply, and You do not need to comply with its terms and conditions.

  3. Term. The term of this Public License is specified in Section 6(a).

  4. Media and formats; technical modifications allowed. The Licensor authorizes You to exercise the Licensed Rights in all media and formats whether now known or hereafter created, and to make technical modifications necessary to do so. The Licensor waives and/or agrees not to assert any right or authority to forbid You from making technical modifications necessary to exercise the Licensed Rights, including technical modifications necessary to circumvent Effective Technological Measures. For purposes of this Public License, simply making modifications authorized by this Section 2(a)(4) never produces Adapted Material.

  5. Downstream recipients.

    A. Offer from the Licensor – Licensed Material. Every recipient of the Licensed Material automatically receives an offer from the Licensor to exercise the Licensed Rights under the terms and conditions of this Public License.

    B. No downstream restrictions. You may not offer or impose any additional or different terms or conditions on, or apply any Effective Technological Measures to, the Licensed Material if doing so restricts exercise of the Licensed Rights by any recipient of the Licensed Material.

  6. No endorsement. Nothing in this Public License constitutes or may be construed as permission to assert or imply that You are, or that Your use of the Licensed Material is, connected with, or sponsored, endorsed, or granted official status by, the Licensor or others designated to receive attribution as provided in Section 3(a)(1)(A)(i).

b. Other rights.

  1. Moral rights, such as the right of integrity, are not licensed under this Public License, nor are publicity, privacy, and/or other similar personality rights; however, to the extent possible, the Licensor waives and/or agrees not to assert any such rights held by the Licensor to the limited extent necessary to allow You to exercise the Licensed Rights, but not otherwise.

  2. Patent and trademark rights are not licensed under this Public License.

  3. To the extent possible, the Licensor waives any right to collect royalties from You for the exercise of the Licensed Rights, whether directly or through a collecting society under any voluntary or waivable statutory or compulsory licensing scheme. In all other cases the Licensor expressly reserves any right to collect such royalties.

Section 3 – License Conditions.

Your exercise of the Licensed Rights is expressly made subject to the following conditions.

a. Attribution.

  1. If You Share the Licensed Material (including in modified form), You must:

    A. retain the following if it is supplied by the Licensor with the Licensed Material:

    i. identification of the creator(s) of the Licensed Material and any others designated to receive attribution, in any reasonable manner requested by the Licensor (including by pseudonym if designated);

    ii. a copyright notice;

    iii. a notice that refers to this Public License;

    iv. a notice that refers to the disclaimer of warranties;

    v. a URI or hyperlink to the Licensed Material to the extent reasonably practicable;

    B. indicate if You modified the Licensed Material and retain an indication of any previous modifications; and

    C. indicate the Licensed Material is licensed under this Public License, and include the text of, or the URI or hyperlink to, this Public License.

  2. You may satisfy the conditions in Section 3(a)(1) in any reasonable manner based on the medium, means, and context in which You Share the Licensed Material. For example, it may be reasonable to satisfy the conditions by providing a URI or hyperlink to a resource that includes the required information.

  3. If requested by the Licensor, You must remove any of the information required by Section 3(a)(1)(A) to the extent reasonably practicable.

  4. If You Share Adapted Material You produce, the Adapter's License You apply must not prevent recipients of the Adapted Material from complying with this Public License.

Section 4 – Sui Generis Database Rights.

Where the Licensed Rights include Sui Generis Database Rights that apply to Your use of the Licensed Material:

a. for the avoidance of doubt, Section 2(a)(1) grants You the right to extract, reuse, reproduce, and Share all or a substantial portion of the contents of the database;

b. if You include all or a substantial portion of the database contents in a database in which You have Sui Generis Database Rights, then the database in which You have Sui Generis Database Rights (but not its individual contents) is Adapted Material; and

c. You must comply with the conditions in Section 3(a) if You Share all or a substantial portion of the contents of the database.

For the avoidance of doubt, this Section 4 supplements and does not replace Your obligations under this Public License where the Licensed Rights include other Copyright and Similar Rights.

Section 5 – Disclaimer of Warranties and Limitation of Liability.

a. Unless otherwise separately undertaken by the Licensor, to the extent possible, the Licensor offers the Licensed Material as-is and as-available, and makes no representations or warranties of any kind concerning the Licensed Material, whether express, implied, statutory, or other. This includes, without limitation, warranties of title, merchantability, fitness for a particular purpose, non-infringement, absence of latent or other defects, accuracy, or the presence or absence of errors, whether or not known or discoverable. Where disclaimers of warranties are not allowed in full or in part, this disclaimer may not apply to You.

b. To the extent possible, in no event will the Licensor be liable to You on any legal theory (including, without limitation, negligence) or otherwise for any direct, special, indirect, incidental, consequential, punitive, exemplary, or other losses, costs, expenses, or damages arising out of this Public License or use of the Licensed Material, even if the Licensor has been advised of the possibility of such losses, costs, expenses, or damages. Where a limitation of liability is not allowed in full or in part, this limitation may not apply to You.

c. The disclaimer of warranties and limitation of liability provided above shall be interpreted in a manner that, to the extent possible, most closely approximates an absolute disclaimer and waiver of all liability.

Section 6 – Term and Termination.

a. This Public License applies for the term of the Copyright and Similar Rights licensed here. However, if You fail to comply with this Public License, then Your rights under this Public License terminate automatically.

b. Where Your right to use the Licensed Material has terminated under Section 6(a), it reinstates:

  1. automatically as of the date the violation is cured, provided it is cured within 30 days of Your discovery of the violation; or

  2. upon express reinstatement by the Licensor.

For the avoidance of doubt, this Section 6(b) does not affect any right the Licensor may have to seek remedies for Your violations of this Public License.

c. For the avoidance of doubt, the Licensor may also offer the Licensed Material under separate terms or conditions or stop distributing the Licensed Material at any time; however, doing so will not terminate this Public License.

d. Sections 1, 5, 6, 7, and 8 survive termination of this Public License.

Section 7 – Other Terms and Conditions.

a. The Licensor shall not be bound by any additional or different terms or conditions communicated by You unless expressly agreed.

b. Any arrangements, understandings, or agreements regarding the Licensed Material not stated herein are separate from and independent of the terms and conditions of this Public License.

Section 8 – Interpretation.

a. For the avoidance of doubt, this Public License does not, and shall not be interpreted to, reduce, limit, restrict, or impose conditions on any use of the Licensed Material that could lawfully be made without permission under this Public License.

b. To the extent possible, if any provision of this Public License is deemed unenforceable, it shall be automatically reformed to the minimum extent necessary to make it enforceable. If the provision cannot be reformed, it shall be severed from this Public License without affecting the enforceability of the remaining terms and conditions.

c. No term or condition of this Public License will be waived and no failure to comply consented to unless expressly agreed to by the Licensor.

d. Nothing in this Public License constitutes or may be interpreted as a limitation upon, or waiver of, any privileges and immunities that apply to the Licensor or You, including from the legal processes of any jurisdiction or authority.

Creative Commons is not a party to its public licenses. Notwithstanding, Creative Commons may elect to apply one of its public licenses to material it publishes and in those instances will be considered the “Licensor.” Except for the limited purpose of indicating that material is shared under a Creative Commons public license or as otherwise permitted by the Creative Commons policies published at creativecommons.org/policies, Creative Commons does not authorize the use of the trademark “Creative Commons” or any other trademark or logo of Creative Commons without its prior written consent including, without limitation, in connection with any unauthorized modifications to any of its public licenses or any other arrangements, understandings, or agreements concerning use of licensed material. For the avoidance of doubt, this paragraph does not form part of the public licenses.

Creative Commons may be contacted at creativecommons.org

MIT

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Contributors List

This document is Copyright (C) 2025 Lilium Project (See Contributrors file for full details).

It is released under the terms of the CC-BY 4.0 License. Any Code Snippet or example provided is released under the terms of the MIT license.