Merge https://gitlab.denx.de/u-boot/custodians/u-boot-x86
[platform/kernel/u-boot.git] / include / acpi / acpi_dp.h
1 /* SPDX-License-Identifier: GPL-2.0 */
2 /*
3  * Device properties, a temporary data structure for adding to ACPI code
4  *
5  * Copyright 2019 Google LLC
6  * Mostly taken from coreboot file acpi_device.h
7  */
8
9 #ifndef __ACPI_DP_H
10 #define __ACPI_DP_H
11
12 struct acpi_ctx;
13
14 #include <acpi/acpi_device.h>
15
16 /*
17  * Writing Device Properties objects via _DSD
18  *
19  * This is described in ACPI 6.3 section 6.2.5
20  *
21  * This provides a structure to handle nested device-specific data which ends
22  * up in a _DSD table.
23  *
24  * https://www.kernel.org/doc/html/latest/firmware-guide/acpi/DSD-properties-rules.html
25  * https://uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf
26  * https://uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf
27  *
28  * The Device Property Hierarchy can be multiple levels deep with multiple
29  * children possible in each level.  In order to support this flexibility
30  * the device property hierarchy must be built up before being written out.
31  *
32  * For example:
33  *
34  * Child table with string and integer:
35  * struct acpi_dp *child = acpi_dp_new_table("CHLD");
36  * acpi_dp_add_string(child, "childstring", "CHILD");
37  * acpi_dp_add_integer(child, "childint", 100);
38  *
39  * _DSD table with integer and gpio and child pointer:
40  * struct acpi_dp *dsd = acpi_dp_new_table("_DSD");
41  * acpi_dp_add_integer(dsd, "number1", 1);
42  * acpi_dp_add_gpio(dsd, "gpio", "\_SB.PCI0.GPIO", 0, 0, 1);
43  * acpi_dp_add_child(dsd, "child", child);
44  *
45  * Write entries into SSDT and clean up resources:
46  * acpi_dp_write(dsd);
47  *
48  * Name(_DSD, Package() {
49  *   ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301")
50  *   Package() {
51  *     Package() { "gpio", Package() { \_SB.PCI0.GPIO, 0, 0, 0 } }
52  *     Package() { "number1", 1 }
53  *   }
54  *   ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b")
55  *   Package() {
56  *     Package() { "child", CHLD }
57  *   }
58  * }
59  * Name(CHLD, Package() {
60  *   ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301")
61  *   Package() {
62  *     Package() { "childstring", "CHILD" }
63  *     Package() { "childint", 100 }
64  *   }
65  * }
66  */
67
68 #define ACPI_DP_UUID            "daffd814-6eba-4d8c-8a91-bc9bbf4aa301"
69 #define ACPI_DP_CHILD_UUID      "dbb8e3e6-5886-4ba6-8795-1319f52a966b"
70
71 /**
72  * enum acpi_dp_type - types of device property objects
73  *
74  * These refer to the types defined by struct acpi_dp below
75  *
76  * @ACPI_DP_TYPE_UNKNOWN: Unknown / do not use
77  * @ACPI_DP_TYPE_INTEGER: Integer value (u64) in @integer
78  * @ACPI_DP_TYPE_STRING: String value in @string
79  * @ACPI_DP_TYPE_REFERENCE: Reference to another object, with value in @string
80  * @ACPI_DP_TYPE_TABLE: Type for a top-level table which may have children
81  * @ACPI_DP_TYPE_ARRAY: Array of items with first item in @array and following
82  *      items linked from that item's @next
83  * @ACPI_DP_TYPE_CHILD: Child object, with siblings in that child's @next
84  */
85 enum acpi_dp_type {
86         ACPI_DP_TYPE_UNKNOWN,
87         ACPI_DP_TYPE_INTEGER,
88         ACPI_DP_TYPE_STRING,
89         ACPI_DP_TYPE_REFERENCE,
90         ACPI_DP_TYPE_TABLE,
91         ACPI_DP_TYPE_ARRAY,
92         ACPI_DP_TYPE_CHILD,
93 };
94
95 /**
96  * struct acpi_dp - ACPI device properties
97  *
98  * @type: Table type
99  * @name: Name of object, typically _DSD but could be CHLD for a child object.
100  *      This can be NULL if there is no name
101  * @next: Next object in list (next array element or next sibling)
102  * @child: Pointer to first child, if @type == ACPI_DP_TYPE_CHILD, else NULL
103  * @array: First array element, if @type == ACPI_DP_TYPE_ARRAY, else NULL
104  * @integer: Integer value of the property, if @type == ACPI_DP_TYPE_INTEGER
105  * @string: String value of the property, if @type == ACPI_DP_TYPE_STRING;
106  *      child name if @type == ACPI_DP_TYPE_CHILD;
107  *      reference name if @type == ACPI_DP_TYPE_REFERENCE;
108  */
109 struct acpi_dp {
110         enum acpi_dp_type type;
111         const char *name;
112         struct acpi_dp *next;
113         union {
114                 struct acpi_dp *child;
115                 struct acpi_dp *array;
116         };
117         union {
118                 u64 integer;
119                 const char *string;
120         };
121 };
122
123 /**
124  * acpi_dp_new_table() - Start a new Device Property table
125  *
126  * @ref: ACPI reference (e.g. "_DSD")
127  * @return pointer to table, or NULL if out of memory
128  */
129 struct acpi_dp *acpi_dp_new_table(const char *ref);
130
131 /**
132  * acpi_dp_add_integer() - Add integer Device Property
133  *
134  * A new node is added to the end of the property list of @dp
135  *
136  * @dp: Table to add this property to
137  * @name: Name of property, or NULL for none
138  * @value: Integer value
139  * @return pointer to new node, or NULL if out of memory
140  */
141 struct acpi_dp *acpi_dp_add_integer(struct acpi_dp *dp, const char *name,
142                                     u64 value);
143
144 /**
145  * acpi_dp_add_string() - Add string Device Property
146  *
147  * A new node is added to the end of the property list of @dp
148  *
149  * @dp: Table to add this property to
150  * @name: Name of property, or NULL for none
151  * @string: String value
152  * @return pointer to new node, or NULL if out of memory
153  */
154 struct acpi_dp *acpi_dp_add_string(struct acpi_dp *dp, const char *name,
155                                    const char *string);
156
157 /**
158  * acpi_dp_add_reference() - Add reference Device Property
159  *
160  * A new node is added to the end of the property list of @dp
161  *
162  * @dp: Table to add this property to
163  * @name: Name of property, or NULL for none
164  * @reference: Reference value
165  * @return pointer to new node, or NULL if out of memory
166  */
167 struct acpi_dp *acpi_dp_add_reference(struct acpi_dp *dp, const char *name,
168                                       const char *reference);
169
170 /**
171  * acpi_dp_add_array() - Add array Device Property
172  *
173  * A new node is added to the end of the property list of @dp, with the array
174  * attached to that.
175  *
176  * @dp: Table to add this property to
177  * @name: Name of property, or NULL for none
178  * @return pointer to new node, or NULL if out of memory
179  */
180 struct acpi_dp *acpi_dp_add_array(struct acpi_dp *dp, struct acpi_dp *array);
181
182 /**
183  * acpi_dp_add_integer_array() - Add an array of integers
184  *
185  * A new node is added to the end of the property list of @dp, with the array
186  * attached to that. Each element of the array becomes a new node.
187  *
188  * @dp: Table to add this property to
189  * @name: Name of property, or NULL for none
190  * @return pointer to new array node, or NULL if out of memory
191  */
192 struct acpi_dp *acpi_dp_add_integer_array(struct acpi_dp *dp, const char *name,
193                                           u64 *array, int len);
194
195 /**
196  * acpi_dp_add_child() - Add a child table of Device Properties
197  *
198  * A new node is added as a child of @dp
199  *
200  * @dp: Table to add this child to
201  * @name: Name of child, or NULL for none
202  * @child: Child node to add
203  * @return pointer to new child node, or NULL if out of memory
204  */
205 struct acpi_dp *acpi_dp_add_child(struct acpi_dp *dp, const char *name,
206                                   struct acpi_dp *child);
207
208 /**
209  * acpi_dp_add_gpio() - Add a GPIO to a list of Device Properties
210  *
211  * A new node is added to the end of the property list of @dp, with the
212  * GPIO properties added to the the new node
213  *
214  * @dp: Table to add this property to
215  * @name: Name of property
216  * @ref: Reference to device with a _CRS containing GpioIO or GpioInt
217  * @index: Index of the GPIO resource in _CRS starting from zero
218  * @pin: Pin in the GPIO resource, typically zero
219  * @polarity: GPIO polarity. Note that ACPI_IRQ_ACTIVE_BOTH is not supported
220  * @return pointer to new node, or NULL if out of memory
221  */
222 struct acpi_dp *acpi_dp_add_gpio(struct acpi_dp *dp, const char *name,
223                                  const char *ref, int index, int pin,
224                                  enum acpi_irq_polarity polarity);
225
226 /**
227  * acpi_dp_write() - Write Device Property hierarchy and clean up resources
228  *
229  * This writes the table using acpigen and then frees it
230  *
231  * @ctx: ACPI context
232  * @table: Table to write
233  * @return 0 if OK, -ve on error
234  */
235 int acpi_dp_write(struct acpi_ctx *ctx, struct acpi_dp *table);
236
237 /**
238  * acpi_dp_ofnode_copy_int() - Copy a property from device tree to DP
239  *
240  * This copies an integer property from the device tree to the ACPI DP table.
241  *
242  * @node: Node to copy from
243  * @dp: DP to copy to
244  * @prop: Property name to copy
245  * @return 0 if OK, -ve on error
246  */
247 int acpi_dp_ofnode_copy_int(ofnode node, struct acpi_dp *dp, const char *prop);
248
249 /**
250  * acpi_dp_ofnode_copy_str() - Copy a property from device tree to DP
251  *
252  * This copies a string property from the device tree to the ACPI DP table.
253  *
254  * @node: Node to copy from
255  * @dp: DP to copy to
256  * @prop: Property name to copy
257  * @return 0 if OK, -ve on error
258  */
259 int acpi_dp_ofnode_copy_str(ofnode node, struct acpi_dp *dp, const char *prop);
260
261 /**
262  * acpi_dp_dev_copy_int() - Copy a property from device tree to DP
263  *
264  * This copies an integer property from the device tree to the ACPI DP table.
265  *
266  * @dev: Device to copy from
267  * @dp: DP to copy to
268  * @prop: Property name to copy
269  * @return 0 if OK, -ve on error
270  */
271 int acpi_dp_dev_copy_int(const struct udevice *dev, struct acpi_dp *dp,
272                          const char *prop);
273
274 /**
275  * acpi_dp_dev_copy_str() - Copy a property from device tree to DP
276  *
277  * This copies a string property from the device tree to the ACPI DP table.
278  *
279  * @dev: Device to copy from
280  * @dp: DP to copy to
281  * @prop: Property name to copy
282  * @return 0 if OK, -ve on error
283  */
284 int acpi_dp_dev_copy_str(const struct udevice *dev, struct acpi_dp *dp,
285                          const char *prop);
286
287 #endif