mirror of
https://git.FreeBSD.org/src.git
synced 2024-10-18 02:19:39 +00:00
loader: Document the lua loader table.
Document all the public functions from the "loader" table. Sponsored by: Netflix Reviewed by: pauamma_gundo.com, tsoome, kevans Differential Revision: https://reviews.freebsd.org/D43701
This commit is contained in:
Warner Losh
parent
15483f9620
commit
621dae89f3
@ -8,6 +8,7 @@ MAN= loader.conf.lua.5 \
|
||||
core.lua.8 \
|
||||
drawer.lua.8 \
|
||||
hook.lua.8 \
|
||||
loader.lua.8 \
|
||||
menu.lua.8 \
|
||||
password.lua.8 \
|
||||
screen.lua.8
|
||||
|
||||
247
stand/lua/loader.lua.8
Normal file
247
stand/lua/loader.lua.8
Normal file
@ -0,0 +1,247 @@
|
||||
.\"
|
||||
.\" Copyright (c) 2024 Netflix, Inc.
|
||||
.\"
|
||||
.\" SPDX-License-Identifier: BSD-2-Clause
|
||||
.\"
|
||||
.Dd February 6, 2024
|
||||
.Dt LOADER.LUA 8
|
||||
.Os
|
||||
.Sh NAME
|
||||
.Nm loader.lua
|
||||
.Nd Fx Lua loader module
|
||||
.Sh DESCRIPTION
|
||||
The built-in Lua bindings for the
|
||||
.Fx
|
||||
boot loaders using the Lua interpreter
|
||||
are available via the
|
||||
.Ic loader
|
||||
table.
|
||||
.Pp
|
||||
The
|
||||
.Ic loader
|
||||
table is always available in Lua scripts.
|
||||
There is no need to require it like other loader-specific modules.
|
||||
.Ss Exported Variables
|
||||
The following variables are provided by the Lua interpreter in the
|
||||
.Nm loader
|
||||
table:
|
||||
.Bl -tag -width machine_arch
|
||||
.It Ic machine
|
||||
The target's
|
||||
.Va hw.machine
|
||||
.Xr sysctl 8
|
||||
value.
|
||||
.It Ic machine_arch
|
||||
The target's
|
||||
.Va hw.machine_arch
|
||||
.Xr sysctl 8
|
||||
value.
|
||||
Some boot loaders are 32-bit applications that then load a 64-bit
|
||||
kernel.
|
||||
In these cases,
|
||||
.Ic machine_arch
|
||||
represents the 32-bit architecture, not the 64-bit architecture.
|
||||
.It Ic lua_path
|
||||
The current lua loading path.
|
||||
.It Ic version
|
||||
The version of the boot program.
|
||||
.El
|
||||
.Ss Exported Functions
|
||||
The following functions are exported in the
|
||||
.Nm loader
|
||||
table.
|
||||
.Bl -tag -width term_putimage
|
||||
.It Fn delay usec
|
||||
Delay for
|
||||
.Va usec
|
||||
microseconds.
|
||||
.It Fn command_error
|
||||
Returns the error string from the last command to fail.
|
||||
.It Fn command argc argv
|
||||
Like
|
||||
.Fn perform
|
||||
but the arguments are already parsed onto the stack.
|
||||
.It Fn interpret str
|
||||
Execute the loader builtin command
|
||||
.Va str
|
||||
as if it were typed by the user.
|
||||
This will first try to execute
|
||||
.Va str
|
||||
as Lua.
|
||||
If that fails, it will attempt to execute it as a cli command,
|
||||
including those defined by the
|
||||
.Xr cli.lua 8
|
||||
mechanism.
|
||||
If that fails, it will attempt to execute it as a builtin command
|
||||
and return the same values as
|
||||
.Fn perform .
|
||||
.It Fn parse str
|
||||
Parses the command
|
||||
.Va str
|
||||
into its words and return those words on the stack.
|
||||
.It Fn getenv name
|
||||
Obtains the value of the environment variable
|
||||
.Va name .
|
||||
.It Fn has_command cmd
|
||||
returns
|
||||
.Va true
|
||||
if
|
||||
.Va commmand
|
||||
is present in the interpreter as a builtin.
|
||||
Otherwise it returns
|
||||
.Va nil
|
||||
and an error string.
|
||||
It does not check the
|
||||
.Dq cli
|
||||
table to see if a user defined command has been created.
|
||||
.It Fn has_feature feature
|
||||
returns
|
||||
.Va true
|
||||
if the
|
||||
.Va feature
|
||||
is enabled.
|
||||
Otherwise it returns
|
||||
.Va nil
|
||||
and an error string.
|
||||
.It Fn perform str
|
||||
Execute the loader builtin command
|
||||
.Va str .
|
||||
Returns the result of the command, one of the following values:
|
||||
.Bl -tag -width loader -offset indent
|
||||
.It loader.CMD_OK
|
||||
The command completed successfully.
|
||||
.It loader.CMD_WARN
|
||||
The command was successful, but the user stopped its output
|
||||
prematurely.
|
||||
.It loader.CMD_ERROR
|
||||
The command did not complete successfully.
|
||||
Use
|
||||
.Va command_error
|
||||
to retrieve the error.
|
||||
.It loader.CMD_CRIT
|
||||
The command returned a critical error that was already printed.
|
||||
.It loader.CMD_FATAL
|
||||
The command determined continuation was not possible
|
||||
and the loader panicked.
|
||||
In practice, though,
|
||||
.Fn panic
|
||||
does not return.
|
||||
.El
|
||||
.It Fn printc str
|
||||
Outputs the string using the loader's
|
||||
.Fn putchar
|
||||
function.
|
||||
This function is also available globally as
|
||||
.Fn printc .
|
||||
.It Fn setenv name value
|
||||
Insert or reset the environment variable
|
||||
.Va name
|
||||
into the loader's environment list.
|
||||
If no environment variable with this name exists, one is created.
|
||||
If one exists, its value is replaced.
|
||||
.It Fn time
|
||||
Returns the loader's notion of time, in seconds since 1970.
|
||||
The value of loader's notion varies somewhat between different loading
|
||||
environments.
|
||||
.It Fn unsetenv name
|
||||
Removes the environment variable
|
||||
.Va name
|
||||
from the loader's environment list.
|
||||
.It Fn fb_bezier x0 y0 x1 y1 x2 y2 width
|
||||
Draw a bezier curve through the points
|
||||
.Pq Va x0 , Va y0 ,
|
||||
.Pq Va x1 , Va y1 ,
|
||||
and
|
||||
.Pq Va x2 , Va y2
|
||||
of width
|
||||
.Va width .
|
||||
The units are in pixels and have an origin of
|
||||
.Pq 0 , 0 .
|
||||
.It Fn fb_drawrect x0 y0 x1 y1 fill
|
||||
Fill in a rectangle with the pixel
|
||||
.Va fill
|
||||
with the corners
|
||||
.Pq Va x0 , Va y0
|
||||
and
|
||||
.Pq Va x1 , Va y1 .
|
||||
The units are in pixels and have an origin of
|
||||
.Pq 0 , 0 .
|
||||
.It Fn fb_line x0 y0 x1 y1 width
|
||||
Draw a line from
|
||||
.Pq Va x0 , Va y0
|
||||
to
|
||||
.Pq Va x1 , Va y1
|
||||
with a width of
|
||||
.Va width .
|
||||
The units are in pixels and have an origin of
|
||||
.Pq 0 , 0 .
|
||||
.It Fn fb_putimage name x0 y0 x1 y1 f
|
||||
Load the PNG file
|
||||
.Va name
|
||||
and place it in the rectangle
|
||||
with the corners
|
||||
.Pq Va x0 , Va y0
|
||||
and
|
||||
.Pq Va x1 , Va y1
|
||||
and fill with pixel
|
||||
.Va f .
|
||||
The units are in pixels and have an origin of
|
||||
.Pq 0 , 0 .
|
||||
.It Fn fb_set_pixel x y
|
||||
Sets the pixel at
|
||||
.Pq Va x , Va y .
|
||||
The units are in pixels and have an origin of
|
||||
.Pq 0 , 0 .
|
||||
.It Fn term_drawrect x0 y0 x1 y1
|
||||
Draw the outline of a rectangle with the text coordinate corners of
|
||||
.Pq Va x0 , Va y0
|
||||
and
|
||||
.Pq Va x1 , Va y1 .
|
||||
The units are in character cells and have an origin of
|
||||
.Pq 1 , 1 .
|
||||
.It Fn term_putimage name x0 y0 x1 y1 f
|
||||
Load the PNG file
|
||||
.Va name
|
||||
and place it in the rectangle
|
||||
with the text coordinate corners
|
||||
.Pq Va x0 , Va y0
|
||||
and
|
||||
.Pq Va x1 , Va y1
|
||||
and fill with pixel
|
||||
.Va f .
|
||||
The units are in character cells and have an origin of
|
||||
.Pq 1 , 1 .
|
||||
.El
|
||||
.Pp
|
||||
The functions starting with
|
||||
.Fn fb_
|
||||
and
|
||||
.Fn term_
|
||||
are optional.
|
||||
They should only be used if they are non-nil and if
|
||||
.Fn core.isFramebufferConsole
|
||||
is true.
|
||||
.Ss Default File
|
||||
In addition, the Lua interpreters start with the file
|
||||
.Pa /boot/lua/loader.lua
|
||||
when they start to boot the system.
|
||||
The default one will fixup the screen, load the configuration files, check for a
|
||||
password, and then load the menu or load the kernel file and then return.
|
||||
If autoboot is enabled, the loaded files will boot.
|
||||
.Sh SEE ALSO
|
||||
.Xr loader.conf 5 ,
|
||||
.Xr core.lua 8 ,
|
||||
.Xr loader 8 ,
|
||||
.Xr sysctl 8
|
||||
.Sh AUTHORS
|
||||
The
|
||||
.Nm
|
||||
man page was written by
|
||||
.An Warner Losh Aq Mt imp@FreeBSD.org .
|
||||
.Sh BUGS
|
||||
.Fn command
|
||||
and
|
||||
.Fn perform
|
||||
should return a tuple when there's
|
||||
.Va CMD_ERROR
|
||||
or worse.
|
||||
Loading…
Reference in New Issue
Block a user