acpigen.h 12 KB

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