diff options
Diffstat (limited to 'docs/configuration/gpio.md')
| -rw-r--r-- | docs/configuration/gpio.md | 99 |
1 files changed, 52 insertions, 47 deletions
diff --git a/docs/configuration/gpio.md b/docs/configuration/gpio.md index 4e13a7cb59..f4a5c4719a 100644 --- a/docs/configuration/gpio.md +++ b/docs/configuration/gpio.md @@ -4,18 +4,18 @@ GPIO setup is done for every board variant, but never for the baseboard, by configuring the file `./board/<board>/gpio.inc`. This file configures all the the pins on the EC chipset through the following macros. -- `GPIO(<name>, ...)` - Configures simple GPIO input and outputs -- `GPIO_INT(<name>, ...)` - Configures GPIO inputs that connect to an interrupt - service routine. Historically these entries are defined first, but this no - longer required. -- `ALTERNATE(...)` - Configures a pin for an alternate function (e.g I2C, ADC, - SPI, etc) -- `UNIMPLEMENTED(<name>, ...)` - Creates a fake GPIO entry +- `GPIO(<name>, ...)` - Configures simple GPIO input and outputs +- `GPIO_INT(<name>, ...)` - Configures GPIO inputs that connect to an + interrupt service routine. Historically these entries are defined first, but + this no longer required. +- `ALTERNATE(...)` - Configures a pin for an alternate function (e.g I2C, ADC, + SPI, etc) +- `UNIMPLEMENTED(<name>, ...)` - Creates a fake GPIO entry The `GPIO()`, `GPIO_INT()`, and `UNIMPLEMENTED()` macros create a C enumeration -of the form `GPIO_<name>` that can be used in the code. As noted in [GPIO -Naming](../new_board_checklist.md#GPIO-Naming), the `<name>` parameter should -always match the schematic net name. +of the form `GPIO_<name>` that can be used in the code. As noted in +[GPIO Naming](../new_board_checklist.md#GPIO-Naming), the `<name>` parameter +should always match the schematic net name. ## `GPIO()` macro @@ -23,13 +23,13 @@ always match the schematic net name. `GPIO(name, pin, flags)` -- `name` - Defines the schematic net name, which is expanded to the enumeration - `GPIO_name` by the macro. -- `pin` - Use the `PIN(group,pin)` macro to define the GPIO group and pin - number. Note that on a few EC chipsets, the PIN macro is just `PIN(pin)`. -- `flags` - Define attributes of the pin (direction, pullup/pulldown, open - drain, voltage level, etc). All supported flags are found following the - `GPIO_FLAG_NONE` definition in [./include/gpio.h](../../include/gpio.h). +- `name` - Defines the schematic net name, which is expanded to the + enumeration `GPIO_name` by the macro. +- `pin` - Use the `PIN(group,pin)` macro to define the GPIO group and pin + number. Note that on a few EC chipsets, the PIN macro is just `PIN(pin)`. +- `flags` - Define attributes of the pin (direction, pullup/pulldown, open + drain, voltage level, etc). All supported flags are found following the + `GPIO_FLAG_NONE` definition in [./include/gpio.h](../../include/gpio.h). ### Example @@ -49,15 +49,16 @@ should also map the net name to the EC name in the `board.h` file. ## `GPIO_INT()` macro ### Prototype + `GPIO_INT(name, pin, flags, signal)` -- `name` - Defines the schematic net name, which is expanded to the enumeration - `GPIO_name` by the macro. -- `pin` - Same definition as `GPIO()` macro. -- `flags` - Same definition as `GPIO()` macro. Should always have one of the - `GPIO_INT_*` flags set. -- `signal` - Interrupt service routine called when the pin asserts according to - the flags set. +- `name` - Defines the schematic net name, which is expanded to the + enumeration `GPIO_name` by the macro. +- `pin` - Same definition as `GPIO()` macro. +- `flags` - Same definition as `GPIO()` macro. Should always have one of the + `GPIO_INT_*` flags set. +- `signal` - Interrupt service routine called when the pin asserts according + to the flags set. ### Example @@ -77,42 +78,43 @@ need to map the net name to the EC name in the `board.h` file. ## `ALTERNATE()` macro ### Prototype + `ALTERNATE(pinmask, function, module, flags)` -- `pinmask` - Defines a set of pins in the same GPIO group to assign to a - different function. -- `function` - A chip-specific function number. Only used if the EC chipset - provides multiple alternate functions in addition to GPIO (e.g. pin can be - UART, I2C, SPI, or GPIO). The permitted values for this parameter vary based - on the EC chipset type. - - STM32 - 0 to 7 - - Maxim - 1 to 3 - - Microchip - 0 to 3 - - MediaTek - 0 to 7 - - All others (Nuvton, ITE, TI Stellaris, ) only support one alternate - function per pin, so this parameter should be set to 0. -- `module` - One of the enum module_id values defined in - [./include/module_id.h](../../include/module_id.h). -- `flags` - Same definition as `GPIO()` macro. +- `pinmask` - Defines a set of pins in the same GPIO group to assign to a + different function. +- `function` - A chip-specific function number. Only used if the EC chipset + provides multiple alternate functions in addition to GPIO (e.g. pin can be + UART, I2C, SPI, or GPIO). The permitted values for this parameter vary based + on the EC chipset type. + - STM32 - 0 to 7 + - Maxim - 1 to 3 + - Microchip - 0 to 3 + - MediaTek - 0 to 7 + - All others (Nuvton, ITE, TI Stellaris, ) only support one alternate + function per pin, so this parameter should be set to 0. +- `module` - One of the enum module_id values defined in + [./include/module_id.h](../../include/module_id.h). +- `flags` - Same definition as `GPIO()` macro. ### Notes At runtime there are two mechanisms for switching a pin between GPIO mode and alternate function mode. -- `gpio_config_module(enum module_id id, int enable)` - Configures all pins - matching the module enumeration `id`. -- `gpio_config_pin(enum module_id id, enum gpio_signal signal, int enable)` - - Configures a single pin matching the GPIO enumeration `signal`. +- `gpio_config_module(enum module_id id, int enable)` - Configures all pins + matching the module enumeration `id`. +- `gpio_config_pin(enum module_id id, enum gpio_signal signal, int enable)` - + Configures a single pin matching the GPIO enumeration `signal`. For both routines, if `enable` is 1, then the corresponding pins are configured -for alternate mode operation. If `enable` is 0, then the corresponding pins are +for alternate mode operation. If `enable` is 0, then the corresponding pins are configure for GPIO mode. `gpio_config_module()` is automatically called at runtime for all enabled interfaces (I2C, SPI, UART, etc). You can use `gpio_config_pin()` to temporarily configure a pin for GPIO operation, and to restore the original alternate -function. The I2C bus error recovery employs this mechanism to temporarily +function. The I2C bus error recovery employs this mechanism to temporarily driver the I2C SCL and SDA signals to known states, without interference by the I2C controller in the EC chipset. @@ -132,8 +134,6 @@ The general recipe for overriding alternate functions is shown below. gpio_config_pin(MODULE_I2C, GPIO_I2C1_SDA, 1); ``` - - ### Example ![ALTERNATE Example] @@ -148,8 +148,13 @@ ALTERNATE(PIN_MASK(B, BIT(4) | BIT(5)), 0, MODULE_I2C, (GPIO_INPUT | GPIO_SEL_1P appending "export/png" to the Google Drive link. --> <!-- https://docs.google.com/drawings/d/18cWTYQRRCpypYDOLlvKQJTObwcj6wOjUga02B0oZXBg --> + [GPIO Example]: ../images/gpio_example.png + <!-- https://docs.google.com/drawings/d/1X6p5XfB6BBmUUKCrwOg56Bz6LZj9P_WPQXsOdk-OIiI --> + [GPIO_INT Example]: ../images/gpio_int_example.png + <!-- https://docs.google.com/drawings/d/1-kroVezQuA_KdQLzqYPs8u94EBg37z3k6lKzkSLRv-0 --> + [ALTERNATE Example]: ../images/alternate_example.png |