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 also

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 also

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.

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.

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

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.

Parameters

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.

Parameters

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

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 also

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 also

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.

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.