1 /* SPDX-License-Identifier: GPL-2.0 */
3 * Core ACPI (Advanced Configuration and Power Interface) support
5 * Copyright 2019 Google LLC
7 * Modified from coreboot file acpigen.h
10 #ifndef __ACPI_ACPIGEN_H
11 #define __ACPI_ACPIGEN_H
13 #include <linux/types.h>
16 struct acpi_gen_regaddr;
19 /* Top 4 bits of the value used to indicate a three-byte length value */
20 #define ACPI_PKG_LEN_3_BYTES 0x80
22 #define ACPI_METHOD_NARGS_MASK 0x7
23 #define ACPI_METHOD_SERIALIZED_MASK BIT(3)
25 #define ACPI_END_TAG 0x79
27 /* ACPI Op/Prefix codes */
42 DUAL_NAME_PREFIX = 0x2e,
43 MULTI_NAME_PREFIX = 0x2f,
65 * acpigen_get_current() - Get the current ACPI code output pointer
67 * @ctx: ACPI context pointer
68 * @return output pointer
70 u8 *acpigen_get_current(struct acpi_ctx *ctx);
73 * acpigen_emit_byte() - Emit a byte to the ACPI code
75 * @ctx: ACPI context pointer
76 * @data: Value to output
78 void acpigen_emit_byte(struct acpi_ctx *ctx, uint data);
81 * acpigen_emit_word() - Emit a 16-bit word to the ACPI code
83 * @ctx: ACPI context pointer
84 * @data: Value to output
86 void acpigen_emit_word(struct acpi_ctx *ctx, uint data);
89 * acpigen_emit_dword() - Emit a 32-bit 'double word' to the ACPI code
91 * @ctx: ACPI context pointer
92 * @data: Value to output
94 void acpigen_emit_dword(struct acpi_ctx *ctx, uint data);
97 * acpigen_emit_stream() - Emit a stream of bytes
99 * @ctx: ACPI context pointer
100 * @data: Data to output
101 * @size: Size of data in bytes
103 void acpigen_emit_stream(struct acpi_ctx *ctx, const char *data, int size);
106 * acpigen_emit_string() - Emit a string
108 * Emit a string with a null terminator
110 * @ctx: ACPI context pointer
111 * @str: String to output, or NULL for an empty string
113 void acpigen_emit_string(struct acpi_ctx *ctx, const char *str);
116 * acpigen_write_len_f() - Write a 'forward' length placeholder
118 * This adds space for a length value in the ACPI stream and pushes the current
119 * position (before the length) on the stack. After calling this you can write
120 * some data and then call acpigen_pop_len() to update the length value.
124 * acpigen_write_len_f() ------\
125 * acpigen_write...() |
126 * acpigen_write...() |
127 * acpigen_write_len_f() --\ |
128 * acpigen_write...() | |
129 * acpigen_write...() | |
130 * acpigen_pop_len() ------/ |
131 * acpigen_write...() |
132 * acpigen_pop_len() ----------/
134 * See ACPI 6.3 section 20.2.4 Package Length Encoding
136 * This implementation always uses a 3-byte packet length for simplicity. It
137 * could be adjusted to support other lengths.
139 * @ctx: ACPI context pointer
141 void acpigen_write_len_f(struct acpi_ctx *ctx);
144 * acpigen_pop_len() - Update the previously stacked length placeholder
146 * Call this after the data for the block has been written. It updates the
147 * top length value in the stack and pops it off.
149 * @ctx: ACPI context pointer
151 void acpigen_pop_len(struct acpi_ctx *ctx);
154 * acpigen_write_package() - Start writing a package
156 * A package collects together a number of elements in the ACPI code. To write
159 * acpigen_write_package(ctx, 3);
163 * If you don't know the number of elements in advance, acpigen_write_package()
164 * returns a pointer to the value so you can update it later:
166 * char *num_elements = acpigen_write_package(ctx, 0);
168 * *num_elements += 1;
170 * *num_elements += 1;
173 * @ctx: ACPI context pointer
174 * @nr_el: Number of elements (0 if not known)
175 * @returns pointer to the number of elements, which can be updated by the
178 char *acpigen_write_package(struct acpi_ctx *ctx, int nr_el);
181 * acpigen_write_byte() - Write a byte
183 * @ctx: ACPI context pointer
184 * @data: Value to write
186 void acpigen_write_byte(struct acpi_ctx *ctx, unsigned int data);
189 * acpigen_write_word() - Write a word
191 * @ctx: ACPI context pointer
192 * @data: Value to write
194 void acpigen_write_word(struct acpi_ctx *ctx, unsigned int data);
197 * acpigen_write_dword() - Write a dword
199 * @ctx: ACPI context pointer
200 * @data: Value to write
202 void acpigen_write_dword(struct acpi_ctx *ctx, unsigned int data);
205 * acpigen_write_qword() - Write a qword
207 * @ctx: ACPI context pointer
208 * @data: Value to write
210 void acpigen_write_qword(struct acpi_ctx *ctx, u64 data);
213 * acpigen_write_zero() - Write zero
215 * @ctx: ACPI context pointer
217 void acpigen_write_zero(struct acpi_ctx *ctx);
220 * acpigen_write_one() - Write one
222 * @ctx: ACPI context pointer
224 void acpigen_write_one(struct acpi_ctx *ctx);
227 * acpigen_write_integer() - Write an integer
229 * This writes an operation (BYTE_OP, WORD_OP, DWORD_OP, QWORD_OP depending on
230 * the integer size) and an integer value. Note that WORD means 16 bits in ACPI.
232 * @ctx: ACPI context pointer
233 * @data: Integer to write
235 void acpigen_write_integer(struct acpi_ctx *ctx, u64 data);
238 * acpigen_write_string() - Write a string
240 * This writes a STRING_PREFIX followed by a null-terminated string
242 * @ctx: ACPI context pointer
243 * @str: String to write
245 void acpigen_write_string(struct acpi_ctx *ctx, const char *str);
248 * acpigen_emit_namestring() - Emit an ACPI name
250 * This writes out an ACPI name or path in the required special format. It does
251 * not add the NAME_OP prefix.
253 * @ctx: ACPI context pointer
254 * @namepath: Name / path to emit
256 void acpigen_emit_namestring(struct acpi_ctx *ctx, const char *namepath);
259 * acpigen_write_name() - Write out an ACPI name
261 * This writes out an ACPI name or path in the required special format with a
264 * @ctx: ACPI context pointer
265 * @namepath: Name / path to emit
267 void acpigen_write_name(struct acpi_ctx *ctx, const char *namepath);
270 * acpigen_write_scope() - Write a scope
272 * @ctx: ACPI context pointer
273 * @scope: Scope to write (e.g. "\\_SB.ABCD")
275 void acpigen_write_scope(struct acpi_ctx *ctx, const char *scope);
278 * acpigen_write_uuid() - Write a UUID
280 * This writes out a UUID in the format used by ACPI, with a BUFFER_OP prefix.
282 * @ctx: ACPI context pointer
283 * @uuid: UUID to write in the form aabbccdd-eeff-gghh-iijj-kkllmmnnoopp
284 * @return 0 if OK, -EINVAL if the format is incorrect
286 int acpigen_write_uuid(struct acpi_ctx *ctx, const char *uuid);
289 * acpigen_emit_ext_op() - Emit an extended op with the EXT_OP_PREFIX prefix
291 * @ctx: ACPI context pointer
292 * @op: Operation code (e.g. SLEEP_OP)
294 void acpigen_emit_ext_op(struct acpi_ctx *ctx, uint op);
297 * acpigen_write_method() - Write a method header
299 * @ctx: ACPI context pointer
300 * @name: Method name (4 characters)
301 * @nargs: Number of method arguments (0 if none)
303 void acpigen_write_method(struct acpi_ctx *ctx, const char *name, int nargs);
306 * acpigen_write_method_serialized() - Write a method header
308 * This sets the 'serialized' flag so that the method is thread-safe
310 * @ctx: ACPI context pointer
311 * @name: Method name (4 characters)
312 * @nargs: Number of method arguments (0 if none)
314 void acpigen_write_method_serialized(struct acpi_ctx *ctx, const char *name,
318 * acpigen_write_device() - Write an ACPI device
320 * @ctx: ACPI context pointer
321 * @name: Device name to write
323 void acpigen_write_device(struct acpi_ctx *ctx, const char *name);
326 * acpigen_write_sta() - Write a _STA method
328 * @ctx: ACPI context pointer
329 * @status: Status value to return
331 void acpigen_write_sta(struct acpi_ctx *ctx, uint status);
334 * acpigen_write_resourcetemplate_header() - Write a ResourceTemplate header
336 * @ctx: ACPI context pointer
338 void acpigen_write_resourcetemplate_header(struct acpi_ctx *ctx);
341 * acpigen_write_resourcetemplate_footer() - Write a ResourceTemplate footer
343 * @ctx: ACPI context pointer
345 void acpigen_write_resourcetemplate_footer(struct acpi_ctx *ctx);
348 * acpigen_write_register_resource() - Write a register resource
350 * This writes a header, the address information and a footer
352 * @ctx: ACPI context pointer
353 * @addr: Address to write
355 void acpigen_write_register_resource(struct acpi_ctx *ctx,
356 const struct acpi_gen_regaddr *addr);
359 * acpigen_write_sleep() - Write a sleep operation
361 * @ctx: ACPI context pointer
362 * @sleep_ms: Number of milliseconds to sleep for
364 void acpigen_write_sleep(struct acpi_ctx *ctx, u64 sleep_ms);
367 * acpigen_write_store() - Write a store operation
369 * @ctx: ACPI context pointer
371 void acpigen_write_store(struct acpi_ctx *ctx);
374 * acpigen_write_debug_string() - Write a debug string
376 * This writes a debug operation with an associated string
378 * @ctx: ACPI context pointer
379 * @str: String to write
381 void acpigen_write_debug_string(struct acpi_ctx *ctx, const char *str);
384 * acpigen_write_or() - Write a bitwise OR operation
388 * @ctx: ACPI context pointer
389 * @arg1: ACPI opcode for operand 1 (e.g. LOCAL0_OP)
390 * @arg2: ACPI opcode for operand 2 (e.g. LOCAL1_OP)
391 * @res: ACPI opcode for result (e.g. LOCAL2_OP)
393 void acpigen_write_or(struct acpi_ctx *ctx, u8 arg1, u8 arg2, u8 res);
396 * acpigen_write_and() - Write a bitwise AND operation
400 * @ctx: ACPI context pointer
401 * @arg1: ACPI opcode for operand 1 (e.g. LOCAL0_OP)
402 * @arg2: ACPI opcode for operand 2 (e.g. LOCAL1_OP)
403 * @res: ACPI opcode for result (e.g. LOCAL2_OP)
405 void acpigen_write_and(struct acpi_ctx *ctx, u8 arg1, u8 arg2, u8 res);
408 * acpigen_write_not() - Write a bitwise NOT operation
412 * @ctx: ACPI context pointer
413 * @arg: ACPI opcode for operand (e.g. LOCAL0_OP)
414 * @res: ACPI opcode for result (e.g. LOCAL2_OP)
416 void acpigen_write_not(struct acpi_ctx *ctx, u8 arg, u8 res);
419 * acpigen_write_power_res() - Write a power resource
421 * Name (_PRx, Package(One) { name })
423 * PowerResource (name, level, order)
425 * The caller should fill in the rest of the power resource and then call
426 * acpigen_pop_len() to close it off
428 * @ctx: ACPI context pointer
429 * @name: Name of power resource (e.g. "PRIC")
430 * @level: Deepest sleep level that this resource must be kept on (0=S0, 3=S3)
431 * @order: Order that this must be enabled/disabled (e.g. 0)
432 * @dev_stats: List of states to define, e.g. {"_PR0", "_PR3"}
433 * @dev_states_count: Number of dev states
435 void acpigen_write_power_res(struct acpi_ctx *ctx, const char *name, uint level,
436 uint order, const char *const dev_states[],
437 size_t dev_states_count);
440 * acpigen_set_enable_tx_gpio() - Emit ACPI code to enable/disable a GPIO
442 * This emits code to either enable to disable a Tx GPIO. It takes account of
445 * The code needs access to the DW0 register for the pad being used. This is
446 * provided by gpio->pin0_addr and ACPI methods must be defined for the board
447 * which can read and write the pad's DW0 register given this address:
448 * @dw0_read: takes a single argument, the DW0 address
449 * returns the DW0 value
450 * @dw0:write: takes two arguments, the DW0 address and the value to write
453 * Example code (-- means comment):
455 * -- Get Pad Configuration DW0 register value
456 * Method (GPC0, 0x1, Serialized)
458 * -- Arg0 - GPIO DW0 address
459 * Store (Arg0, Local0)
460 * OperationRegion (PDW0, SystemMemory, Local0, 4)
461 * Field (PDW0, AnyAcc, NoLock, Preserve) {
467 * -- Set Pad Configuration DW0 register value
468 * Method (SPC0, 0x2, Serialized)
470 * -- Arg0 - GPIO DW0 address
471 * -- Arg1 - Value for DW0 register
472 * Store (Arg0, Local0)
473 * OperationRegion (PDW0, SystemMemory, Local0, 4)
474 * Field (PDW0, AnyAcc, NoLock, Preserve) {
481 * @ctx: ACPI context pointer
482 * @tx_state_val: Mask to use to toggle the TX state on the GPIO pin, e,g.
484 * @dw0_read: Method name to use to read dw0, e.g. "\\_SB.GPC0"
485 * @dw0_write: Method name to use to read dw0, e.g. "\\_SB.SPC0"
486 * @gpio: GPIO to change
487 * @enable: true to enable GPIO, false to disable
488 * Returns 0 on success, -ve on error.
490 int acpigen_set_enable_tx_gpio(struct acpi_ctx *ctx, u32 tx_state_val,
491 const char *dw0_read, const char *dw0_write,
492 struct acpi_gpio *gpio, bool enable);