acpigen.h 15 KB

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