uACPI, a portable and easy-to-integrate ACPI implementation

[8infy]

Hi all!

uACPI is an ACPI implementation (including an AML interpreter and other components) that aims to be easy to port and integrate.
Project on GitHub: https://github.com/UltraOS/uACPI

Current state of the project
- A well-tested interpreter fully supporting all of AML
- A fully implemented resource subsystem supporting all existing descriptors
- Lots of API already available, this includes sleep/reset, device search, namespace management, opregion/notify handlers, gas read/write, pci routing, interrupt model
- Works on all real hardware tested so far (about 8 different computers), and all VMs. This includes namespace initialization, reading battery state, shutting down and rebooting

More details in the README: https://github.com/UltraOS/uACPI?tab=re ... he-project

Project goals
- Perfect compatibility with the Windows NT ACPI interpreter
- Addressing some of the fundamental design flaws of ACPICA: the global interpreter lock, unsafe object lifetimes, NT incompatibility (reference semantics, implicit-casts, etc)
- Simplifying code by embracing AML designed for the NT ACPI interpreter, instead of trying to work around it (see: ACPICA two-pass package named object resolution)
- Ease of integration and development

Some code examples & more details in the README: https://github.com/UltraOS/uACPI?tab=re ... ver-acpica

A reddit post by me showcasing the interpreter on real hardware: https://www.reddit.com/r/osdev/comments ... _hardware/

Thanks!

[eekee]

Excellent goals! I particularly like that the instructions for building it without CMake are just 2 lines. Bookmarked.

[8infy]

An update on the state of the project:
- uACPI now has a fairly complete event subsystem for fixed and general purpose events
- Added support for gracefully skipping opcodes attempting to create duplicate named objects during namespace load
- A bunch of small improvements and various bug fixes, removed strtoull os dependency, now shipping own implementation
- We have tested a lot more computers since, the number is probably close to 20 if not more at the moment, all working just fine!
- uACPI is now the official ACPI subsystem used by the managarm operating system: https://github.com/managarm/managarm

[rdos]

Interesting. How does it compare in executable size to ACPICA? What does it require from the runtime library? Does it work for a 32-bit protected mode kernel?

[8infy]

How does it compare in executable size to ACPICA?

I haven't measured, but it's ~20k loc of C code, so that should give you an idea

What does it require from the runtime library?

A few very common libc functions (memcpy, strcmp, ...) + snprintf. Besides that, kernel API like map/unmap, alloc/free, mutexes, ticks, etc.

Does it work for a 32-bit protected mode kernel?

This is not something I've tested personally, but there aren't any places in code that assume 64-bit at least as far as I'm aware, so might just work

[8infy]

Yet another project state update!

- Dynamic table loads from AML via (Load/LoadTable) are no longer recursive (they are in ACPICA even to this day!)
- Fixed a bunch of bugs/missing error checks found via fuzzing
- Sped up name string parsing
- Added a bunch of new tests

[8infy]

uACPI now has a page on osdev wiki! https://wiki.osdev.org/UACPI

Since the last update I also:
- Added a highly requested UACPI_SIZED_FREES mode, which makes all frees include a size argument
- Made 32-bit builds first class citizen (now run 32-bit CI for every commit as well)
- Did some more fuzzing thanks to the help from a friend, this time against 500 publicly available real hardware AML blobs
- Fixed a few important bugs (we no longer have any crashes when fuzzing! perhaps needs longer sessions)
- Reworked secondary table loading to include PSDTs and made failures non-critical
- Added a more verbose log level (with some extra interpreter bytecode tracing on top)

[8infy]

Been a while since the last update, quite a lot has been done:

- uACPI is now fully self-contained by default, only kernel_api.h needs to be implemented by the host
- Implemented support for managing the global ACPI firmware lock (for locked fields, _GL acquires, as well as public API)
- Added an interface management subsystem (controlling what features/vendor strings are reported as supported via _OSI)
- Implemented While loop timeouts, it's no longer possible to hang the interpreter from AML
- All of the publicly available (354) AML blobs are now tested against uACPI on every commit with ASAN+UBSAN in both 32 and 64 bit modes, this executes the blobs and runs all existing _STA/_INI/_HID/_CID/_UID/_CLS/_CRS/_PRS methods
- A bunch of constness correctness for public API
- Simplified a bunch of APIs to make language interop easier
- A whole bunch of bug fixes
- Added tons of code examples to the osdev wiki page

With this, uACPI is very close to being a finished library at its 1.0 release and API stabilization.
Pretty much the only critical piece currently missing is general thread safety for public APIs + interpreter.
I'm also considering adding a few more convenience helpers/APIs, but will see about that.

[AnotherIdiot]

Any update on uACPI? I have been considering using it for a while now in my OS.

[sounds]

I'm also excited for this project. One thing I am wondering is, where did all these projects discover and integrate uACPI? It's only recently popped on my radar.

https://github.com/uACPI

1. proxima
2. davix
3. ilobilix
4. Managarm
5. pmOS
6. menix
7. Astral
8. imaginarium
9. OBOS
10. NyauxKC

These projects have test results posted on the uACPI github. Is there a forum I can read more about it?

[no92]

There is a fairly active uACPI thread on the 'Operating System Development' Discord[0], and that's how a lot of these get infos about development. I assume you got the list from the 'leaderboard', which is a fun way for us to compete.

Integration of uACPI is similar to how a lot of other library-like projects operate, by having you implement a few functions as a sysdep layer. Another example that operates with similar principles is mlibc[1], which is a libc that is portable by having OSes implement a few sysdeps as well.

I can only speak for managarm, but we switched to uACPI fairly early on and it's been working great so far! Currently we rely on uACPI for discovering some devices, for instance 'MCFG' for ECAM discovery, PS/2 controllers and battery devices.

[0] https://discord.gg/RnCtsqD
[1] https://github.com/managarm/mlibc

[8infy]

Any update on uACPI? I have been considering using it for a while now in my OS.

Sorry, it's been a while since the last update here as I'm mostly active on the discord server these days.

uACPI is basically done feature-wise, at this point it has more features than ACPICA, e.g. the barebones mode, support for expressions within packages etc.
There are a lot of projects integrating it already and it has been tested on tons of hardware, even stuff like loongarch works.
It's currently being integrated by ReactOS and Haiku expressed interest as well, we'll see how it goes!

[rdos]

There seem to be multiple problems with compiling it with the OpenWatcom compiler.

1. Structs are partly initialized with '.' operator which is not supported by Watcom.
2. Watcom doesn't have a static_assert operator, so asserts must be disabled
3. Watcom C doesn't allow structs to be defined mixed with code (they must be defined first).
4. Binary encodings (e.g. 0b11) are not standard C and are not supported by watcom.

The extensive use of macros also makes debugging the code quite complex. It might be more portable, but it is not debug-friendly.

Not sure how to fix this. I've created a fork on github, but if I need to make too many modifications due to compiler problems, then it would be problematic to sync when uACPI is updated.

[nullplan]

1. Structs are partly initialized with '.' operator which is not supported by Watcom.

So Watcom doesn't support C99, then. Well, it's only lagging behind by 26 years at this point.

2. Watcom doesn't have a static_assert operator, so asserts must be disabled

That would be C11.

3. Watcom C doesn't allow structs to be defined mixed with code (they must be defined first).

Bloody hell, it doesn't even have C95? Because mixing declarations and statements was added in C95.

4. Binary encodings (e.g. 0b11) are not standard C and are not supported by watcom.

And that's a C23 feature. A pretty useless one as long as hex constants still exist. I do not get why people are so enamored with writing long strings of zeroes and ones.

Not sure how to fix this.

The compiler is open-source and can therefore be changed. So bring it up to C99 standard at least.

[rdos]

I don't think the compiler will be up to C99 anytime soon, so the only realistic solution is to fix this in uACPI. I have no idea how to fix the compiler myself. Also, being portable means it can be built with older compilers and not just gcc and clang.

Both ACPICA and OpenSSL build without these kinds of issues. Portable code should not rely on new C features, particularly not when they can be avoided without much impact.