LAI: Lightweight AML Interpreter

[Korona]

While some people on this forum might remember LAI, there is no official announcement thread for it yet. Hence, I am posting this thread to change this fact. While I am the one posting the thread, I want to make clear that LAI is by no means a solo achivement of mine: the original code was written by Nour (formerly known as omarrx024 on this forum). qookie, thomtl, Itay, toor and me did most of the work to bring it into its current shape.

What is LAI? LAI is a portable interpreter library for AML, the ACPI machine language. As such, it is an alternative to the much more heavyweight ACPICA library. Like ACPICA, LAI parses the ACPI tables that contain AML (i.e., the DSDT and SSDT tables), constructs the ACPI namespace, and is able to evaluate nodes (control methods or other objects) of this namespace. Unlike ACPICA, however, LAI a minimal interpreter - it executes AML but it does not provide a full solution to every ACPI-related task. I do not perceive this to be a shortcoming of LAI: instead, when working with ACPICA on managarm, I noticed that the OS kernel often wants to use its own high level code anyway.

What is the current state of LAI? Today, LAI can execute most AML code (but some exotic opcodes might remain unimplemented until someone posts a bug report about encountering them ). As demonstrated by qookie in the screenshot thread, LAI can handle PCI routing on a variety of hardware and on all widely-used VMs. The project is quite active - bug reports are usually fixed within a few days. Thus, while LAI is not as mature as ACPICA, we encourage you to try it out in your own OSes if you are in need of a working ACPI implementation.

The project can be found at: https://github.com/qword-os/lai. You might also want to take a look at our core API documentation. We have Linux-based unit tests and CI for the project at https://github.com/qword-os/lai_tools. Feel free to ask any questions about the project and let us know if you plan to use LAI in your own projects!

[Octacone]

I've been following this project for a long time. I'm quite impressed with what you guys have done.
Finally there is something that can compete with ACPICA (which is way too bloated and 1000 times bigger than my entire project).
This will definitely help me (and others) understand how such an interpreter works internally, once I start working on my own (in the future far far away).
I'm amazed by the fact that everybody kept telling it was impossible/too hard, yet here you are.

I have a question, I assume your goal is to build a fully fledged interpreter, how much smaller would this project be if your only goal was the be able to shutdown, restart and sleep?

[zaval]

nicey. ^_^ why I wanted to say something is because I definitely remember Korona strongly questioned the approach of creating yet another AML interpreter, when there is ACPICA. it was in relation to openbsd's one. was there that or I confused something? interesting, why you changed your mind.

[Korona]

I have a question, I assume your goal is to build a fully fledged interpreter, how much smaller would this project be if your only goal was the be able to shutdown, restart and sleep?

Unfortunately, the core cannot be much smaller, even if only sleeping needs to be supported. Sleeping involves calling the _PTS, _S1 - _S5 and _WAK control methods which can contain arbitrary AML code.

That being said, the interpreter core is already quite small: right now, there core consists of around 5k sloc. Extending it to handle all exotic instructions and edge cases might add quite a bit of additional code. However, I expect the interpreter to stay below 10k sloc even once everything is handled 100% correctly.

nicey. ^_^ why I wanted to say something is because I definitely remember Korona strongly questioned the approach of creating yet another AML interpreter, when there is ACPICA. it was in relation to openbsd's one. was there that or I confused something? interesting, why you changed your mind.

Honestly, I don't remember the context . But it is true that I was satisfied with ACPICA for quite some time. After a while, however, I noticed that ACPICA made it hard to understand what was going on behind the scenes. LAI's API should make this much more clear: the core just evaluates the AML methods that the user calls. All helper functions that we add on top of that should just be a thin layer above the core. In fact, all helper functions should be implemented using the public core API only, without using any knowledge about the interpreter's implementation. We do not expect an OS to make use of all helpers anyway - OSes are expected to use the core API and pick some additional helpers that seem useful to them, while re-implementing others according to their own ideas.