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 struct acpi_gpio;
  17
  18 /* Top 4 bits of the value used to indicate a three-byte length value */
  19 #define ACPI_PKG_LEN_3_BYTES    0x80
  20
  21 #define ACPI_METHOD_NARGS_MASK          0x7
  22 #define ACPI_METHOD_SERIALIZED_MASK     BIT(3)
  23
  24 /* ACPI Op/Prefix codes */
  25 enum {
  26         ZERO_OP                 = 0x00,
  27         ONE_OP                  = 0x01,
  28         NAME_OP                 = 0x08,
  29         BYTE_PREFIX             = 0x0a,
  30         WORD_PREFIX             = 0x0b,
  31         DWORD_PREFIX            = 0x0c,
  32         STRING_PREFIX           = 0x0d,
  33         QWORD_PREFIX            = 0x0e,
  34         SCOPE_OP                = 0x10,
  35         BUFFER_OP               = 0x11,
  36         PACKAGE_OP              = 0x12,
  37         METHOD_OP               = 0x14,
  38         SLEEP_OP                = 0x22,
  39         DUAL_NAME_PREFIX        = 0x2e,
  40         MULTI_NAME_PREFIX       = 0x2f,
  41         DEBUG_OP                = 0x31,
  42         EXT_OP_PREFIX           = 0x5b,
  43         ROOT_PREFIX             = 0x5c,
  44         LOCAL0_OP               = 0x60,
  45         LOCAL1_OP               = 0x61,
  46         LOCAL2_OP               = 0x62,
  47         LOCAL3_OP               = 0x63,
  48         LOCAL4_OP               = 0x64,
  49         LOCAL5_OP               = 0x65,
  50         LOCAL6_OP               = 0x66,
  51         LOCAL7_OP               = 0x67,
  52         STORE_OP                = 0x70,
  53         AND_OP                  = 0x7b,
  54         OR_OP                   = 0x7d,
  55         NOT_OP                  = 0x80,
  56         POWER_RES_OP            = 0x84,
  57         RETURN_OP               = 0xa4,
  58 };
  59
  60 /**
  61  * acpigen_get_current() - Get the current ACPI code output pointer
  62  *
  63  * @ctx: ACPI context pointer
  64  * @return output pointer
  65  */
  66 u8 *acpigen_get_current(struct acpi_ctx *ctx);
  67
  68 /**
  69  * acpigen_emit_byte() - Emit a byte to the ACPI code
  70  *
  71  * @ctx: ACPI context pointer
  72  * @data: Value to output
  73  */
  74 void acpigen_emit_byte(struct acpi_ctx *ctx, uint data);
  75
  76 /**
  77  * acpigen_emit_word() - Emit a 16-bit word to the ACPI code
  78  *
  79  * @ctx: ACPI context pointer
  80  * @data: Value to output
  81  */
  82 void acpigen_emit_word(struct acpi_ctx *ctx, uint data);
  83
  84 /**
  85  * acpigen_emit_dword() - Emit a 32-bit 'double word' to the ACPI code
  86  *
  87  * @ctx: ACPI context pointer
  88  * @data: Value to output
  89  */
  90 void acpigen_emit_dword(struct acpi_ctx *ctx, uint data);
  91
  92 /**
  93  * acpigen_emit_stream() - Emit a stream of bytes
  94  *
  95  * @ctx: ACPI context pointer
  96  * @data: Data to output
  97  * @size: Size of data in bytes
  98  */
  99 void acpigen_emit_stream(struct acpi_ctx *ctx, const char *data, int size);
 100
 101 /**
 102  * acpigen_emit_string() - Emit a string
 103  *
 104  * Emit a string with a null terminator
 105  *
 106  * @ctx: ACPI context pointer
 107  * @str: String to output, or NULL for an empty string
 108  */
 109 void acpigen_emit_string(struct acpi_ctx *ctx, const char *str);
 110
 111 /**
 112  * acpigen_write_len_f() - Write a 'forward' length placeholder
 113  *
 114  * This adds space for a length value in the ACPI stream and pushes the current
 115  * position (before the length) on the stack. After calling this you can write
 116  * some data and then call acpigen_pop_len() to update the length value.
 117  *
 118  * Usage:
 119  *
 120  *    acpigen_write_len_f() ------\
 121  *    acpigen_write...()          |
 122  *    acpigen_write...()          |
 123  *      acpigen_write_len_f() --\ |
 124  *      acpigen_write...()      | |
 125  *      acpigen_write...()      | |
 126  *      acpigen_pop_len() ------/ |
 127  *    acpigen_write...()          |
 128  *    acpigen_pop_len() ----------/
 129  *
 130  * See ACPI 6.3 section 20.2.4 Package Length Encoding
 131  *
 132  * This implementation always uses a 3-byte packet length for simplicity. It
 133  * could be adjusted to support other lengths.
 134  *
 135  * @ctx: ACPI context pointer
 136  */
 137 void acpigen_write_len_f(struct acpi_ctx *ctx);
 138
 139 /**
 140  * acpigen_pop_len() - Update the previously stacked length placeholder
 141  *
 142  * Call this after the data for the block has been written. It updates the
 143  * top length value in the stack and pops it off.
 144  *
 145  * @ctx: ACPI context pointer
 146  */
 147 void acpigen_pop_len(struct acpi_ctx *ctx);
 148
 149 /**
 150  * acpigen_write_package() - Start writing a package
 151  *
 152  * A package collects together a number of elements in the ACPI code. To write
 153  * a package use:
 154  *
 155  * acpigen_write_package(ctx, 3);
 156  * ...write things
 157  * acpigen_pop_len()
 158  *
 159  * If you don't know the number of elements in advance, acpigen_write_package()
 160  * returns a pointer to the value so you can update it later:
 161  *
 162  * char *num_elements = acpigen_write_package(ctx, 0);
 163  * ...write things
 164  * *num_elements += 1;
 165  * ...write things
 166  * *num_elements += 1;
 167  * acpigen_pop_len()
 168  *
 169  * @ctx: ACPI context pointer
 170  * @nr_el: Number of elements (0 if not known)
 171  * @returns pointer to the number of elements, which can be updated by the
 172  *      caller if needed
 173  */
 174 char *acpigen_write_package(struct acpi_ctx *ctx, int nr_el);
 175
 176 /**
 177  * acpigen_write_byte() - Write a byte
 178  *
 179  * @ctx: ACPI context pointer
 180  * @data: Value to write
 181  */
 182 void acpigen_write_byte(struct acpi_ctx *ctx, unsigned int data);
 183
 184 /**
 185  * acpigen_write_word() - Write a word
 186  *
 187  * @ctx: ACPI context pointer
 188  * @data: Value to write
 189  */
 190 void acpigen_write_word(struct acpi_ctx *ctx, unsigned int data);
 191
 192 /**
 193  * acpigen_write_dword() - Write a dword
 194  *
 195  * @ctx: ACPI context pointer
 196  * @data: Value to write
 197  */
 198 void acpigen_write_dword(struct acpi_ctx *ctx, unsigned int data);
 199
 200 /**
 201  * acpigen_write_qword() - Write a qword
 202  *
 203  * @ctx: ACPI context pointer
 204  * @data: Value to write
 205  */
 206 void acpigen_write_qword(struct acpi_ctx *ctx, u64 data);
 207
 208 /**
 209  * acpigen_write_zero() - Write zero
 210  *
 211  * @ctx: ACPI context pointer
 212  */
 213 void acpigen_write_zero(struct acpi_ctx *ctx);
 214
 215 /**
 216  * acpigen_write_one() - Write one
 217  *
 218  * @ctx: ACPI context pointer
 219  */
 220 void acpigen_write_one(struct acpi_ctx *ctx);
 221
 222 /**
 223  * acpigen_write_integer() - Write an integer
 224  *
 225  * This writes an operation (BYTE_OP, WORD_OP, DWORD_OP, QWORD_OP depending on
 226  * the integer size) and an integer value. Note that WORD means 16 bits in ACPI.
 227  *
 228  * @ctx: ACPI context pointer
 229  * @data: Integer to write
 230  */
 231 void acpigen_write_integer(struct acpi_ctx *ctx, u64 data);
 232
 233 /**
 234  * acpigen_write_string() - Write a string
 235  *
 236  * This writes a STRING_PREFIX followed by a null-terminated string
 237  *
 238  * @ctx: ACPI context pointer
 239  * @str: String to write
 240  */
 241 void acpigen_write_string(struct acpi_ctx *ctx, const char *str);
 242
 243 /**
 244  * acpigen_emit_namestring() - Emit an ACPI name
 245  *
 246  * This writes out an ACPI name or path in the required special format. It does
 247  * not add the NAME_OP prefix.
 248  *
 249  * @ctx: ACPI context pointer
 250  * @namepath: Name / path to emit
 251  */
 252 void acpigen_emit_namestring(struct acpi_ctx *ctx, const char *namepath);
 253
 254 /**
 255  * acpigen_write_name() - Write out an ACPI name
 256  *
 257  * This writes out an ACPI name or path in the required special format with a
 258  * NAME_OP prefix.
 259  *
 260  * @ctx: ACPI context pointer
 261  * @namepath: Name / path to emit
 262  */
 263 void acpigen_write_name(struct acpi_ctx *ctx, const char *namepath);
 264
 265 /**
 266  * acpigen_write_scope() - Write a scope
 267  *
 268  * @ctx: ACPI context pointer
 269  * @scope: Scope to write (e.g. "\\_SB.ABCD")
 270  */
 271 void acpigen_write_scope(struct acpi_ctx *ctx, const char *scope);
 272
 273 /**
 274  * acpigen_write_uuid() - Write a UUID
 275  *
 276  * This writes out a UUID in the format used by ACPI, with a BUFFER_OP prefix.
 277  *
 278  * @ctx: ACPI context pointer
 279  * @uuid: UUID to write in the form aabbccdd-eeff-gghh-iijj-kkllmmnnoopp
 280  * @return 0 if OK, -EINVAL if the format is incorrect
 281  */
 282 int acpigen_write_uuid(struct acpi_ctx *ctx, const char *uuid);
 283
 284 /**
 285  * acpigen_emit_ext_op() - Emit an extended op with the EXT_OP_PREFIX prefix
 286  *
 287  * @ctx: ACPI context pointer
 288  * @op: Operation code (e.g. SLEEP_OP)
 289  */
 290 void acpigen_emit_ext_op(struct acpi_ctx *ctx, uint op);
 291
 292 /**
 293  * acpigen_write_method() - Write a method header
 294  *
 295  * @ctx: ACPI context pointer
 296  * @name: Method name (4 characters)
 297  * @nargs: Number of method arguments (0 if none)
 298  */
 299 void acpigen_write_method(struct acpi_ctx *ctx, const char *name, int nargs);
 300
 301 /**
 302  * acpigen_write_method_serialized() - Write a method header
 303  *
 304  * This sets the 'serialized' flag so that the method is thread-safe
 305  *
 306  * @ctx: ACPI context pointer
 307  * @name: Method name (4 characters)
 308  * @nargs: Number of method arguments (0 if none)
 309  */
 310 void acpigen_write_method_serialized(struct acpi_ctx *ctx, const char *name,
 311                                      int nargs);
 312
 313 /**
 314  * acpigen_write_sta() - Write a _STA method
 315  *
 316  * @ctx: ACPI context pointer
 317  * @status: Status value to return
 318  */
 319 void acpigen_write_sta(struct acpi_ctx *ctx, uint status);
 320
 321 /**
 322  * acpigen_write_sleep() - Write a sleep operation
 323  *
 324  * @ctx: ACPI context pointer
 325  * @sleep_ms: Number of milliseconds to sleep for
 326  */
 327 void acpigen_write_sleep(struct acpi_ctx *ctx, u64 sleep_ms);
 328
 329 /**
 330  * acpigen_write_store() - Write a store operation
 331  *
 332  * @ctx: ACPI context pointer
 333  */
 334 void acpigen_write_store(struct acpi_ctx *ctx);
 335
 336 /**
 337  * acpigen_write_debug_string() - Write a debug string
 338  *
 339  * This writes a debug operation with an associated string
 340  *
 341  * @ctx: ACPI context pointer
 342  * @str: String to write
 343  */
 344 void acpigen_write_debug_string(struct acpi_ctx *ctx, const char *str);
 345
 346 /**
 347  * acpigen_write_or() - Write a bitwise OR operation
 348  *
 349  * res = arg1 | arg2
 350  *
 351  * @ctx: ACPI context pointer
 352  * @arg1: ACPI opcode for operand 1 (e.g. LOCAL0_OP)
 353  * @arg2: ACPI opcode for operand 2 (e.g. LOCAL1_OP)
 354  * @res: ACPI opcode for result (e.g. LOCAL2_OP)
 355  */
 356 void acpigen_write_or(struct acpi_ctx *ctx, u8 arg1, u8 arg2, u8 res);
 357
 358 /**
 359  * acpigen_write_and() - Write a bitwise AND operation
 360  *
 361  * res = arg1 & arg2
 362  *
 363  * @ctx: ACPI context pointer
 364  * @arg1: ACPI opcode for operand 1 (e.g. LOCAL0_OP)
 365  * @arg2: ACPI opcode for operand 2 (e.g. LOCAL1_OP)
 366  * @res: ACPI opcode for result (e.g. LOCAL2_OP)
 367  */
 368 void acpigen_write_and(struct acpi_ctx *ctx, u8 arg1, u8 arg2, u8 res);
 369
 370 /**
 371  * acpigen_write_not() - Write a bitwise NOT operation
 372  *
 373  * res = ~arg1
 374  *
 375  * @ctx: ACPI context pointer
 376  * @arg: ACPI opcode for operand (e.g. LOCAL0_OP)
 377  * @res: ACPI opcode for result (e.g. LOCAL2_OP)
 378  */
 379 void acpigen_write_not(struct acpi_ctx *ctx, u8 arg, u8 res);
 380
 381 /**
 382  * acpigen_write_power_res() - Write a power resource
 383  *
 384  * Name (_PRx, Package(One) { name })
 385  * ...
 386  * PowerResource (name, level, order)
 387  *
 388  * The caller should fill in the rest of the power resource and then call
 389  * acpigen_pop_len() to close it off
 390  *
 391  * @ctx: ACPI context pointer
 392  * @name: Name of power resource (e.g. "PRIC")
 393  * @level: Deepest sleep level that this resource must be kept on (0=S0, 3=S3)
 394  * @order: Order that this must be enabled/disabled (e.g. 0)
 395  * @dev_stats: List of states to define, e.g. {"_PR0", "_PR3"}
 396  * @dev_states_count: Number of dev states
 397  */
 398 void acpigen_write_power_res(struct acpi_ctx *ctx, const char *name, uint level,
 399                              uint order, const char *const dev_states[],
 400                              size_t dev_states_count);
 401
 402 /**
 403  * acpigen_set_enable_tx_gpio() - Emit ACPI code to enable/disable a GPIO
 404  *
 405  * This emits code to either enable to disable a Tx GPIO. It takes account of
 406  * the GPIO polarity.
 407  *
 408  * The code needs access to the DW0 register for the pad being used. This is
 409  * provided by gpio->pin0_addr and ACPI methods must be defined for the board
 410  * which can read and write the pad's DW0 register given this address:
 411  *    @dw0_read: takes a single argument, the DW0 address
 412  *               returns the DW0 value
 413  *    @dw0:write: takes two arguments, the DW0 address and the value to write
 414  *               no return value
 415  *
 416  * Example code (-- means comment):
 417  *
 418  *      -- Get Pad Configuration DW0 register value
 419  *      Method (GPC0, 0x1, Serialized)
 420  *      {
 421  *              -- Arg0 - GPIO DW0 address
 422  *              Store (Arg0, Local0)
 423  *              OperationRegion (PDW0, SystemMemory, Local0, 4)
 424  *              Field (PDW0, AnyAcc, NoLock, Preserve) {
 425  *                      TEMP, 32
 426  *              }
 427  *              Return (TEMP)
 428  *      }
 429  *
 430  *      -- Set Pad Configuration DW0 register value
 431  *      Method (SPC0, 0x2, Serialized)
 432  *      {
 433  *              -- Arg0 - GPIO DW0 address
 434  *              -- Arg1 - Value for DW0 register
 435  *              Store (Arg0, Local0)
 436  *              OperationRegion (PDW0, SystemMemory, Local0, 4)
 437  *              Field (PDW0, AnyAcc, NoLock, Preserve) {
 438  *                      TEMP,32
 439  *              }
 440  *              Store (Arg1, TEMP)
 441  *      }
 442  *
 443  *
 444  * @ctx: ACPI context pointer
 445  * @tx_state_val: Mask to use to toggle the TX state on the GPIO pin, e,g.
 446  *      PAD_CFG0_TX_STATE
 447  * @dw0_read: Method name to use to read dw0, e.g. "\\_SB.GPC0"
 448  * @dw0_write: Method name to use to read dw0, e.g. "\\_SB.SPC0"
 449  * @gpio: GPIO to change
 450  * @enable: true to enable GPIO, false to disable
 451  * Returns 0 on success, -ve on error.
 452  */
 453 int acpigen_set_enable_tx_gpio(struct acpi_ctx *ctx, u32 tx_state_val,
 454                                const char *dw0_read, const char *dw0_write,
 455                                struct acpi_gpio *gpio, bool enable);
 456
 457 #endif