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_gen_regaddr;
  17 struct acpi_gpio;
  18
  19 /* Top 4 bits of the value used to indicate a three-byte length value */
  20 #define ACPI_PKG_LEN_3_BYTES    0x80
  21
  22 #define ACPI_METHOD_NARGS_MASK          0x7
  23 #define ACPI_METHOD_SERIALIZED_MASK     BIT(3)
  24
  25 #define ACPI_END_TAG                    0x79
  26
  27 /* ACPI Op/Prefix codes */
  28 enum {
  29         ZERO_OP                 = 0x00,
  30         ONE_OP                  = 0x01,
  31         NAME_OP                 = 0x08,
  32         BYTE_PREFIX             = 0x0a,
  33         WORD_PREFIX             = 0x0b,
  34         DWORD_PREFIX            = 0x0c,
  35         STRING_PREFIX           = 0x0d,
  36         QWORD_PREFIX            = 0x0e,
  37         SCOPE_OP                = 0x10,
  38         BUFFER_OP               = 0x11,
  39         PACKAGE_OP              = 0x12,
  40         METHOD_OP               = 0x14,
  41         SLEEP_OP                = 0x22,
  42         DUAL_NAME_PREFIX        = 0x2e,
  43         MULTI_NAME_PREFIX       = 0x2f,
  44         DEBUG_OP                = 0x31,
  45         EXT_OP_PREFIX           = 0x5b,
  46         ROOT_PREFIX             = 0x5c,
  47         LOCAL0_OP               = 0x60,
  48         LOCAL1_OP               = 0x61,
  49         LOCAL2_OP               = 0x62,
  50         LOCAL3_OP               = 0x63,
  51         LOCAL4_OP               = 0x64,
  52         LOCAL5_OP               = 0x65,
  53         LOCAL6_OP               = 0x66,
  54         LOCAL7_OP               = 0x67,
  55         STORE_OP                = 0x70,
  56         AND_OP                  = 0x7b,
  57         OR_OP                   = 0x7d,
  58         NOT_OP                  = 0x80,
  59         DEVICE_OP               = 0x82,
  60         POWER_RES_OP            = 0x84,
  61         RETURN_OP               = 0xa4,
  62 };
  63
  64 /**
  65  * acpigen_get_current() - Get the current ACPI code output pointer
  66  *
  67  * @ctx: ACPI context pointer
  68  * @return output pointer
  69  */
  70 u8 *acpigen_get_current(struct acpi_ctx *ctx);
  71
  72 /**
  73  * acpigen_emit_byte() - Emit a byte to the ACPI code
  74  *
  75  * @ctx: ACPI context pointer
  76  * @data: Value to output
  77  */
  78 void acpigen_emit_byte(struct acpi_ctx *ctx, uint data);
  79
  80 /**
  81  * acpigen_emit_word() - Emit a 16-bit word to the ACPI code
  82  *
  83  * @ctx: ACPI context pointer
  84  * @data: Value to output
  85  */
  86 void acpigen_emit_word(struct acpi_ctx *ctx, uint data);
  87
  88 /**
  89  * acpigen_emit_dword() - Emit a 32-bit 'double word' to the ACPI code
  90  *
  91  * @ctx: ACPI context pointer
  92  * @data: Value to output
  93  */
  94 void acpigen_emit_dword(struct acpi_ctx *ctx, uint data);
  95
  96 /**
  97  * acpigen_emit_stream() - Emit a stream of bytes
  98  *
  99  * @ctx: ACPI context pointer
 100  * @data: Data to output
 101  * @size: Size of data in bytes
 102  */
 103 void acpigen_emit_stream(struct acpi_ctx *ctx, const char *data, int size);
 104
 105 /**
 106  * acpigen_emit_string() - Emit a string
 107  *
 108  * Emit a string with a null terminator
 109  *
 110  * @ctx: ACPI context pointer
 111  * @str: String to output, or NULL for an empty string
 112  */
 113 void acpigen_emit_string(struct acpi_ctx *ctx, const char *str);
 114
 115 /**
 116  * acpigen_write_len_f() - Write a 'forward' length placeholder
 117  *
 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.
 121  *
 122  * Usage:
 123  *
 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() ----------/
 133  *
 134  * See ACPI 6.3 section 20.2.4 Package Length Encoding
 135  *
 136  * This implementation always uses a 3-byte packet length for simplicity. It
 137  * could be adjusted to support other lengths.
 138  *
 139  * @ctx: ACPI context pointer
 140  */
 141 void acpigen_write_len_f(struct acpi_ctx *ctx);
 142
 143 /**
 144  * acpigen_pop_len() - Update the previously stacked length placeholder
 145  *
 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.
 148  *
 149  * @ctx: ACPI context pointer
 150  */
 151 void acpigen_pop_len(struct acpi_ctx *ctx);
 152
 153 /**
 154  * acpigen_write_package() - Start writing a package
 155  *
 156  * A package collects together a number of elements in the ACPI code. To write
 157  * a package use:
 158  *
 159  * acpigen_write_package(ctx, 3);
 160  * ...write things
 161  * acpigen_pop_len()
 162  *
 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:
 165  *
 166  * char *num_elements = acpigen_write_package(ctx, 0);
 167  * ...write things
 168  * *num_elements += 1;
 169  * ...write things
 170  * *num_elements += 1;
 171  * acpigen_pop_len()
 172  *
 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
 176  *      caller if needed
 177  */
 178 char *acpigen_write_package(struct acpi_ctx *ctx, int nr_el);
 179
 180 /**
 181  * acpigen_write_byte() - Write a byte
 182  *
 183  * @ctx: ACPI context pointer
 184  * @data: Value to write
 185  */
 186 void acpigen_write_byte(struct acpi_ctx *ctx, unsigned int data);
 187
 188 /**
 189  * acpigen_write_word() - Write a word
 190  *
 191  * @ctx: ACPI context pointer
 192  * @data: Value to write
 193  */
 194 void acpigen_write_word(struct acpi_ctx *ctx, unsigned int data);
 195
 196 /**
 197  * acpigen_write_dword() - Write a dword
 198  *
 199  * @ctx: ACPI context pointer
 200  * @data: Value to write
 201  */
 202 void acpigen_write_dword(struct acpi_ctx *ctx, unsigned int data);
 203
 204 /**
 205  * acpigen_write_qword() - Write a qword
 206  *
 207  * @ctx: ACPI context pointer
 208  * @data: Value to write
 209  */
 210 void acpigen_write_qword(struct acpi_ctx *ctx, u64 data);
 211
 212 /**
 213  * acpigen_write_zero() - Write zero
 214  *
 215  * @ctx: ACPI context pointer
 216  */
 217 void acpigen_write_zero(struct acpi_ctx *ctx);
 218
 219 /**
 220  * acpigen_write_one() - Write one
 221  *
 222  * @ctx: ACPI context pointer
 223  */
 224 void acpigen_write_one(struct acpi_ctx *ctx);
 225
 226 /**
 227  * acpigen_write_integer() - Write an integer
 228  *
 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.
 231  *
 232  * @ctx: ACPI context pointer
 233  * @data: Integer to write
 234  */
 235 void acpigen_write_integer(struct acpi_ctx *ctx, u64 data);
 236
 237 /**
 238  * acpigen_write_name_zero() - Write a named zero value
 239  *
 240  * @ctx: ACPI context pointer
 241  * @name: Name of the value
 242  */
 243 void acpigen_write_name_zero(struct acpi_ctx *ctx, const char *name);
 244
 245 /**
 246  * acpigen_write_name_one() - Write a named one value
 247  *
 248  * @ctx: ACPI context pointer
 249  * @name: Name of the value
 250  */
 251 void acpigen_write_name_one(struct acpi_ctx *ctx, const char *name);
 252
 253 /**
 254  * acpigen_write_name_byte() - Write a named byte value
 255  *
 256  * @ctx: ACPI context pointer
 257  * @name: Name of the value
 258  * @val: Value to write
 259  */
 260 void acpigen_write_name_byte(struct acpi_ctx *ctx, const char *name, uint val);
 261
 262 /**
 263  * acpigen_write_name_word() - Write a named word value
 264  *
 265  * @ctx: ACPI context pointer
 266  * @name: Name of the value
 267  * @val: Value to write
 268  */
 269 void acpigen_write_name_word(struct acpi_ctx *ctx, const char *name, uint val);
 270
 271 /**
 272  * acpigen_write_name_dword() - Write a named dword value
 273  *
 274  * @ctx: ACPI context pointer
 275  * @name: Name of the value
 276  * @val: Value to write
 277  */
 278 void acpigen_write_name_dword(struct acpi_ctx *ctx, const char *name, uint val);
 279
 280 /**
 281  * acpigen_write_name_qword() - Write a named qword value
 282  *
 283  * @ctx: ACPI context pointer
 284  * @name: Name of the value
 285  * @val: Value to write
 286  */
 287 void acpigen_write_name_qword(struct acpi_ctx *ctx, const char *name, u64 val);
 288
 289 /**
 290  * acpigen_write_name_integer() - Write a named integer value
 291  *
 292  * @ctx: ACPI context pointer
 293  * @name: Name of the value
 294  * @val: Value to write
 295  */
 296 void acpigen_write_name_integer(struct acpi_ctx *ctx, const char *name,
 297                                 u64 val);
 298
 299 /**
 300  * acpigen_write_name_string() - Write a named string value
 301  *
 302  * @ctx: ACPI context pointer
 303  * @name: Name of the value
 304  * @string: String to write
 305  */
 306 void acpigen_write_name_string(struct acpi_ctx *ctx, const char *name,
 307                                const char *string);
 308
 309 /**
 310  * acpigen_write_string() - Write a string
 311  *
 312  * This writes a STRING_PREFIX followed by a null-terminated string
 313  *
 314  * @ctx: ACPI context pointer
 315  * @str: String to write
 316  */
 317 void acpigen_write_string(struct acpi_ctx *ctx, const char *str);
 318
 319 /**
 320  * acpigen_emit_namestring() - Emit an ACPI name
 321  *
 322  * This writes out an ACPI name or path in the required special format. It does
 323  * not add the NAME_OP prefix.
 324  *
 325  * @ctx: ACPI context pointer
 326  * @namepath: Name / path to emit
 327  */
 328 void acpigen_emit_namestring(struct acpi_ctx *ctx, const char *namepath);
 329
 330 /**
 331  * acpigen_write_name() - Write out an ACPI name
 332  *
 333  * This writes out an ACPI name or path in the required special format with a
 334  * NAME_OP prefix.
 335  *
 336  * @ctx: ACPI context pointer
 337  * @namepath: Name / path to emit
 338  */
 339 void acpigen_write_name(struct acpi_ctx *ctx, const char *namepath);
 340
 341 /**
 342  * acpigen_write_scope() - Write a scope
 343  *
 344  * @ctx: ACPI context pointer
 345  * @scope: Scope to write (e.g. "\\_SB.ABCD")
 346  */
 347 void acpigen_write_scope(struct acpi_ctx *ctx, const char *scope);
 348
 349 /**
 350  * acpigen_write_uuid() - Write a UUID
 351  *
 352  * This writes out a UUID in the format used by ACPI, with a BUFFER_OP prefix.
 353  *
 354  * @ctx: ACPI context pointer
 355  * @uuid: UUID to write in the form aabbccdd-eeff-gghh-iijj-kkllmmnnoopp
 356  * @return 0 if OK, -EINVAL if the format is incorrect
 357  */
 358 int acpigen_write_uuid(struct acpi_ctx *ctx, const char *uuid);
 359
 360 /**
 361  * acpigen_emit_ext_op() - Emit an extended op with the EXT_OP_PREFIX prefix
 362  *
 363  * @ctx: ACPI context pointer
 364  * @op: Operation code (e.g. SLEEP_OP)
 365  */
 366 void acpigen_emit_ext_op(struct acpi_ctx *ctx, uint op);
 367
 368 /**
 369  * acpigen_write_method() - Write a method header
 370  *
 371  * @ctx: ACPI context pointer
 372  * @name: Method name (4 characters)
 373  * @nargs: Number of method arguments (0 if none)
 374  */
 375 void acpigen_write_method(struct acpi_ctx *ctx, const char *name, int nargs);
 376
 377 /**
 378  * acpigen_write_method_serialized() - Write a method header
 379  *
 380  * This sets the 'serialized' flag so that the method is thread-safe
 381  *
 382  * @ctx: ACPI context pointer
 383  * @name: Method name (4 characters)
 384  * @nargs: Number of method arguments (0 if none)
 385  */
 386 void acpigen_write_method_serialized(struct acpi_ctx *ctx, const char *name,
 387                                      int nargs);
 388
 389 /**
 390  * acpigen_write_device() - Write an ACPI device
 391  *
 392  * @ctx: ACPI context pointer
 393  * @name: Device name to write
 394  */
 395 void acpigen_write_device(struct acpi_ctx *ctx, const char *name);
 396
 397 /**
 398  * acpigen_write_sta() - Write a _STA method
 399  *
 400  * @ctx: ACPI context pointer
 401  * @status: Status value to return
 402  */
 403 void acpigen_write_sta(struct acpi_ctx *ctx, uint status);
 404
 405 /**
 406  * acpigen_write_resourcetemplate_header() - Write a ResourceTemplate header
 407  *
 408  * @ctx: ACPI context pointer
 409  */
 410 void acpigen_write_resourcetemplate_header(struct acpi_ctx *ctx);
 411
 412 /**
 413  * acpigen_write_resourcetemplate_footer() - Write a ResourceTemplate footer
 414  *
 415  * @ctx: ACPI context pointer
 416  */
 417 void acpigen_write_resourcetemplate_footer(struct acpi_ctx *ctx);
 418
 419 /**
 420  * acpigen_write_register_resource() - Write a register resource
 421  *
 422  * This writes a header, the address information and a footer
 423  *
 424  * @ctx: ACPI context pointer
 425  * @addr: Address to write
 426  */
 427 void acpigen_write_register_resource(struct acpi_ctx *ctx,
 428                                      const struct acpi_gen_regaddr *addr);
 429
 430 /**
 431  * acpigen_write_sleep() - Write a sleep operation
 432  *
 433  * @ctx: ACPI context pointer
 434  * @sleep_ms: Number of milliseconds to sleep for
 435  */
 436 void acpigen_write_sleep(struct acpi_ctx *ctx, u64 sleep_ms);
 437
 438 /**
 439  * acpigen_write_store() - Write a store operation
 440  *
 441  * @ctx: ACPI context pointer
 442  */
 443 void acpigen_write_store(struct acpi_ctx *ctx);
 444
 445 /**
 446  * acpigen_write_debug_string() - Write a debug string
 447  *
 448  * This writes a debug operation with an associated string
 449  *
 450  * @ctx: ACPI context pointer
 451  * @str: String to write
 452  */
 453 void acpigen_write_debug_string(struct acpi_ctx *ctx, const char *str);
 454
 455 /**
 456  * acpigen_write_or() - Write a bitwise OR operation
 457  *
 458  * res = arg1 | arg2
 459  *
 460  * @ctx: ACPI context pointer
 461  * @arg1: ACPI opcode for operand 1 (e.g. LOCAL0_OP)
 462  * @arg2: ACPI opcode for operand 2 (e.g. LOCAL1_OP)
 463  * @res: ACPI opcode for result (e.g. LOCAL2_OP)
 464  */
 465 void acpigen_write_or(struct acpi_ctx *ctx, u8 arg1, u8 arg2, u8 res);
 466
 467 /**
 468  * acpigen_write_and() - Write a bitwise AND operation
 469  *
 470  * res = arg1 & arg2
 471  *
 472  * @ctx: ACPI context pointer
 473  * @arg1: ACPI opcode for operand 1 (e.g. LOCAL0_OP)
 474  * @arg2: ACPI opcode for operand 2 (e.g. LOCAL1_OP)
 475  * @res: ACPI opcode for result (e.g. LOCAL2_OP)
 476  */
 477 void acpigen_write_and(struct acpi_ctx *ctx, u8 arg1, u8 arg2, u8 res);
 478
 479 /**
 480  * acpigen_write_not() - Write a bitwise NOT operation
 481  *
 482  * res = ~arg1
 483  *
 484  * @ctx: ACPI context pointer
 485  * @arg: ACPI opcode for operand (e.g. LOCAL0_OP)
 486  * @res: ACPI opcode for result (e.g. LOCAL2_OP)
 487  */
 488 void acpigen_write_not(struct acpi_ctx *ctx, u8 arg, u8 res);
 489
 490 /**
 491  * acpigen_write_power_res() - Write a power resource
 492  *
 493  * Name (_PRx, Package(One) { name })
 494  * ...
 495  * PowerResource (name, level, order)
 496  *
 497  * The caller should fill in the rest of the power resource and then call
 498  * acpigen_pop_len() to close it off
 499  *
 500  * @ctx: ACPI context pointer
 501  * @name: Name of power resource (e.g. "PRIC")
 502  * @level: Deepest sleep level that this resource must be kept on (0=S0, 3=S3)
 503  * @order: Order that this must be enabled/disabled (e.g. 0)
 504  * @dev_stats: List of states to define, e.g. {"_PR0", "_PR3"}
 505  * @dev_states_count: Number of dev states
 506  */
 507 void acpigen_write_power_res(struct acpi_ctx *ctx, const char *name, uint level,
 508                              uint order, const char *const dev_states[],
 509                              size_t dev_states_count);
 510
 511 /**
 512  * acpigen_set_enable_tx_gpio() - Emit ACPI code to enable/disable a GPIO
 513  *
 514  * This emits code to either enable to disable a Tx GPIO. It takes account of
 515  * the GPIO polarity.
 516  *
 517  * The code needs access to the DW0 register for the pad being used. This is
 518  * provided by gpio->pin0_addr and ACPI methods must be defined for the board
 519  * which can read and write the pad's DW0 register given this address:
 520  *    @dw0_read: takes a single argument, the DW0 address
 521  *               returns the DW0 value
 522  *    @dw0:write: takes two arguments, the DW0 address and the value to write
 523  *               no return value
 524  *
 525  * Example code (-- means comment):
 526  *
 527  *      -- Get Pad Configuration DW0 register value
 528  *      Method (GPC0, 0x1, Serialized)
 529  *      {
 530  *              -- Arg0 - GPIO DW0 address
 531  *              Store (Arg0, Local0)
 532  *              OperationRegion (PDW0, SystemMemory, Local0, 4)
 533  *              Field (PDW0, AnyAcc, NoLock, Preserve) {
 534  *                      TEMP, 32
 535  *              }
 536  *              Return (TEMP)
 537  *      }
 538  *
 539  *      -- Set Pad Configuration DW0 register value
 540  *      Method (SPC0, 0x2, Serialized)
 541  *      {
 542  *              -- Arg0 - GPIO DW0 address
 543  *              -- Arg1 - Value for DW0 register
 544  *              Store (Arg0, Local0)
 545  *              OperationRegion (PDW0, SystemMemory, Local0, 4)
 546  *              Field (PDW0, AnyAcc, NoLock, Preserve) {
 547  *                      TEMP,32
 548  *              }
 549  *              Store (Arg1, TEMP)
 550  *      }
 551  *
 552  *
 553  * @ctx: ACPI context pointer
 554  * @tx_state_val: Mask to use to toggle the TX state on the GPIO pin, e,g.
 555  *      PAD_CFG0_TX_STATE
 556  * @dw0_read: Method name to use to read dw0, e.g. "\\_SB.GPC0"
 557  * @dw0_write: Method name to use to read dw0, e.g. "\\_SB.SPC0"
 558  * @gpio: GPIO to change
 559  * @enable: true to enable GPIO, false to disable
 560  * Returns 0 on success, -ve on error.
 561  */
 562 int acpigen_set_enable_tx_gpio(struct acpi_ctx *ctx, u32 tx_state_val,
 563                                const char *dw0_read, const char *dw0_write,
 564                                struct acpi_gpio *gpio, bool enable);
 565
 566 /**
 567  * acpigen_write_prw() - Write a power resource for wake (_PRW)
 568  *
 569  * @ctx: ACPI context pointer
 570  * @wake: GPE that wakes up the device
 571  * @level: Deepest power system sleeping state that can be entered while still
 572  *      providing wake functionality
 573  */
 574 void acpigen_write_prw(struct acpi_ctx *ctx, uint wake, uint level);
 575
 576 #endif