diff --git a/stand/lua/cli.lua.8 b/stand/lua/cli.lua.8 index 4077ca6b0b56..aee1d3d53579 100644 --- a/stand/lua/cli.lua.8 +++ b/stand/lua/cli.lua.8 @@ -1,158 +1,158 @@ .\" .\" SPDX-License-Identifier: BSD-2-Clause .\" .\" Copyright (c) 2018 Kyle Evans .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd July 24, 2021 +.Dd March 29, 2025 .Dt CLI.LUA 8 .Os .Sh NAME .Nm cli.lua -.Nd FreeBSD Lua CLI module +.Nd bootloader command line interpreter module .Sh DESCRIPTION .Nm contains the main functionality required to add new CLI commands, which can be executed at the loader prompt. .Pp Before hooking into the functionality provided by .Nm , it must be included with a statement such as the following: .Pp .Dl local cli = require("cli") .Ss Adding new commands New loader commands may be created by adding functions to the object returned by requiring the .Nm module. .Pp For instance: .Pp .Bd -literal -offset indent -compact local cli = require("cli") cli.foo = function(...) -- Expand args to command name and the rest of argv. These arguments -- are pushed directly to the stack by loader, then handed off to -- cli_execute. cli_execute then passes them on to the invoked -- function, where they appear as varargs that must be peeled apart into -- their respective components. local _, argv = cli.arguments(...) print("This is the foo command!") for k, v in ipairs(argv) do print("arg #" .. tostring(k) .. ": '" .. v .. "'") end -- Perform a loader command directly. This will not get dispatched back -- to Lua, so it is acceptable to have a function of the exact same name -- in loader. Lua will have the first chance to handle any commands -- executed at the loader prompt. loader.perform("foo") end .Ed .Pp This function may be invoked by a user at the loader prompt by simply typing .Ic foo . Arguments may be passed to it as usual, space-delimited. .Ss Default Commands The .Nm module provides the following default commands: .Bl -bullet .\"-width toggle-module -offset indent .It .Ic autoboot .It .Ic boot .It .Ic boot-conf .It .Ic reload-conf .It .Ic disable-device .It .Ic disable-module .It .Ic enable-module .It .Ic toggle-module .It .Ic show-module-options .El .Pp For .Ic autoboot , .Ic boot , and .Ic boot-conf , the .Xr core.lua 8 module will load all ELF modules as-needed before executing the equivalent built-in loader commands. All non-kernel arguments to these commands are passed in the same order to the loader command. .Pp The .Ic reload-conf command will reload the configuration from disk. This is useful if you have manually changed currdev and would like to easily reload the configuration from the new device. .Pp The .Ic enable-module , .Ic disable-module , and .Ic toggle-module commands manipulate the list of modules to be loaded along with the kernel. Modules blacklisted are considered disabled by .Ic toggle-module . These commands will override any such restriction as needed. The .Ic show-module-options command will dump the list of modules that loader has been made aware of and any applicable options using paged output. .Pp The .Ic disable-device command sets the environment variable that disables the device argument. .Ss Exported Functions The following functions are exported from .Nm : .Bl -tag -width cli.arguments -offset indent .It Fn cli.arguments ... Takes varargs passed on the stack from .Xr loader 8 to .Ic cli_execute , splits them out into two return values: the command name, traditionally argv[0], and the rest of argv. .El .Sh SEE ALSO .Xr loader.conf 5 , .Xr core.lua 8 , .Xr loader 8 .Sh AUTHORS The .Nm file was originally written by .An Kyle Evans Aq Mt kevans@FreeBSD.org . diff --git a/stand/lua/color.lua.8 b/stand/lua/color.lua.8 index 8a31d2034a48..9a3b9b1b9385 100644 --- a/stand/lua/color.lua.8 +++ b/stand/lua/color.lua.8 @@ -1,130 +1,130 @@ .\" .\" SPDX-License-Identifier: BSD-2-Clause .\" .\" Copyright (c) 2018 Kyle Evans .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd August 19, 2018 +.Dd March 29, 2025 .Dt COLOR.LUA 8 .Os .Sh NAME .Nm color.lua -.Nd FreeBSD color module +.Nd bootloader color module .Sh DESCRIPTION .Nm contains functionality for working with colors. .Pp Before using the functionality provided by .Nm , it must be included with a statement such as the following: .Pp .Dl local color = require("color") .Pp The following color constants are exported from .Nm : .Bl -tag -width "Ic color.MAGENTA" -offset indent .It Ic color.BLACK .It Ic color.RED .It Ic color.GREEN .It Ic color.YELLOW .It Ic color.BLUE .It Ic color.MAGENTA .It Ic color.CYAN .It Ic color.WHITE .El .Pp The following attribute constants are exported from .Nm : .Bl -tag -width "Ic color.DEFAULT" -offset indent .It Ic color.DEFAULT .It Ic color.BRIGHT .It Ic color.DIM .El .Pp The following functions are exported from .Nm : .Bl -tag -width "Fn color.isEnabled" -offset indent .It Fn color.isEnabled Returns True if .Xr loader 8 has been configured to not allow color, False otherwise. This checks the .Ev loader_color .Xr loader.conf 5 variable, along with .Fn core.isSerialBoot . .It Fn color.escapefg color_value Returns the escape sequence that encodes .Fa color_value as a foreground color. .Fn color.escapefg returns an empty string if color is disabled. .It Fn color.resetfg Returns the escape sequence for the default foreground color. .Fn color.resetfg returns an empty string if color is disabled. .It Fn color.escapebg color_value Returns the escape sequence that encodes .Fa color_value as a background color. .Fn color.escapebg returns an empty string if color is disabled. .It Fn color.resetbg Returns the escape sequence for the default background color. .Fn color.resetbg returns an empty string if color is disabled. .It Fn color.escape fg_color bg_color attribute Returns an escape sequence that encodes .Fa fg_color as the foreground color, .Fa bg_color as the background color, and .Fa attribute applied. .Fn color.escape returns an empty string if color is disabled. .It Fn color.default Returns the escape sequence for the default color scheme, white on black with no attributes applied. .Fn color.default returns an empty string if color is disabled. .It Fn color.highlight str Returns .Fa str with the .Ic color.BRIGHT attribute applied before it and reset after it. .Fn color.highlight returns .Fa str if color is disabled. .El .Sh SEE ALSO .Xr screen.lua 8 .Sh AUTHORS The .Nm file was originally written by .An Pedro Souza Aq Mt pedrosouza@FreeBSD.org . Later work and this manual page was done by .An Kyle Evans Aq Mt kevans@FreeBSD.org . diff --git a/stand/lua/config.lua.8 b/stand/lua/config.lua.8 index b2b1122285eb..7e8863203446 100644 --- a/stand/lua/config.lua.8 +++ b/stand/lua/config.lua.8 @@ -1,246 +1,246 @@ .\" .\" SPDX-License-Identifier: BSD-2-Clause .\" .\" Copyright (c) 2018 Kyle Evans .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd December 17, 2020 +.Dd March 29, 2025 .Dt CONFIG.LUA 8 .Os .Sh NAME .Nm config.lua -.Nd FreeBSD config module +.Nd bootloader configuration module .Sh DESCRIPTION .Nm contains configuration and module loading functionality. .Pp Before hooking into or using the functionality provided by .Nm , it must be included with a statement such as the following: .Pp .Dl local config = require("config") .Ss Exported functions The following functions are exported from .Nm : .Bl -tag -width "config.setCarouselIndex(id, idx)" -offset indent .It Fn config.getCarouselIndex id Returns the currently chosen index in the carousel menu entry described by .Ev id . See the definition of .Xr menu.lua 8 for a more in-depth explanation of carousels. .It Fn config.setCarouselIndex id idx Set the chosen index for the carousel menu entry described by .Ev id to .Ev idx . A lookup will be done as needed to determine what value .Ev idx actually corresponds to. .It Fn config.readConf file loaded_files Process .Pa file as a configuration file .Po e.g., as .Pa loader.conf .Pc and then process files listed in the .Ev loader_conf_files variable. Additionnaly, the top-level call to readConf will process files listed in the .Ev loader_conf_dirs and .Ev local_loader_conf_files variables .Po see .Xr loader.conf 5 .Pc . The caller may optionally pass in a table as the .Ev loaded_files argument, which uses filenames as keys and any non-nil value to indicate that the file named by the key has already been loaded and should not be loaded again. .It Fn config.processFile name silent Process and parse .Ev name as a configuration file. Returns true if .Ev name exists and parses without error, false otherwise. If .Ev silent is true, .Fn config.processFile will not consider a failure to read the file as a failure. .It Fn config.parse text Parse .Ev text as a configuration file. This is used internally by .Fn config.processFile to parse the contents of a configuration file. Returns true if parsing succeeds without error, false if an error occurred. A message is also printed to the console if an error is encountered. .It Fn config.loadKernel other_kernel Attempts to load .Ev other_kernel as a kernel. If .Ev other_kernel is unset .Fn config.loadKernel will attempt to load .Dq kernel . Otherwise, it will try to load .Dq kernel first from .Pa /boot/{other_kernel} , then from .Pa {other_kernel} . .Pp The latter is tried in case an absolute path has been specified to the kernel to use. .Ev module_path is amended to include the directory the kernel was found in if either of these paths result in a loaded kernel. .Pp If no kernel was loaded from either of these paths, .Fn config.loadKernel will attempt to load a kernel named .Dq {other_kernel} from .Ev module_path instead of attempting to load a kernel named .Dq kernel . .Pp Returns true if a kernel was loaded, false if no kernel was loaded. .It Fn config.selectKernel kernel Set .Ev kernel to the kernel that will be loaded when either .Ic autoboot or .Ic boot are invoked. This is usually called by the menu system as the kernel selector carousel is toggled through. .It Fn config.load file reload Loads .Ev file as a configuration file. If .Ev file is not specified, .Pa /boot/defaults/loader.conf is used. .Fn config.load will then silently attempt to process any files specified in .Ev loader_conf_files after .Ev file has been processed. .Xr nextboot 8 configuration will also be checked as part of .Fn config.load . Before returning, all .Dq config.loaded hooks will be run if .Ev reload is not set to true. .It Fn config.reload file Reloads .Ev file as a configuration file. .Fn config.reload will restore the environment to how it existed before the last config was loaded, then it will invoke .Fn config.load file . Before returning, all .Dq config.reloaded hooks will be run. .It Fn config.loadelf Loads all ELF objects, the selected kernel as well as any modules configured to be preloaded in .Xr loader.conf 5 . This will be called by the Lua intercepted .Ic autoboot and .Ic boot commands. .It Fn config.enableModule modname Marks a module named .Fa modname to be loaded during .Fn config.loadelf . If the module was previously blacklisted, then it will be forcefully allowed to load. .It Fn config.disableModule modname Marks a module named .Fa modname to not be loaded during .Fn config.loadelf . .It Fn config.isModuleEnabled modname Checks if the module named .Fa modname will be loaded during .Fn config.loadelf . It checks both that the module is marked for loading and that it is either forced or not blacklisted. .It Fn config.getModuleInfo Returns a table with .Dq modules and .Dq blacklist tables describing the modules that the config module has been made aware of via .Xr loader.conf 5 as well as a representation of .Ar module_blacklist . .El .Ss Defined Hooks The following hooks are defined in .Nm : .Bl -tag -width "config.reloaded" -offset indent .It Fn config.buildenv env .It Fn config.loaded .It Fn config.reloaded .It Fn kernel.loaded .It Fn modules.loaded .El .Pp Note that the .Fn config.buildenv hook is only invoked when an environment needs to be built to execute a lua configuration file that has been specified in .Ev loader_conf_files . It will be invoked for each configuration file encountered. .Sh SEE ALSO .Xr loader.conf 5 , .Xr loader 8 , .Xr menu.lua 8 , .Xr nextboot 8 .Sh AUTHORS The .Nm file was originally written by .An Pedro Souza Aq Mt pedrosouza@FreeBSD.org . Later work and this manual page was done by .An Kyle Evans Aq Mt kevans@FreeBSD.org . diff --git a/stand/lua/core.lua.8 b/stand/lua/core.lua.8 index 208dbf5e12c9..de43d3e2b220 100644 --- a/stand/lua/core.lua.8 +++ b/stand/lua/core.lua.8 @@ -1,236 +1,236 @@ .\" .\" SPDX-License-Identifier: BSD-2-Clause .\" .\" Copyright (c) 2018 Kyle Evans .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd December 28, 2023 +.Dd March 29, 2025 .Dt CORE.LUA 8 .Os .Sh NAME .Nm core.lua -.Nd FreeBSD core module +.Nd bootloader core module .Sh DESCRIPTION .Nm contains core functionality that does not have a more fitting module. .Pp Before hooking into or using the functionality provided by .Nm , it must be included with a statement such as the following: .Pp .Dl local core = require("core") .Ss CONSTANTS The following raw key code constants are defined in .Nm : .Bl -tag -width KEY_BACKSPACE -compact -offset indent .It Ic KEY_BACKSPACE The backspace code. Should generally be checked along with .Ic KEY_DELETE for backspace functionality. .It Ic KEY_ENTER The enter key, or hard return. .It Ic KEY_DELETE The delete code. Should generally be checked along with .Ic KEY_BACKSPACE for backspace functionality. .El .Pp The following key-string constants are defined in .Nm : .Bl -tag -width KEYSTR_ESCAPE -compact -offset indent .It Ic KEYSTR_ESCAPE The escape key. .It Ic KEYSTR_CSI The ANSI CSI sequence. .El .Pp The following menu entry type constants are defined in .Nm : .Bl -tag -width MENU_CAROUSEL_ENTRY -compact -offset indent .It Ic MENU_RETURN Return to the parent menu. .It Ic MENU_ENTRY A normal menu entry. .It Ic MENU_SEPARATOR A menu entry that serves as a separator. .It Ic MENU_SUBMENU A menu entry that opens a submenu when selected. .It Ic MENU_CAROUSEL_ENTRY A menu entry that rotates through items like a carousel upon selection of the menu entry. .El .Pp Please see .Xr menu.lua 8 for extended descriptions and usage of the .Ic MENU_* constants. .Ss Exported functions The following functions are exported from .Nm : .Bl -tag -width core.setSingleUser -offset indent .It Fn core.setVerbose verbose Sets or unsets .Ev boot_verbose . If .Fa verbose is omitted, toggle the current verbose setting. .It Fn core.setSingleUser singleUser Sets or unsets .Ev boot_single . If .Fa singleUser is omitted, toggle the current single user setting. .It Fn core.getACPI Return true if ACPI is both present and not explicitly disabled by .Ev hints.acpi.0.disabled . .It Fn core.hasACPI Checks whether ACPI support is present. This requires the loader to probe the system and set .Ev acpi.rsdp early before starting the interpreter. .It Fn core.setACPI acpi Sets or unsets .Ev acpi_load , .Ev hint.acpi.0.disabled , and .Ev loader.acpi_disabled_by_user . If .Fa acpi is omitted, toggle the current ACPI setting. .It Fn core.setSafeMode safeMode Set the safe mode setting. Sets or unsets .Ev kern.smp.disabled , .Ev hw.ata.ata_dma , .Ev hw.ata.atapi_dma , .Ev kern.eventtimer.periodic , and .Ev kern.geom.part.check_integrity . If .Fa safeMode is omitted, toggle the current safe mode setting. .It Fn core.clearCachedKernels Clears out the cache of kernels to be displayed on the boot menu. This function is registered as a .Ev config.reloaded hook. It is used to invalidate the kernel list whenever it may have changed, either due to a boot environment change or a potential change in either .Ic kernel or .Ic kernels . .It Fn core.hasFeature featureName Checks whether the named .Fa featureName is enabled in the current loader. This is specifically used for detecting capabilities of the loaded loader binary, so that one can reasonably implement backwards compatibility shims if needed. .It Fn core.kernelList Returns a table of kernels to display on the boot menu. This will combine .Ic kernel and .Ic kernels from .Xr loader.conf 5 . If .Ic kernels_autodetect is set in .Xr loader.conf 5 , kernels will be autodetected from the current system. .It Fn core.bootenvDefault Returns the default boot environment, nil if unset. .It Fn core.bootenvList Returns a table of boot environments, or an empty table. These will be picked up using the .Ev bootenvs and .Ev bootenvs_count variables set by .Xr loader 8 . .It Fn core.setDefaults Resets ACPI, safe mode, single user, and verbose settings to their system defauilts. .It Fn core.autoboot argstr Loads the kernel and specified modules, then invokes the .Ic autoboot .Xr loader 8 command with .Fa argstr as-is. .It Fn core.boot argstr Loads the kernel and specified modules, then invokes the .Ic boot .Xr loader 8 command with .Fa argstr as-is. .It Fn core.isSingleUserBoot Returns true if .Ev boot_single is set to yes. .It Fn core.isZFSBoot Returns true if .Ev currdev is set to a .Xr zfs 8 dataset. .It Fn core.isSerialBoot Returns true if we are booting over serial. This checks .Ev console , .Ev boot_serial , and .Ev boot_multicons . .It Fn core.deepCopyTable tbl Recursively deep copies .Fa tbl and returns the result. .It Fn core.popFrontTable tbl Pops the front element off of .Fa tbl , and returns two return values: the front element, and the rest of the table. If there are no elements, this returns nil and nil. If there is one element, this returns the front element and an empty table. This will not operate on truly associative tables; numeric indices are required. .It Fn core.loaderTooOld Returns true if the loader is too old. Specifically, this means, is the loader old enough to require one or more workarounds in the current lua base modules. .El .Sh SEE ALSO .Xr loader.conf 5 , .Xr loader 8 , .Xr menu.lua 8 .Sh AUTHORS The .Nm file was originally written by .An Pedro Souza Aq Mt pedrosouza@FreeBSD.org . Later work and this manual page was done by .An Kyle Evans Aq Mt kevans@FreeBSD.org . diff --git a/stand/lua/drawer.lua.8 b/stand/lua/drawer.lua.8 index a3a4865d3efe..91738f4b2434 100644 --- a/stand/lua/drawer.lua.8 +++ b/stand/lua/drawer.lua.8 @@ -1,177 +1,177 @@ .\" .\" SPDX-License-Identifier: BSD-2-Clause .\" .\" Copyright (c) 2018 Kyle Evans .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd August 19, 2018 +.Dd March 29, 2025 .Dt DRAWER.LUA 8 .Os .Sh NAME .Nm drawer.lua -.Nd FreeBSD menu/screen drawer module +.Nd bootloader menu/screen drawer module .Sh DESCRIPTION .Nm contains functionality for drawing and manipulating the menu, logo, and brand to the screen. .Pp Before using the functionality provided by .Nm , it must be included with a statement such as the following: .Pp .Dl local drawer = require("drawer") .Ss BRAND DEFINITIONS Brand definitions describe a .Dq brand , traditionally drawn above the menu. The exact position may be controlled by using the .Xr loader.conf 5 variables .Va loader_brand_x and .Va loader_brand_y . The following keys may be defined for a brand definition: .Bl -tag -width ".Ic Graphic" -offset indent .It Ic graphic A table of strings containing rows of text to be drawn to the screen. .El .Ss LOGO DEFINITIONS Logo definitions describe a .Dq logo , traditionally to the right of the menu. The exact position may be controlled by using the .Xr loader.conf 5 variables .Va loader_logo_x and .Va loader_logo_y . The following keys may be defined for a logo definition: .Bl -tag -width ".Ic requires_color" -offset indent .It Ic requires_color A boolean describing whether or not this logo definition requires color. If it is chosen to be drawn and it requires color on a color-disabled boot, .Nm will elect to use the default .Dq orbbw logo rather than the chosen logo. .It Ic graphic A table of strings containing rows of text to be drawn to the screen. .It Ic shift A table describing the .Va x and .Va y shift that should be applied to all elements should this logo be selected. This is typically used for shifting the menu and brand if an empty or minimal logo are selected. .El .Ss CUSTOM BRANDS AND LOGOS The brand and logo system is designed to allow brands and logos to be easily plugged in. When an unrecognized .Ev loader_brand or .Ev loader_logo are encountered, .Nm will attempt to include .Pa brand-${loader_brand}.lua or .Pa logo-${loader_logo}.lua respectively. These files are expected to call either .Fn drawer.addBrand or .Fn drawer.addLogo to add the requested branddef or logodef. .Nm will attempt to do another lookup for the requested brand or logo before falling back to one of the following: .Bl -tag -width ".Ic drawer.default_color_logodef" -offset indent .It Ic drawer.default_brand The default brand to be used if the requested brand cannot be located. .It Ic drawer.default_color_logodef The default logodef to be used if an invalid logodef is requested and .Xr loader 8 has been configured to allow output of color. .It Ic drawer.default_bw_logodef The default logodef to be used if either an invalid logodef has been requested, or a logodef has been requested that requires color and .Xr loader 8 has been configured to not output color. .El .Ss FRAME STYLES .Nm contains the definitions for the different frame styles that may be drawn around the menu. Frame styles define the characters drawn for horizontal lines, vertical aligns, and each of the four corner styles. The following keys may be defined for a frame style: .Bl -bullet -width "" .It horizontal .It vertical .It top_left .It bottom_left .It top_right .It bottom_right .El Frame styles are currently defined in the table .Ic drawer.frame_styles indexed by the name used for .Ev loader_menu_frame . No API currently exists for manipulating this table indirectly. .Ss Exported functions The following functions are exported from .Nm : .Bl -tag -width hook.registerType -offset indent .It Fn drawer.addBrand name def Add the brand definition described by .Fa def to the table of known brand definitions, indexed by .Fa name . .It Fn drawer.addLogo name def Add the logo definition described by .Fa def to the table of known logo definitions, indexed by .Fa name . .It Fn drawer.drawscreen menudef Draws the logo, brand, menu frame, and the current menu as described in .Fa menudef , formatted as defined by .Xr menu.lua 8 . .El .Sh SEE ALSO .Xr menu.lua 8 .Sh AUTHORS The .Nm file was originally written by .An Pedro Souza Aq Mt pedrosouza@FreeBSD.org . Later work and this manual page was done by .An Kyle Evans Aq Mt kevans@FreeBSD.org . diff --git a/stand/lua/gfx.lua.8 b/stand/lua/gfx.lua.8 index 82d3f90f4af7..75f258026804 100644 --- a/stand/lua/gfx.lua.8 +++ b/stand/lua/gfx.lua.8 @@ -1,106 +1,106 @@ .\" .\" Copyright (c) 2024 Netflix, Inc. .\" .\" SPDX-License-Identifier: BSD-2-Clause .\" -.Dd February 6, 2024 +.Dd March 29, 2025 .Dt GFX.LUA 8 .Os .Sh NAME .Nm gfx.lua -.Nd Fx Lua gfx module +.Nd bootloader graphics 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/hook.lua.8 b/stand/lua/hook.lua.8 index f0e20153a924..91d5f76b6e1c 100644 --- a/stand/lua/hook.lua.8 +++ b/stand/lua/hook.lua.8 @@ -1,94 +1,94 @@ .\" .\" SPDX-License-Identifier: BSD-2-Clause .\" .\" Copyright (c) 2018 Kyle Evans .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd April 28, 2020 +.Dd March 29, 2025 .Dt HOOK.LUA 8 .Os .Sh NAME .Nm hook.lua -.Nd FreeBSD hook module +.Nd bootloader hook module .Sh DESCRIPTION .Nm contains functionality for defining hook types and attaching hooks. Hooks are functions used to attach custom behaviors at pre-defined points in loader execution. These pre-defined points are what we refer to as .Dq hook types . Hooks may also take an optional data parameter, which may or may not be populated by the caller. .Pp Before using the functionality provided by .Nm , it must be included with a statement such as the following: .Pp .Dl local hook = require("hook") .Ss Exported functions The following functions are exported from .Nm : .Bl -tag -width hook.registerType -offset indent .It Fn hook.registerType hooktype Adds .Ev hooktype as a recognized hook type. This allows functions to be added to run when hooks of this type are invoked using .Fn hook.runAll hooktype . .It Fn hook.register hooktype hookfunc Register .Ev hookfunc to be run when hooks of type .Ev hooktype are invoked. .It Fn hook.runAll hooktype Invoke all hooks registered for type .Ev hooktype . Hooks are invoked in the order in which they are registered. .El .Ss Hook Naming Guidelines Hook names should consist of the name of the module they are defined in, as well as a verb describing when the hook is executed, separated by a period. For example, .Dq config.reloaded is defined in the .Xr config.lua 8 module and run when the configuration is reloaded. .Sh EXAMPLES To register a hook to be run when configuration is reloaded: .Pp .Bd -literal -offset indent -compact local hook = require("hook") local function configuration_was_reloaded() print("Configuration was reloaded!") end hook.register("config.reloaded", configuration_was_reloaded) .Ed .Sh AUTHORS The .Nm file was originally written by .An Kyle Evans Aq Mt kevans@FreeBSD.org . diff --git a/stand/lua/loader.conf.lua.5 b/stand/lua/loader.conf.lua.5 index 7fad7d2f78dd..509944ab6598 100644 --- a/stand/lua/loader.conf.lua.5 +++ b/stand/lua/loader.conf.lua.5 @@ -1,75 +1,75 @@ .\" .\" SPDX-License-Identifier: BSD-2-Clause .\" .\" Copyright (c) 2020 Kyle Evans .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .Dd May 10, 2023 .Dt LOADER.CONF.LUA 5 .Os .Sh NAME .Nm loader.conf.lua -.Nd Lua-based system bootstrap configuration file +.Nd system bootstrap Lua configuration information .Sh DESCRIPTION When the lua-based .Xr loader 8 encounters a filename in .Va loader_conf_files that has a .Dq .lua suffix, it will be loaded and executed by the lua interpreter in a limited environment. .Pp The limited environment does not contain the ability to reference or load other lua modules. Existing loader environment variables may be referenced as if they were already defined global variables. .Pp A lua configuration file may set any global variable, which will subsequently be processed and added to the environment after execution of the configuration file has completed. Other than the .Ar exec setting, all variables described in .Xr loader.conf 5 operate the same in the .Nm environment. Note that the settings describing module options can only be set in the environment; there is currently no way for a .Pa loader.conf.lua to fetch them. At this time, global table and function values are ignored. .Pp The .Fn config.buildenv hook will be run with an empty environment provided to it that may be populated by a custom .Pa local.lua . .Sh SEE ALSO .Xr loader.conf 5 .Sh AUTHORS The mechanism for loading .Nm files was originally written by .An Kyle Evans Aq Mt kevans@FreeBSD.org . diff --git a/stand/lua/loader.lua.8 b/stand/lua/loader.lua.8 index e5aee7e8602d..ffee46526c9f 100644 --- a/stand/lua/loader.lua.8 +++ b/stand/lua/loader.lua.8 @@ -1,196 +1,196 @@ .\" .\" Copyright (c) 2024 Netflix, Inc. .\" .\" SPDX-License-Identifier: BSD-2-Clause .\" -.Dd February 6, 2024 +.Dd March 29, 2025 .Dt LOADER.LUA 8 .Os .Sh NAME .Nm loader.lua -.Nd Fx Lua loader module +.Nd bootloader Lua binding 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 exit status Exit the boot loader back to the firmware with a status of .Va status . The interpretation of this value is firmware specific. .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. .El .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_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. diff --git a/stand/lua/menu.lua.8 b/stand/lua/menu.lua.8 index e2a0ff09ffd9..e2e32efdf3b4 100644 --- a/stand/lua/menu.lua.8 +++ b/stand/lua/menu.lua.8 @@ -1,300 +1,300 @@ .\" .\" SPDX-License-Identifier: BSD-2-Clause .\" .\" Copyright (c) 2018 Kyle Evans .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd March 31, 2021 +.Dd March 29, 2025 .Dt MENU.LUA 8 .Os .Sh NAME .Nm menu.lua -.Nd FreeBSD dynamic menu boot module +.Nd bootloader dynamic menu module .Sh DESCRIPTION .Nm contains the main functionality required to build a dynamic menu system. It also contains definitions for the built-in menus, some of which are influenced by .Xr loader 8 environment variables. .Pp Before hooking into the functionality provided by .Nm , it must be included with a statement such as the following: .Pp .Dl local menu = require("menu") .Ss MENU DEFINITIONS Menus are represented in .Nm as a table. That table .Sy must contain an .Va entries key. .Pp If the value of the .Va entries key is itself a table, then each value in this table defines a single entry in this menu. See .Sx MENU ITEM DEFINITIONS for the structure of each entry. .Pp .Va entries may also be a function. This function must return a table, each value of which defines a single entry in this menu. See .Sx MENU ITEM DEFINITIONS . .Ss MENU ITEM DEFINITIONS The following keys may be defined for a menu item: .Bl -tag -width disable-module_module -offset indent .It Ic entry_type The type of this menu entry. See .Sx MENU ITEM TYPES . .It Ic carousel_id A unique string id for this carousel. A carousel is a menu entry that rotates through a selection of items. Used for storage of the carousel's current setting. .It Ic visible A lambda that returns .Dv true if this menu item should be visible and .Dv false if it should not be visible. .It Ic items A table (or a lambda that returns a table) of the possible choices for this carousel. .It Ic name A string (or a lambda that returns a string) containing the current name of this item. .It Ic func The function executed when this entry is selected. Every type except for .Ic core.MENU_SEPARATOR may have a .Ic func . .It Ic submenu The submenu menu definition to draw when this entry is selected. .It Ic alias A table of case-sensitive aliases for this menu entry. All menu entries that can be selected may have any number of .Ic alias entries. .El .Pp .Ic entry_type is the only required key for every entry type. .Ic name is required for all entry types except for .Ic core.MENU_SEPARATOR . .Ss MENU ITEM TYPES The menu item type constants are defined in .Xr core.lua 8 . The following types are available: .Bl -tag -width core.MENU_CAROUSEL_ENTRY -offset indent .It Ic core.MENU_RETURN Return to the parent menu. If the current menu is the default menu, .Nm will exit the menu and begin the autoboot sequence (if applicable). This type of menu entry may execute .Ic func , when selected, and has a .Ic name . .It Ic core.MENU_ENTRY A normal menu entry that executes .Ic func when selected, and has a .Ic name . .It Ic core.MENU_SEPARATOR A menu entry that serves as a separator. It may have a .Ic name . .It Ic core.MENU_SUBMENU A menu entry that opens .Ic submenu when selected. It may have a .Ic name . .It Ic core.MENU_CAROUSEL_ENTRY A menu entry that rotates through .Ic items like a carousel. .Ic func is executed when selected, and the callback is passed the choice index, name of the current choice, and the table of choices. .El .Ss EXPORTED MENUS The following menus are exported by .Nm : .Bl -tag -width menu.boot_environments -offset indent .It Ic menu.default The default menu to draw. Set to .Ic menu.welcome by default. .It Ic menu.welcome The welcome menu. Contains single and multi user boot options, as well as entries to access other menus. .It Ic menu.boot_options The "Boot Options" menu. .It Ic menu.boot_environments The "Boot Environments" menu. This menu is only visible if the system is booted on a ZFS partition and more than one boot environment was detected at boot. .El .Sh EXAMPLES To replace the default boot menu with a simple boot menu: .Pp .Bd -literal -offset indent -compact local core = require("core") local menu = require("menu") menu.default = { entries = { { entry_type = core.MENU_ENTRY, name = "Boot", func = core.boot, }, { entry_type = core.MENU_CAROUSEL_ENTRY, carousel_id = "unique_boot_entry_name", items = {"NO", "YES"}, name = function(_, choice, _) return "Option: " .. choice end, func = function(_, _, _) loader.setenv("some_envvar", "some_value") end, }, }, } .Ed .Pp To add another option to the welcome menu: .Pp .Bd -literal -offset indent -compact local core = require("core") local menu = require("menu") local my_entry = { entry_type = core.MENU_ENTRY, name = "Fancy Boot", func = core.boot, }, local stock_entries = menu.welcome.entries function menu.welcome.entries() local ents = stock_entries() ents[#ents + 1] = my_entry return ents end .Ed .Pp To create a vendor submenu or other vendor menu option, override .Ic menu.welcome.all_entires.vendor like so: .Pp .Bd -literal -offset indent -compact local core = require("core") local menu = require("menu") -- Fill in with vendor specific entries local vendor_options = { entries = { ... }, } local welcome_entries = menu.welcome.all_entries welcome_entries.vendor = { entry_type = core.MENU_SUBMENU, name = color.highlight("V") .. "endor Options", submenu = vendor_options, alias = {"v", "V"}, visible = function() return true end, } .Ed In the above example, .Ic vendor_options is a local variable that defines the vendor submenu. .Pp To add an additional option, change the .Ic menu.boot_options.entries array. The following illustrates this concept: .Pp .Bd -literal -offset indent -compact -- This is a silly example that rotates local_option through the values -- 0 to 4. local_option would still need to be used elsewhere. local local_option = 0 -- The `entries` of a menu may either be a table or a function. In this -- example we're augmenting a menu that just has a static table, but if we -- wanted to be more robust then we would need to instead check the type -- of `stock_options` here to determine our next move. -- -- If `entries` is a table, then the stock menu system won't be changing it -- so we can just add our menu option as we do below. -- -- If `entries` is a function, then we would need to provide a new function to -- replace `entries` that does a core.deepCopyTable() of the result and adds -- the below item to it. The deep copy is necessary to avoid duplicating our -- new menu item and allowing the menu to alter its behavior however it pleases. local stock_options = menu.boot_options.entries stock_options[#stock_options + 1] = { entry_type = core.MENU_ENTRY, name = function() return color.highlight('L') .. "ocal Option : " .. local_option end, func = function() local_option = (local_option + 1) % 5 end, alias= {"l", "L"} } .Ed .Sh SEE ALSO .Xr loader.conf 5 , .Xr core.lua 8 , .Xr loader 8 .Sh HISTORY The .Nm file first appeared in .Fx 12.0 . .Sh AUTHORS The .Nm file was originally written by .An Pedro Souza Aq Mt pedrosouza@FreeBSD.org . Later work and this manual page was done by .An Kyle Evans Aq Mt kevans@FreeBSD.org . diff --git a/stand/lua/password.lua.8 b/stand/lua/password.lua.8 index 1fbe395ab0db..34623c001206 100644 --- a/stand/lua/password.lua.8 +++ b/stand/lua/password.lua.8 @@ -1,72 +1,72 @@ .\" .\" SPDX-License-Identifier: BSD-2-Clause .\" .\" Copyright (c) 2018 Kyle Evans .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd August 19, 2018 +.Dd March 29, 2025 .Dt PASSWORD.LUA 8 .Os .Sh NAME .Nm password.lua -.Nd FreeBSD password module +.Nd bootloader password module .Sh DESCRIPTION .Nm contains functionality for prompting for and checking passwords. .Pp Before using the functionality provided by .Nm , it must be included with a statement such as the following: .Pp .Dl local password = require("password") .Pp The following functions are exported from .Nm : .Bl -tag -width "Fn password.read prompt_length" -offset indent .It Fn password.read prompt_length Read a password following a prompt. .Fa prompt_length is required so that the twiddle may be properly drawn as the user is typing. .It Fn password.check Drives the primary password checks done by the loader. The .Fn password.check function will check .Ev bootlock_password , .Ev geom_eli_passphrase_prompt , and .Ev password and prompt the user for passwords as-needed. If .Ev password is set, the autoboot sequence will begin as the user is prompted for a password. .El .Sh SEE ALSO .Xr screen.lua 8 .Sh AUTHORS The .Nm file was originally written by .An Pedro Souza Aq Mt pedrosouza@FreeBSD.org . Later work and this manual page was done by .An Kyle Evans Aq Mt kevans@FreeBSD.org . diff --git a/stand/lua/screen.lua.8 b/stand/lua/screen.lua.8 index 691af5bf0758..a41ce6faf08b 100644 --- a/stand/lua/screen.lua.8 +++ b/stand/lua/screen.lua.8 @@ -1,100 +1,100 @@ .\" .\" SPDX-License-Identifier: BSD-2-Clause .\" .\" Copyright (c) 2018 Kyle Evans .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd August 19, 2018 +.Dd March 29, 2025 .Dt SCREEN.LUA 8 .Os .Sh NAME .Nm screen.lua -.Nd FreeBSD screen manipulation module +.Nd bootloader screen manipulation module .Sh DESCRIPTION .Nm contains functionality for manipulating the screen. This includes functionality such as clearing the screen, moving the cursor, and setting foreground/background colors using sequences provided by .Xr color.lua 8 . .Pp Before using the functionality provided by .Nm , it must be included with a statement such as the following: .Pp .Dl local screen = require("screen") .Pp The following variables are exported from .Nm : .Bl -tag -width "Ic screen.default_x" -offset indent .It Ic screen.default_x The x component of the default cursor position. .It Ic screen.default_y The y component of the default cursor position. .El .Pp The following functions are exported from .Nm : .Bl -tag -width "Fn screen.clear" -offset indent .It Fn screen.clear Clears the screen. .Fn screen.clear will do nothing if a serial boot is detected. .It Fn screen.setcursor x y Sets the cursor position to .Fa x , .Fa y . .Fn screen.setcursor will do nothing if a serial boot is detected. .It Fn screen.setforeground color_value Sets the foreground color to .Fa color_value , which should be a constant defined in .Xr color.lua 8 . .Fn screen.setforeground will do nothing if color is disabled. .It Fn screen.setbackground color_value Sets the background color to .Fa color_value , which should be a constant defined in .Xr color.lua 8 . .Fn screen.setbackground will do nothing if color is disabled. .It Fn screen.defcolor Sets the default color scheme, as defined by .Fn color.default . .Fn screen.defcolor will do nothing if color is disabled. .It Fn screen.defcursor Sets the default cursor position to that defined by .Ic screen.default_x , .Ic screen.default_y . .El .Sh SEE ALSO .Xr color.lua 8 .Sh AUTHORS The .Nm file was originally written by .An Pedro Souza Aq Mt pedrosouza@FreeBSD.org . Later work and this manual page was done by .An Kyle Evans Aq Mt kevans@FreeBSD.org .