diff --git a/stand/lua/Makefile b/stand/lua/Makefile index e8fa16e6b589..4462a803beef 100644 --- a/stand/lua/Makefile +++ b/stand/lua/Makefile @@ -1,33 +1,34 @@ .include MAN= loader.conf.lua.5 \ cli.lua.8 \ color.lua.8 \ config.lua.8 \ core.lua.8 \ drawer.lua.8 \ + gfx.lua.8 \ hook.lua.8 \ loader.lua.8 \ menu.lua.8 \ password.lua.8 \ screen.lua.8 FILESDIR= ${LUAPATH} FILES= cli.lua \ color.lua \ config.lua \ core.lua \ drawer.lua \ hook.lua \ loader.lua \ gfx-beastie.lua \ gfx-beastiebw.lua \ gfx-fbsdbw.lua \ gfx-orb.lua \ gfx-orbbw.lua \ menu.lua \ password.lua \ screen.lua .include diff --git a/stand/lua/gfx.lua.8 b/stand/lua/gfx.lua.8 new file mode 100644 index 000000000000..82d3f90f4af7 --- /dev/null +++ b/stand/lua/gfx.lua.8 @@ -0,0 +1,106 @@ +.\" +.\" Copyright (c) 2024 Netflix, Inc. +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.Dd February 6, 2024 +.Dt GFX.LUA 8 +.Os +.Sh NAME +.Nm gfx.lua +.Nd Fx Lua gfx module +.Sh DESCRIPTION +The built-in graphics related Lua bindings for the +.Fx +boot loaders using the Lua interpreter are available via the +.Ic gfx +table. +.Ss Exported Functions +The following functions are exported in the +.Nm loader +table. +.Bl -tag -width term_putimage +.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 +This table is optional and should only be used if it is non-nil and if +.Fn core.isFramebufferConsole +is true. +.Ss Compatibility +All the interfaces described above are also available via the +.Ic loader +table through at last FreeBSD 15.0. +.Sh SEE ALSO +.Xr loader.conf 5 , +.Xr core.lua 8 , +.Xr loader 8 , +.Xr loader.lua 8 +.Sh AUTHORS +The +.Nm +man page was written by +.An Warner Losh Aq Mt imp@FreeBSD.org . + diff --git a/stand/lua/loader.lua.8 b/stand/lua/loader.lua.8 index cd436255d4a5..ff3b91ddfb09 100644 --- a/stand/lua/loader.lua.8 +++ b/stand/lua/loader.lua.8 @@ -1,247 +1,192 @@ .\" .\" 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_ +.Ss Compatibility +The functions +.Fn fb_bezier , +.Fn fb_drawrect , +.Fn fb_line , +.Fn fb_putimage , +.Fn fb_set_pixel , +.Fn term_drawrect , and -.Fn term_ -are optional. -They should only be used if they are non-nil and if -.Fn core.isFramebufferConsole -is true. +.Fn term_putimage +have moved to the +.Ic gfx +table. +They remain in the +.Ic loader +table for a transition period and are documented in +.Xr gfx.lua 8 . .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 gfx.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.