=== ACPI Lua Bindings

Links: +
link:https://www.github.com/kpowkitty/freebsd-src[GitHub] URL: link:https://www.github.com/kpowkitty/freebsd-src[] +
link:https://www.github.com/freebsd/freebsd-src/pull/1740[PR: libsa: Add isprint()] URL: link:https://www.github.com/freebsd/freebsd-src/pull/1740[] +
link:https://www.github.com/freebsd/freebsd-src/pull/1843[PR: loader: Move ACPI RSDP detection] URL: link:https://www.github.com/freebsd/freebsd-src/pull/1843[] +
link:https://www.github.com/freebsd/freebsd-src/pull/1818[PR: efi: Create libacpi] URL: link:https://www.github.com/freebsd/freebsd-src/pull/1818[] +
link:https://www.github.com/freebsd/freebsd-src/pull/1819[PR: liblua: ACPICA Lua bindings] URL: link:https://www.github.com/freebsd/freebsd-src/pull/1819[]

Contact: Kayla Powell (AKA Kat) <kpowkitty@FreeBSD.org> +
Mentor: Warner Losh <imp@FreeBSD.org>

==== Introduction

For Google Summer of Code 2025, I have been working on a project under mailto:imp@FreeBSD.org[Warner Losh] for ACPI Lua Bindings.
ACPI (Advanced Power and Configuration Interface) is an interface for managing power in the OS, rather than in the BIOS.
The goal is to expose ACPI to Lua in the loader for amd64 platforms, with future arm64 support.

==== Outcomes

* Lua is a much simpler, higher level scripting language that enables faster development.
* It reduces ACPI-related guesswork in the bootloader.
* It allows users to query and manipulate ACPI data before the kernel is entered, giving them control over loader-time configuration.

==== Remarks

If there are any specialized use cases for ACPI in the loader that my interface does not aid in, please reach out to me, and I will see what I can do.
For now, this is the interface that I will be committing to the tree for GSoC, so while any extra work will have to come afterwards, I am interested in it (and encourage it).

==== Current status

* Completed:
** ACPICA initialized in loader for amd64
*** [.filename]#OsdMemory.c#
*** [.filename]#osunixxf.c#
*** AcpiInitializeSubsystem
*** AcpiInitializeTables
*** AcpiEnableSubsystem (in reduced hardware mode, with events enabled)
*** AcpiLoadTables
*** AcpiWalkNamespace
*** AcpiEvaluateObject
*** AcpiAttachData
*** AcpiGetData
*** AcpiDetachData
** Lua bindings
*** [.filename]#lacpi_walk.c#
**** Users can walk and read nodes on the namespace
*** [.filename]#lacpi_object.c#
**** Users can evaluate objects
*** [.filename]#lacpi_data.c#
**** Users can attach, get, and detach data from nodes
*** Man Page
* Future plans:
** [.filename]#lacpi_walk.c# (V2)
*** Namespace printout format
** [.filename]#lacpi_walk.c# (V3)
*** Strategies for walking the namespace
** arm64 compat

==== Design constraints

The loader is meant to be lightweight and prepare the kernel.
In order to adhere to that, its initialization of ACPI has been reduced by 130 functions.
These functions were picked such that they were not necessary for the above interface, or lacked possibility in the loader.
They are:

* AcpiInitializeObjects
* AcpiInstallNotifyHandler
* AcpiRemoveNotifyHandler

Some functions needed to be stubbed in respect to the loader's limited library (specifically in [.filename]#osunixxf.c#).
Some functions needed to handle physical addresses, rather than virtual memory mappings (specifically in [.filename]#OsdMemory.c#).

==== Testing

* Confirmation tests were performed, demonstrating that the ACPI namespace is initialized correctly by dumping it in the loader (in C and in Lua) and in the kernel (in C) and comparing the results.
* Regression tests were performed, ensuring FreeBSD builds across all architectures with this change.
* Unit tests were performed on the Lua bindings, verifying their functionality.

Sponsor: Google Summer of Code 2025