Examples of integrating ACPI into the kernel?

[mrjbom]

Hi.
I'm trying to integrate ACPI into my OS, but I absolutely don't understand how to integrate ACPICA and what IT needs.
The article about ACPICA on the wiki didn't give me much. I never figured out how to make it work in my core.
Where can I see examples of how to embed this in my kernel?

What else can I use to get the most information about the computer?

Thanks.

[Love4Boobies]

Can you ask more specific questions? In order to be portable, ACPICA abstracts the OS-specific services into a layer it calls the OSL. Namely, the AcpiOs* family of functions ought to be implemented by the host OS so that ACPICA can call them to do OS-specific things. In other words, it's the API exposed to ACPICA by the implementation.

For instance, AcpiOsAllocate is how ACPICA can ask the host OS for memory without having any idea about the details of its memory allocator. When it wants to free it, it informs the host OS to do so by calling AcpiOsFree. If you have a C standard library ported, these two functions could very well be wrappers for malloc and free.

I'm not sure why you need examples for what is essentially basic programming: how to use abstractions. Either way, the reference implementation has an OSL for EFI. I'm also not sure why you're using the wiki as a reference instead of reading the official documentation. I never bothered with ACPICA but it took me two minutes to look up its basic architecture and the relevant resources.

[Korona]

You need to implement the ACPI glue functions, afterwards you can call ACPICA functions to initialize ACPI, walk through the ACPI namespace and invoke control methods. Managarm implemented ACPICA before, but the port was somewhat ugly and imcomplete; other OSes will almost certainly have cleaner examples for ACPICA.

You might also want to take a look at LAI, a more lightweight AML interpreter. Disclosure: I'm a contributor of that project. Qookie's OS quack implements the LAI bindings nice and concisely. Here is also some example usage from quack, i.e., code to translate PCI IRQs to GSIs (= I/O APIC vectors).

[Love4Boobies]

ACPICA has its own AML interpreter, by the way, if you want to use that one.

[mrjbom]

Can you ask more specific questions? In order to be portable, ACPICA abstracts the OS-specific services into a layer it calls the OSL. Namely, the AcpiOs* family of functions ought to be implemented by the host OS so that ACPICA can call them to do OS-specific things. In other words, it's the API exposed to ACPICA by the implementation.

For instance, AcpiOsAllocate is how ACPICA can ask the host OS for memory without having any idea about the details of its memory allocator. When it wants to free it, it informs the host OS to do so by calling AcpiOsFree. If you have a C standard library ported, these two functions could very well be wrappers for malloc and free.

I'm not sure why you need examples for what is essentially basic programming: how to use abstractions. Either way, the reference implementation has an OSL for EFI. I'm also not sure why you're using the wiki as a reference instead of reading the official documentation. I never bothered with ACPICA but it took me two minutes to look up its basic architecture and the relevant resources.

What exactly does ACPI need besides dynamic memory? What should my operating system be able to do to implement OS layer?

[kzinti]

What exactly does ACPI need besides dynamic memory? What should my operating system be able to do to implement OS layer?

You are going to read the docs / give it a try to know for sure. But I did something like this (add ACPI to my kernel) a few years ago. I didn't get to finish all the work, but this should give you an idea of what you need to provide:

https://github.com/kiznit/kiznix/blob/f ... nel/acpi.c

Roughly memory, threads/processes, mutexes/semaphores, timers, sleep, ports I/O and logging functions.

ACPICA's source code provides a bunch of examples for existing OS, see:
https://github.com/kiznit/kiznix/tree/f ... ice_layers

Example for Linux:
https://github.com/kiznit/kiznix/blob/f ... linuxtbl.c

This should give you an idea of what your kernel needs to be able to run and use ACPICA.

[Korona]

ACPICA has its own AML interpreter, by the way, if you want to use that one.

That's the whole point of ACPICA. Or am I misunderstanding your statement? LAI is an alternative to ACPICA, it doesn't complement it.

EDIT: I should maybe elaborate why I dislike ACPICA to motivate LAI. ACPICA is often a black box and you do not really know what's going on inside. It almost gives the impression that by using ACPICA, you don't need to understand the ACPI specification in detail. But that is very wrong. You need to understand the ACPI specification in all its details, or else you will end up using ACPICA in a wrong way (e.g., initializing devices in a wrong order, initializing OperationRegion()s in the wrong order, ...). You could say that ACPICA abstracts over details, except when it doesn't; so you still have to read ACPICA's code to know where the abstraction fails (e.g., in the case of AML reference types). LAI does not try to hide the ugly details. LAI gives you an AML interpreter but doesn't suggest an opinionated way to use it.

[Love4Boobies]

What should my operating system be able to do to implement OS layer?

It should implement those functions. There's a list on the wiki and in the documentation I've linked you to, together with a description of what ACPICA expects them to do. You want me to list them here so you can simply not read them all over again? I trust that you have the basic intelligence to be able to tell whether or not your OS already provides the functionality to support them or whether you need to implement it. But, just in case, here's an example of basic thinking: "AcpiOsCreateMutex. Hmm, it says here that it creates a mutex and returns a handle to it. Does my OS have mutexes?"

ACPICA has its own AML interpreter, by the way, if you want to use that one.

That's the whole point of ACPICA. Or am I misunderstanding your statement? LAI is an alternative to ACPICA, it doesn't complement it.

EDIT: I should maybe elaborate why I dislike ACPICA to motivate LAI. ACPICA is often a black box and you do not really know what's going on inside. It almost gives the impression that by using ACPICA, you don't need to understand the ACPI specification in detail. But that is very wrong. You need to understand the ACPI specification in all its details, or else you will end up using ACPICA in a wrong way (e.g., initializing devices in a wrong order, initializing OperationRegion()s in the wrong order, ...). You could say that ACPICA abstracts over details, except when it doesn't; so you still have to read ACPICA's code to know where the abstraction fails (e.g., in the case of AML reference types). LAI does not try to hide the ugly details. LAI gives you an AML interpreter but doesn't suggest an opinionated way to use it.

Well, ACPICA isn't just its AML interpreter so if he's going to use it for other things as well, I pointed out that it has one. But I don't agree with your criticism of ACPICA, which as I read it is "Someone might misuse it because they might be tempted to not familiarize themselves with ACPI." Who are these people implementing ACPI but not familiarizing themselves with it? (Other than the OP, heh.)

[bzt]

If anyone interested in alternatives, OpenBSD has a fairly complete, yet simple ACPI implementation. It's far far less bloated than ACPICA. It's implemented as a "device driver", so it is pretty well separated, not tied to the OpenBSD kernel which makes porting easier. This is only the run-time part (which you want to integrate into a kernel), without the compile-time tools (no AML compiler for example, just the parser).

Cheers,
bzt

[Korona]

Well, ACPICA isn't just its AML interpreter so if he's going to use it for other things as well, I pointed out that it has one. But I don't agree with your criticism of ACPICA, which as I read it is "Someone might misuse it because they might be tempted to not familiarize themselves with ACPI." Who are these people implementing ACPI but not familiarizing themselves with it? (Other than the OP, heh.)

Well, basically everyone? Outside of Linux and the BSDs (and maybe Haiku), I don't think that I have seen a correct ACPI initialization sequence ever (i.e., in no hobby OS at all). Most hobby OS I saw just do _PIC, AcpiEnableSubsystem() and AcpiInitializeObjects(), without looking at the namespace at all. How many hobby OSes run _REG on non-zero PCI busses? How many hobby OSes read the ECDT before calling AcpiEnableSubsystem? These are not exotic things that you'll never need - there are laptops in 2020 (and earlier!) that will just fail ACPI initialization if you forget to do it.

ACPICA was made to meet a very specific need: an ACPI implementation for Linux and FreeBSD. Unless you understand precisely how ACPICA calls match to the ACPI specification, using it can be very misleading. If you're using AcpiInitializeObjects() because ACPICA's manual lists it in the initialization sequence, you're doing something wrong. You have to know: this function calls _REG on all memory and I/O OperationRegion()s. It then walks the namespace recursively, calling _STA and _INI as needed. It also calls _PRW but does not enable the corresponding GPEs. Yes, that is documented. But how many people using ACPICA are actually aware of it? How many are using AcpiInitializeObjects() exactly for this purpose and at the correct time during their kernel's initialization (rather than just because they saw that it's part of the initialization sequence)?

My technical criticism is that once you do know all these details, you do not need ACPICA's high level functions anymore. If you are not Linux, the chance is high that you actually want to use your own abstractions instead. But when you take away the high level functions from ACPICA, you're left with a very ugly low level interface.

[Love4Boobies]

Well, basically everyone? Outside of Linux and the BSDs (and maybe Haiku), I don't think that I have seen a correct ACPI initialization sequence ever (i.e., in no hobby OS at all).

I don't judge the usefulness of ACPICA by a couple of cringe operating systems hacked on by some students living in their parents' basements. I judge it by it being useful and simple to use for people who know what they are doing and have a good reason to implement OSPM. Implementing OSPM in a hobby OS is probably a waste of time anyway, given that most of them never make it onto real hardware.

ACPICA was made to meet a very specific need: an ACPI implementation for Linux and FreeBSD.

It's used in many other places, not just FreeBSD and Linux.

My technical criticism is that once you do know all these details, you do not need ACPICA's high level functions anymore. If you are not Linux, the chance is high that you actually want to use your own abstractions instead. But when you take away the high level functions from ACPICA, you're left with a very ugly low level interface.

Or maybe you want to save yourself the hassle of doing all that design and implementation work and actually learn about ACPI and how to use ACPICA so you can move on to more relevant things rather than reinventing the wheel, possibly making mistakes in the process---and then having to maintain it, too.

[Korona]

I don't judge the usefulness of ACPICA by a couple of cringe operating systems hacked on by some students living in their parents' basements.

In all likelihood, you're giving advise to students writing "cringe operating systems" (whatever that is) in their parents' basement, if you're posting in this forum.

ACPICA was made to meet a very specific need: an ACPI implementation for Linux and FreeBSD.

It's used in many other places, not just FreeBSD and Linux.

Which ones?

By the way, ACPICA is a good ACPI implementation for Linux and FreeBSD - and a better one than LAI will ever be. But its AML interpreter API is more cumbersome to use than LAIs and that's what matters to me. YMMV. No one is doubting that ACPICA is useful. It also has some parts that will never be provided by LAI, e.g., an AML compiler (which we use for our unit tests, too!).

Re: reinventing the wheel - that's true. But isn't developing better APIs and implementations part of the reason why we do OSdev?

[Love4Boobies]

I may have misunderstood your position. It sounded to me as if you were saying ACPICA is generally bad and I was trying to express that I do not think that it is. For hobbyists, maybe something simpler is the way to go. It depends on the scope of the project but again... how many hobby OSes get to see bare metal enough for power management to even matter?

That said, I don't think most people in the community are actually working on hobby OSes. Some have and eventually moved on to more interesting things, some haven't at all but are generally interested in the subject. I haven't touched a kernel in over 10 years and back then I did it to educate myself on the matter. Even if I had time to actively work on one today, I don't think it would be a good investment of my time. I believe many here feel the same, not that there is anything wrong with working on such a project. Do whatever entertains you, it's your hobby after all. There are a couple of projects from various members that have clearly had much effort put into them. Examples include ToaruOS and Pedigree. Kudos to them.