MUX

MUX Controller Interface. More...

Topics
	Devicetree MUX API

Data Structures
struct	mux_control
	Addressing-only specifier for a single MUX control line. More...
struct	mux_state
	Addressing + default state pair for a MUX control line. More...
struct	mux_control_driver_api
	MUX controller driver API. More...

Macros
#define	MUX_CONTROL_DT_SPEC_DEFINE_BY_IDX(node_id, idx)
	Define a mux_control object from a mux-controls entry.
#define	MUX_CONTROL_DT_SPEC_DEFINE(node_id)
	Equivalent to MUX_CONTROL_DT_SPEC_DEFINE_BY_IDX(node_id, 0).
#define	MUX_CONTROL_DT_SPEC_DEFINE_BY_NAME(node_id, name)
	Define a mux_control object by name from a mux-control-names entry.
#define	MUX_STATE_DT_SPEC_DEFINE_BY_IDX(node_id, idx)
	Define a mux_state object from a mux-states entry.
#define	MUX_STATE_DT_SPEC_DEFINE(node_id)
	Equivalent to MUX_STATE_DT_SPEC_DEFINE_BY_IDX(node_id, 0).
#define	MUX_STATE_DT_SPEC_DEFINE_BY_NAME(node_id, name)
	Define a mux_state object by name from a mux-state-names entry.

Functions
int	mux_control_set (const struct device *dev, const struct mux_control *control, uint32_t state)
	Drive a MUX control line to the given state.
int	mux_state_apply (const struct device *dev, const struct mux_state *mstate)
	Apply a devicetree-defined default state to a MUX control line.
int	mux_state_get (const struct device *dev, const struct mux_control *control, uint32_t *state)
	Read back the current state of a MUX control line.
int	mux_control_disconnect (const struct device *dev, const struct mux_control *control)
	Physically disconnect a MUX control line.

Detailed Description

MUX Controller Interface.

Generic device model for multiplexer (signal-routing) controllers. The devicetree model is derived from Linux, but this subsystem intentionally does NOT provide shared-line arbitration: there is no mux_control_select()/deselect() and no per-control concurrency lock. A control line is assumed to have a single owner; concurrent consumers driving the same line are not protected against each other.

Since

4.5

Version

0.1.0

Macro Definition Documentation

MUX_CONTROL_DT_SPEC_DEFINE

#define MUX_CONTROL_DT_SPEC_DEFINE

(

node_id

)

#include <mux.h>

Value:

MUX_CONTROL_DT_SPEC_DEFINE_BY_IDX(node_id, 0)

Equivalent to MUX_CONTROL_DT_SPEC_DEFINE_BY_IDX(node_id, 0).

Example devicetree fragment:

n: node {
        mux-controls = <&mux0 5>;
};

Example usage:

MUX_CONTROL_DT_SPEC_DEFINE(DT_NODELABEL(n));
const struct mux_control *m = MUX_CONTROL_DT_GET(DT_NODELABEL(n));

Parameters

node_id

Devicetree node identifier of the consumer.

See also

MUX_CONTROL_DT_SPEC_DEFINE_BY_IDX()

MUX_CONTROL_DT_SPEC_DEFINE_BY_IDX

#define MUX_CONTROL_DT_SPEC_DEFINE_BY_IDX	(		node_id,
			idx )

#include <mux.h>

Value:

Z_MUX_CTRL_DEFINE_BY_IDX(node_id, idx)

Define a mux_control object from a mux-controls entry.

Emits file-scope storage for the cells array and the mux_control object referencing it. Pair with MUX_CONTROL_DT_GET_BY_IDX() (declared in <zephyr/devicetree/mux.h>) to retrieve a pointer.

Must be invoked at file scope. Each idx should only be defined once to avoid duplicate storage

Example devicetree fragment (a hypothetical multi-channel backend):

mux0: mux-controller@... {
        compatible = "vendor,demux";
        #mux-control-cells = <1>;
        ...
};

n: node {
        mux-controls = <&mux0 5>, <&mux0 7>;
};

Example usage:

MUX_CONTROL_DT_SPEC_DEFINE_BY_IDX(DT_NODELABEL(n), 0);
MUX_CONTROL_DT_SPEC_DEFINE_BY_IDX(DT_NODELABEL(n), 1);

const struct mux_control *m0 = MUX_CONTROL_DT_GET_BY_IDX(DT_NODELABEL(n), 0);
const struct device *d  = MUX_CONTROL_DT_DEV_GET_BY_IDX(DT_NODELABEL(n), 0);
mux_control_set(d, m0, 1);  // drive channel 5 to state 1

Parameters

node_id	Devicetree node identifier of the consumer.
idx	Logical index into the mux-controls property.

See also

MUX_CONTROL_DT_GET_BY_IDX()

MUX_CONTROL_DT_SPEC_DEFINE_BY_NAME

#define MUX_CONTROL_DT_SPEC_DEFINE_BY_NAME	(		node_id,
			name )

#include <mux.h>

Value:

MUX_CONTROL_DT_SPEC_DEFINE_BY_IDX(node_id,        \
        DT_PHA_ELEM_IDX_BY_NAME(node_id, mux_controls, name))

Define a mux_control object by name from a mux-control-names entry.

Equivalent to MUX_CONTROL_DT_SPEC_DEFINE_BY_IDX() with the index resolved from the mux-control-names property.

Example devicetree fragment:

n: node {
        mux-controls = <&mux0 5>, <&mux0 7>;
        mux-control-names = "phase_a", "phase_b";
};

Example usage:

MUX_CONTROL_DT_SPEC_DEFINE_BY_NAME(DT_NODELABEL(n), phase_a);
const struct mux_control *ma =
        MUX_CONTROL_DT_GET_BY_NAME(DT_NODELABEL(n), phase_a);

Parameters

node_id	Devicetree node identifier of the consumer.
name	Lowercase-and-underscores name from the mux-control-names property.

See also

MUX_CONTROL_DT_GET_BY_NAME()

MUX_STATE_DT_SPEC_DEFINE

#define MUX_STATE_DT_SPEC_DEFINE

(

node_id

)

#include <mux.h>

Value:

MUX_STATE_DT_SPEC_DEFINE_BY_IDX(node_id, 0)

Equivalent to MUX_STATE_DT_SPEC_DEFINE_BY_IDX(node_id, 0).

Example devicetree fragment:

n: node {
        mux-states = <&mux0 5 2>;
};

Example usage:

MUX_STATE_DT_SPEC_DEFINE(DT_NODELABEL(n));
const struct mux_state *s = MUX_STATE_DT_GET(DT_NODELABEL(n));

Parameters

node_id

Devicetree node identifier of the consumer.

See also

MUX_STATE_DT_SPEC_DEFINE_BY_IDX()

MUX_STATE_DT_SPEC_DEFINE_BY_IDX

#define MUX_STATE_DT_SPEC_DEFINE_BY_IDX	(		node_id,
			idx )

#include <mux.h>

Value:

Z_MUX_STATE_DEFINE_BY_IDX(node_id, idx)

Define a mux_state object from a mux-states entry.

Emits file-scope storage for the addressing cells, the embedded mux_control, and the mux_state. The leading cells of the specifier become the addressing portion (mux_state.control->cells); the trailing cell becomes mux_state.state.

Must be invoked at file scope. Each idx should only be defined once to avoid duplicate storage.

Example devicetree fragment (a hypothetical multi-channel backend):

mux0: mux-controller@... {
        compatible = "vendor,demux";
        #mux-control-cells = <1>;
        #mux-state-cells   = <2>;
        ...
};

n: node {
        // <controller channel state>
        mux-states = <&mux0 5 2>, <&mux0 7 3>;
};

Example usage:

MUX_STATE_DT_SPEC_DEFINE_BY_IDX(DT_NODELABEL(n), 0);

const struct mux_state *s0 = MUX_STATE_DT_GET_BY_IDX(DT_NODELABEL(n), 0);
// s0->control->cells[0] == 5, s0->state == 2
mux_state_apply(MUX_STATE_DT_DEV_GET_BY_IDX(DT_NODELABEL(n), 0), s0);

Parameters

node_id	Devicetree node identifier of the consumer.
idx	Logical index into the mux-states property.

See also

MUX_STATE_DT_GET_BY_IDX(), mux_state_apply()

MUX_STATE_DT_SPEC_DEFINE_BY_NAME

#define MUX_STATE_DT_SPEC_DEFINE_BY_NAME	(		node_id,
			name )

#include <mux.h>

Value:

MUX_STATE_DT_SPEC_DEFINE_BY_IDX(node_id,        \
        DT_PHA_ELEM_IDX_BY_NAME(node_id, mux_states, name))

Define a mux_state object by name from a mux-state-names entry.

Equivalent to MUX_STATE_DT_SPEC_DEFINE_BY_IDX() with the index resolved from the mux-state-names property.

Example devicetree fragment:

n: node {
        mux-states      = <&mux0 5 2>, <&mux0 7 3>;
        mux-state-names = "default", "alt";
};

Example usage:

MUX_STATE_DT_SPEC_DEFINE_BY_NAME(DT_NODELABEL(n), default);
const struct mux_state *def =
        MUX_STATE_DT_GET_BY_NAME(DT_NODELABEL(n), default);

Parameters

node_id	Devicetree node identifier of the consumer.
name	Lowercase-and-underscores name from the mux-state-names property.

See also

MUX_STATE_DT_GET_BY_NAME()

Function Documentation

mux_control_disconnect()

int mux_control_disconnect	(	const struct device *	dev,
		const struct mux_control *	control )

#include <mux.h>

Physically disconnect a MUX control line.

Drives the addressed control line into its open/off state, in which no input is routed. How that state is reached is backend-specific: it may be a dedicated enable gate that latches the previously selected route for reconnect (for example an enable pin), or the all-open state of a switch array (all underlying switches turned off). A subsequent mux_control_set() reconnects the line and applies the requested route; there is no separate reconnect operation.

The affected scope is exactly the routing unit covered by the addressed control line, as modeled by the backend's devicetree binding. A backend exposing each channel as its own control line disconnects only the addressed channel; a backend modeling the whole device as a single control line (#mux-control-cells = 0) disconnects the whole device.

Optional operation. Backends that cannot reach an open state (for example a plain GPIO select bus that always drives some pattern, with no enable line) leave the disconnect op NULL, in which case this returns -ENOSYS.

Parameters

dev	MUX controller device.
control	Addressing of the control line to disconnect.

Return values

0	On success.
-ENOSYS	If the driver does not implement this operation, or this instance has no disconnect capability.
-EINVAL	If addressing is out of range.
-errno	Other negative errno on failure.

mux_control_set()

int mux_control_set	(	const struct device *	dev,
		const struct mux_control *	control,
		uint32_t	state )

#include <mux.h>

Drive a MUX control line to the given state.

Parameters

dev	MUX controller device.
control	Addressing of the control line to drive.
state	Target state value.

Return values

0	On success.
-EINVAL	If addressing or state is out of range.
-EACCES	If the control line is locked.
-errno	Other negative errno on failure.

mux_state_apply()

int mux_state_apply	(	const struct device *	dev,
		const struct mux_state *	mstate )

#include <mux.h>

Apply a devicetree-defined default state to a MUX control line.

Convenience for mux-states consumers: extracts the default state from mstate and forwards to mux_control_set().

Parameters

dev	MUX controller device.
mstate	Addressing + default state pair.

Return values

0	On success.
-errno	Negative errno on failure.

mux_state_get()

int mux_state_get	(	const struct device *	dev,
		const struct mux_control *	control,
		uint32_t *	state )

#include <mux.h>

Read back the current state of a MUX control line.

Optional operation: hardware that cannot read back its routing leaves the get_state op NULL, in which case this returns -ENOSYS.

Parameters

dev	MUX controller device.
control	Addressing of the control line to query.
state	Output: current state value (only valid on success).

Return values

0	On success.
-ENOSYS	If the driver does not implement this operation.
-EINVAL	If addressing is out of range.
-errno	Other negative errno on failure.