include/acpi/acpigen.h

   1 /* SPDX-License-Identifier: GPL-2.0 */
   2 /*
   3  * Core ACPI (Advanced Configuration and Power Interface) support
   4  *
   5  * Copyright 2019 Google LLC
   6  *
   7  * Modified from coreboot file acpigen.h
   8  */
   9
  10 #ifndef __ACPI_ACPIGEN_H
  11 #define __ACPI_ACPIGEN_H
  12
  13 #include <linux/types.h>
  14
  15 struct acpi_ctx;
  16
  17 /* Top 4 bits of the value used to indicate a three-byte length value */
  18 #define ACPI_PKG_LEN_3_BYTES    0x80
  19
  20 #define ACPI_METHOD_NARGS_MASK          0x7
  21 #define ACPI_METHOD_SERIALIZED_MASK     BIT(3)
  22
  23 /* ACPI Op/Prefix codes */
  24 enum {
  25         ZERO_OP                 = 0x00,
  26         ONE_OP                  = 0x01,
  27         NAME_OP                 = 0x08,
  28         BYTE_PREFIX             = 0x0a,
  29         WORD_PREFIX             = 0x0b,
  30         DWORD_PREFIX            = 0x0c,
  31         STRING_PREFIX           = 0x0d,
  32         QWORD_PREFIX            = 0x0e,
  33         BUFFER_OP               = 0x11,
  34         PACKAGE_OP              = 0x12,
  35         METHOD_OP               = 0x14,
  36         SLEEP_OP                = 0x22,
  37         DUAL_NAME_PREFIX        = 0x2e,
  38         MULTI_NAME_PREFIX       = 0x2f,
  39         DEBUG_OP                = 0x31,
  40         EXT_OP_PREFIX           = 0x5b,
  41         ROOT_PREFIX             = 0x5c,
  42         LOCAL0_OP               = 0x60,
  43         LOCAL1_OP               = 0x61,
  44         LOCAL2_OP               = 0x62,
  45         LOCAL3_OP               = 0x63,
  46         LOCAL4_OP               = 0x64,
  47         LOCAL5_OP               = 0x65,
  48         LOCAL6_OP               = 0x66,
  49         LOCAL7_OP               = 0x67,
  50         STORE_OP                = 0x70,
  51         AND_OP                  = 0x7b,
  52         OR_OP                   = 0x7d,
  53         NOT_OP                  = 0x80,
  54         POWER_RES_OP            = 0x84,
  55         RETURN_OP               = 0xa4,
  56 };
  57
  58 /**
  59  * acpigen_get_current() - Get the current ACPI code output pointer
  60  *
  61  * @ctx: ACPI context pointer
  62  * @return output pointer
  63  */
  64 u8 *acpigen_get_current(struct acpi_ctx *ctx);
  65
  66 /**
  67  * acpigen_emit_byte() - Emit a byte to the ACPI code
  68  *
  69  * @ctx: ACPI context pointer
  70  * @data: Value to output
  71  */
  72 void acpigen_emit_byte(struct acpi_ctx *ctx, uint data);
  73
  74 /**
  75  * acpigen_emit_word() - Emit a 16-bit word to the ACPI code
  76  *
  77  * @ctx: ACPI context pointer
  78  * @data: Value to output
  79  */
  80 void acpigen_emit_word(struct acpi_ctx *ctx, uint data);
  81
  82 /**
  83  * acpigen_emit_dword() - Emit a 32-bit 'double word' to the ACPI code
  84  *
  85  * @ctx: ACPI context pointer
  86  * @data: Value to output
  87  */
  88 void acpigen_emit_dword(struct acpi_ctx *ctx, uint data);
  89
  90 /**
  91  * acpigen_emit_stream() - Emit a stream of bytes
  92  *
  93  * @ctx: ACPI context pointer
  94  * @data: Data to output
  95  * @size: Size of data in bytes
  96  */
  97 void acpigen_emit_stream(struct acpi_ctx *ctx, const char *data, int size);
  98
  99 /**
 100  * acpigen_emit_string() - Emit a string
 101  *
 102  * Emit a string with a null terminator
 103  *
 104  * @ctx: ACPI context pointer
 105  * @str: String to output, or NULL for an empty string
 106  */
 107 void acpigen_emit_string(struct acpi_ctx *ctx, const char *str);
 108
 109 /**
 110  * acpigen_write_len_f() - Write a 'forward' length placeholder
 111  *
 112  * This adds space for a length value in the ACPI stream and pushes the current
 113  * position (before the length) on the stack. After calling this you can write
 114  * some data and then call acpigen_pop_len() to update the length value.
 115  *
 116  * Usage:
 117  *
 118  *    acpigen_write_len_f() ------\
 119  *    acpigen_write...()          |
 120  *    acpigen_write...()          |
 121  *      acpigen_write_len_f() --\ |
 122  *      acpigen_write...()      | |
 123  *      acpigen_write...()      | |
 124  *      acpigen_pop_len() ------/ |
 125  *    acpigen_write...()          |
 126  *    acpigen_pop_len() ----------/
 127  *
 128  * See ACPI 6.3 section 20.2.4 Package Length Encoding
 129  *
 130  * This implementation always uses a 3-byte packet length for simplicity. It
 131  * could be adjusted to support other lengths.
 132  *
 133  * @ctx: ACPI context pointer
 134  */
 135 void acpigen_write_len_f(struct acpi_ctx *ctx);
 136
 137 /**
 138  * acpigen_pop_len() - Update the previously stacked length placeholder
 139  *
 140  * Call this after the data for the block has been written. It updates the
 141  * top length value in the stack and pops it off.
 142  *
 143  * @ctx: ACPI context pointer
 144  */
 145 void acpigen_pop_len(struct acpi_ctx *ctx);
 146
 147 /**
 148  * acpigen_write_package() - Start writing a package
 149  *
 150  * A package collects together a number of elements in the ACPI code. To write
 151  * a package use:
 152  *
 153  * acpigen_write_package(ctx, 3);
 154  * ...write things
 155  * acpigen_pop_len()
 156  *
 157  * If you don't know the number of elements in advance, acpigen_write_package()
 158  * returns a pointer to the value so you can update it later:
 159  *
 160  * char *num_elements = acpigen_write_package(ctx, 0);
 161  * ...write things
 162  * *num_elements += 1;
 163  * ...write things
 164  * *num_elements += 1;
 165  * acpigen_pop_len()
 166  *
 167  * @ctx: ACPI context pointer
 168  * @nr_el: Number of elements (0 if not known)
 169  * @returns pointer to the number of elements, which can be updated by the
 170  *      caller if needed
 171  */
 172 char *acpigen_write_package(struct acpi_ctx *ctx, int nr_el);
 173
 174 /**
 175  * acpigen_write_integer() - Write an integer
 176  *
 177  * This writes an operation (BYTE_OP, WORD_OP, DWORD_OP, QWORD_OP depending on
 178  * the integer size) and an integer value. Note that WORD means 16 bits in ACPI.
 179  *
 180  * @ctx: ACPI context pointer
 181  * @data: Integer to write
 182  */
 183 void acpigen_write_integer(struct acpi_ctx *ctx, u64 data);
 184
 185 /**
 186  * acpigen_write_string() - Write a string
 187  *
 188  * This writes a STRING_PREFIX followed by a null-terminated string
 189  *
 190  * @ctx: ACPI context pointer
 191  * @str: String to write
 192  */
 193 void acpigen_write_string(struct acpi_ctx *ctx, const char *str);
 194
 195 /**
 196  * acpigen_emit_namestring() - Emit an ACPI name
 197  *
 198  * This writes out an ACPI name or path in the required special format. It does
 199  * not add the NAME_OP prefix.
 200  *
 201  * @ctx: ACPI context pointer
 202  * @namepath: Name / path to emit
 203  */
 204 void acpigen_emit_namestring(struct acpi_ctx *ctx, const char *namepath);
 205
 206 /**
 207  * acpigen_write_name() - Write out an ACPI name
 208  *
 209  * This writes out an ACPI name or path in the required special format with a
 210  * NAME_OP prefix.
 211  *
 212  * @ctx: ACPI context pointer
 213  * @namepath: Name / path to emit
 214  */
 215 void acpigen_write_name(struct acpi_ctx *ctx, const char *namepath);
 216
 217 /**
 218  * acpigen_write_uuid() - Write a UUID
 219  *
 220  * This writes out a UUID in the format used by ACPI, with a BUFFER_OP prefix.
 221  *
 222  * @ctx: ACPI context pointer
 223  * @uuid: UUID to write in the form aabbccdd-eeff-gghh-iijj-kkllmmnnoopp
 224  * @return 0 if OK, -EINVAL if the format is incorrect
 225  */
 226 int acpigen_write_uuid(struct acpi_ctx *ctx, const char *uuid);
 227
 228 /**
 229  * acpigen_emit_ext_op() - Emit an extended op with the EXT_OP_PREFIX prefix
 230  *
 231  * @ctx: ACPI context pointer
 232  * @op: Operation code (e.g. SLEEP_OP)
 233  */
 234 void acpigen_emit_ext_op(struct acpi_ctx *ctx, uint op);
 235
 236 /**
 237  * acpigen_write_method() - Write a method header
 238  *
 239  * @ctx: ACPI context pointer
 240  * @name: Method name (4 characters)
 241  * @nargs: Number of method arguments (0 if none)
 242  */
 243 void acpigen_write_method(struct acpi_ctx *ctx, const char *name, int nargs);
 244
 245 /**
 246  * acpigen_write_method_serialized() - Write a method header
 247  *
 248  * This sets the 'serialized' flag so that the method is thread-safe
 249  *
 250  * @ctx: ACPI context pointer
 251  * @name: Method name (4 characters)
 252  * @nargs: Number of method arguments (0 if none)
 253  */
 254 void acpigen_write_method_serialized(struct acpi_ctx *ctx, const char *name,
 255                                      int nargs);
 256
 257 /**
 258  * acpigen_write_sta() - Write a _STA method
 259  *
 260  * @ctx: ACPI context pointer
 261  * @status: Status value to return
 262  */
 263 void acpigen_write_sta(struct acpi_ctx *ctx, uint status);
 264
 265 /**
 266  * acpigen_write_sleep() - Write a sleep operation
 267  *
 268  * @ctx: ACPI context pointer
 269  * @sleep_ms: Number of milliseconds to sleep for
 270  */
 271 void acpigen_write_sleep(struct acpi_ctx *ctx, u64 sleep_ms);
 272
 273 /**
 274  * acpigen_write_store() - Write a store operation
 275  *
 276  * @ctx: ACPI context pointer
 277  */
 278 void acpigen_write_store(struct acpi_ctx *ctx);
 279
 280 /**
 281  * acpigen_write_debug_string() - Write a debug string
 282  *
 283  * This writes a debug operation with an associated string
 284  *
 285  * @ctx: ACPI context pointer
 286  * @str: String to write
 287  */
 288 void acpigen_write_debug_string(struct acpi_ctx *ctx, const char *str);
 289
 290 /**
 291  * acpigen_write_or() - Write a bitwise OR operation
 292  *
 293  * res = arg1 | arg2
 294  *
 295  * @ctx: ACPI context pointer
 296  * @arg1: ACPI opcode for operand 1 (e.g. LOCAL0_OP)
 297  * @arg2: ACPI opcode for operand 2 (e.g. LOCAL1_OP)
 298  * @res: ACPI opcode for result (e.g. LOCAL2_OP)
 299  */
 300 void acpigen_write_or(struct acpi_ctx *ctx, u8 arg1, u8 arg2, u8 res);
 301
 302 /**
 303  * acpigen_write_and() - Write a bitwise AND operation
 304  *
 305  * res = arg1 & arg2
 306  *
 307  * @ctx: ACPI context pointer
 308  * @arg1: ACPI opcode for operand 1 (e.g. LOCAL0_OP)
 309  * @arg2: ACPI opcode for operand 2 (e.g. LOCAL1_OP)
 310  * @res: ACPI opcode for result (e.g. LOCAL2_OP)
 311  */
 312 void acpigen_write_and(struct acpi_ctx *ctx, u8 arg1, u8 arg2, u8 res);
 313
 314 /**
 315  * acpigen_write_not() - Write a bitwise NOT operation
 316  *
 317  * res = ~arg1
 318  *
 319  * @ctx: ACPI context pointer
 320  * @arg: ACPI opcode for operand (e.g. LOCAL0_OP)
 321  * @res: ACPI opcode for result (e.g. LOCAL2_OP)
 322  */
 323 void acpigen_write_not(struct acpi_ctx *ctx, u8 arg, u8 res);
 324
 325 /**
 326  * acpigen_write_power_res() - Write a power resource
 327  *
 328  * Name (_PRx, Package(One) { name })
 329  * ...
 330  * PowerResource (name, level, order)
 331  *
 332  * The caller should fill in the rest of the power resource and then call
 333  * acpigen_pop_len() to close it off
 334  *
 335  * @ctx: ACPI context pointer
 336  * @name: Name of power resource (e.g. "PRIC")
 337  * @level: Deepest sleep level that this resource must be kept on (0=S0, 3=S3)
 338  * @order: Order that this must be enabled/disabled (e.g. 0)
 339  * @dev_stats: List of states to define, e.g. {"_PR0", "_PR3"}
 340  * @dev_states_count: Number of dev states
 341  */
 342 void acpigen_write_power_res(struct acpi_ctx *ctx, const char *name, uint level,
 343                              uint order, const char *const dev_states[],
 344                              size_t dev_states_count);
 345
 346 #endif