1.\" 2.\" Copyright (c) 2024 Netflix, Inc. 3.\" 4.\" SPDX-License-Identifier: BSD-2-Clause 5.\" 6.Dd February 6, 2024 7.Dt LOADER.LUA 8 8.Os 9.Sh NAME 10.Nm loader.lua 11.Nd Fx Lua loader module 12.Sh DESCRIPTION 13The built-in Lua bindings for the 14.Fx 15boot loaders using the Lua interpreter 16are available via the 17.Ic loader 18table. 19.Pp 20The 21.Ic loader 22table is always available in Lua scripts. 23There is no need to require it like other loader-specific modules. 24.Ss Exported Variables 25The following variables are provided by the Lua interpreter in the 26.Nm loader 27table: 28.Bl -tag -width machine_arch 29.It Ic machine 30The target's 31.Va hw.machine 32.Xr sysctl 8 33value. 34.It Ic machine_arch 35The target's 36.Va hw.machine_arch 37.Xr sysctl 8 38value. 39Some boot loaders are 32-bit applications that then load a 64-bit 40kernel. 41In these cases, 42.Ic machine_arch 43represents the 32-bit architecture, not the 64-bit architecture. 44.It Ic lua_path 45The current lua loading path. 46.It Ic version 47The version of the boot program. 48.El 49.Ss Exported Functions 50The following functions are exported in the 51.Nm loader 52table. 53.Bl -tag -width term_putimage 54.It Fn delay usec 55Delay for 56.Va usec 57microseconds. 58.It Fn command_error 59Returns the error string from the last command to fail. 60.It Fn command argc argv 61Like 62.Fn perform 63but the arguments are already parsed onto the stack. 64.It Fn exit status 65Exit the boot loader back to the firmware with a status of 66.Va status . 67The interpretation of this value is firmware specific. 68.It Fn interpret str 69Execute the loader builtin command 70.Va str 71as if it were typed by the user. 72This will first try to execute 73.Va str 74as Lua. 75If that fails, it will attempt to execute it as a cli command, 76including those defined by the 77.Xr cli.lua 8 78mechanism. 79If that fails, it will attempt to execute it as a builtin command 80and return the same values as 81.Fn perform . 82.It Fn parse str 83Parses the command 84.Va str 85into its words and return those words on the stack. 86.It Fn getenv name 87Obtains the value of the environment variable 88.Va name . 89.It Fn has_command cmd 90returns 91.Va true 92if 93.Va commmand 94is present in the interpreter as a builtin. 95Otherwise it returns 96.Va nil 97and an error string. 98It does not check the 99.Dq cli 100table to see if a user defined command has been created. 101.It Fn has_feature feature 102returns 103.Va true 104if the 105.Va feature 106is enabled. 107Otherwise it returns 108.Va nil 109and an error string. 110.It Fn perform str 111Execute the loader builtin command 112.Va str . 113Returns the result of the command, one of the following values: 114.Bl -tag -width loader -offset indent 115.It loader.CMD_OK 116The command completed successfully. 117.It loader.CMD_WARN 118The command was successful, but the user stopped its output 119prematurely. 120.It loader.CMD_ERROR 121The command did not complete successfully. 122Use 123.Va command_error 124to retrieve the error. 125.It loader.CMD_CRIT 126The command returned a critical error that was already printed. 127.It loader.CMD_FATAL 128The command determined continuation was not possible 129and the loader panicked. 130In practice, though, 131.Fn panic 132does not return. 133.El 134.It Fn printc str 135Outputs the string using the loader's 136.Fn putchar 137function. 138This function is also available globally as 139.Fn printc . 140.It Fn setenv name value 141Insert or reset the environment variable 142.Va name 143into the loader's environment list. 144If no environment variable with this name exists, one is created. 145If one exists, its value is replaced. 146.It Fn time 147Returns the loader's notion of time, in seconds since 1970. 148The value of loader's notion varies somewhat between different loading 149environments. 150.It Fn unsetenv name 151Removes the environment variable 152.Va name 153from the loader's environment list. 154.El 155.Ss Compatibility 156The functions 157.Fn fb_bezier , 158.Fn fb_drawrect , 159.Fn fb_line , 160.Fn fb_putimage , 161.Fn fb_set_pixel , 162.Fn term_drawrect , 163and 164.Fn term_putimage 165have moved to the 166.Ic gfx 167table. 168They remain in the 169.Ic loader 170table for a transition period and are documented in 171.Xr gfx.lua 8 . 172.Ss Default File 173In addition, the Lua interpreters start with the file 174.Pa /boot/lua/loader.lua 175when they start to boot the system. 176The default one will fixup the screen, load the configuration files, check for a 177password, and then load the menu or load the kernel file and then return. 178If autoboot is enabled, the loaded files will boot. 179.Sh SEE ALSO 180.Xr loader.conf 5 , 181.Xr core.lua 8 , 182.Xr gfx.lua 8 , 183.Xr loader 8 , 184.Xr sysctl 8 185.Sh AUTHORS 186The 187.Nm 188man page was written by 189.An Warner Losh Aq Mt imp@FreeBSD.org . 190.Sh BUGS 191.Fn command 192and 193.Fn perform 194should return a tuple when there's 195.Va CMD_ERROR 196or worse. 197