acpi_device.h 16 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497
  1. /* SPDX-License-Identifier: GPL-2.0 */
  2. /*
  3. * Generation of tables for particular device types
  4. *
  5. * Copyright 2019 Google LLC
  6. * Mostly taken from coreboot file of the same name
  7. */
  8. #ifndef __ACPI_DEVICE_H
  9. #define __ACPI_DEVICE_H
  10. #include <i2c.h>
  11. #include <irq.h>
  12. #include <spi.h>
  13. #include <asm-generic/gpio.h>
  14. #include <linux/bitops.h>
  15. struct acpi_ctx;
  16. struct gpio_desc;
  17. struct irq;
  18. struct udevice;
  19. /* ACPI descriptor values for common descriptors: SERIAL_BUS means I2C */
  20. #define ACPI_DESCRIPTOR_LARGE BIT(7)
  21. #define ACPI_DESCRIPTOR_REGISTER (ACPI_DESCRIPTOR_LARGE | 2)
  22. #define ACPI_DESCRIPTOR_INTERRUPT (ACPI_DESCRIPTOR_LARGE | 9)
  23. #define ACPI_DESCRIPTOR_GPIO (ACPI_DESCRIPTOR_LARGE | 12)
  24. #define ACPI_DESCRIPTOR_SERIAL_BUS (ACPI_DESCRIPTOR_LARGE | 14)
  25. /* Length of a full path to an ACPI device */
  26. #define ACPI_PATH_MAX 30
  27. /* UUID for an I2C _DSM method */
  28. #define ACPI_DSM_I2C_HID_UUID "3cdff6f7-4267-4555-ad05-b30a3d8938de"
  29. /* Values that can be returned for ACPI device _STA method */
  30. enum acpi_dev_status {
  31. ACPI_DSTATUS_PRESENT = BIT(0),
  32. ACPI_DSTATUS_ENABLED = BIT(1),
  33. ACPI_DSTATUS_SHOW_IN_UI = BIT(2),
  34. ACPI_DSTATUS_OK = BIT(3),
  35. ACPI_DSTATUS_HAS_BATTERY = BIT(4),
  36. ACPI_DSTATUS_ALL_OFF = 0,
  37. ACPI_DSTATUS_HIDDEN_ON = ACPI_DSTATUS_PRESENT | ACPI_DSTATUS_ENABLED |
  38. ACPI_DSTATUS_OK,
  39. ACPI_DSTATUS_ALL_ON = ACPI_DSTATUS_HIDDEN_ON |
  40. ACPI_DSTATUS_SHOW_IN_UI,
  41. };
  42. /** enum acpi_irq_mode - edge/level trigger mode */
  43. enum acpi_irq_mode {
  44. ACPI_IRQ_EDGE_TRIGGERED,
  45. ACPI_IRQ_LEVEL_TRIGGERED,
  46. };
  47. /**
  48. * enum acpi_irq_polarity - polarity of interrupt
  49. *
  50. * @ACPI_IRQ_ACTIVE_LOW - for ACPI_IRQ_EDGE_TRIGGERED this means falling edge
  51. * @ACPI_IRQ_ACTIVE_HIGH - for ACPI_IRQ_EDGE_TRIGGERED this means rising edge
  52. * @ACPI_IRQ_ACTIVE_BOTH - not meaningful for ACPI_IRQ_EDGE_TRIGGERED
  53. */
  54. enum acpi_irq_polarity {
  55. ACPI_IRQ_ACTIVE_LOW,
  56. ACPI_IRQ_ACTIVE_HIGH,
  57. ACPI_IRQ_ACTIVE_BOTH,
  58. };
  59. /**
  60. * enum acpi_irq_shared - whether interrupt is shared or not
  61. *
  62. * @ACPI_IRQ_EXCLUSIVE: only this device uses the interrupt
  63. * @ACPI_IRQ_SHARED: other devices may use this interrupt
  64. */
  65. enum acpi_irq_shared {
  66. ACPI_IRQ_EXCLUSIVE,
  67. ACPI_IRQ_SHARED,
  68. };
  69. /** enum acpi_irq_wake - indicates whether this interrupt can wake the device */
  70. enum acpi_irq_wake {
  71. ACPI_IRQ_NO_WAKE,
  72. ACPI_IRQ_WAKE,
  73. };
  74. /**
  75. * struct acpi_irq - representation of an ACPI interrupt
  76. *
  77. * @pin: ACPI pin that is monitored for the interrupt
  78. * @mode: Edge/level triggering
  79. * @polarity: Interrupt polarity
  80. * @shared: Whether interrupt is shared or not
  81. * @wake: Whether interrupt can wake the device from sleep
  82. */
  83. struct acpi_irq {
  84. unsigned int pin;
  85. enum acpi_irq_mode mode;
  86. enum acpi_irq_polarity polarity;
  87. enum acpi_irq_shared shared;
  88. enum acpi_irq_wake wake;
  89. };
  90. /**
  91. * enum acpi_gpio_type - type of the descriptor
  92. *
  93. * @ACPI_GPIO_TYPE_INTERRUPT: GpioInterrupt
  94. * @ACPI_GPIO_TYPE_IO: GpioIo
  95. */
  96. enum acpi_gpio_type {
  97. ACPI_GPIO_TYPE_INTERRUPT,
  98. ACPI_GPIO_TYPE_IO,
  99. };
  100. /**
  101. * enum acpi_gpio_pull - pull direction
  102. *
  103. * @ACPI_GPIO_PULL_DEFAULT: Use default value for pin
  104. * @ACPI_GPIO_PULL_UP: Pull up
  105. * @ACPI_GPIO_PULL_DOWN: Pull down
  106. * @ACPI_GPIO_PULL_NONE: No pullup/pulldown
  107. */
  108. enum acpi_gpio_pull {
  109. ACPI_GPIO_PULL_DEFAULT,
  110. ACPI_GPIO_PULL_UP,
  111. ACPI_GPIO_PULL_DOWN,
  112. ACPI_GPIO_PULL_NONE,
  113. };
  114. /**
  115. * enum acpi_gpio_io_restrict - controls input/output of pin
  116. *
  117. * @ACPI_GPIO_IO_RESTRICT_NONE: no restrictions
  118. * @ACPI_GPIO_IO_RESTRICT_INPUT: input only (no output)
  119. * @ACPI_GPIO_IO_RESTRICT_OUTPUT: output only (no input)
  120. * @ACPI_GPIO_IO_RESTRICT_PRESERVE: preserve settings when driver not active
  121. */
  122. enum acpi_gpio_io_restrict {
  123. ACPI_GPIO_IO_RESTRICT_NONE,
  124. ACPI_GPIO_IO_RESTRICT_INPUT,
  125. ACPI_GPIO_IO_RESTRICT_OUTPUT,
  126. ACPI_GPIO_IO_RESTRICT_PRESERVE,
  127. };
  128. /** enum acpi_gpio_polarity - controls the GPIO polarity */
  129. enum acpi_gpio_polarity {
  130. ACPI_GPIO_ACTIVE_HIGH = 0,
  131. ACPI_GPIO_ACTIVE_LOW = 1,
  132. };
  133. #define ACPI_GPIO_REVISION_ID 1
  134. #define ACPI_GPIO_MAX_PINS 2
  135. /**
  136. * struct acpi_gpio - representation of an ACPI GPIO
  137. *
  138. * @pin_count: Number of pins represented
  139. * @pins: List of pins
  140. * @pin0_addr: Address in memory of the control registers for pin 0. This is
  141. * used when generating ACPI tables
  142. * @type: GPIO type
  143. * @pull: Pullup/pulldown setting
  144. * @resource: Resource name for this GPIO controller
  145. * For GpioInt:
  146. * @interrupt_debounce_timeout: Debounce timeout in units of 10us
  147. * @irq: Interrupt
  148. *
  149. * For GpioIo:
  150. * @output_drive_strength: Drive strength in units of 10uA
  151. * @io_shared; true if GPIO is shared
  152. * @io_restrict: I/O restriction setting
  153. * @polarity: GPIO polarity
  154. *
  155. * Note that GpioIo doesn't have any means of Active Low / High setting, so a
  156. * _DSD must be provided to mitigate this.
  157. *
  158. * GpioIo doesn't properly communicate the initial state of the output pin,
  159. * thus Linux assumes the simple rule:
  160. *
  161. * Pull Bias Polarity Requested...
  162. *
  163. * Implicit x AS IS (assumed firmware configured for us)
  164. * Explicit x (no _DSD) as Pull Bias (Up == High, Down == Low),
  165. * assuming non-active (Polarity = !Pull Bias)
  166. *
  167. * Down Low as low, assuming active
  168. * Down High as high, assuming non-active
  169. * Up Low as high, assuming non-active
  170. * Up High as high, assuming active
  171. *
  172. * GpioIo() can be used as interrupt and in this case the IoRestriction mustn't
  173. * be OutputOnly. It also requires active_low flag from _DSD in cases where it's
  174. * needed (better to always provide than rely on above assumption made on OS
  175. * level).
  176. */
  177. struct acpi_gpio {
  178. int pin_count;
  179. u16 pins[ACPI_GPIO_MAX_PINS];
  180. ulong pin0_addr;
  181. enum acpi_gpio_type type;
  182. enum acpi_gpio_pull pull;
  183. char resource[ACPI_PATH_MAX];
  184. /* GpioInt */
  185. u16 interrupt_debounce_timeout;
  186. struct acpi_irq irq;
  187. /* GpioIo */
  188. u16 output_drive_strength;
  189. bool io_shared;
  190. enum acpi_gpio_io_restrict io_restrict;
  191. enum acpi_gpio_polarity polarity;
  192. };
  193. /* ACPI Descriptors for Serial Bus interfaces */
  194. #define ACPI_SERIAL_BUS_TYPE_I2C 1
  195. #define ACPI_SERIAL_BUS_TYPE_SPI 2
  196. #define ACPI_I2C_SERIAL_BUS_REVISION_ID 1 /* TODO: upgrade to 2 */
  197. #define ACPI_I2C_TYPE_SPECIFIC_REVISION_ID 1
  198. #define ACPI_SPI_SERIAL_BUS_REVISION_ID 1
  199. #define ACPI_SPI_TYPE_SPECIFIC_REVISION_ID 1
  200. /**
  201. * struct acpi_i2c - representation of an ACPI I2C device
  202. *
  203. * @address: 7-bit or 10-bit I2C address
  204. * @mode_10bit: Which address size is used
  205. * @speed: Bus speed in Hz
  206. * @resource: Resource name for the I2C controller
  207. */
  208. struct acpi_i2c {
  209. u16 address;
  210. enum i2c_address_mode mode_10bit;
  211. enum i2c_speed_rate speed;
  212. const char *resource;
  213. };
  214. /**
  215. * struct acpi_spi - representation of an ACPI SPI device
  216. *
  217. * @device_select: Chip select used by this device (typically 0)
  218. * @device_select_polarity: Polarity for the device
  219. * @wire_mode: Number of wires used for SPI
  220. * @speed: Bus speed in Hz
  221. * @data_bit_length: Word length for SPI (typically 8)
  222. * @clock_phase: Clock phase to capture data
  223. * @clock_polarity: Bus polarity
  224. * @resource: Resource name for the SPI controller
  225. */
  226. struct acpi_spi {
  227. u16 device_select;
  228. enum spi_polarity device_select_polarity;
  229. enum spi_wire_mode wire_mode;
  230. unsigned int speed;
  231. u8 data_bit_length;
  232. enum spi_clock_phase clock_phase;
  233. enum spi_polarity clock_polarity;
  234. const char *resource;
  235. };
  236. /**
  237. * struct acpi_i2c_priv - Information read from device tree
  238. *
  239. * This is used by devices which want to specify various pieces of ACPI
  240. * information, including power control. It allows a generic function to
  241. * generate the information for ACPI, based on device-tree properties.
  242. *
  243. * @disable_gpio_export_in_crs: Don't export GPIOs in the CRS
  244. * @reset_gpio: GPIO used to assert reset to the device
  245. * @enable_gpio: GPIO used to enable the device
  246. * @stop_gpio: GPIO used to stop the device
  247. * @irq_gpio: GPIO used for interrupt (if @irq is not used)
  248. * @irq: IRQ used for interrupt (if @irq_gpio is not used)
  249. * @hid: _HID value for device (required)
  250. * @uid: _UID value for device
  251. * @desc: _DDN value for device
  252. * @wake: Wake event, e.g. GPE0_DW1_15; 0 if none
  253. * @property_count: Number of other DSD properties (currently always 0)
  254. * @probed: true set set 'linux,probed' property
  255. * @compat_string: Device tree compatible string to report through ACPI
  256. * @has_power_resource: true if this device has a power resource
  257. * @reset_delay_ms: Delay after de-asserting reset, in ms
  258. * @reset_off_delay_ms: Delay after asserting reset (during power off)
  259. * @enable_delay_ms: Delay after asserting enable
  260. * @enable_off_delay_ms: Delay after de-asserting enable (during power off)
  261. * @stop_delay_ms: Delay after de-aserting stop
  262. * @stop_off_delay_ms: Delay after asserting stop (during power off)
  263. * @hid_desc_reg_offset: HID register offset (for Human Interface Devices)
  264. */
  265. struct acpi_i2c_priv {
  266. bool disable_gpio_export_in_crs;
  267. struct gpio_desc reset_gpio;
  268. struct gpio_desc enable_gpio;
  269. struct gpio_desc irq_gpio;
  270. struct gpio_desc stop_gpio;
  271. struct irq irq;
  272. const char *hid;
  273. u32 uid;
  274. const char *desc;
  275. u32 wake;
  276. u32 property_count;
  277. bool probed;
  278. const char *compat_string;
  279. bool has_power_resource;
  280. u32 reset_delay_ms;
  281. u32 reset_off_delay_ms;
  282. u32 enable_delay_ms;
  283. u32 enable_off_delay_ms;
  284. u32 stop_delay_ms;
  285. u32 stop_off_delay_ms;
  286. u32 hid_desc_reg_offset;
  287. };
  288. /**
  289. * acpi_device_path() - Get the full path to an ACPI device
  290. *
  291. * This gets the full path in the form XXXX.YYYY.ZZZZ where XXXX is the root
  292. * and ZZZZ is the device. All parent devices are added to the path.
  293. *
  294. * @dev: Device to check
  295. * @buf: Buffer to place the path in (should be ACPI_PATH_MAX long)
  296. * @maxlen: Size of buffer (typically ACPI_PATH_MAX)
  297. * @return 0 if OK, -ve on error
  298. */
  299. int acpi_device_path(const struct udevice *dev, char *buf, int maxlen);
  300. /**
  301. * acpi_device_scope() - Get the scope of an ACPI device
  302. *
  303. * This gets the scope which is the full path of the parent device, as per
  304. * acpi_device_path().
  305. *
  306. * @dev: Device to check
  307. * @buf: Buffer to place the path in (should be ACPI_PATH_MAX long)
  308. * @maxlen: Size of buffer (typically ACPI_PATH_MAX)
  309. * @return 0 if OK, -EINVAL if the device has no parent, other -ve on other
  310. * error
  311. */
  312. int acpi_device_scope(const struct udevice *dev, char *scope, int maxlen);
  313. /**
  314. * acpi_device_status() - Get the status of a device
  315. *
  316. * This currently just returns ACPI_DSTATUS_ALL_ON. It does not support
  317. * inactive or hidden devices.
  318. *
  319. * @dev: Device to check
  320. * @return device status, as ACPI_DSTATUS_...
  321. */
  322. enum acpi_dev_status acpi_device_status(const struct udevice *dev);
  323. /**
  324. * acpi_device_write_interrupt_irq() - Write an interrupt descriptor
  325. *
  326. * This writes an ACPI interrupt descriptor for the given interrupt, converting
  327. * fields as needed.
  328. *
  329. * @ctx: ACPI context pointer
  330. * @req_irq: Interrupt to output
  331. * @return IRQ pin number if OK, -ve on error
  332. */
  333. int acpi_device_write_interrupt_irq(struct acpi_ctx *ctx,
  334. const struct irq *req_irq);
  335. /**
  336. * acpi_device_write_gpio() - Write GpioIo() or GpioInt() descriptor
  337. *
  338. * @gpio: GPIO information to write
  339. * @return GPIO pin number of first GPIO if OK, -ve on error
  340. */
  341. int acpi_device_write_gpio(struct acpi_ctx *ctx, const struct acpi_gpio *gpio);
  342. /**
  343. * acpi_device_write_gpio_desc() - Write a GPIO to ACPI
  344. *
  345. * This creates a GPIO descriptor for a GPIO, including information ACPI needs
  346. * to use it.
  347. *
  348. * @ctx: ACPI context pointer
  349. * @desc: GPIO to write
  350. * @return 0 if OK, -ve on error
  351. */
  352. int acpi_device_write_gpio_desc(struct acpi_ctx *ctx,
  353. const struct gpio_desc *desc);
  354. /**
  355. * acpi_device_write_interrupt_or_gpio() - Write interrupt or GPIO to ACPI
  356. *
  357. * This reads an interrupt from the device tree "interrupts-extended" property,
  358. * if available. If not it reads the first GPIO with the name @prop.
  359. *
  360. * If an interrupt is found, an ACPI interrupt descriptor is written to the ACPI
  361. * output. If not, but if a GPIO is found, a GPIO descriptor is written.
  362. *
  363. * @return irq or GPIO pin number if OK, -ve if neither an interrupt nor a GPIO
  364. * could be found, or some other error occurred
  365. */
  366. int acpi_device_write_interrupt_or_gpio(struct acpi_ctx *ctx,
  367. struct udevice *dev, const char *prop);
  368. /**
  369. * acpi_device_write_dsm_i2c_hid() - Write a device-specific method for HID
  370. *
  371. * This writes a DSM for an I2C Human-Interface Device based on the config
  372. * provided
  373. *
  374. * @hid_desc_reg_offset: HID register offset
  375. */
  376. int acpi_device_write_dsm_i2c_hid(struct acpi_ctx *ctx,
  377. int hid_desc_reg_offset);
  378. /**
  379. * acpi_device_write_i2c_dev() - Write an I2C device to ACPI
  380. *
  381. * This creates a I2cSerialBusV2 descriptor for an I2C device, including
  382. * information ACPI needs to use it.
  383. *
  384. * @ctx: ACPI context pointer
  385. * @dev: I2C device to write
  386. * @return I2C address of device if OK, -ve on error
  387. */
  388. int acpi_device_write_i2c_dev(struct acpi_ctx *ctx, const struct udevice *dev);
  389. /**
  390. * acpi_device_write_spi_dev() - Write a SPI device to ACPI
  391. *
  392. * This writes a serial bus descriptor for the SPI device so that ACPI can use
  393. * it
  394. *
  395. * @ctx: ACPI context pointer
  396. * @dev: SPI device to write
  397. * @return 0 if OK, -ve on error
  398. */
  399. int acpi_device_write_spi_dev(struct acpi_ctx *ctx, const struct udevice *dev);
  400. /**
  401. * acpi_device_add_power_res() - Add a basic PowerResource block for a device
  402. *
  403. * This includes GPIOs to control enable, reset and stop operation of the
  404. * device. Each GPIO is optional, but at least one must be provided.
  405. * This can be applied to any device that has power control, so is fairly
  406. * generic.
  407. *
  408. * Reset - Put the device into / take the device out of reset.
  409. * Enable - Enable / disable power to device.
  410. * Stop - Stop / start operation of device.
  411. *
  412. * @ctx: ACPI context pointer
  413. * @tx_state_val: Mask to use to toggle the TX state on the GPIO pin, e,g.
  414. * PAD_CFG0_TX_STATE
  415. * @dw0_read: Name to use to read dw0, e.g. "\\_SB.GPC0"
  416. * @dw0_write: Name to use to read dw0, e.g. "\\_SB.SPC0"
  417. * @reset_gpio: GPIO used to take device out of reset or to put it into reset
  418. * @reset_delay_ms: Delay to be inserted after device is taken out of reset
  419. * (_ON method delay)
  420. * @reset_off_delay_ms: Delay to be inserted after device is put into reset
  421. * (_OFF method delay)
  422. * @enable_gpio: GPIO used to enable device
  423. * @enable_delay_ms: Delay to be inserted after device is enabled
  424. * @enable_off_delay_ms: Delay to be inserted after device is disabled
  425. * (_OFF method delay)
  426. * @stop_gpio: GPIO used to stop operation of device
  427. * @stop_delay_ms: Delay to be inserted after disabling stop (_ON method delay)
  428. * @stop_off_delay_ms: Delay to be inserted after enabling stop.
  429. * (_OFF method delay)
  430. *
  431. * @return 0 if OK, -ve if at least one GPIO is not provided
  432. */
  433. int acpi_device_add_power_res(struct acpi_ctx *ctx, u32 tx_state_val,
  434. const char *dw0_read, const char *dw0_write,
  435. const struct gpio_desc *reset_gpio,
  436. uint reset_delay_ms, uint reset_off_delay_ms,
  437. const struct gpio_desc *enable_gpio,
  438. uint enable_delay_ms, uint enable_off_delay_ms,
  439. const struct gpio_desc *stop_gpio,
  440. uint stop_delay_ms, uint stop_off_delay_ms);
  441. /**
  442. * acpi_device_infer_name() - Infer the name from its uclass or parent
  443. *
  444. * Many ACPI devices have a standard name that can be inferred from the uclass
  445. * they are in, or the uclass of their parent. These rules are implemented in
  446. * this function. It attempts to produce a name for a device based on these
  447. * rules.
  448. *
  449. * NOTE: This currently supports only x86 devices. Feel free to enhance it for
  450. * other architectures as needed.
  451. *
  452. * @dev: Device to check
  453. * @out_name: Place to put the name (must hold ACPI_NAME_MAX bytes)
  454. * @return 0 if a name was found, -ENOENT if not found, -ENXIO if the device
  455. * sequence number could not be determined
  456. */
  457. int acpi_device_infer_name(const struct udevice *dev, char *out_name);
  458. #endif