1#pragma once
2
3#include <uacpi/types.h>
4#include <uacpi/status.h>
5
6#ifdef __cplusplus
7extern "C" {
8#endif
9
10#ifndef UACPI_BAREBONES_MODE
11
12typedef struct uacpi_namespace_node uacpi_namespace_node;
13
14uacpi_namespace_node *uacpi_namespace_root(void);
15
16typedef enum uacpi_predefined_namespace {
17 UACPI_PREDEFINED_NAMESPACE_ROOT = 0,
18 UACPI_PREDEFINED_NAMESPACE_GPE,
19 UACPI_PREDEFINED_NAMESPACE_PR,
20 UACPI_PREDEFINED_NAMESPACE_SB,
21 UACPI_PREDEFINED_NAMESPACE_SI,
22 UACPI_PREDEFINED_NAMESPACE_TZ,
23 UACPI_PREDEFINED_NAMESPACE_GL,
24 UACPI_PREDEFINED_NAMESPACE_OS,
25 UACPI_PREDEFINED_NAMESPACE_OSI,
26 UACPI_PREDEFINED_NAMESPACE_REV,
27 UACPI_PREDEFINED_NAMESPACE_MAX = UACPI_PREDEFINED_NAMESPACE_REV,
28} uacpi_predefined_namespace;
29uacpi_namespace_node *uacpi_namespace_get_predefined(
30 uacpi_predefined_namespace
31);
32
33/**
34 * Returns UACPI_TRUE if the provided 'node' is an alias.
35 */
36uacpi_bool uacpi_namespace_node_is_alias(uacpi_namespace_node *node);
37
38uacpi_object_name uacpi_namespace_node_name(const uacpi_namespace_node *node);
39
40/**
41 * Returns the type of object stored at the namespace node.
42 *
43 * NOTE: due to the existance of the CopyObject operator in AML, the
44 * return value of this function is subject to TOCTOU bugs.
45 */
46uacpi_status uacpi_namespace_node_type(
47 const uacpi_namespace_node *node, uacpi_object_type *out_type
48);
49
50/**
51 * Returns UACPI_TRUE via 'out' if the type of the object stored at the
52 * namespace node matches the provided value, UACPI_FALSE otherwise.
53 *
54 * NOTE: due to the existance of the CopyObject operator in AML, the
55 * return value of this function is subject to TOCTOU bugs.
56 */
57uacpi_status uacpi_namespace_node_is(
58 const uacpi_namespace_node *node, uacpi_object_type type, uacpi_bool *out
59);
60
61/**
62 * Returns UACPI_TRUE via 'out' if the type of the object stored at the
63 * namespace node matches any of the type bits in the provided value,
64 * UACPI_FALSE otherwise.
65 *
66 * NOTE: due to the existance of the CopyObject operator in AML, the
67 * return value of this function is subject to TOCTOU bugs.
68 */
69uacpi_status uacpi_namespace_node_is_one_of(
70 const uacpi_namespace_node *node, uacpi_object_type_bits type_mask,
71 uacpi_bool *out
72);
73
74uacpi_size uacpi_namespace_node_depth(const uacpi_namespace_node *node);
75
76uacpi_namespace_node *uacpi_namespace_node_parent(
77 uacpi_namespace_node *node
78);
79
80uacpi_status uacpi_namespace_node_find(
81 uacpi_namespace_node *parent,
82 const uacpi_char *path,
83 uacpi_namespace_node **out_node
84);
85
86/**
87 * Same as uacpi_namespace_node_find, except the search recurses upwards when
88 * the namepath consists of only a single nameseg. Usually, this behavior is
89 * only desired if resolving a namepath specified in an aml-provided object,
90 * such as a package element.
91 */
92uacpi_status uacpi_namespace_node_resolve_from_aml_namepath(
93 uacpi_namespace_node *scope,
94 const uacpi_char *path,
95 uacpi_namespace_node **out_node
96);
97
98typedef uacpi_iteration_decision (*uacpi_iteration_callback) (
99 void *user, uacpi_namespace_node *node, uacpi_u32 node_depth
100);
101
102#define UACPI_MAX_DEPTH_ANY 0xFFFFFFFF
103
104/**
105 * Depth-first iterate the namespace starting at the first child of 'parent'.
106 */
107uacpi_status uacpi_namespace_for_each_child_simple(
108 uacpi_namespace_node *parent, uacpi_iteration_callback callback, void *user
109);
110
111/**
112 * Depth-first iterate the namespace starting at the first child of 'parent'.
113 *
114 * 'descending_callback' is invoked the first time a node is visited when
115 * walking down. 'ascending_callback' is invoked the second time a node is
116 * visited after we reach the leaf node without children and start walking up.
117 * Either of the callbacks may be NULL, but not both at the same time.
118 *
119 * Only nodes matching 'type_mask' are passed to the callbacks.
120 *
121 * 'max_depth' is used to limit the maximum reachable depth from 'parent',
122 * where 1 is only direct children of 'parent', 2 is children of first-level
123 * children etc. Use UACPI_MAX_DEPTH_ANY or -1 to specify infinite depth.
124 */
125uacpi_status uacpi_namespace_for_each_child(
126 uacpi_namespace_node *parent, uacpi_iteration_callback descending_callback,
127 uacpi_iteration_callback ascending_callback,
128 uacpi_object_type_bits type_mask, uacpi_u32 max_depth, void *user
129);
130
131/**
132 * Retrieve the next peer namespace node of '*iter', or, if '*iter' is
133 * UACPI_NULL, retrieve the first child of 'parent' instead. The resulting
134 * namespace node is stored at '*iter'.
135 *
136 * This API can be used to implement an "iterator" version of the
137 * for_each_child helpers.
138 *
139 * Example usage:
140 * void recurse(uacpi_namespace_node *parent) {
141 * uacpi_namespace_node *iter = UACPI_NULL;
142 *
143 * while (uacpi_namespace_node_next(parent, &iter) == UACPI_STATUS_OK) {
144 * // Do something with iter...
145 * descending_callback(iter);
146 *
147 * // Recurse down to walk over the children of iter
148 * recurse(iter);
149 * }
150 * }
151 *
152 * Prefer the for_each_child family of helpers if possible instead of this API
153 * as they avoid recursion and/or the need to use dynamic data structures
154 * entirely.
155 */
156uacpi_status uacpi_namespace_node_next(
157 uacpi_namespace_node *parent, uacpi_namespace_node **iter
158);
159
160/**
161 * Retrieve the next peer namespace node of '*iter', or, if '*iter' is
162 * UACPI_NULL, retrieve the first child of 'parent' instead. The resulting
163 * namespace node is stored at '*iter'. Only nodes which type matches one
164 * of the types set in 'type_mask' are returned.
165 *
166 * See comment above 'uacpi_namespace_node_next' for usage examples.
167 *
168 * Prefer the for_each_child family of helpers if possible instead of this API
169 * as they avoid recursion and/or the need to use dynamic data structures
170 * entirely.
171 */
172uacpi_status uacpi_namespace_node_next_typed(
173 uacpi_namespace_node *parent, uacpi_namespace_node **iter,
174 uacpi_object_type_bits type_mask
175);
176
177const uacpi_char *uacpi_namespace_node_generate_absolute_path(
178 const uacpi_namespace_node *node
179);
180void uacpi_free_absolute_path(const uacpi_char *path);
181
182#endif // !UACPI_BAREBONES_MODE
183
184#ifdef __cplusplus
185}
186#endif
187