The latest development version of this page may be more current than this released 3.0.0 version.

Pin Control

group pinctrl_interface

Pin Controller Interface.

Pin control states


Default state (state used when the device is in operational state).


Sleep state (state used when the device is in low power mode).


This and higher values refer to custom private states.



Utility macro to indicate no register is used.


Declare pin control configuration for a given node identifier.

This macro should be used by tests or applications using runtime pin control to declare the pin control configuration for a device. PINCTRL_DT_DEV_CONFIG_GET can later be used to obtain a reference to such configuration.

Only available if CONFIG_PINCTRL_NON_STATIC is selected.

  • node_id – Node identifier.


Define all pin control information for the given node identifier.

This helper macro should be called together with device definition. It defines and initializes the pin control configuration for the device represented by node_id. Each pin control state (pinctrl-0, …, pinctrl-N) is also defined and initialized. Note that states marked to be skipped will not be defined (refer to Z_PINCTRL_SKIP_STATE for more details).

  • node_id – Node identifier.


Define all pin control information for the given compatible index.

  • inst – Instance number.


Obtain a reference to the pin control configuration given a node identifier.

  • node_id – Node identifier.


Obtain a reference to the pin control configuration given current compatible instance number.

  • inst – Instance number.


int pinctrl_lookup_state(const struct pinctrl_dev_config *config, uint8_t id, const struct pinctrl_state **state)

Find the state configuration for the given state id.

  • config – Pin controller configuration.

  • id – Pin controller state id (see PINCTRL_STATES).

  • state – Found state.

Return values
  • 0 – If state has been found.

  • -ENOENT – If the state has not been found.

int pinctrl_configure_pins(const pinctrl_soc_pin_t *pins, uint8_t pin_cnt, uintptr_t reg)

Configure a set of pins.

This function will configure the necessary hardware blocks to make the configuration immediately effective.


This function must never be used to configure pins used by an instantiated device driver.

  • pins – List of pins to be configured.

  • pin_cnt – Number of pins.

  • reg – Device register (optional, use PINCTRL_REG_NONE if not used).

Return values
  • 0 – If succeeded

  • -errno – Negative errno for other failures.

static inline int pinctrl_apply_state_direct(const struct pinctrl_dev_config *config, const struct pinctrl_state *state)

Apply a state directly from the provided state configuration.

  • config – Pin control configuration.

  • state – State.

Return values
  • 0 – If succeeded

  • -errno – Negative errno for other failures.

static inline int pinctrl_apply_state(const struct pinctrl_dev_config *config, uint8_t id)

Apply a state from the given device configuration.

  • config – Pin control configuration.

  • id – Id of the state to be applied (see PINCTRL_STATES).

Return values
  • 0 – If succeeded.

  • -ENOENT – If given state id does not exist.

  • -errno – Negative errno for other failures.

struct pinctrl_state
#include <pinctrl.h>

Pin control state configuration.

Public Members

const pinctrl_soc_pin_t *pins

Pin configurations.

uint8_t pin_cnt

Number of pin configurations.

uint8_t id

State identifier (see PINCTRL_STATES).

struct pinctrl_dev_config
#include <pinctrl.h>

Pin controller configuration for a given device.

Public Members

uintptr_t reg

Device address (only available if CONFIG_PINCTRL_STORE_REG is enabled).

const struct pinctrl_state *states

List of state configurations.

uint8_t state_cnt

Number of state configurations.

Dynamic pin control

group pinctrl_interface_dynamic



Helper macro to define the pins of a pin control state from Devicetree.

The name of the defined state pins variable is the same used by prop. This macro is expected to be used in conjunction with PINCTRL_DT_STATE_INIT.

  • node_id – Node identifier containing prop.

  • prop – Property within node_id containing state configuration.


Utility macro to initialize a pin control state.

This macro should be used in conjunction with PINCTRL_DT_STATE_PINS_DEFINE when using dynamic pin control to define an alternative state configuration stored in Devicetree.


// board.dts

     zephyr,user {
             // uart0_alt_default node contains alternative pin config
             uart0_alt_default = <&uart0_alt_default>;

// application

PINCTRL_DT_STATE_PINS_DEFINE(DT_PATH(zephyr_user), uart0_alt_default);

static const struct pinctrl_state uart0_alt[] = {

  • prop – Property name in Devicetree containing state configuration.

  • state – State represented by prop (see PINCTRL_STATES).


int pinctrl_update_states(struct pinctrl_dev_config *config, const struct pinctrl_state *states, uint8_t state_cnt)

Update states with a new set.


In order to guarantee device drivers correct operation the same states have to be provided. For example, if default and sleep are in the current list of states, it is expected that the new array of states also contains both.

  • config – Pin control configuration.

  • states – New states to be set.

  • state_cnt – Number of new states to be set.

Return values
  • -EINVAL – If the new configuration does not contain the same states as the current active configuration.

  • -ENOSYS – If the functionality is not available.

  • 0 – On success.