GPIO provide support for general purpose I/Os on the platform, including initialization, setting and interrupt management.
| Kconfig Option | Default | Documentation |
|---|---|---|
CONFIG_GPIO | n | Include GPIO drivers in system config |
CONFIG_PLATFORM_EC_GPIO_INIT_PRIORITY | 51 | GPIO Init Priority |
No sub-options available.
Configure the GPIO module by declaring all GPIOs as child nodes in the devicetree node with compatible property named-gpios. The GPIO module automatically initializes all GPIOs from this node (unless the no-auto-init property is present). Legacy C source code accesses GPIOs using the specified enum-name property as an enum name of the GPIO. Zephyr based code uses the node label, an alias, or other node reference to identify the GPIO.
Named GPIO properties:
| Property | Description | Settings |
|---|---|---|
gpios | GPIO phandle-array, identifies the port (X), pin number (Y) and flags. | <&gpioX Y flags> |
enum-name | An optional name used to define an enum to refer to the GPIO in legacy code. | GPIO_<NAME> |
no-auto-init | If present, the GPIO will not be initialized at start-up. | boolean, default false |
The use of no-auto-init allows GPIOs to be skipped at start-up initialization time, and selectively enabled by code at some later time.
The file gpio-enum-name.yaml defines the list of valid enum-name values.
In the GPIO declaration use the lowercase net name from the schematic as the node name, and the same net name prefixed with gpio_ as node label. For example:
named-gpios {
compatible = "named-gpios";
...
gpio_en_pp5000_fan: en_pp5000_fan {
gpios = <&gpio6 1 GPIO_OUT_LOW>;
enum-name = "GPIO_EN_PP5000_FAN";
};
gpio_power_on_odl: power_on {
gpios = <&gpio4 4 GPIO_INPUT_PULL_UP>;
};
};
...
aliases {
gpio-power = &gpio_power_on_odl;
};
The flags cell of the gpios property defines the GPIO signal properties, valid options are listed in dt-bindings/gpio_defines.h, which is normally included from the main board DTS file.
For platform specific features, other flags may be available in the Zephyr dt-bindings/gpio/gpio.h file, such as GPIO_VOLTAGE_1P8.
All pins are configured as GPIO by default, so normally pinctrl configuration for GPIO pins is not required. Note that on NPCX ECs some pins default to a non-GPIO function after reset. These are explicitly set to GPIO during initialization, based on the def-io-conf-list node in npcx9.dtsi, so they do not need to be set to GPIO usage, but they need an explicit pinctrl-x entry to be set back to the specific function.
Only GPIOs that require referencing from legacy common code should have an enum-name property. The legacy API (e.g gpio_get_level(enum gpio_signal)) requires a known name for the enum, which is set using the enum-name property.
Do not use enum gpio_signal or the enum signal names in any Zephyr based code - instead, use the standard Zephyr GPIO API.
GPIOs references that are not in legacy common code should use the standard Zephyr API to access the GPIO.
GPIOs are referenced in the named-gpios child nodes using the node label (if one exists), an alias to a node label, or indirectly as a node reference via as a phandle in another node.
To facilitate this, all GPIO child nodes in named-gpios have preinitialised const struct gpio_dt_spec * pointers created that may be used directly in the Zephyr GPIO API calls. These pointers are accessible via the following macros:
| Macro | Argument | Description |
|---|---|---|
GPIO_DT_FROM_NODELABEL | nodelabel | Uses a node label to reference the GPIO node. |
GPIO_DT_FROM_NODE | node | Uses a node id (referenced as a phandle in another node). |
GPIO_DT_FROM_ALIAS | alias | Uses an alias to a label on the GPIO node. |
The legacy enum can also be used to retrieve the gpio_dt_spec for a GPIO via the function gpio_get_dt_spec() (though this is a runtime lookup). E.g:
fan_status = gpio_pin_get_dt(GPIO_DT_FROM_NODELABEL(gpio_en_pp5000_fan));
power_status = gpio_pin_get_dt(GPIO_DT_FROM_ALIAS(gpio_power));
...
/*
* Legacy code gave us an enum gpio_signal, get a Zephyr reference
* for that GPIO.
*/
const struct gpio_dt_spec *my_gpio = gpio_get_dt_spec(my_signal);
my_status = gpio_pin_get_dt(my_gpio);
The GPIO_DT_FROM_NODE macro is used when a named-gpio is referenced from another node via a phandle property.
gpio-interrupts {
compatible = "cros-ec,gpio-interrupts";
int_power_button: power_button {
irq-pin = <&gpio_gsc_ec_pwr_btn_odl>;
...
};
...
/*
* Get the GPIO associated with interrupt.
*/
const struct gpio_dt_spec *pwr_btn =
GPIO_DT_FROM_NODE(DT_PHANDLE(DT_NODELABEL(int_power_button), irq_pin));
pwr_on = gpio_pin_get_dt(pwr_btn);
When referencing a named-gpio child node from another DTS node, it is important not to use gpio or gpios as the trailing suffix of the name property. Any referencing property with a name ending in gpio or gpios is treated specially in devicetree, and assumes the target node is a GPIO node (i.e a node with cell specifiers of pin and flags).
The goal is to migrate away from using the legacy API (using the Zephyr API instead), and deprecate the use of the enum-name property to generate the GPIO signal enum.
It is common to have different hardware configurations supported within the same EC image by using FW_CONFIG configuration bits to selectively choose or enable/disable hardware options. Previously, GPIOs were aliased via a #define in gpio_map.h to a common GPIO in named-gpios, allowing different names to be used for the same GPIO. At run-time the GPIO would be configured according to the usage required.
However this scheme relies on the use of the legacy enum gpio_signal to identify the GPIO. Given that code is being migrated to the Zephyr API, it is preferred that a separate named-gpio node be allocated to each use of the GPIO in question, and use the no-auto-init property to allow the initialisation only when code requires it.
So if a board had 2 GPIOs with different use depending on a board type, the configuration would appear:
gpio_hdmi_enable: hdmi_enable{
gpios = <&gpio0 2 0>;
no-auto-init;
};
gpio_udb_c1_int: udb_c1_int {
gpios = <&gpio0 2 GPIO_PULL_UP>;
no-auto-init;
};
The board config handling may have:
...
if (board_type() == 1) {
gpio_pin_configure_dt(GPIO_DT_FROM_NODELABEL(gpio_hdmi_enable), GPIO_OUTPUT);
} else {
gpio_pin_configure_dt(GPIO_DT_FROM_NODELABEL(gpio_usb_c1_int), GPIO_INPUT);
}
Alternatively, a DTS alias may be used:
gpio_alt_pin: alt_pin {
gpios = <&gpio0 2 GPIO_PULL_UP>;
no-auto-init;
};
...
aliases {
gpio-usb-c1-int = &gpio_alt_pin;
gpio-hdmi-enable = &gpio_alt_pin;
};
...
if (board_type() == 1) {
/* Use as output to enable the HDMI port */
gpio_pin_configure_dt(GPIO_DT_FROM_ALIAS(gpio_hdmi_enable), GPIO_OUTPUT);
} else {
/* Use as type C port 1 interrupt */
gpio_pin_configure_dt(GPIO_DT_FROM_ALIAS(gpio_usb_c1_int), GPIO_INPUT);
/* enable interrupt */
...
}
Note that the alias names have a dash instead of an underscore (because the alias name is a property, not a node name), but the name is converted to lower case with underscores for code access.
Unused GPIOs should be listed separately in an unused-gpio node. EC chip specific code initializes all the unused GPIOs for optimum power consumption.
For example on the Volteer reference board:
unused-pins {
compatible = "unused-gpios";
unused-gpios =
<&gpio3 4 0>, /* Unused, default platform initialization. */
...
<&gpiob 6 GPIO_OUTPUT_LOW>; /* Explicit initialization flags. */
};
Low voltage pins configuration depends on the specific chip family.
For Nuvoton, this is done using the GPIO_VOLTAGE_1P8 flag in the named-gpios child node. For example
named-gpios {
compatible = "named-gpios";
...
ec-i2c-sensor-scl {
gpios = <&gpiob 5 (GPIO_INPUT | GPIO_VOLTAGE_1P8)>;
};
...
}
For ITE, this is done using the GPIO_VOLTAGE_1P8 flag in the named-gpios child node. For example
named-gpios {
compatible = "named-gpios";
...
spi0_cs {
gpios = <&gpiom 5 (GPIO_INPUT | GPIO_VOLTAGE_1P8)>;
enum-name = "GPIO_SPI0_CS";
};
...
}
GPIO interrupts are specified in a device tree node with a compatible property of cros-ec,gpio-interrupts.
Child nodes of this single node contain the following properties:
| Property | Description | Settings |
|---|---|---|
irq-pin | A reference via a node label to the named-gpio that is associated with this interrupt. | <&gpio_label> |
flags | The GPIO interrupt flags that define how the interrupt is generated. | GPIO_INT_<flags> |
handler | The C name of the interrupt handler that handles the interrupt. | C function name. |
For example:
gpio-interrupts {
compatible = "cros-ec,gpio-interrupts";
...
int_power_button: power_button {
irq-pin = <&gpio_ec_pwr_btn_l>;
flags = <GPIO_INT_EDGE_BOTH>;
handler = "power_button_interrupt";
};
...
}
There must only be one named node containing all of the device tree interrupt configuration, but of course overlays may be used to add child nodes or modify the single node.
The C handler takes one argument, the enum signal of the GPIO, such as:
void power_button_interrupt(enum gpio_signal signal)
{
/* Process power button event */
...
}
This matches the function signature of the existing legacy interrupt handlers, so no shims are required.
Interrupt handlers in Zephyr based code may need to compare the signal against known GPIOs, if (for instance) there is a common handler for events from multiple GPIOs. Rather than using the predefined enums (which require that the GPIO has an enum-name property), the macro GPIO_SIGNAL(node_id) may be used to uniquely identify the signal regardless of whether an enum-name property is on the GPIO e.g:
void button_input(enum gpio_signal signal)
{
switch(signal) {
case GPIO_SIGNAL(DT_NODELABEL(gpio_volume_up)):
...
break;
case GPIO_SIGNAL(DT_NODELABEL(gpio_volume_down)):
...
break;
case GPIO_SIGNAL(DT_NODELABEL(gpio_power_button)):
...
break;
}
}
Before any interrupt can be received, it must be enabled. Legacy code uses the functions gpio_enable_interrupt(enum signal) and gpio_disable_interrupt(enum signal) functions. Do not use these in any Zephyr based code.
Whilst it is possible to use the Zephyr GPIO interrupt API directly, for convenience (until the deprecation of the legacy GPIO enum signal names) interrupts can be identified via a macro and the label on the interrupt nodes, and these can be used to enable or disable the interrupts:
gpio_enable_dt_interrupt(GPIO_INT_FROM_NODELABEL(int_power_button));
This avoid having to create boiler-plate callbacks as part of the interrupt setup.
For nodes that require a reference to an GPIO interrupt (such as sensor configuration node etc.), the node can be referenced directly using GPIO_INT_FROM_NODE e.g:
[DTS] sensor-irqs = < &int_imu &int_accel >; [code] #define ENABLE_SENSOR_INTS(i, id) \ gpio_enable_dt_interrupt(GPIO_INT_FROM_NODE(DT_PHANDLE_BY_IDX(id, sensor_irqs, i)))
GPIO support does not enable any threads.
The EC application defines two different shell commands to read and change the state of a GPIO:
| Command | Description | Usage |
|---|---|---|
gpioget | Read the current state of a GPIO | gpioget [name] |
gpioset | Change the state of a GPIO | gpioset name <value> |
GPIO parameter summary:
| Parameter | Description |
|---|---|
name | The GPIO node name as defined in the devicetree. |
value | The requested state, 0 or 1. |
The image below shows a GPIO assignment on the Volteer reference board.
In this example, the EC_ENTERING_RW line could be configured as:
| Net Name | Port | Pin | Flags |
|---|---|---|---|
| EC_ENTERING_RW | GPIOE | 3 | Output, initialize low |
Which translate in the devicetree node:
named-gpios {
compatible = "named-gpios";
...
gpio_ec_entering_rw: ec_entering_rw {
gpios = <&gpioe 3 GPIO_OUT_LOW>;
enum-name = "GPIO_ENTERING_RW";
};
...
}
Set or get the GPIO value in the C source code directly using the enum-name property GPIO_ENTERING_RW.
gpio_set_level(GPIO_ENTERING_RW, 0);
val = gpio_get_level(GPIO_ENTERING_RW);
Use the node label to reference the GPIO in other devicetree nodes:
my_node: my-node {
compatible = "cros-ec,my-feature"
signal-pin = <&gpio_ec_entering_rw>;
};
The named-gpios node and subnodes are normally declared in a separate gpio.dts file, which is added as an overlay in the BUILD.py file for the project.