.Dd October 5, 2015
.Dt KERNEL 7
.Os
.Sh NAME
.Nm kernel
.Nd operating system kernel
.Sh SYNOPSIS
.Pa /boot/sortix.bin
.Op Fl \-console Ns = Ns Ar terminal
.Op Fl \-disable-em
.Op Fl \-disable-network-drivers
.Op Fl \-disable-logo
.Op Fl \-enable-em
.Op Fl \-enable-network-drivers
.Op Fl \-enable-logo
.Op Fl \-firmware Ns = Ns Oo Sy bios "|" Sy efi "|" pc Oc
.Op Fl \-no-random-seed
.Op Fl \-term Ns = Ns Ar terminal
.Op Fl \-
.Op Ar init ...
.Sh DESCRIPTION
.Pa /boot/sortix.bin
is the operating system
.Nm kernel .
It initializes and manages the hardware to provide a multitasking computing
environment.
The kernel is a
.Xr multiboot 7
compatible executable loaded by the bootloader along with a companion
.Xr initrd 7
that contains a userland.
.Pp
The kernel extracts the initrd into the initial kernel memory root filesystem.
The specified
.Ar init
program is invoked with the given arguments, defaulting to the
.Xr init 8
at
.Pa /sbin/init
if
.Ar init
is not specified.
If the
.Nm init
is to receive any argument starting with a dash, first pass the
.Fl \-
delimiter to stop kernel option parsing.
The computer is powered off if the
.Nm init
process exits 0, rebooted if it exits 1,
halted with an complaint about an
.Nm init
fatality if it exits 2, and halted with a complaint about an unexpected exit code
otherwise.
.Pp
The options are as follows:
.Bl -tag -width "12345678"
.It Fl \-console Ns = Ns Ar terminal
Use the
.Ar terminal
as the console and the session for
.Xr init 8
along with options for initializing the terminal.
The choices are:
.Bl -tag -width "12345678"
.It Sy com Ns Ar n Ns Oo , Ns Oo BBBBPN Oc Ns Oo Ns , Ns Ar columns Ns Sy x Ns Ar rows Oc Oc
Use the
.Xr com 4
serial line; optionally initializing it with the speed
.Ar BBBB ,
with the parity
.Ar P
being either
.Sy n
for no parity,
.Sy o
for odd parity,
or
.Sy e
for even parity, and
.Ar N
is the number of bits per character;
and optionally initializing the terminal window size to the selected
.Ar columns
and
.Ar rows
or 80x25 by default.
The
.Fl \-term
option is useful to select the
.Ev TERM
environment variable.
.Pp
This choice currently disables the
.Sy tty1
terminal because its logterminal driver needs a major restructuring.
.It Sy tty1
Use the
.Sy tty1
virtual terminal as the console.
This terminal is the default console.
.El
.It Fl \-disable-em
Don't initialize the
.Xr em 4
driver.
.It Fl \-disable-logo
Don't display the operating system boot on the console during boot.
.It Fl \-disable-network-drivers
Don't initialize any network drivers.
This option ensures the booted system is not networked.
.It Fl \-enable-em
Do initialize the
.Xr em 4
driver.
.It Fl \-enable-logo
Display the operating system boot on the console during boot.
This is the default behavior.
.It Fl \-enable-network-drivers
Do initialize network drivers.
This is the default behavior.
.It Fl \-firmware Ns = Ns Oo Sy bios "|" Sy efi "|" pc Oc
Informs the kernel the system is booted using
.Sy bios or
.Sy efi .
The
.Sy pc
value is a synonym for
.Sy bios .
.It Fl \-no-random-seed
Don't warn if no random seed file was loaded by the bootloader (usually from
.Pa /boot/random.seed ) .
This option is useful for live environments where this situation is unavoidable.
.It Fl \-term Ns = Ns Ar terminal
Set the
.Ev TERM
environment variable to the selected
.Ar terminal .
This option is useful in combination with selecting a serial line as the
.Fl \-console.
The default
.Ev TERM
is
.Sy sortix .
.El
.Pp
The kernel accepts multiboot modules from the bootloader, which are processed
in order.
The
.Xr initrd 7
must be passed through this mechanism.
.Pp
The format of each multiboot module is automatically detected by default:
.Pp
.Bl -bullet -compact
.It
.Xr tar 7
archives in the ustar format are extracted into the root directory.
The bootloader must already have decompressed the archive.
.El
.Pp
Each multiboot module has its own command line where the options are as follows:
.Bl -tag -width "12345678"
.It Fl \-append-to Ns "=" Ns Ar file
Append the contents of the module to the specifed
.Ar file ,
creating it with mode 644 if it doesn't exist.
Non-existent parent directories are created with mode 755 as needed.
.It Fl \-create-to Ns "=" Ns Ar file
Create the specified
.Ar file
with mode 644 with contents of the module, but only if it doesn't already exist.
No action is taken if the file already existed.
Non-existent parent directories are created with mode 755 as needed.
.It Fl \-random-seed
The module contains random data used to seed the kernel entropy gathering.
This file is supposed to contain 256 bytes of secret randomness that hasn't been
used before.
Recycling the random seed is dangerous and insecure.
Omitting the random seed will cause the kernel entropy to be collected in the
background, which will take some time and system usage before it is secure.
with the current time and other readily available information.
The bootloader normally loads the random seed from
.Pa /boot/random.seed .
.It Fl \-to Ns "=" Ns Ar file
Write the contents of the module to the specifed
.Ar file ,
creating it with mode 644 if it doesn't exist, and truncating it if it does exist.
Non-existent parent directories are created with mode 755 as needed.
.El
.Sh SEE ALSO
.Xr initrd 7 ,
.Xr init 8