tables.h File Reference

#include <uacpi/types.h>
#include <uacpi/status.h>

Include dependency graph for tables.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	uacpi_table_identifiers
struct	uacpi_table
struct	uacpi_table_info

Macros
#define	UACPI_TABLE_LOADED   (1 << 0)
#define	UACPI_TABLE_CSUM_CHECKED   (1 << 1)
#define	UACPI_TABLE_CSUM_BAD   (1 << 2)

Typedefs
typedef struct uacpi_table_identifiers	uacpi_table_identifiers
typedef struct uacpi_table	uacpi_table
typedef enum uacpi_table_installation_disposition	uacpi_table_installation_disposition
typedef uacpi_table_installation_disposition(*	uacpi_table_installation_handler) (struct acpi_sdt_hdr *hdr, uacpi_u64 *out_override_address)
typedef enum uacpi_table_origin	uacpi_table_origin
typedef struct uacpi_table_info	uacpi_table_info
typedef uacpi_iteration_decision(*	uacpi_table_iteration_callback) (uacpi_handle, uacpi_table_info *info)
typedef uacpi_iteration_decision(*	uacpi_subtable_iteration_callback) (uacpi_handle, struct acpi_entry_hdr *)

Enumerations
enum	uacpi_table_installation_disposition { UACPI_TABLE_INSTALLATION_DISPOSITON_ALLOW = 0 , UACPI_TABLE_INSTALLATION_DISPOSITON_DENY , UACPI_TABLE_INSTALLATION_DISPOSITON_VIRTUAL_OVERRIDE , UACPI_TABLE_INSTALLATION_DISPOSITON_PHYSICAL_OVERRIDE }
enum	uacpi_table_origin { UACPI_TABLE_ORIGIN_FIRMWARE_PHYSICAL = 1 << 0 , UACPI_TABLE_ORIGIN_FIRMWARE_VIRTUAL = 1 << 1 , UACPI_TABLE_ORIGIN_HOST_PHYSICAL = 1 << 2 , UACPI_TABLE_ORIGIN_HOST_VIRTUAL = 1 << 3 }

Functions
uacpi_size	uacpi_table_count (void)
uacpi_status	uacpi_table_install (void *, uacpi_table *out_table)
uacpi_status	uacpi_table_install_physical (uacpi_phys_addr, uacpi_table *out_table)
uacpi_status	uacpi_table_load (uacpi_size index)
uacpi_status	uacpi_table_find_by_signature (const uacpi_char *signature, uacpi_table *out_table)
uacpi_status	uacpi_table_find_by_signature_at (const uacpi_char *signature, uacpi_size offset, uacpi_table *out_table)
uacpi_status	uacpi_table_find_nth_by_signature (const uacpi_char *signature, uacpi_size nth, uacpi_table *out_table)
uacpi_status	uacpi_table_find_next_with_same_signature (uacpi_table *in_out_table)
uacpi_status	uacpi_table_find (const uacpi_table_identifiers *id, uacpi_table *out_table)
uacpi_status	uacpi_table_get_by_index (uacpi_size, uacpi_table *out_table)
uacpi_status	uacpi_table_ref (uacpi_table *)
uacpi_status	uacpi_table_ref_by_index (uacpi_size)
uacpi_status	uacpi_table_unref (uacpi_table *)
uacpi_status	uacpi_table_unref_by_index (uacpi_size)
uacpi_status	uacpi_table_fadt (struct acpi_fadt **)
uacpi_status	uacpi_set_table_installation_handler (uacpi_table_installation_handler handler)
uacpi_status	uacpi_for_each_table (uacpi_table_iteration_callback, void *user)
uacpi_status	uacpi_table_info_get_by_index (uacpi_size idx, uacpi_table_info *out_info)
uacpi_status	uacpi_for_each_subtable (struct acpi_sdt_hdr *hdr, size_t hdr_size, uacpi_subtable_iteration_callback cb, void *user)

Macro Definition Documentation

UACPI_TABLE_CSUM_BAD

#define UACPI_TABLE_CSUM_BAD   (1 << 2)

This table's checksum was found to be incorrect. Note that if UACPI_FLAG_PROACTIVE_TBL_CSUM is enabled alongside UACPI_FLAG_BAD_CSUM_FATAL, such tables are never installed in the first place.

Definition at line 257 of file tables.h.

UACPI_TABLE_CSUM_CHECKED

#define UACPI_TABLE_CSUM_CHECKED   (1 << 1)

This table's checksum has been checked. The checksum is valid if UACPI_TABLE_CSUM_BAD is not set.

Definition at line 249 of file tables.h.

UACPI_TABLE_LOADED

#define UACPI_TABLE_LOADED   (1 << 0)

This table has been processed & loaded by the AML interpreter. Only applicable for AML bytecode tables.

Definition at line 243 of file tables.h.

Typedef Documentation

uacpi_subtable_iteration_callback

typedef uacpi_iteration_decision(* uacpi_subtable_iteration_callback) (uacpi_handle, struct acpi_entry_hdr *)

Definition at line 297 of file tables.h.

uacpi_table

typedef struct uacpi_table uacpi_table

uacpi_table_identifiers

typedef struct uacpi_table_identifiers uacpi_table_identifiers

uacpi_table_info

typedef struct uacpi_table_info uacpi_table_info

uacpi_table_installation_disposition

typedef enum uacpi_table_installation_disposition uacpi_table_installation_disposition

uacpi_table_installation_handler

typedef uacpi_table_installation_disposition(* uacpi_table_installation_handler) (struct acpi_sdt_hdr *hdr, uacpi_u64 *out_override_address)

Definition at line 163 of file tables.h.

uacpi_table_iteration_callback

typedef uacpi_iteration_decision(* uacpi_table_iteration_callback) (uacpi_handle, uacpi_table_info *info)

Definition at line 270 of file tables.h.

uacpi_table_origin

typedef enum uacpi_table_origin uacpi_table_origin

Enumeration Type Documentation

uacpi_table_installation_disposition

enum uacpi_table_installation_disposition

Enumerator
UACPI_TABLE_INSTALLATION_DISPOSITON_ALLOW
UACPI_TABLE_INSTALLATION_DISPOSITON_DENY	Deny the table from being installed completely. This is useful for debugging various problems, e.g. AML loading bad SSDTs that cause the system to hang or enter an undesired state.
UACPI_TABLE_INSTALLATION_DISPOSITON_VIRTUAL_OVERRIDE	Override the table being installed with the table at the virtual address returned in 'out_override_address'.
UACPI_TABLE_INSTALLATION_DISPOSITON_PHYSICAL_OVERRIDE	Override the table being installed with the table at the physical address returned in 'out_override_address'.

Definition at line 139 of file tables.h.

                                                  {
    // Allow the table to be installed as-is
    UACPI_TABLE_INSTALLATION_DISPOSITON_ALLOW = 0,
 
    UACPI_TABLE_INSTALLATION_DISPOSITON_DENY,
 
    UACPI_TABLE_INSTALLATION_DISPOSITON_VIRTUAL_OVERRIDE,
 
    UACPI_TABLE_INSTALLATION_DISPOSITON_PHYSICAL_OVERRIDE,
} uacpi_table_installation_disposition;

uacpi_table_origin

enum uacpi_table_origin

Enumerator
UACPI_TABLE_ORIGIN_FIRMWARE_PHYSICAL	A table that originated from a physical address provided by the firmware. All tables discovered via RSDP have this origin.
UACPI_TABLE_ORIGIN_FIRMWARE_VIRTUAL	A table that was dynamically loaded by the AML firmware. This includes both Load/LoadTable opcodes. Such tables live in a heap-allocated kernel buffer.
UACPI_TABLE_ORIGIN_HOST_PHYSICAL	A table installed by the client code via uacpi_table_install_physical().
UACPI_TABLE_ORIGIN_HOST_VIRTUAL	A table installed by the client code via uacpi_table_install().

Definition at line 176 of file tables.h.

                                {
    UACPI_TABLE_ORIGIN_FIRMWARE_PHYSICAL = 1 << 0,
 
    UACPI_TABLE_ORIGIN_FIRMWARE_VIRTUAL = 1 << 1,
 
    UACPI_TABLE_ORIGIN_HOST_PHYSICAL = 1 << 2,
 
    UACPI_TABLE_ORIGIN_HOST_VIRTUAL = 1 << 3,
} uacpi_table_origin;

Function Documentation

uacpi_for_each_subtable()

uacpi_status uacpi_for_each_subtable	(	struct acpi_sdt_hdr *	hdr,
		size_t	hdr_size,
		uacpi_subtable_iteration_callback	cb,
		void *	user
	)

Iterate every subtable of a table such as MADT or SRAT.

'hdr' is the pointer to the main table, 'hdr_size' is the number of bytes in the table before the beginning of the subtable records. 'cb' is the callback invoked for each subtable with the 'user' context pointer passed for every invocation.

Example usage: uacpi_table tbl;

uacpi_table_find_by_signature(ACPI_MADT_SIGNATURE, &tbl); uacpi_for_each_subtable( tbl.hdr, sizeof(struct acpi_madt), parse_madt, NULL );

Definition at line 1600 of file tables.c.

{
    void *cursor;
    size_t bytes_left;
 
    cursor = UACPI_PTR_ADD(hdr, hdr_size);
    bytes_left = hdr->length - hdr_size;
 
    if (uacpi_unlikely(bytes_left > hdr->length))
        return UACPI_STATUS_INVALID_TABLE_LENGTH;
 
    while (bytes_left > sizeof(struct acpi_entry_hdr)) {
        struct acpi_entry_hdr *subtable_hdr = cursor;
 
        if (uacpi_unlikely(subtable_hdr->length > bytes_left ||
                           subtable_hdr->length < sizeof(*subtable_hdr))) {
            uacpi_error(
                "corrupted '%.4s' subtable length: %u (%zu bytes left)",
                hdr->signature, subtable_hdr->length, bytes_left
            );
            return UACPI_STATUS_INVALID_TABLE_LENGTH;
        }
 
        switch (cb(user, subtable_hdr)) {
        case UACPI_ITERATION_DECISION_CONTINUE:
            break;
        case UACPI_ITERATION_DECISION_BREAK:
            return UACPI_STATUS_OK;
        default:
            return UACPI_STATUS_INVALID_ARGUMENT;
        }
 
        cursor = UACPI_PTR_ADD(cursor, subtable_hdr->length);
        bytes_left -= subtable_hdr->length;
    }
 
    if (uacpi_unlikely(bytes_left != 0)) {
        uacpi_warn(
            "found %zu stray bytes in table '%.4s'",
            bytes_left, hdr->signature
        );
    }
 
    return UACPI_STATUS_OK;
}

uacpi_for_each_table()

uacpi_status uacpi_for_each_table	(	uacpi_table_iteration_callback	cb,
		void *	user
	)

Iterate every installed table on the system.

The provided callback receives the information about each table in the 'info' pointer. A table may be mapped by client code if needed via uacpi_table_get_by_index().

Note that this is a low level helper that iterates every installed table, even tables that are unreachable via uacpi_table_find() etc. due to bad checksum.

Definition at line 658 of file tables.c.

{
    uacpi_status ret;
    uacpi_size num_tables, i = 0;
    uacpi_table_info info;
 
    ENSURE_TABLES_ONLINE();
 
    for (;;) {
        ret = uacpi_acquire_native_mutex_may_be_null(table_mutex);
        if (uacpi_unlikely_error(ret))
            return ret;
 
        // Number of tables may have increased while we were in the callback
        num_tables = table_array_size(&tables);
        if (i >= num_tables) {
            ret = uacpi_release_native_mutex_may_be_null(table_mutex);
            return ret;
        }
 
        table_info_by_index_unchecked(i, &info);
 
        ret = uacpi_release_native_mutex_may_be_null(table_mutex);
        if (uacpi_unlikely_error(ret))
            return ret;
 
        if (cb(user, &info) == UACPI_ITERATION_DECISION_BREAK)
            break;
 
        i++;
    }
 
    return UACPI_STATUS_OK;
}

uacpi_set_table_installation_handler()

uacpi_status uacpi_set_table_installation_handler

(

uacpi_table_installation_handler

handler

)

Set a handler that is invoked for each table before it gets installed.

Depending on the return value, the table is either allowed to be installed as-is, denied, or overriden with a new one.

Definition at line 392 of file tables.c.

{
    uacpi_status ret;
 
    ret = uacpi_acquire_native_mutex_may_be_null(table_mutex);
    if (uacpi_unlikely_error(ret))
        return ret;
 
    if (installation_handler != UACPI_NULL && handler != UACPI_NULL)
        goto out;
 
    installation_handler = handler;
 
out:
    uacpi_release_native_mutex_may_be_null(table_mutex);
    return ret;
}

uacpi_table_count()

uacpi_size uacpi_table_count

(

void

)

Returns the number of tables stored in the internal array via 'out_count'. This includes all firmware-provided, dynamically loaded, as well as client-installed tables via 'uacpi_table_install' etc.

Definition at line 211 of file tables.c.

{
    return table_array_size(&tables);
}

uacpi_table_fadt()

uacpi_status uacpi_table_fadt

(

struct acpi_fadt **

out_fadt

)

Returns the pointer to a sanitized internal version of FADT.

The revision is guaranteed to be correct. All of the registers are converted to GAS format. Fields that might contain garbage are cleared.

Definition at line 1589 of file tables.c.

{
    ENSURE_TABLES_ONLINE();
 
    if (!fadt_available)
        return UACPI_STATUS_NOT_FOUND;
 
    *out_fadt = &g_uacpi_rt_ctx.fadt;
    return UACPI_STATUS_OK;
}

uacpi_table_find()

uacpi_status uacpi_table_find	(	const uacpi_table_identifiers *	id,
		uacpi_table *	out_table
	)

Definition at line 1178 of file tables.c.

{
    ENSURE_TABLES_ONLINE();
 
    return find_table(0, 0, id, out_table);
}

Referenced by handle_create_data_region(), and handle_load_table().

uacpi_table_find_by_signature()

uacpi_status uacpi_table_find_by_signature	(	const uacpi_char *	signature,
		uacpi_table *	out_table
	)

Helpers for finding tables.

for find_by_signature: 'signature' is an array of 4 characters, a null terminator is not necessary and can be omitted (especially useful for non-C language bindings)

for find_by_signature_at: 'offset' specifies the base index in the internal array where to start searching for the table

for find_nth_by_signature: This works exactly like find_by_signature, but finds the nth copy of the specified table in the firmware enumeration order

'out_table' is a pointer to a caller allocated uacpi_table structure that receives the table pointer & its internal index in case the call was successful.

NOTE: The returned table's reference count is incremented by 1, which keeps its mapping alive forever unless uacpi_table_unref() is called for this table later on. Calling uacpi_table_find_next_with_same_signature() on a table also drops its reference count by 1, so if you want to keep it mapped you must manually call uacpi_table_ref() beforehand.

Definition at line 1153 of file tables.c.

{
    return find_table_by_signature(signature_string, 0, 0, out_table);
}

Referenced by uacpi_namespace_load().

uacpi_table_find_by_signature_at()

uacpi_status uacpi_table_find_by_signature_at	(	const uacpi_char *	signature,
		uacpi_size	offset,
		uacpi_table *	out_table
	)

Definition at line 1139 of file tables.c.

{
    return find_table_by_signature(signature, idx, 0, out_table);
}

uacpi_table_find_next_with_same_signature()

uacpi_status uacpi_table_find_next_with_same_signature

(

uacpi_table *

in_out_table

)

Definition at line 1160 of file tables.c.

{
    struct uacpi_table_identifiers id = { 0 };
 
    ENSURE_TABLES_ONLINE();
 
    if (uacpi_unlikely(in_out_table->ptr == UACPI_NULL))
        return UACPI_STATUS_INVALID_ARGUMENT;
 
    uacpi_memcpy(&id.signature, in_out_table->hdr->signature,
                 sizeof(id.signature));
    uacpi_table_unref(in_out_table);
 
    return find_table(in_out_table->index + 1, 0, &id, in_out_table);
}

uacpi_table_find_nth_by_signature()

uacpi_status uacpi_table_find_nth_by_signature	(	const uacpi_char *	signature,
		uacpi_size	nth,
		uacpi_table *	out_table
	)

Definition at line 1146 of file tables.c.

{
    return find_table_by_signature(signature, 0, nth, out_table);
}

uacpi_table_get_by_index()

uacpi_status uacpi_table_get_by_index	(	uacpi_size	idx,
		uacpi_table *	out_table
	)

Returns a table by its index in the internal table array.

The number of available tables can be queried via 'uacpi_table_count()'.

NOTE: Even if a table is present, this may still fail with UACPI_STATUS_BAD_CHECKSUM in case UACPI_FLAG_BAD_CSUM_FATAL is enabled.

Definition at line 1318 of file tables.c.

{
    uacpi_status ret;
    struct table_ctl_request req = {
        .type = TABLE_CTL_GET,
    };
 
    ret = table_ctl(idx, &req);
    if (uacpi_unlikely_error(ret))
        return ret;
 
    out_table->ptr = req.out_tbl;
    out_table->index = idx;
    return UACPI_STATUS_OK;
}

uacpi_table_info_get_by_index()

uacpi_status uacpi_table_info_get_by_index	(	uacpi_size	idx,
		uacpi_table_info *	out_info
	)

Definition at line 630 of file tables.c.

{
    uacpi_status ret;
 
    ENSURE_TABLES_ONLINE();
 
    ret = uacpi_acquire_native_mutex_may_be_null(table_mutex);
    if (uacpi_unlikely_error(ret))
        return ret;
 
    if (uacpi_unlikely(table_array_size(&tables) <= idx)) {
        uacpi_error(
            "requested invalid table index %zu (%zu tables installed)",
            idx, table_array_size(&tables)
        );
        ret = UACPI_STATUS_INVALID_ARGUMENT;
        goto out;
    }
 
    table_info_by_index_unchecked(idx, out_info);
 
out:
    uacpi_release_native_mutex_may_be_null(table_mutex);
    return ret;
}

uacpi_table_install()

uacpi_status uacpi_table_install	(	void *	virt,
		uacpi_table *	out_table
	)

Install a table from either a virtual or a physical address. The table is simply stored in the internal table array, and not loaded by the interpreter (see uacpi_table_load).

The table is optionally returned via 'out_table'.

Manual calls to uacpi_table_install are not subject to filtering via the table installation callback (if any).

Definition at line 951 of file tables.c.

{
    ENSURE_TABLES_ONLINE();
 
    return uacpi_table_install_with_origin(
        virt, UACPI_TABLE_ORIGIN_HOST_VIRTUAL, out_table
    );
}

uacpi_table_install_physical()

uacpi_status uacpi_table_install_physical	(	uacpi_phys_addr	addr,
		uacpi_table *	out_table
	)

Definition at line 960 of file tables.c.

{
    ENSURE_TABLES_ONLINE();
 
    return uacpi_table_install_physical_with_origin(
        addr, UACPI_TABLE_ORIGIN_HOST_PHYSICAL, out_table
    );
}

uacpi_table_load()

uacpi_status uacpi_table_load

(

uacpi_size

index

)

Load a previously installed table by feeding it to the interpreter.

Definition at line 1303 of file tables.c.

{
    return uacpi_table_load_with_cause(idx, UACPI_TABLE_LOAD_CAUSE_HOST);
}

uacpi_table_ref()

uacpi_status uacpi_table_ref

(

uacpi_table *

tbl

)

Increment/decrement a table's reference count. The table is unmapped when the reference count drops to 0.

Definition at line 1343 of file tables.c.

{
    return uacpi_table_ref_by_index(tbl->index);
}

uacpi_table_ref_by_index()

uacpi_status uacpi_table_ref_by_index

(

uacpi_size

index

)

Definition at line 1334 of file tables.c.

{
    struct table_ctl_request req = {
        .type = TABLE_CTL_GET
    };
 
    return table_ctl(index, &req);
}

Referenced by uacpi_table_ref().

uacpi_table_unref()

uacpi_status uacpi_table_unref

(

uacpi_table *

tbl

)

Definition at line 1357 of file tables.c.

{
    return uacpi_table_unref_by_index(tbl->index);
}

Referenced by free_op_region(), handle_load(), handle_load_table(), uacpi_namespace_load(), and uacpi_table_find_next_with_same_signature().

uacpi_table_unref_by_index()

uacpi_status uacpi_table_unref_by_index

(

uacpi_size

index

)

Definition at line 1348 of file tables.c.

{
    struct table_ctl_request req = {
        .type = TABLE_CTL_PUT
    };
 
    return table_ctl(index, &req);
}

Referenced by uacpi_table_unref().