This is the documentation for the latest (main) development branch of Zephyr. If you are looking for the documentation of previous releases, use the drop-down menu on the left and select the desired version.

Pin Control

group pinctrl_interface

Pin Controller Interface.

Pin control states

PINCTRL_STATE_DEFAULT

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

PINCTRL_STATE_SLEEP

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

PINCTRL_STATE_PRIV_START

This and higher values refer to custom private states.

Defines

PINCTRL_REG_NONE

Utility macro to indicate no register is used.

PINCTRL_DT_DEV_CONFIG_DECLARE(node_id)

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.

Parameters
  • node_id – Node identifier.

PINCTRL_DT_DEFINE(node_id)

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).

Parameters
  • node_id – Node identifier.

PINCTRL_DT_INST_DEFINE(inst)

Define all pin control information for the given compatible index.

See

PINCTRL_DT_DEFINE

Parameters
  • inst – Instance number.

PINCTRL_DT_DEV_CONFIG_GET(node_id)

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

Parameters
  • node_id – Node identifier.

PINCTRL_DT_INST_DEV_CONFIG_GET(inst)

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

See

PINCTRL_DT_DEV_CONFIG_GET

Parameters
  • inst – Instance number.

Functions

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.

Parameters
  • config – Pin controller configuration.

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

  • state – Found state.

Returns

  • 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.

Warning

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

Parameters
  • pins – List of pins to be configured.

  • pin_cnt – Number of pins.

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

Returns

  • 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.

Parameters
  • config – Pin control configuration.

  • state – State.

Returns

  • 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.

Parameters
  • config – Pin control configuration.

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

Returns

  • 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

Defines

PINCTRL_DT_STATE_PINS_DEFINE(node_id, prop)

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.

See

PINCTRL_DT_STATE_INIT

Parameters
  • node_id – Node identifier containing prop.

  • prop – Property within node_id containing state configuration.

PINCTRL_DT_STATE_INIT(prop, state)

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.

Example:

// 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[] = {
    PINCTRL_DT_STATE_INIT(uart0_alt_default, PINCTRL_STATE_DEFAULT)
};

See

PINCTRL_DT_STATE_PINS_DEFINE

Parameters
  • prop – Property name in Devicetree containing state configuration.

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

Functions

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

Update states with a new set.

Note

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.

Parameters
  • config – Pin control configuration.

  • states – New states to be set.

  • state_cnt – Number of new states to be set.

Returns

  • -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.