From nobody Tue Apr 16 20:12:36 2024 X-Original-To: dev-commits-src-all@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 4VJwFJ6ldvz5H0MM; Tue, 16 Apr 2024 20:12:36 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "R3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4VJwFJ4lR8z4ssn; Tue, 16 Apr 2024 20:12:36 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1713298356; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=plei8EbtF5Sw127hm0W4ZjO0uH/H4zXRPde0yT2xfU4=; b=uh9fY81zimiVmeahxMEIBBtaGNYDujXgy1+UnHMPHp8mUJ8RBwxVf5110fvrDNtUU/Niuu ebJuCoh6GuxAbZAUcXOtXP08uUKmPjEIyJyYQgx11+F6zS+juciOXTBSRzEIuteqDmQx5P 6aogZS9K1jjmF9sXfKvLVkysoVQkjwCkuHot16R0sEVInpi3NMpNaiDkNL1Mj2dP6nDkU1 ZzKvNGrfm6o1KrD77/nhA96ISNpn7eus7BCUoSeq8WfC5xmMDK+hLkIVZLByUwDmNbPXf+ 0uslmYKOTInZxqwalmC3XITJ5QuIiwtXxWUAJKB89QprnZGbK2vN0B1w2qPt0Q== ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1713298356; a=rsa-sha256; cv=none; b=wzNbjOg8bbjRWazZUNIhYQ8gshSxJDLE5m6HgNHnfdYbVKMj0kJeFiHvtCdg4zWPzRm1Ib NQLIPpe+sqdzxstC5+dXlLkx+02m1GXwp4ekwEKke0KMyk+pkrq20pAo/b0y/NZQOogTdW f7WILXGtIRLnWG4qe+E5gxVFp1ur+yMjHHeTiZLqB4vFwTEtXwiu7M6unPUk2IuqUyd+St ta3zKT7Am5lkYISvMR1AwlZCI0XY6CuibF6povXUrXw5hgz4PBPYoyzzcIdY4ju9JlkY5T NHR1poJrHenQSCiCrd9EdFSL/hlYQOAh2ryPO4pWreaduBAYZmUw9hFv0dK8ig== ARC-Authentication-Results: i=1; mx1.freebsd.org; none ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1713298356; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=plei8EbtF5Sw127hm0W4ZjO0uH/H4zXRPde0yT2xfU4=; b=MNMz+14YPWbSxJeK8YJrqdsEm9xen0BXgufhWedUPAJUC22V8xUjbRNX3Nf36jVQ7WPPcD RiDd6dCCLT4fZj0xbjVWSTsyRn+GO2n5Vl3h6vuUfan9BKTxdJaFo38r2XuvAuLqKBWMF4 3i27pc6SqkCgiIoJl0kmpzA41CjeuM3G0Px/r3snSB+xnHMA2ehoI2CtHsYXxUkXr1Tti3 y4Qs3D3oIyP/N1rcbniw22tJKYdBKW1H+ZBoSzSjMt3eqbW6SSu40HKO9rLv6yChJKeeMK X6Hp7GmJoijaCp91nZEYKlakSB7UAMA0zst6sOFXnV2ROJDt3rsYZLZySj08Ew== Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 4VJwFJ4JrWzwwB; Tue, 16 Apr 2024 20:12:36 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.17.1/8.17.1) with ESMTP id 43GKCa7o037401; Tue, 16 Apr 2024 20:12:36 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.17.1/8.17.1/Submit) id 43GKCagr037398; Tue, 16 Apr 2024 20:12:36 GMT (envelope-from git) Date: Tue, 16 Apr 2024 20:12:36 GMT Message-Id: <202404162012.43GKCagr037398@gitrepo.freebsd.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-branches@FreeBSD.org From: Warner Losh Subject: git: cfe4f061a78a - stable/14 - loader: Document the lua loader table. List-Id: Commit messages for all branches of the src repository List-Archive: https://lists.freebsd.org/archives/dev-commits-src-all List-Help: List-Post: List-Subscribe: List-Unsubscribe: X-BeenThere: dev-commits-src-all@freebsd.org Sender: owner-dev-commits-src-all@FreeBSD.org MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: imp X-Git-Repository: src X-Git-Refname: refs/heads/stable/14 X-Git-Reftype: branch X-Git-Commit: cfe4f061a78af28bc9a63617766697b154c3a829 Auto-Submitted: auto-generated The branch stable/14 has been updated by imp: URL: https://cgit.FreeBSD.org/src/commit/?id=cfe4f061a78af28bc9a63617766697b154c3a829 commit cfe4f061a78af28bc9a63617766697b154c3a829 Author: Warner Losh AuthorDate: 2024-02-10 18:49:09 +0000 Commit: Warner Losh CommitDate: 2024-04-16 19:54:22 +0000 loader: Document the lua loader table. Document all the public functions from the "loader" table. Sponsored by: Netflix Reviewed by: pauamma_gundo.com, tsoome, kevans Differential Revision: https://reviews.freebsd.org/D43701 (cherry picked from commit 621dae89f3c70b86bef255a621a76bf553f733ff) --- stand/lua/Makefile | 1 + stand/lua/loader.lua.8 | 247 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 248 insertions(+) diff --git a/stand/lua/Makefile b/stand/lua/Makefile index 6b1064dc1815..e8fa16e6b589 100644 --- a/stand/lua/Makefile +++ b/stand/lua/Makefile @@ -8,6 +8,7 @@ MAN= loader.conf.lua.5 \ core.lua.8 \ drawer.lua.8 \ hook.lua.8 \ + loader.lua.8 \ menu.lua.8 \ password.lua.8 \ screen.lua.8 diff --git a/stand/lua/loader.lua.8 b/stand/lua/loader.lua.8 new file mode 100644 index 000000000000..cd436255d4a5 --- /dev/null +++ b/stand/lua/loader.lua.8 @@ -0,0 +1,247 @@ +.\" +.\" 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_ +and +.Fn term_ +are optional. +They should only be used if they are non-nil and if +.Fn core.isFramebufferConsole +is true. +.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 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.