include/acpi/acpi_device.h

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