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         RETURN_OP               = 0xa4,
  55 };
  56
  57 /**
  58  * acpigen_get_current() - Get the current ACPI code output pointer
  59  *
  60  * @ctx: ACPI context pointer
  61  * @return output pointer
  62  */
  63 u8 *acpigen_get_current(struct acpi_ctx *ctx);
  64
  65 /**
  66  * acpigen_emit_byte() - Emit a byte to the ACPI code
  67  *
  68  * @ctx: ACPI context pointer
  69  * @data: Value to output
  70  */
  71 void acpigen_emit_byte(struct acpi_ctx *ctx, uint data);
  72
  73 /**
  74  * acpigen_emit_word() - Emit a 16-bit word to the ACPI code
  75  *
  76  * @ctx: ACPI context pointer
  77  * @data: Value to output
  78  */
  79 void acpigen_emit_word(struct acpi_ctx *ctx, uint data);
  80
  81 /**
  82  * acpigen_emit_dword() - Emit a 32-bit 'double word' to the ACPI code
  83  *
  84  * @ctx: ACPI context pointer
  85  * @data: Value to output
  86  */
  87 void acpigen_emit_dword(struct acpi_ctx *ctx, uint data);
  88
  89 /**
  90  * acpigen_emit_stream() - Emit a stream of bytes
  91  *
  92  * @ctx: ACPI context pointer
  93  * @data: Data to output
  94  * @size: Size of data in bytes
  95  */
  96 void acpigen_emit_stream(struct acpi_ctx *ctx, const char *data, int size);
  97
  98 /**
  99  * acpigen_emit_string() - Emit a string
 100  *
 101  * Emit a string with a null terminator
 102  *
 103  * @ctx: ACPI context pointer
 104  * @str: String to output, or NULL for an empty string
 105  */
 106 void acpigen_emit_string(struct acpi_ctx *ctx, const char *str);
 107
 108 /**
 109  * acpigen_write_len_f() - Write a 'forward' length placeholder
 110  *
 111  * This adds space for a length value in the ACPI stream and pushes the current
 112  * position (before the length) on the stack. After calling this you can write
 113  * some data and then call acpigen_pop_len() to update the length value.
 114  *
 115  * Usage:
 116  *
 117  *    acpigen_write_len_f() ------\
 118  *    acpigen_write...()          |
 119  *    acpigen_write...()          |
 120  *      acpigen_write_len_f() --\ |
 121  *      acpigen_write...()      | |
 122  *      acpigen_write...()      | |
 123  *      acpigen_pop_len() ------/ |
 124  *    acpigen_write...()          |
 125  *    acpigen_pop_len() ----------/
 126  *
 127  * See ACPI 6.3 section 20.2.4 Package Length Encoding
 128  *
 129  * This implementation always uses a 3-byte packet length for simplicity. It
 130  * could be adjusted to support other lengths.
 131  *
 132  * @ctx: ACPI context pointer
 133  */
 134 void acpigen_write_len_f(struct acpi_ctx *ctx);
 135
 136 /**
 137  * acpigen_pop_len() - Update the previously stacked length placeholder
 138  *
 139  * Call this after the data for the block has been written. It updates the
 140  * top length value in the stack and pops it off.
 141  *
 142  * @ctx: ACPI context pointer
 143  */
 144 void acpigen_pop_len(struct acpi_ctx *ctx);
 145
 146 /**
 147  * acpigen_write_package() - Start writing a package
 148  *
 149  * A package collects together a number of elements in the ACPI code. To write
 150  * a package use:
 151  *
 152  * acpigen_write_package(ctx, 3);
 153  * ...write things
 154  * acpigen_pop_len()
 155  *
 156  * If you don't know the number of elements in advance, acpigen_write_package()
 157  * returns a pointer to the value so you can update it later:
 158  *
 159  * char *num_elements = acpigen_write_package(ctx, 0);
 160  * ...write things
 161  * *num_elements += 1;
 162  * ...write things
 163  * *num_elements += 1;
 164  * acpigen_pop_len()
 165  *
 166  * @ctx: ACPI context pointer
 167  * @nr_el: Number of elements (0 if not known)
 168  * @returns pointer to the number of elements, which can be updated by the
 169  *      caller if needed
 170  */
 171 char *acpigen_write_package(struct acpi_ctx *ctx, int nr_el);
 172
 173 /**
 174  * acpigen_write_integer() - Write an integer
 175  *
 176  * This writes an operation (BYTE_OP, WORD_OP, DWORD_OP, QWORD_OP depending on
 177  * the integer size) and an integer value. Note that WORD means 16 bits in ACPI.
 178  *
 179  * @ctx: ACPI context pointer
 180  * @data: Integer to write
 181  */
 182 void acpigen_write_integer(struct acpi_ctx *ctx, u64 data);
 183
 184 /**
 185  * acpigen_write_string() - Write a string
 186  *
 187  * This writes a STRING_PREFIX followed by a null-terminated string
 188  *
 189  * @ctx: ACPI context pointer
 190  * @str: String to write
 191  */
 192 void acpigen_write_string(struct acpi_ctx *ctx, const char *str);
 193
 194 /**
 195  * acpigen_emit_namestring() - Emit an ACPI name
 196  *
 197  * This writes out an ACPI name or path in the required special format. It does
 198  * not add the NAME_OP prefix.
 199  *
 200  * @ctx: ACPI context pointer
 201  * @namepath: Name / path to emit
 202  */
 203 void acpigen_emit_namestring(struct acpi_ctx *ctx, const char *namepath);
 204
 205 /**
 206  * acpigen_write_name() - Write out an ACPI name
 207  *
 208  * This writes out an ACPI name or path in the required special format with a
 209  * NAME_OP prefix.
 210  *
 211  * @ctx: ACPI context pointer
 212  * @namepath: Name / path to emit
 213  */
 214 void acpigen_write_name(struct acpi_ctx *ctx, const char *namepath);
 215
 216 /**
 217  * acpigen_write_uuid() - Write a UUID
 218  *
 219  * This writes out a UUID in the format used by ACPI, with a BUFFER_OP prefix.
 220  *
 221  * @ctx: ACPI context pointer
 222  * @uuid: UUID to write in the form aabbccdd-eeff-gghh-iijj-kkllmmnnoopp
 223  * @return 0 if OK, -EINVAL if the format is incorrect
 224  */
 225 int acpigen_write_uuid(struct acpi_ctx *ctx, const char *uuid);
 226
 227 /**
 228  * acpigen_emit_ext_op() - Emit an extended op with the EXT_OP_PREFIX prefix
 229  *
 230  * @ctx: ACPI context pointer
 231  * @op: Operation code (e.g. SLEEP_OP)
 232  */
 233 void acpigen_emit_ext_op(struct acpi_ctx *ctx, uint op);
 234
 235 /**
 236  * acpigen_write_method() - Write a method header
 237  *
 238  * @ctx: ACPI context pointer
 239  * @name: Method name (4 characters)
 240  * @nargs: Number of method arguments (0 if none)
 241  */
 242 void acpigen_write_method(struct acpi_ctx *ctx, const char *name, int nargs);
 243
 244 /**
 245  * acpigen_write_method_serialized() - Write a method header
 246  *
 247  * This sets the 'serialized' flag so that the method is thread-safe
 248  *
 249  * @ctx: ACPI context pointer
 250  * @name: Method name (4 characters)
 251  * @nargs: Number of method arguments (0 if none)
 252  */
 253 void acpigen_write_method_serialized(struct acpi_ctx *ctx, const char *name,
 254                                      int nargs);
 255
 256 /**
 257  * acpigen_write_sta() - Write a _STA method
 258  *
 259  * @ctx: ACPI context pointer
 260  * @status: Status value to return
 261  */
 262 void acpigen_write_sta(struct acpi_ctx *ctx, uint status);
 263
 264 /**
 265  * acpigen_write_sleep() - Write a sleep operation
 266  *
 267  * @ctx: ACPI context pointer
 268  * @sleep_ms: Number of milliseconds to sleep for
 269  */
 270 void acpigen_write_sleep(struct acpi_ctx *ctx, u64 sleep_ms);
 271
 272 /**
 273  * acpigen_write_store() - Write a store operation
 274  *
 275  * @ctx: ACPI context pointer
 276  */
 277 void acpigen_write_store(struct acpi_ctx *ctx);
 278
 279 /**
 280  * acpigen_write_debug_string() - Write a debug string
 281  *
 282  * This writes a debug operation with an associated string
 283  *
 284  * @ctx: ACPI context pointer
 285  * @str: String to write
 286  */
 287 void acpigen_write_debug_string(struct acpi_ctx *ctx, const char *str);
 288
 289 /**
 290  * acpigen_write_or() - Write a bitwise OR operation
 291  *
 292  * res = arg1 | arg2
 293  *
 294  * @ctx: ACPI context pointer
 295  * @arg1: ACPI opcode for operand 1 (e.g. LOCAL0_OP)
 296  * @arg2: ACPI opcode for operand 2 (e.g. LOCAL1_OP)
 297  * @res: ACPI opcode for result (e.g. LOCAL2_OP)
 298  */
 299 void acpigen_write_or(struct acpi_ctx *ctx, u8 arg1, u8 arg2, u8 res);
 300
 301 /**
 302  * acpigen_write_and() - Write a bitwise AND operation
 303  *
 304  * res = arg1 & arg2
 305  *
 306  * @ctx: ACPI context pointer
 307  * @arg1: ACPI opcode for operand 1 (e.g. LOCAL0_OP)
 308  * @arg2: ACPI opcode for operand 2 (e.g. LOCAL1_OP)
 309  * @res: ACPI opcode for result (e.g. LOCAL2_OP)
 310  */
 311 void acpigen_write_and(struct acpi_ctx *ctx, u8 arg1, u8 arg2, u8 res);
 312
 313 /**
 314  * acpigen_write_not() - Write a bitwise NOT operation
 315  *
 316  * res = ~arg1
 317  *
 318  * @ctx: ACPI context pointer
 319  * @arg: ACPI opcode for operand (e.g. LOCAL0_OP)
 320  * @res: ACPI opcode for result (e.g. LOCAL2_OP)
 321  */
 322 void acpigen_write_not(struct acpi_ctx *ctx, u8 arg, u8 res);
 323
 324 #endif