UEFI Specification

Currently this spec is still under construction and thus neither followed by the built-in UEFI, nor by Advanced OS. This however will change in the future.

This page intends to describe an interface between the UEFI bootloaders and operating systems such as Advanced OS. As the name "bootloader" implies, the purpose is to find and boot an operating system, either from a local disk or over the network. Additionally, the bootloader may want to set up printing for easily facilitating user interaction and displaying errors. For solely indicating boot-errors, one can also resort to beep-codes via `computer:beep()` as indicated below.

Specification

To boot an operating system, the bootloaders needs to find an operating system installation, specifically by looking for the file /boot.lua at the root of a storage medium. This initial file is then to be loaded via Lua's load() function and then the resulting function shall be executed without passing any arguments.

OS boot arguments

Any values exposed to the operating system by UEFI must be located in the table _ENV.__UEFI, where _ENV refers to the environment passed to the load() call that loads the entry point of the operating system. UEFIs must provide the entries below. If an optional entry is not implemented it shall not be present in the table, i.e. it shall have a value of nil.

_ENV.__UEFI contents

Name	Required	Type	Description
bootDrive	Yes	ManagedMassStorageUD or UnmanagedMassStorageUD or table	The instance of ManagedMassStorage (or UnmanagedMassStorage) that boot.lua was loaded from. Without this, an OS has no way of knowing which disk was selected in a dual-boot environment. In case such an component is not available, for example during a network-boot, bootloader must provide a table that provides the same fields of either Managed- or UnmanagedMassStorage. Note: Neither bootloaders nor OSes are required to support booting from UnmanagedMassStorages nor network.
_*	No	any	Any custom, non-standard values starting with an underscore may be added to this table, for any kind of purpose. OSes may make use of them but cannot expect them to always be present. Always precede custom values with an underscore as to not run into a conflict with future versions of this spec.

Beep codes

If you decide to use computer:beep() codes during the boot process, follow the tables below. Symbols with indicated range shall always use the maximum duration, if the beep code indicates an error. Between two non-pause symbols there shall be a pause of 0.25 seconds. It is not necessary to make use of all beep codes. For ease of readability it is best to not mix symbols of different durations.

Symbols

Symbol	Duration	Pitch	Notes
d	0.1 - 0.5 sec	200	A short, deep sound played via computer:beep(200, 0.5).
h	0.1 - 0.5 sec	1500	Short, high pitch, via computer:beep(1500, 0.5).
D	1 sec	200	Similar.
H	1 sec	1500
-	1 sec		A pause of 1 second, equivalent to sleep(1).

Beep codes

Sequence	Description
hd-*	A custom error code not described here. See the specific bootloader's description instead.
h	Successfully found and load()'ed boot.lua (suggested duration: 0.1 seconds). Does not imply successful boot of the operating system itself.
dh-d	No storage media installed.
dh-h	Error during compiling boot.lua.
dh-dd	No screen connected (If bootloader requires screen).

Display setup

Currently the built-in bootloader does set up display interaction and provide functions such as print. This however shall not be relied upon by operating systems. Instead every OS should set up its own display handling and clear the Gpu's TextBuffers via gpuUD:freeAllBuffers().