Pulse IO

Pulse IO Interface. More...

Files
file	pulse_io.h
	Main header file for the Pulse IO subsystem API.

Data Structures
struct	pulse_symbol
	One symbol of a pulse stream. More...
struct	pulse_cell
	One cell of a fixed-period pulse stream. More...
struct	pulse_io_caps
	Per-instance capability descriptor. More...
struct	pulse_io_config
	Channel configuration. More...
struct	pulse_io_tx_req
	TX submission descriptor. More...
struct	pulse_io_rx_req
	RX submission descriptor. More...
struct	pulse_io_driver_api
	Driver vtable. More...
struct	pulse_io_bit_template
	Per-bit template used by pulse_io_encode_bytes. More...
struct	pulse_io_encoder_api
	Encoder vtable: protocol bytes to pulse symbols. More...
struct	pulse_io_decoder_api
	Decoder vtable: pulse symbols to protocol bytes. More...

Enumerations
enum	pulse_io_mode { PULSE_IO_MODE_SYMBOL = BIT(0) , PULSE_IO_MODE_CELL = BIT(1) }
	Pulse stream submission modes. More...
enum	pulse_io_dir { PULSE_IO_DIR_TX , PULSE_IO_DIR_RX }
	Direction of a configured channel. More...

Functions
int	pulse_io_get_capabilities (const struct device *dev, struct pulse_io_caps *caps)
	Query backend capabilities.
int	pulse_io_channel_get (const struct device *dev, uint8_t channel_idx, struct pulse_io_channel **chan)
	Reserve a channel for exclusive use.
int	pulse_io_channel_release (const struct device *dev, struct pulse_io_channel *chan)
	Release a channel previously obtained via pulse_io_channel_get.
int	pulse_io_channel_configure (const struct device *dev, struct pulse_io_channel *chan, const struct pulse_io_config *cfg)
	Configure a reserved channel.
int	pulse_io_transmit_sync (const struct device *dev, struct pulse_io_channel *chan, const struct pulse_io_tx_req *req, k_timeout_t timeout)
	Blocking transmit.
int	pulse_io_receive_sync (const struct device *dev, struct pulse_io_channel *chan, const struct pulse_io_rx_req *req, size_t *count, k_timeout_t timeout)
	Blocking receive.
int	pulse_io_stop (const struct device *dev, struct pulse_io_channel *chan)
	Stop any in-flight transmit or receive on the channel.

Encoder helpers (pre-expansion)
v1 ships pre-expansion helpers only: each call expands a protocol payload into a fully-resolved pulse_symbol array which the caller then submits via pulse_io_transmit_sync or the RTIO path. A future revision may add a streaming variant that consumes payload incrementally from the TX ISR; that path will be additive and will not change the entry points defined here.
int	pulse_io_encode_bytes (const struct pulse_io_bit_template *tmpl, const uint8_t *bytes, size_t nbytes, struct pulse_symbol *out, size_t out_cap, size_t *produced)
	Expand a byte stream into pulse symbols using a bit template.

RTIO integration
A backend may expose an RTIO submit path plus protocol encoder and decoder vtables, mirroring the sensor subsystem. With these the userspace and asynchronous I/O machinery is provided by RTIO: the client encodes a payload into a symbol buffer, submits it through an RTIO queue, and decodes any captured reply.
int	pulse_io_get_encoder (const struct device *dev, const struct pulse_io_encoder_api **api)
	Fetch the backend encoder vtable.
int	pulse_io_get_decoder (const struct device *dev, const struct pulse_io_decoder_api **api)
	Fetch the backend decoder vtable.
int	pulse_io_decode_bytes (const struct pulse_io_bit_template *tmpl, uint32_t tolerance_ticks, const struct pulse_symbol *in, size_t nsyms, uint8_t *out, size_t out_cap, size_t *produced)
	Default symbol-stream decoder.

Detailed Description

Pulse IO Interface.

Since

4.4

Version

0.1.0

The pulse_io subsystem abstracts hardware peripherals that generate and capture timed digital edges on a single GPIO line. It is intended as a common API for the dedicated edge-timing peripherals that several MCU families provide under different names.

The API supports two submission modes, advertised through capabilities:

• PULSE_IO_MODE_SYMBOL - arbitrary {level, duration} pairs.
• PULSE_IO_MODE_CELL - fixed-period cells with varying duty or level (suits PWM-style hardware).

Clients query pulse_io_get_capabilities at probe time to decide which mode and feature set to use.

Enumeration Type Documentation

pulse_io_dir

enum pulse_io_dir

#include <zephyr/drivers/pulse_io.h>

Direction of a configured channel.

Enumerator
PULSE_IO_DIR_TX	Transmit (generate edges).
PULSE_IO_DIR_RX	Receive (capture edges).

pulse_io_mode

enum pulse_io_mode

#include <zephyr/drivers/pulse_io.h>

Pulse stream submission modes.

Enumerator
PULSE_IO_MODE_SYMBOL	Arbitrary {level, duration} symbol stream.
PULSE_IO_MODE_CELL	Fixed-period cells with per-cell duty or level.

Function Documentation

pulse_io_channel_configure()

int pulse_io_channel_configure	(	const struct device *	dev,
		struct pulse_io_channel *	chan,
		const struct pulse_io_config *	cfg )

#include <zephyr/drivers/pulse_io.h>

Configure a reserved channel.

Must be called before any transmit / receive on the channel. May be called again to reconfigure between operations.

Return values

0	on success.
-ENOTSUP	if cfg requests an unsupported mode or feature.
-EINVAL	if cfg has out-of-range values.

pulse_io_channel_get()

int pulse_io_channel_get	(	const struct device *	dev,
		uint8_t	channel_idx,
		struct pulse_io_channel **	chan )

#include <zephyr/drivers/pulse_io.h>

Reserve a channel for exclusive use.

Parameters

dev	Pulse IO device.
channel_idx	Hardware channel index, 0..caps.num_channels - 1.
chan	Output: handle for subsequent calls.

Return values

0	on success.
-EBUSY	if the channel is already reserved.
-ENODEV	if channel_idx is out of range.

pulse_io_channel_release()

int pulse_io_channel_release	(	const struct device *	dev,
		struct pulse_io_channel *	chan )

#include <zephyr/drivers/pulse_io.h>

Release a channel previously obtained via pulse_io_channel_get.

pulse_io_decode_bytes()

int pulse_io_decode_bytes	(	const struct pulse_io_bit_template *	tmpl,
		uint32_t	tolerance_ticks,
		const struct pulse_symbol *	in,
		size_t	nsyms,
		uint8_t *	out,
		size_t	out_cap,
		size_t *	produced )

#include <zephyr/drivers/pulse_io.h>

Default symbol-stream decoder.

Inverse of pulse_io_encode_bytes(): matches consecutive symbol pairs against tmpl within tolerance_ticks and rebuilds the byte stream. Backends may point their decoder vtable at this.

pulse_io_encode_bytes()

int pulse_io_encode_bytes	(	const struct pulse_io_bit_template *	tmpl,
		const uint8_t *	bytes,
		size_t	nbytes,
		struct pulse_symbol *	out,
		size_t	out_cap,
		size_t *	produced )

#include <zephyr/drivers/pulse_io.h>

Expand a byte stream into pulse symbols using a bit template.

Parameters

tmpl	Bit template.
bytes	Input byte stream.
nbytes	Length of bytes.
out	Output buffer.
out_cap	Capacity of out in symbols.
produced	Output: number of symbols written.

Return values

0	on success.
-ENOMEM	if out_cap is insufficient.

pulse_io_get_capabilities()

int pulse_io_get_capabilities	(	const struct device *	dev,
		struct pulse_io_caps *	caps )

#include <zephyr/drivers/pulse_io.h>

Query backend capabilities.

Return values

0	on success.
-ENOSYS	if the backend does not implement this.

pulse_io_get_decoder()

int pulse_io_get_decoder	(	const struct device *	dev,
		const struct pulse_io_decoder_api **	api )

#include <zephyr/drivers/pulse_io.h>

Fetch the backend decoder vtable.

Return values

0	on success.
-ENOSYS	if the backend exposes no RTIO codec.

pulse_io_get_encoder()

int pulse_io_get_encoder	(	const struct device *	dev,
		const struct pulse_io_encoder_api **	api )

#include <zephyr/drivers/pulse_io.h>

Fetch the backend encoder vtable.

Return values

0	on success.
-ENOSYS	if the backend exposes no RTIO codec.

pulse_io_receive_sync()

int pulse_io_receive_sync	(	const struct device *	dev,
		struct pulse_io_channel *	chan,
		const struct pulse_io_rx_req *	req,
		size_t *	count,
		k_timeout_t	timeout )

#include <zephyr/drivers/pulse_io.h>

Blocking receive.

One-shot capture terminated by idle threshold or buffer full. count is set to the number of valid entries on success.

pulse_io_stop()

int pulse_io_stop	(	const struct device *	dev,
		struct pulse_io_channel *	chan )

#include <zephyr/drivers/pulse_io.h>

Stop any in-flight transmit or receive on the channel.

pulse_io_transmit_sync()

int pulse_io_transmit_sync	(	const struct device *	dev,
		struct pulse_io_channel *	chan,
		const struct pulse_io_tx_req *	req,
		k_timeout_t	timeout )

#include <zephyr/drivers/pulse_io.h>

Blocking transmit.

Returns once the entire req has been transmitted or the timeout elapses. Infinite loops (loop_count == UINT32_MAX) cannot be used with this call; use the RTIO path instead.