namespace.h File Reference

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

Include dependency graph for namespace.h:

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

Go to the source code of this file.

Macros
#define	UACPI_MAX_DEPTH_ANY   0xFFFFFFFF

Typedefs
typedef struct uacpi_namespace_node	uacpi_namespace_node
typedef enum uacpi_predefined_namespace	uacpi_predefined_namespace
typedef uacpi_iteration_decision(*	uacpi_iteration_callback) (void *user, uacpi_namespace_node *node, uacpi_u32 node_depth)

Enumerations
enum	uacpi_predefined_namespace {   UACPI_PREDEFINED_NAMESPACE_ROOT = 0 , UACPI_PREDEFINED_NAMESPACE_GPE , UACPI_PREDEFINED_NAMESPACE_PR , UACPI_PREDEFINED_NAMESPACE_SB ,   UACPI_PREDEFINED_NAMESPACE_SI , UACPI_PREDEFINED_NAMESPACE_TZ , UACPI_PREDEFINED_NAMESPACE_GL , UACPI_PREDEFINED_NAMESPACE_OS ,   UACPI_PREDEFINED_NAMESPACE_OSI , UACPI_PREDEFINED_NAMESPACE_REV , UACPI_PREDEFINED_NAMESPACE_MAX = UACPI_PREDEFINED_NAMESPACE_REV }

Functions
uacpi_namespace_node *	uacpi_namespace_root (void)
uacpi_namespace_node *	uacpi_namespace_get_predefined (uacpi_predefined_namespace)
uacpi_bool	uacpi_namespace_node_is_alias (uacpi_namespace_node *node)
uacpi_object_name	uacpi_namespace_node_name (const uacpi_namespace_node *node)
uacpi_status	uacpi_namespace_node_type (const uacpi_namespace_node *node, uacpi_object_type *out_type)
uacpi_status	uacpi_namespace_node_is (const uacpi_namespace_node *node, uacpi_object_type type, uacpi_bool *out)
uacpi_status	uacpi_namespace_node_is_one_of (const uacpi_namespace_node *node, uacpi_object_type_bits type_mask, uacpi_bool *out)
uacpi_size	uacpi_namespace_node_depth (const uacpi_namespace_node *node)
uacpi_namespace_node *	uacpi_namespace_node_parent (uacpi_namespace_node *node)
uacpi_status	uacpi_namespace_node_find (uacpi_namespace_node *parent, const uacpi_char *path, uacpi_namespace_node **out_node)
uacpi_status	uacpi_namespace_node_resolve_from_aml_namepath (uacpi_namespace_node *scope, const uacpi_char *path, uacpi_namespace_node **out_node)
uacpi_status	uacpi_namespace_for_each_child_simple (uacpi_namespace_node *parent, uacpi_iteration_callback callback, void *user)
uacpi_status	uacpi_namespace_for_each_child (uacpi_namespace_node *parent, uacpi_iteration_callback descending_callback, uacpi_iteration_callback ascending_callback, uacpi_object_type_bits type_mask, uacpi_u32 max_depth, void *user)
uacpi_status	uacpi_namespace_node_next (uacpi_namespace_node *parent, uacpi_namespace_node **iter)
uacpi_status	uacpi_namespace_node_next_typed (uacpi_namespace_node *parent, uacpi_namespace_node **iter, uacpi_object_type_bits type_mask)
const uacpi_char *	uacpi_namespace_node_generate_absolute_path (const uacpi_namespace_node *node)
void	uacpi_free_absolute_path (const uacpi_char *path)

Macro Definition Documentation

UACPI_MAX_DEPTH_ANY

#define UACPI_MAX_DEPTH_ANY   0xFFFFFFFF

Definition at line 102 of file namespace.h.

Typedef Documentation

uacpi_iteration_callback

typedef uacpi_iteration_decision(* uacpi_iteration_callback) (void *user, uacpi_namespace_node *node, uacpi_u32 node_depth)

Definition at line 98 of file namespace.h.

uacpi_namespace_node

typedef struct uacpi_namespace_node uacpi_namespace_node

Definition at line 12 of file namespace.h.

uacpi_predefined_namespace

typedef enum uacpi_predefined_namespace uacpi_predefined_namespace

Enumeration Type Documentation

uacpi_predefined_namespace

enum uacpi_predefined_namespace

Enumerator
UACPI_PREDEFINED_NAMESPACE_ROOT
UACPI_PREDEFINED_NAMESPACE_GPE
UACPI_PREDEFINED_NAMESPACE_PR
UACPI_PREDEFINED_NAMESPACE_SB
UACPI_PREDEFINED_NAMESPACE_SI
UACPI_PREDEFINED_NAMESPACE_TZ
UACPI_PREDEFINED_NAMESPACE_GL
UACPI_PREDEFINED_NAMESPACE_OS
UACPI_PREDEFINED_NAMESPACE_OSI
UACPI_PREDEFINED_NAMESPACE_REV
UACPI_PREDEFINED_NAMESPACE_MAX

Definition at line 16 of file namespace.h.

                                        {
    UACPI_PREDEFINED_NAMESPACE_ROOT = 0,
    UACPI_PREDEFINED_NAMESPACE_GPE,
    UACPI_PREDEFINED_NAMESPACE_PR,
    UACPI_PREDEFINED_NAMESPACE_SB,
    UACPI_PREDEFINED_NAMESPACE_SI,
    UACPI_PREDEFINED_NAMESPACE_TZ,
    UACPI_PREDEFINED_NAMESPACE_GL,
    UACPI_PREDEFINED_NAMESPACE_OS,
    UACPI_PREDEFINED_NAMESPACE_OSI,
    UACPI_PREDEFINED_NAMESPACE_REV,
    UACPI_PREDEFINED_NAMESPACE_MAX = UACPI_PREDEFINED_NAMESPACE_REV,
} uacpi_predefined_namespace;

Function Documentation

uacpi_free_absolute_path()

void uacpi_free_absolute_path

(

const uacpi_char *

path

)

Definition at line 1074 of file namespace.c.

{
    uacpi_free_dynamic_string(path);
}

Referenced by exec_op().

uacpi_namespace_for_each_child()

uacpi_status uacpi_namespace_for_each_child	(	uacpi_namespace_node *	parent,
		uacpi_iteration_callback	descending_callback,
		uacpi_iteration_callback	ascending_callback,
		uacpi_object_type_bits	type_mask,
		uacpi_u32	max_depth,
		void *	user
	)

Depth-first iterate the namespace starting at the first child of 'parent'.

'descending_callback' is invoked the first time a node is visited when walking down. 'ascending_callback' is invoked the second time a node is visited after we reach the leaf node without children and start walking up. Either of the callbacks may be NULL, but not both at the same time.

Only nodes matching 'type_mask' are passed to the callbacks.

'max_depth' is used to limit the maximum reachable depth from 'parent', where 1 is only direct children of 'parent', 2 is children of first-level children etc. Use UACPI_MAX_DEPTH_ANY or -1 to specify infinite depth.

Definition at line 948 of file namespace.c.

{
    return uacpi_namespace_do_for_each_child(
        parent, descending_callback, ascending_callback, type_mask, max_depth,
        UACPI_SHOULD_LOCK_YES, UACPI_PERMANENT_ONLY_YES, user
    );
}

Referenced by uacpi_find_devices_at(), and uacpi_namespace_initialize().

uacpi_namespace_for_each_child_simple()

uacpi_status uacpi_namespace_for_each_child_simple	(	uacpi_namespace_node *	parent,
		uacpi_iteration_callback	callback,
		void *	user
	)

Depth-first iterate the namespace starting at the first child of 'parent'.

Definition at line 938 of file namespace.c.

{
    return uacpi_namespace_do_for_each_child(
        parent, callback, UACPI_NULL, UACPI_OBJECT_ANY_BIT, UACPI_MAX_DEPTH_ANY,
        UACPI_SHOULD_LOCK_YES, UACPI_PERMANENT_ONLY_YES, user
    );
}

uacpi_namespace_get_predefined()

uacpi_namespace_node * uacpi_namespace_get_predefined

(

uacpi_predefined_namespace

ns

)

Definition at line 269 of file namespace.c.

{
    if (uacpi_unlikely(ns > UACPI_PREDEFINED_NAMESPACE_MAX)) {
        uacpi_warn("requested invalid predefined namespace %d", ns);
        return UACPI_NULL;
    }
 
    return &predefined_namespaces[ns];
}

Referenced by do_sta_ini(), eval_sst(), initialize_gpes(), sanitize_device_and_find_gpe(), and uacpi_namespace_initialize().

uacpi_namespace_node_depth()

uacpi_size uacpi_namespace_node_depth

(

const uacpi_namespace_node *

node

)

Definition at line 1015 of file namespace.c.

{
    uacpi_size depth = 0;
 
    while (node->parent) {
        depth++;
        node = node->parent;
    }
 
    return depth;
}

Referenced by uacpi_namespace_node_generate_absolute_path().

uacpi_namespace_node_find()

uacpi_status uacpi_namespace_node_find	(	uacpi_namespace_node *	parent,
		const uacpi_char *	path,
		uacpi_namespace_node **	out_node
	)

Definition at line 623 of file namespace.c.

{
    return uacpi_namespace_node_resolve(
        parent, path, UACPI_SHOULD_LOCK_YES, UACPI_MAY_SEARCH_ABOVE_PARENT_NO,
        UACPI_PERMANENT_ONLY_YES, out_node
    );
}

uacpi_namespace_node_generate_absolute_path()

const uacpi_char * uacpi_namespace_node_generate_absolute_path

(

const uacpi_namespace_node *

node

)

Definition at line 1034 of file namespace.c.

{
    uacpi_size depth, offset;
    uacpi_size bytes_needed;
    uacpi_char *path;
 
    depth = uacpi_namespace_node_depth(node) + 1;
 
    // \ only needs 1 byte, the rest is 4 bytes
    bytes_needed = 1 + (depth - 1) * sizeof(uacpi_object_name);
 
    // \ and the first NAME don't need a '.', every other segment does
    bytes_needed += depth > 2 ? depth - 2 : 0;
 
    // Null terminator
    bytes_needed += 1;
 
    path = uacpi_kernel_alloc(bytes_needed);
    if (uacpi_unlikely(path == UACPI_NULL))
        return path;
 
    path[0] = '\\';
 
    offset = bytes_needed - 1;
    path[offset] = '\0';
 
    while (node != uacpi_namespace_root()) {
        offset -= sizeof(uacpi_object_name);
        uacpi_memcpy(&path[offset], node->name.text, sizeof(uacpi_object_name));
 
        node = node->parent;
        if (node != uacpi_namespace_root())
            path[--offset] = '.';
    }
 
    return path;
}

Referenced by exec_op(), handle_notify(), trace_invalid_return_type(), trace_method_abort(), trace_named_object_lookup_or_creation_failure(), trace_region_io(), uacpi_dispatch_opregion_io(), uacpi_eval_dstate_method_template(), and uacpi_trace_region_error().

uacpi_namespace_node_is()

uacpi_status uacpi_namespace_node_is	(	const uacpi_namespace_node *	node,
		uacpi_object_type	type,
		uacpi_bool *	out
	)

Returns UACPI_TRUE via 'out' if the type of the object stored at the namespace node matches the provided value, UACPI_FALSE otherwise.

NOTE: due to the existance of the CopyObject operator in AML, the return value of this function is subject to TOCTOU bugs.

Definition at line 825 of file namespace.c.

{
    return uacpi_namespace_node_is_one_of(
        node, 1u << type, out
    );
}

Referenced by eval_resource_helper(), uacpi_install_gpe_block(), uacpi_setup_gpe_for_wake(), and uacpi_uninstall_gpe_block().

uacpi_namespace_node_is_alias()

uacpi_bool uacpi_namespace_node_is_alias

(

uacpi_namespace_node *

node

)

Returns UACPI_TRUE if the provided 'node' is an alias.

Definition at line 328 of file namespace.c.

{
    return node->flags & UACPI_NAMESPACE_NODE_FLAG_ALIAS;
}

Referenced by do_sta_ini().

uacpi_namespace_node_is_one_of()

uacpi_status uacpi_namespace_node_is_one_of	(	const uacpi_namespace_node *	node,
		uacpi_object_type_bits	type_mask,
		uacpi_bool *	out
	)

Returns UACPI_TRUE via 'out' if the type of the object stored at the namespace node matches any of the type bits in the provided value, UACPI_FALSE otherwise.

NOTE: due to the existance of the CopyObject operator in AML, the return value of this function is subject to TOCTOU bugs.

Definition at line 808 of file namespace.c.

{
    uacpi_status ret;
 
    ret = uacpi_namespace_read_lock();
    if (uacpi_unlikely_error(ret))
        return ret;
 
    ret = uacpi_namespace_node_is_one_of_unlocked(node,type_mask, out);
 
    uacpi_namespace_read_unlock();
    return ret;
}

Referenced by uacpi_namespace_node_is().

uacpi_namespace_node_name()

uacpi_object_name uacpi_namespace_node_name

(

const uacpi_namespace_node *

node

)

Definition at line 752 of file namespace.c.

{
    return node->name;
}

Referenced by async_run_gpe_handler(), uacpi_eval_cid(), uacpi_eval_hid(), uacpi_eval_uid(), and uacpi_get_namespace_node_info().

uacpi_namespace_node_next()

uacpi_status uacpi_namespace_node_next	(	uacpi_namespace_node *	parent,
		uacpi_namespace_node **	iter
	)

Retrieve the next peer namespace node of '*iter', or, if '*iter' is UACPI_NULL, retrieve the first child of 'parent' instead. The resulting namespace node is stored at '*iter'.

This API can be used to implement an "iterator" version of the for_each_child helpers.

Example usage: void recurse(uacpi_namespace_node *parent) { uacpi_namespace_node *iter = UACPI_NULL;

while (uacpi_namespace_node_next(parent, &iter) == UACPI_STATUS_OK) { // Do something with iter... descending_callback(iter);

// Recurse down to walk over the children of iter recurse(iter); } }

Prefer the for_each_child family of helpers if possible instead of this API as they avoid recursion and/or the need to use dynamic data structures entirely.

Definition at line 1006 of file namespace.c.

{
    return uacpi_namespace_node_next_typed(
        parent, iter, UACPI_OBJECT_ANY_BIT
    );
}

uacpi_namespace_node_next_typed()

uacpi_status uacpi_namespace_node_next_typed	(	uacpi_namespace_node *	parent,
		uacpi_namespace_node **	iter,
		uacpi_object_type_bits	type_mask
	)

Retrieve the next peer namespace node of '*iter', or, if '*iter' is UACPI_NULL, retrieve the first child of 'parent' instead. The resulting namespace node is stored at '*iter'. Only nodes which type matches one of the types set in 'type_mask' are returned.

See comment above 'uacpi_namespace_node_next' for usage examples.

Prefer the for_each_child family of helpers if possible instead of this API as they avoid recursion and/or the need to use dynamic data structures entirely.

Definition at line 960 of file namespace.c.

{
    uacpi_status ret;
    uacpi_bool is_one_of;
    uacpi_namespace_node *node;
 
    UACPI_ENSURE_INIT_LEVEL_AT_LEAST(UACPI_INIT_LEVEL_SUBSYSTEM_INITIALIZED);
 
    if (uacpi_unlikely(parent == UACPI_NULL && *iter == UACPI_NULL))
        return UACPI_STATUS_INVALID_ARGUMENT;
 
    ret = uacpi_namespace_read_lock();
    if (uacpi_unlikely_error(ret))
        return ret;
 
    node = *iter;
    if (node == UACPI_NULL)
        node = parent->child;
    else
        node = node->next;
 
    for (; node != UACPI_NULL; node = node->next) {
        if (uacpi_namespace_node_is_temporary(node))
            continue;
 
        ret = uacpi_namespace_node_is_one_of_unlocked(
            node, type_mask, &is_one_of
        );
        if (uacpi_unlikely_error(ret))
            break;
        if (is_one_of)
            break;
    }
 
    uacpi_namespace_read_unlock();
    if (node == UACPI_NULL)
        return UACPI_STATUS_NOT_FOUND;
 
    if (uacpi_likely_success(ret))
        *iter = node;
    return ret;
}

Referenced by uacpi_namespace_node_next().

uacpi_namespace_node_parent()

uacpi_namespace_node * uacpi_namespace_node_parent

(

uacpi_namespace_node *

node

)

Definition at line 1027 of file namespace.c.

{
    return node->parent;
}

uacpi_namespace_node_resolve_from_aml_namepath()

uacpi_status uacpi_namespace_node_resolve_from_aml_namepath	(	uacpi_namespace_node *	scope,
		const uacpi_char *	path,
		uacpi_namespace_node **	out_node
	)

Same as uacpi_namespace_node_find, except the search recurses upwards when the namepath consists of only a single nameseg. Usually, this behavior is only desired if resolving a namepath specified in an aml-provided object, such as a package element.

Definition at line 634 of file namespace.c.

{
    return uacpi_namespace_node_resolve(
        scope, path, UACPI_SHOULD_LOCK_YES, UACPI_MAY_SEARCH_ABOVE_PARENT_YES,
        UACPI_PERMANENT_ONLY_YES, out_node
    );
}

Referenced by uacpi_object_resolve_as_aml_namepath().

uacpi_namespace_node_type()

uacpi_status uacpi_namespace_node_type	(	const uacpi_namespace_node *	node,
		uacpi_object_type *	out_type
	)

Returns the type of object stored at the namespace node.

NOTE: due to the existance of the CopyObject operator in AML, the return value of this function is subject to TOCTOU bugs.

Definition at line 774 of file namespace.c.

{
    uacpi_status ret;
 
    ret = uacpi_namespace_read_lock();
    if (uacpi_unlikely_error(ret))
        return ret;
 
    ret = uacpi_namespace_node_type_unlocked(node, out_type);
 
    uacpi_namespace_read_unlock();
    return ret;
}

Referenced by do_sta_ini(), and pci_region_attach().

uacpi_namespace_root()

uacpi_namespace_node * uacpi_namespace_root

(

void

)

Definition at line 264 of file namespace.c.

{
    return &predefined_namespaces[UACPI_PREDEFINED_NAMESPACE_ROOT];
}

Referenced by eval_pts(), eval_wak(), extract_handlers(), find_pci_root(), frame_reset_post_end_block(), get_slp_type_for_state(), handle_load(), handle_load_table(), object_replace_child(), resolve_name_string(), uacpi_deinitialize_namespace(), uacpi_execute_table(), uacpi_find_devices(), uacpi_initialize_namespace(), uacpi_install_default_address_space_handlers(), uacpi_install_notify_handler(), uacpi_namespace_initialize(), uacpi_namespace_node_find_sub_node(), uacpi_namespace_node_generate_absolute_path(), uacpi_namespace_node_install(), uacpi_namespace_node_resolve(), uacpi_node_get_address_space_handlers(), uacpi_set_interrupt_model(), uacpi_setup_gpe_for_wake(), and uacpi_uninstall_notify_handler().