LAI

From OSDev.wiki
Jump to navigation Jump to search
ACPI
Fixed Tables
Differentiated Tables
Tools/Libs

LAI, or Lightweight AML Interpreter, is a lightweight alternative to the bulky ACPICA. It is much, much smaller, and requires less functions in the OS interface layer be implemented. As well, not all of the functions need to be implemented (although it is optimal to do so) because LAI simply panics when a function is needed and undefined, rather than requiring them at link time. This means that you can use the simpler functions of LAI if you aren't ready to implement an entire OS interface layer just to power off the machine.

As an aside, LAI is permissively MIT-licensed, quite like ACPICA, which allows you to choose between GPLv2, a BSD License, and a non-OSI "Intel" License.

Official documentation can be found on GitHub.

Uses

LAI's core is just an AML interpreter which currently works on most hardware with sane AML. However, it includes drivers and helpers for:

  • Embedded Controller
  • Legacy PCI IRQ pin routing
  • Power management (Setting sleep states S0-S5, reset)
  • Discovering the RSDP in BIOS systems
  • Enabling ACPI mode

LAI is under semi-active development, and the maintainers are relatively quick to reply to contributions.

Porting

In order to call into the kernel LAI has a few standardized "host" functions that the kernel needs to implement, most of these are weakly linked, and are optional. However that does not mean that only the few required host functions are needed, in practice, all of the Required and Integral functions are needed for smooth operation. You can find LAI's full host documentation here

Required

These functions are 100% required for the proper functioning of the interpreter, it will not link without these functions

laihost_log

/* Logs a message. level can either be LAI_DEBUG_LOG for debugging info,
   or LAI_WARN_LOG for warnings */
void laihost_log(int level, const char *msg);

laihost_panic

/* Reports a fatal error, and halts. */
__attribute__((noreturn)) void laihost_panic(const char *msg);

laihost_malloc

void *laihost_malloc(size_t);

laihost_realloc

void *laihost_realloc(void *, size_t);

laihost_free

void *laihost_free(void *);

Integral

These functions, while not required to link with LAI, are practically integral to its operation

laihost_map

/* Maps count bytes from the given physical address and returns
   a virtual address that can be used to access the memory. */
void *laihost_map(size_t address, size_t count);

laihost_unmap

/* Unmaps count bytes from the given virtual address.
   LAI only calls this on memory that was previously mapped by laihost_map(). */
void laihost_unmap(void *pointer, size_t count);

laihost_scan

/* Returns the (virtual) address of the n-th table that has the given signature,
   or NULL when no such table was found. */
void *laihost_scan(char *sig, size_t index);

laihost_out

/* Write a byte/word/dword to the given I/O port. */
void laihost_outb(uint16_t port, uint8_t val);
void laihost_outw(uint16_t port, uint16_t val);
void laihost_outd(uint16_t port, uint32_t val);

laihost_in

/* Read a byte/word/dword from the given I/O port. */
uint8_t laihost_inb(uint16_t port);
uint16_t laihost_inw(uint16_t port);
uint32_t laihost_ind(uint16_t port);

laihost_pci_read

/* Read a byte/word/dword from the given device's PCI configuration space
   at the given offset. */
uint8_t laihost_pci_readb(uint16_t seg, uint8_t bus, uint8_t slot, uint8_t fun, uint16_t offset);
uint16_t laihost_pci_readw(uint16_t seg, uint8_t bus, uint8_t slot, uint8_t fun, uint16_t offset);
uint32_t laihost_pci_readd(uint16_t seg, uint8_t bus, uint8_t slot, uint8_t fun, uint16_t offset);

laihost_pci_write

/* Write a byte/word/dword to the given device's PCI configuration space
   at the given offset. */
void laihost_pci_writeb(uint16_t seg, uint8_t bus, uint8_t slot, uint8_t fun, uint16_t offset, uint8_t val);
void laihost_pci_writew(uint16_t seg, uint8_t bus, uint8_t slot, uint8_t fun, uint16_t offset, uint16_t val);
void laihost_pci_writed(uint16_t seg, uint8_t bus, uint8_t slot, uint8_t fun, uint16_t offset, uint32_t val);

laihost_sleep

/* Sleeps for the given amount of milliseconds. Can be stubbed on emulators */
void laihost_sleep(uint64_t ms);

Optional

These functions are optional and LAI will not use them unless you try to use certain features. For example the sync functions will only be called when a lock is contended, this should not happen if you do not call LAI from 2 threads at once. (However it has been observed on 1 machine with buggy AML)

laihost_sync_wait

/* Blocks the current thread.
   The host ensures that calls to laihost_sync_wait() and laihost_sync_wake()
   on the same lai_sync_state are totally ordered.
   Before blocking, sync->val is compared against val. If these two values are non-equal, the function returns immediately.
   Returns a non-zero value if the timeout was exhausted and zero otherwise. */
int laihost_sync_wait(struct lai_sync_state *sync, unsigned int val, int64_t timeout);

laihost_sync_wake

/* Unblocks a blocked thread.
   The host ensures that calls to laihost_sync_wait() and laihost_sync_wake()
   on the same lai_sync_state are totally ordered. */
void laihost_sync_wake(struct lai_sync_state *sync);

Unnecessary

laihost_handle_amldebug

/* Reports information about a variable.
   This function does not need to be implemented, lai has a default implementation that will print all the info needed for debugging */
void laihost_handle_amldebug(lai_variable_t *var);

Initialization

Before you start using LAI's functions, you need to tell it the ACPI's revision and to let it enumerate the AML namespace.

lai_set_acpi_revision(rsdp->revision);
lai_create_namespace();

API

LAI's full API documentation can be found on GitHub, however here are some simple examples for using some helpers

ACPI Mode

This is how you enter full ACPI mode in LAI, do not forget to install an SCI handler and handle ACPI events.

// From <lai/helpers/sci.h>
lai_enable_acpi(0); // if you use legacy 8259 PIC
lai_enable_acpi(1); // if you use the IOAPIC

Shutdown

This is how you shutdown in LAI:

lai_enter_sleep(5); // From <lai/helpers/pm.h>, requires you have enumerated the namespace and are in ACPI mode

Reboot

This is how you reboot in LAI:

lai_acpi_reset(); // From <lai/helpers/pm.h>