Skip to content

Commit a53ebc2

Browse files
kpowkittykpowkitty
committed
lacpi: Create man page
1 parent e90f340 commit a53ebc2

File tree

1 file changed

+182
-0
lines changed

1 file changed

+182
-0
lines changed

‎stand/lua/acpi.lua.8‎

Lines changed: 182 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,182 @@
1+
.\"
2+
.\" Copyright (c) 2025 Google Summer of Code
3+
.\"
4+
.\" SPDX-License-Identifier: BSD-2-Clause(XXX?)
5+
.\"
6+
.Dd September 28, 2025
7+
.Dt ACPI.LUA 8
8+
.Os
9+
.Sh NAME
10+
.Nm acpi.lua
11+
.Nd ACPI Lua binding module
12+
.Sh DESCRIPTION
13+
The ACPI Lua bindings are for utilizing ACPICA
14+
functionality pre-kernel. They are only available to the
15+
.Fx
16+
Lua bootloader, via the
17+
.Ic loader
18+
table, and require
19+
.Ic amd64
20+
architecture. See
21+
.Xr loader.lua 8
22+
for more information on the loader table.
23+
.Pp
24+
These bindings are in the
25+
.Ic lacpi
26+
namespace, and are divided between three modules:
27+
.Bl -tag -width 0n
28+
.It Sy walk
29+
The
30+
.Ic walk
31+
module is for walking the ACPI namespace under user specified
32+
callbacks and passing the information back to the interpreter
33+
through the Lua stack. Currently, users can walk the entire
34+
namespace or start the walk at a user specified
35+
.Ic handle .
36+
There is currently only one callback, and it retrieves the
37+
following into a Lua table.
38+
.Bl -tag -width 0n
39+
.It Sy pathname
40+
The full pathname of the current device node
41+
.It level
42+
The level of the current device node
43+
.It hid
44+
If applicable, the HID of the current device node
45+
.It uid
46+
If applicable, the UID of the current device node
47+
.El
48+
.It Sy object
49+
The
50+
.Ic object
51+
module is for evaluating ACPI objects. It provides
52+
the ability to
53+
.Bl -tag -width 0n
54+
.It Fn get_handle pathname
55+
Converts a
56+
.Va pathname
57+
to its corresponding
58+
.Ic opaque pointer .
59+
.It Fn evaluate handle abs_path rel_path args
60+
Evaluates an ACPI object. The arguments are:
61+
.Bl -enum
62+
.It
63+
The handle of the node.
64+
.It
65+
The relative pathname to the handle. Optional, and only
66+
provided if the handle is being provided.
67+
.It
68+
An absolute pathname.
69+
.It
70+
An
71+
.Va OBJECT_LIST
72+
for the specified objects
73+
.El
74+
.Pp
75+
This submodule takes either:
76+
.Bl -bullet
77+
.It
78+
A handle, with an optional relative pathname, plus an
79+
optional OBJECT_LIST.
80+
.It
81+
An absolute pathname, plus an optional OBJECT_LIST
82+
.El
83+
.El
84+
.It Sy data
85+
The
86+
.Ic data
87+
module allows users to manipulate data on namespace
88+
nodes. The interface currently provides the abilities:
89+
.Bl -tag -width 0n
90+
.It Fn attach handle ACPI_OBJECT
91+
Attach data onto a namespace node
92+
.It Fn detach handle
93+
Detach data from a namespace node
94+
.It Fn get handle
95+
Get data off of a namespace node
96+
.El
97+
.El
98+
.Sh NOTES
99+
The Lua stack expectations for all places that an ACPI_OBJECT
100+
is required to be passed over is the same ordering as the
101+
ACPI_OBJECT structures are defined. Please see
102+
.Em actypes.h
103+
for reference. In general, the arguments are passed as:
104+
.Bl -enum
105+
.It
106+
Type = ACPI_TYPE_INTEGER
107+
.It
108+
ACPI_OBJECT_TYPE = OBJECT
109+
.El
110+
.Pp
111+
Some examples for passing various ACPI_OBJECTs:
112+
.Bd -literal
113+
args = {{ Type = 1, Integer = 42 },
114+
{ Type = 2, String = "Tis but a scratch"},
115+
{ Type = 3, Buffer = "You liar!"}}
116+
.Ed
117+
.Sh EXIT STATUS
118+
The exit status varies depending on module, and can either
119+
return ACPI_STATUS to tell Lua it successfully completed
120+
its request or send back a table with the information
121+
that Lua requested.
122+
.Pp
123+
On the case of an error, the interface will
124+
provide up to three (optional) arguments:
125+
.Bl -tag -width 0n
126+
.It Sy nil
127+
To specify a fault
128+
.It Sy message
129+
Programmed message depending on the fault.
130+
.It Sy status
131+
.Ic ACPI_STATUS
132+
message translated to user friendly text.
133+
.El
134+
.Sh EXAMPLES
135+
.Bd -literal
136+
.Sy Retrieving a handle
137+
handle = lacpi.object.get_handle("\\\\_SB_.CPUS.C000")
138+
.Ed
139+
.Pp
140+
.Bd -literal
141+
.Sy Evaluating an object
142+
eval = lacpi.object.evaluate(handle, "_STA", nil, nil)
143+
print(eval)
144+
15
145+
.Ed
146+
.Pp
147+
.Bd -literal
148+
.Sy Evaluating an object with arguments
149+
handle = lacpi.object.get_handle("\\\\_SB_.DMY0")
150+
args = {{Type = 1, Integer = 42}}
151+
eval = lacpi.object.evaluate(handle, "ECHO", nil, args)
152+
print(eval)
153+
42
154+
.Ed
155+
.Pp
156+
.Bd -literal
157+
.Sy Attaching data onto a namespace node
158+
f, msg, status = lacpi.data.attach(handle, {Integer = 42})
159+
print(f)
160+
0
161+
.Ed
162+
.Pp
163+
.Bd -literal
164+
.Sy Retrieving data from a namespace node
165+
f, msg, status = lacpi.data.get(handle)
166+
print(f)
167+
42
168+
.Ed
169+
.Pp
170+
.Bd -literal
171+
.Sy Detaching data from a namespace node
172+
f, msg, status = lacpi.data.detach(handle)
173+
print(f)
174+
0
175+
.Ed
176+
.Sh SEE ALSO
177+
.Xr loader.lua 8
178+
.Sh AUTHORS
179+
The
180+
.Nm
181+
man page was written by
182+
.An Kayla Powell (AKA Kat) Aq Mt [email protected] .

0 commit comments

Comments
 (0)