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