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 499