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 interpret str 65Execute the loader builtin command 66.Va str 67as if it were typed by the user. 68This will first try to execute 69.Va str 70as Lua. 71If that fails, it will attempt to execute it as a cli command, 72including those defined by the 73.Xr cli.lua 8 74mechanism. 75If that fails, it will attempt to execute it as a builtin command 76and return the same values as 77.Fn perform . 78.It Fn parse str 79Parses the command 80.Va str 81into its words and return those words on the stack. 82.It Fn getenv name 83Obtains the value of the environment variable 84.Va name . 85.It Fn has_command cmd 86returns 87.Va true 88if 89.Va commmand 90is present in the interpreter as a builtin. 91Otherwise it returns 92.Va nil 93and an error string. 94It does not check the 95.Dq cli 96table to see if a user defined command has been created. 97.It Fn has_feature feature 98returns 99.Va true 100if the 101.Va feature 102is enabled. 103Otherwise it returns 104.Va nil 105and an error string. 106.It Fn perform str 107Execute the loader builtin command 108.Va str . 109Returns the result of the command, one of the following values: 110.Bl -tag -width loader -offset indent 111.It loader.CMD_OK 112The command completed successfully. 113.It loader.CMD_WARN 114The command was successful, but the user stopped its output 115prematurely. 116.It loader.CMD_ERROR 117The command did not complete successfully. 118Use 119.Va command_error 120to retrieve the error. 121.It loader.CMD_CRIT 122The command returned a critical error that was already printed. 123.It loader.CMD_FATAL 124The command determined continuation was not possible 125and the loader panicked. 126In practice, though, 127.Fn panic 128does not return. 129.El 130.It Fn printc str 131Outputs the string using the loader's 132.Fn putchar 133function. 134This function is also available globally as 135.Fn printc . 136.It Fn setenv name value 137Insert or reset the environment variable 138.Va name 139into the loader's environment list. 140If no environment variable with this name exists, one is created. 141If one exists, its value is replaced. 142.It Fn time 143Returns the loader's notion of time, in seconds since 1970. 144The value of loader's notion varies somewhat between different loading 145environments. 146.It Fn unsetenv name 147Removes the environment variable 148.Va name 149from the loader's environment list. 150.El 151.Ss Compatibility 152The functions 153.Fn fb_bezier , 154.Fn fb_drawrect , 155.Fn fb_line , 156.Fn fb_putimage , 157.Fn fb_set_pixel , 158.Fn term_drawrect , 159and 160.Fn term_putimage 161have moved to the 162.Ic gfx 163table. 164They remain in the 165.Ic loader 166table for a transition period and are documented in 167.Xr gfx.lua 8 . 168.Ss Default File 169In addition, the Lua interpreters start with the file 170.Pa /boot/lua/loader.lua 171when they start to boot the system. 172The default one will fixup the screen, load the configuration files, check for a 173password, and then load the menu or load the kernel file and then return. 174If autoboot is enabled, the loaded files will boot. 175.Sh SEE ALSO 176.Xr loader.conf 5 , 177.Xr core.lua 8 , 178.Xr gfx.lua 8 , 179.Xr loader 8 , 180.Xr sysctl 8 181.Sh AUTHORS 182The 183.Nm 184man page was written by 185.An Warner Losh Aq Mt imp@FreeBSD.org . 186.Sh BUGS 187.Fn command 188and 189.Fn perform 190should return a tuple when there's 191.Va CMD_ERROR 192or worse. 193