acpi_device.h 15 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475
  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. struct acpi_gpio {
  156. int pin_count;
  157. u16 pins[ACPI_GPIO_MAX_PINS];
  158. ulong pin0_addr;
  159. enum acpi_gpio_type type;
  160. enum acpi_gpio_pull pull;
  161. char resource[ACPI_PATH_MAX];
  162. /* GpioInt */
  163. u16 interrupt_debounce_timeout;
  164. struct acpi_irq irq;
  165. /* GpioIo */
  166. u16 output_drive_strength;
  167. bool io_shared;
  168. enum acpi_gpio_io_restrict io_restrict;
  169. enum acpi_gpio_polarity polarity;
  170. };
  171. /* ACPI Descriptors for Serial Bus interfaces */
  172. #define ACPI_SERIAL_BUS_TYPE_I2C 1
  173. #define ACPI_SERIAL_BUS_TYPE_SPI 2
  174. #define ACPI_I2C_SERIAL_BUS_REVISION_ID 1 /* TODO: upgrade to 2 */
  175. #define ACPI_I2C_TYPE_SPECIFIC_REVISION_ID 1
  176. #define ACPI_SPI_SERIAL_BUS_REVISION_ID 1
  177. #define ACPI_SPI_TYPE_SPECIFIC_REVISION_ID 1
  178. /**
  179. * struct acpi_i2c - representation of an ACPI I2C device
  180. *
  181. * @address: 7-bit or 10-bit I2C address
  182. * @mode_10bit: Which address size is used
  183. * @speed: Bus speed in Hz
  184. * @resource: Resource name for the I2C controller
  185. */
  186. struct acpi_i2c {
  187. u16 address;
  188. enum i2c_address_mode mode_10bit;
  189. enum i2c_speed_rate speed;
  190. const char *resource;
  191. };
  192. /**
  193. * struct acpi_spi - representation of an ACPI SPI device
  194. *
  195. * @device_select: Chip select used by this device (typically 0)
  196. * @device_select_polarity: Polarity for the device
  197. * @wire_mode: Number of wires used for SPI
  198. * @speed: Bus speed in Hz
  199. * @data_bit_length: Word length for SPI (typically 8)
  200. * @clock_phase: Clock phase to capture data
  201. * @clock_polarity: Bus polarity
  202. * @resource: Resource name for the SPI controller
  203. */
  204. struct acpi_spi {
  205. u16 device_select;
  206. enum spi_polarity device_select_polarity;
  207. enum spi_wire_mode wire_mode;
  208. unsigned int speed;
  209. u8 data_bit_length;
  210. enum spi_clock_phase clock_phase;
  211. enum spi_polarity clock_polarity;
  212. const char *resource;
  213. };
  214. /**
  215. * struct acpi_i2c_priv - Information read from device tree
  216. *
  217. * This is used by devices which want to specify various pieces of ACPI
  218. * information, including power control. It allows a generic function to
  219. * generate the information for ACPI, based on device-tree properties.
  220. *
  221. * @disable_gpio_export_in_crs: Don't export GPIOs in the CRS
  222. * @reset_gpio: GPIO used to assert reset to the device
  223. * @enable_gpio: GPIO used to enable the device
  224. * @stop_gpio: GPIO used to stop the device
  225. * @irq_gpio: GPIO used for interrupt (if @irq is not used)
  226. * @irq: IRQ used for interrupt (if @irq_gpio is not used)
  227. * @hid: _HID value for device (required)
  228. * @uid: _UID value for device
  229. * @desc: _DDN value for device
  230. * @wake: Wake event, e.g. GPE0_DW1_15; 0 if none
  231. * @property_count: Number of other DSD properties (currently always 0)
  232. * @probed: true set set 'linux,probed' property
  233. * @compat_string: Device tree compatible string to report through ACPI
  234. * @has_power_resource: true if this device has a power resource
  235. * @reset_delay_ms: Delay after de-asserting reset, in ms
  236. * @reset_off_delay_ms: Delay after asserting reset (during power off)
  237. * @enable_delay_ms: Delay after asserting enable
  238. * @enable_off_delay_ms: Delay after de-asserting enable (during power off)
  239. * @stop_delay_ms: Delay after de-aserting stop
  240. * @stop_off_delay_ms: Delay after asserting stop (during power off)
  241. * @hid_desc_reg_offset: HID register offset (for Human Interface Devices)
  242. */
  243. struct acpi_i2c_priv {
  244. bool disable_gpio_export_in_crs;
  245. struct gpio_desc reset_gpio;
  246. struct gpio_desc enable_gpio;
  247. struct gpio_desc irq_gpio;
  248. struct gpio_desc stop_gpio;
  249. struct irq irq;
  250. const char *hid;
  251. u32 uid;
  252. const char *desc;
  253. u32 wake;
  254. u32 property_count;
  255. bool probed;
  256. const char *compat_string;
  257. bool has_power_resource;
  258. u32 reset_delay_ms;
  259. u32 reset_off_delay_ms;
  260. u32 enable_delay_ms;
  261. u32 enable_off_delay_ms;
  262. u32 stop_delay_ms;
  263. u32 stop_off_delay_ms;
  264. u32 hid_desc_reg_offset;
  265. };
  266. /**
  267. * acpi_device_path() - Get the full path to an ACPI device
  268. *
  269. * This gets the full path in the form XXXX.YYYY.ZZZZ where XXXX is the root
  270. * and ZZZZ is the device. All parent devices are added to the path.
  271. *
  272. * @dev: Device to check
  273. * @buf: Buffer to place the path in (should be ACPI_PATH_MAX long)
  274. * @maxlen: Size of buffer (typically ACPI_PATH_MAX)
  275. * @return 0 if OK, -ve on error
  276. */
  277. int acpi_device_path(const struct udevice *dev, char *buf, int maxlen);
  278. /**
  279. * acpi_device_scope() - Get the scope of an ACPI device
  280. *
  281. * This gets the scope which is the full path of the parent device, as per
  282. * acpi_device_path().
  283. *
  284. * @dev: Device to check
  285. * @buf: Buffer to place the path in (should be ACPI_PATH_MAX long)
  286. * @maxlen: Size of buffer (typically ACPI_PATH_MAX)
  287. * @return 0 if OK, -EINVAL if the device has no parent, other -ve on other
  288. * error
  289. */
  290. int acpi_device_scope(const struct udevice *dev, char *scope, int maxlen);
  291. /**
  292. * acpi_device_status() - Get the status of a device
  293. *
  294. * This currently just returns ACPI_DSTATUS_ALL_ON. It does not support
  295. * inactive or hidden devices.
  296. *
  297. * @dev: Device to check
  298. * @return device status, as ACPI_DSTATUS_...
  299. */
  300. enum acpi_dev_status acpi_device_status(const struct udevice *dev);
  301. /**
  302. * acpi_device_write_interrupt_irq() - Write an interrupt descriptor
  303. *
  304. * This writes an ACPI interrupt descriptor for the given interrupt, converting
  305. * fields as needed.
  306. *
  307. * @ctx: ACPI context pointer
  308. * @req_irq: Interrupt to output
  309. * @return IRQ pin number if OK, -ve on error
  310. */
  311. int acpi_device_write_interrupt_irq(struct acpi_ctx *ctx,
  312. const struct irq *req_irq);
  313. /**
  314. * acpi_device_write_gpio() - Write GpioIo() or GpioInt() descriptor
  315. *
  316. * @gpio: GPIO information to write
  317. * @return GPIO pin number of first GPIO if OK, -ve on error
  318. */
  319. int acpi_device_write_gpio(struct acpi_ctx *ctx, const struct acpi_gpio *gpio);
  320. /**
  321. * acpi_device_write_gpio_desc() - Write a GPIO to ACPI
  322. *
  323. * This creates a GPIO descriptor for a GPIO, including information ACPI needs
  324. * to use it.
  325. *
  326. * @ctx: ACPI context pointer
  327. * @desc: GPIO to write
  328. * @return 0 if OK, -ve on error
  329. */
  330. int acpi_device_write_gpio_desc(struct acpi_ctx *ctx,
  331. const struct gpio_desc *desc);
  332. /**
  333. * acpi_device_write_interrupt_or_gpio() - Write interrupt or GPIO to ACPI
  334. *
  335. * This reads an interrupt from the device tree "interrupts-extended" property,
  336. * if available. If not it reads the first GPIO with the name @prop.
  337. *
  338. * If an interrupt is found, an ACPI interrupt descriptor is written to the ACPI
  339. * output. If not, but if a GPIO is found, a GPIO descriptor is written.
  340. *
  341. * @return irq or GPIO pin number if OK, -ve if neither an interrupt nor a GPIO
  342. * could be found, or some other error occurred
  343. */
  344. int acpi_device_write_interrupt_or_gpio(struct acpi_ctx *ctx,
  345. struct udevice *dev, const char *prop);
  346. /**
  347. * acpi_device_write_dsm_i2c_hid() - Write a device-specific method for HID
  348. *
  349. * This writes a DSM for an I2C Human-Interface Device based on the config
  350. * provided
  351. *
  352. * @hid_desc_reg_offset: HID register offset
  353. */
  354. int acpi_device_write_dsm_i2c_hid(struct acpi_ctx *ctx,
  355. int hid_desc_reg_offset);
  356. /**
  357. * acpi_device_write_i2c_dev() - Write an I2C device to ACPI
  358. *
  359. * This creates a I2cSerialBus descriptor for an I2C device, including
  360. * information ACPI needs to use it.
  361. *
  362. * @ctx: ACPI context pointer
  363. * @dev: I2C device to write
  364. * @return I2C address of device if OK, -ve on error
  365. */
  366. int acpi_device_write_i2c_dev(struct acpi_ctx *ctx, const struct udevice *dev);
  367. /**
  368. * acpi_device_write_spi_dev() - Write a SPI device to ACPI
  369. *
  370. * This writes a serial bus descriptor for the SPI device so that ACPI can use
  371. * it
  372. *
  373. * @ctx: ACPI context pointer
  374. * @dev: SPI device to write
  375. * @return 0 if OK, -ve on error
  376. */
  377. int acpi_device_write_spi_dev(struct acpi_ctx *ctx, const struct udevice *dev);
  378. /**
  379. * acpi_device_add_power_res() - Add a basic PowerResource block for a device
  380. *
  381. * This includes GPIOs to control enable, reset and stop operation of the
  382. * device. Each GPIO is optional, but at least one must be provided.
  383. * This can be applied to any device that has power control, so is fairly
  384. * generic.
  385. *
  386. * Reset - Put the device into / take the device out of reset.
  387. * Enable - Enable / disable power to device.
  388. * Stop - Stop / start operation of device.
  389. *
  390. * @ctx: ACPI context pointer
  391. * @tx_state_val: Mask to use to toggle the TX state on the GPIO pin, e,g.
  392. * PAD_CFG0_TX_STATE
  393. * @dw0_read: Name to use to read dw0, e.g. "\\_SB.GPC0"
  394. * @dw0_write: Name to use to read dw0, e.g. "\\_SB.SPC0"
  395. * @reset_gpio: GPIO used to take device out of reset or to put it into reset
  396. * @reset_delay_ms: Delay to be inserted after device is taken out of reset
  397. * (_ON method delay)
  398. * @reset_off_delay_ms: Delay to be inserted after device is put into reset
  399. * (_OFF method delay)
  400. * @enable_gpio: GPIO used to enable device
  401. * @enable_delay_ms: Delay to be inserted after device is enabled
  402. * @enable_off_delay_ms: Delay to be inserted after device is disabled
  403. * (_OFF method delay)
  404. * @stop_gpio: GPIO used to stop operation of device
  405. * @stop_delay_ms: Delay to be inserted after disabling stop (_ON method delay)
  406. * @stop_off_delay_ms: Delay to be inserted after enabling stop.
  407. * (_OFF method delay)
  408. *
  409. * @return 0 if OK, -ve if at least one GPIO is not provided
  410. */
  411. int acpi_device_add_power_res(struct acpi_ctx *ctx, u32 tx_state_val,
  412. const char *dw0_read, const char *dw0_write,
  413. const struct gpio_desc *reset_gpio,
  414. uint reset_delay_ms, uint reset_off_delay_ms,
  415. const struct gpio_desc *enable_gpio,
  416. uint enable_delay_ms, uint enable_off_delay_ms,
  417. const struct gpio_desc *stop_gpio,
  418. uint stop_delay_ms, uint stop_off_delay_ms);
  419. /**
  420. * acpi_device_infer_name() - Infer the name from its uclass or parent
  421. *
  422. * Many ACPI devices have a standard name that can be inferred from the uclass
  423. * they are in, or the uclass of their parent. These rules are implemented in
  424. * this function. It attempts to produce a name for a device based on these
  425. * rules.
  426. *
  427. * NOTE: This currently supports only x86 devices. Feel free to enhance it for
  428. * other architectures as needed.
  429. *
  430. * @dev: Device to check
  431. * @out_name: Place to put the name (must hold ACPI_NAME_MAX bytes)
  432. * @return 0 if a name was found, -ENOENT if not found, -ENXIO if the device
  433. * sequence number could not be determined
  434. */
  435. int acpi_device_infer_name(const struct udevice *dev, char *out_name);
  436. #endif