1.\" 2.\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD 3.\" 4.\" Copyright (c) 2018 Kyle Evans <kevans@FreeBSD.org> 5.\" All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.\" $FreeBSD$ 29.\" 30.Dd March 21, 2018 31.Dt CORE.LUA 8 32.Os 33.Sh NAME 34.Nm core.lua 35.Nd FreeBSD core module 36.Sh DESCRIPTION 37.Nm 38contains core functionality that does not have a more fitting module. 39.Pp 40Before hooking into or using the functionality provided by 41.Nm , 42it must be included with a statement such as the following: 43.Pp 44.Dl local core = require("core") 45.Ss CONSTANTS 46The following raw key code constants are defined in 47.Nm : 48.Bl -tag -width KEY_BACKSPACE -compact -offset indent 49.It Ic KEY_BACKSPACE 50The backspace code. 51Should generally be checked along with 52.Ic KEY_DELETE 53for backspace functionality. 54.It Ic KEY_ENTER 55The enter key, or hard return. 56.It Ic KEY_DELETE 57The delete code. 58Should generally be checked along with 59.Ic KEY_BACKSPACE 60for backspace functionality. 61.El 62.Pp 63The following key-string constants are defined in 64.Nm : 65.Bl -tag -width KEYSTR_ESCAPE -compact -offset indent 66.It Ic KEYSTR_ESCAPE 67The escape key. 68.It Ic KEYSTR_CSI 69The ANSI CSI sequence. 70.El 71.Pp 72The following menu entry type constants are defined in 73.Nm : 74.Bl -tag -width MENU_CAROUSEL_ENTRY -compact -offset indent 75.It Ic MENU_RETURN 76Return to the parent menu. 77.It Ic MENU_ENTRY 78A normal menu entry. 79.It Ic MENU_SEPARATOR 80A menu entry that serves as a separator. 81.It Ic MENU_SUBMENU 82A menu entry that opens a submenu when selected. 83.It Ic MENU_CAROUSEL_ENTRY 84A menu entry that rotates through items like a carousel upon selection of the 85menu entry. 86.El 87.Pp 88Please see 89.Xr menu.lua 8 90for extended descriptions and usage of the 91.Ic MENU_* 92constants. 93.Ss Exported functions 94The following functions are exported from 95.Nm : 96.Bl -tag -width core.getACPIPresent -offset indent 97.It Fn core.setVerbose verbose 98Sets or unsets 99.Ev boot_verbose . 100If 101.Fa verbose 102is omitted, toggle the current verbose setting. 103.It Fn core.setSingleUser singleUser 104Sets or unsets 105.Ev boot_single . 106If 107.Fa singleUser 108is omitted, toggle the current single user setting. 109.It Fn core.getACPIPresent checkingSystemDefaults 110Check whether ACPI is present. 111This will only be accurate for i386-compatible loaders, including non-UEFI 112loaders on amd64 systems. 113If 114.Fa checkingSystemDefaults 115is true, ignore the current value of 116.Ev hint.acpi.0.disabled . 117Otherwise, return true only if ACPI is both present and not disabled. 118.It Fn core.setACPI acpi 119Sets or unsets 120.Ev acpi_load , 121.Ev hint.acpi.0.disabled , 122and 123.Ev loader.acpi_disabled_by_user . 124If 125.Fa acpi 126is omitted, toggle the current ACPI setting. 127.It Fn core.setSafeMode safeMode 128Set the safe mode setting. 129Sets or unsets 130.Ev kern.smp.disabled , 131.Ev hw.ata.ata_dma , 132.Ev hw.ata.atapi_dma , 133.Ev hw.ata.wc , 134.Ev hw.eisa_slots , 135.Ev kern.eventtimer.periodic , 136and 137.Ev kern.geom.part.check_integrity . 138If 139.Fa safeMode 140is omitted, toggle the current safe mode setting. 141.It Fn core.clearCachedKernels 142Clears out the cache of kernels to be displayed on the boot menu. 143This function is registered as a 144.Ev config.reloaded 145hook. 146It is used to invalidate the kernel list whenever it may have changed, either 147due to a boot environment change or a potential change in either 148.Ic kernel 149or 150.Ic kernels . 151.It Fn core.kernelList 152Returns a table of kernels to display on the boot menu. 153This will combine 154.Ic kernel 155and 156.Ic kernels 157from 158.Xr loader.conf 5 . 159If 160.Ic kernels_autodetect 161is set in 162.Xr loader.conf 5 , 163kernels will be autodetected from the current system. 164.It Fn core.bootenvDefault 165Returns the default boot environment, nil if unset. 166.It Fn core.bootenvList 167Returns a table of boot environments, or an empty table. 168These will be picked up using the 169.Ev bootenvs 170and 171.Ev bootenvs_count 172variables set by 173.Xr zfsloader 8 . 174.It Fn core.setDefaults 175Resets ACPI, safe mode, single user, and verbose settings to their system 176defauilts. 177.It Fn core.autoboot argstr 178Loads the kernel and specified modules, then invokes the 179.Ic autoboot 180.Xr loader 8 181command with 182.Fa argstr 183as-is. 184.It Fn core.boot argstr 185Loads the kernel and specified modules, then invokes the 186.Ic boot 187.Xr loader 8 188command with 189.Fa argstr 190as-is. 191.It Fn core.isSingleUserBoot 192Returns true if 193.Ev boot_single 194is set to yes. 195.It Fn core.isZFSBoot 196Returns true if 197.Ev currdev 198is set to a 199.Xr zfs 8 200dataset. 201.It Fn core.isSerialBoot 202Returns true if we are booting over serial. 203This checks 204.Ev console , 205.Ev boot_serial , 206and 207.Ev boot_multicons . 208.It Fn core.isSystem386 209Returns true if this bootloader was compiled as an i386 binary. 210This generally applies to i386 loaders as well as non-UEFI loaders on amd64. 211.It Fn core.deepCopyTable tbl 212Recursively deep copies 213.Fa tbl 214and returns the result. 215.It Fn core.popFrontTable tbl 216Pops the front element off of 217.Fa tbl , 218and returns two return values: the front element, and the rest of the table. 219If there are no elements, this returns nil and nil. 220If there is one element, this returns the front element and an empty table. 221This will not operate on truly associative tables; numeric indices are 222required. 223.El 224.Sh SEE ALSO 225.Xr loader.conf 5 , 226.Xr loader 8 , 227.Xr menu.lua 8 228.Sh AUTHORS 229The 230.Nm 231file was originally written by 232.An Pedro Souza Aq Mt pedrosouza@FreeBSD.org . 233Later work and this manual page was done by 234.An Kyle Evans Aq Mt kevans@FreeBSD.org . 235