Zephyr API Documentation 4.5.99
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
pulse_io.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2026 Espressif Systems (Shanghai) Co., Ltd.
3 *
4 * SPDX-License-Identifier: Apache-2.0
5 */
6
7#ifndef ZEPHYR_INCLUDE_DRIVERS_PULSE_IO_H_
8#define ZEPHYR_INCLUDE_DRIVERS_PULSE_IO_H_
9
15
16#include <errno.h>
17#include <stddef.h>
18#include <stdbool.h>
19#include <stdint.h>
20
21#include <zephyr/device.h>
22#include <zephyr/kernel.h>
23#include <zephyr/rtio/rtio.h>
24#include <zephyr/sys/util.h>
25
26#ifdef __cplusplus
27extern "C" {
28#endif
29
53
61
69
85
104
174
216
224struct pulse_io_channel;
225
226/* Forward declarations for the RTIO codec vtables (defined below). */
229
238 union {
240 const struct pulse_symbol *symbols;
242 const struct pulse_cell *cells;
243 };
245 size_t count;
248};
249
255 union {
260 };
262 size_t capacity;
263};
264
269
273__subsystem struct pulse_io_driver_api {
275 int (*get_capabilities)(const struct device *dev, struct pulse_io_caps *caps);
276
278 int (*channel_get)(const struct device *dev, uint8_t channel_idx,
279 struct pulse_io_channel **chan);
280
282 int (*channel_release)(const struct device *dev, struct pulse_io_channel *chan);
283
285 int (*channel_configure)(const struct device *dev, struct pulse_io_channel *chan,
286 const struct pulse_io_config *cfg);
287
289 int (*transmit_sync)(const struct device *dev, struct pulse_io_channel *chan,
290 const struct pulse_io_tx_req *req, k_timeout_t timeout);
291
293 int (*receive_sync)(const struct device *dev, struct pulse_io_channel *chan,
294 const struct pulse_io_rx_req *req, size_t *count, k_timeout_t timeout);
295
297 int (*stop)(const struct device *dev, struct pulse_io_channel *chan);
298
300 void (*submit)(const struct device *dev, struct rtio_iodev_sqe *iodev_sqe);
302 int (*get_encoder)(const struct device *dev, const struct pulse_io_encoder_api **api);
304 int (*get_decoder)(const struct device *dev, const struct pulse_io_decoder_api **api);
305};
306
308
315__syscall int pulse_io_get_capabilities(const struct device *dev, struct pulse_io_caps *caps);
316
317static inline int z_impl_pulse_io_get_capabilities(const struct device *dev,
318 struct pulse_io_caps *caps)
319{
320 const struct pulse_io_driver_api *api = DEVICE_API_GET(pulse_io, dev);
321
322 if (api->get_capabilities == NULL) {
323 return -ENOSYS;
324 }
325 return api->get_capabilities(dev, caps);
326}
327
339__syscall int pulse_io_channel_get(const struct device *dev, uint8_t channel_idx,
340 struct pulse_io_channel **chan);
341
342static inline int z_impl_pulse_io_channel_get(const struct device *dev, uint8_t channel_idx,
343 struct pulse_io_channel **chan)
344{
345 return DEVICE_API_GET(pulse_io, dev)->channel_get(dev, channel_idx, chan);
346}
347
351__syscall int pulse_io_channel_release(const struct device *dev, struct pulse_io_channel *chan);
352
353static inline int z_impl_pulse_io_channel_release(const struct device *dev,
354 struct pulse_io_channel *chan)
355{
356 return DEVICE_API_GET(pulse_io, dev)->channel_release(dev, chan);
357}
358
369__syscall int pulse_io_channel_configure(const struct device *dev, struct pulse_io_channel *chan,
370 const struct pulse_io_config *cfg);
371
372static inline int z_impl_pulse_io_channel_configure(const struct device *dev,
373 struct pulse_io_channel *chan,
374 const struct pulse_io_config *cfg)
375{
376 return DEVICE_API_GET(pulse_io, dev)->channel_configure(dev, chan, cfg);
377}
378
386__syscall int pulse_io_transmit_sync(const struct device *dev, struct pulse_io_channel *chan,
387 const struct pulse_io_tx_req *req, k_timeout_t timeout);
388
389static inline int z_impl_pulse_io_transmit_sync(const struct device *dev,
390 struct pulse_io_channel *chan,
391 const struct pulse_io_tx_req *req,
392 k_timeout_t timeout)
393{
394 return DEVICE_API_GET(pulse_io, dev)->transmit_sync(dev, chan, req, timeout);
395}
396
403__syscall int pulse_io_receive_sync(const struct device *dev, struct pulse_io_channel *chan,
404 const struct pulse_io_rx_req *req, size_t *count,
405 k_timeout_t timeout);
406
407static inline int z_impl_pulse_io_receive_sync(const struct device *dev,
408 struct pulse_io_channel *chan,
409 const struct pulse_io_rx_req *req, size_t *count,
410 k_timeout_t timeout)
411{
412 return DEVICE_API_GET(pulse_io, dev)->receive_sync(dev, chan, req, count, timeout);
413}
414
418__syscall int pulse_io_stop(const struct device *dev, struct pulse_io_channel *chan);
419
420static inline int z_impl_pulse_io_stop(const struct device *dev, struct pulse_io_channel *chan)
421{
422 return DEVICE_API_GET(pulse_io, dev)->stop(dev, chan);
423}
424
437
451
465int pulse_io_encode_bytes(const struct pulse_io_bit_template *tmpl, const uint8_t *bytes,
466 size_t nbytes, struct pulse_symbol *out, size_t out_cap,
467 size_t *produced);
468
470
481
487 int (*encode)(const struct pulse_io_bit_template *tmpl, const uint8_t *bytes, size_t nbytes,
488 struct pulse_symbol *out, size_t out_cap, size_t *produced);
489};
490
500 int (*decode)(const struct pulse_io_bit_template *tmpl, uint32_t tolerance_ticks,
501 const struct pulse_symbol *in, size_t nsyms, uint8_t *out, size_t out_cap,
502 size_t *produced);
503};
504
511__syscall int pulse_io_get_encoder(const struct device *dev,
512 const struct pulse_io_encoder_api **api);
513
514static inline int z_impl_pulse_io_get_encoder(const struct device *dev,
515 const struct pulse_io_encoder_api **api)
516{
517 const struct pulse_io_driver_api *drv = DEVICE_API_GET(pulse_io, dev);
518
519 if (drv->get_encoder == NULL) {
520 return -ENOSYS;
521 }
522 return drv->get_encoder(dev, api);
523}
524
531__syscall int pulse_io_get_decoder(const struct device *dev,
532 const struct pulse_io_decoder_api **api);
533
534static inline int z_impl_pulse_io_get_decoder(const struct device *dev,
535 const struct pulse_io_decoder_api **api)
536{
537 const struct pulse_io_driver_api *drv = DEVICE_API_GET(pulse_io, dev);
538
539 if (drv->get_decoder == NULL) {
540 return -ENOSYS;
541 }
542 return drv->get_decoder(dev, api);
543}
544
545#if defined(CONFIG_RTIO) || defined(__DOXYGEN__)
554static inline void pulse_io_iodev_submit(const struct device *dev, struct rtio_iodev_sqe *iodev_sqe)
555{
556 const struct pulse_io_driver_api *drv = DEVICE_API_GET(pulse_io, dev);
557
558 if (drv->submit == NULL) {
559 rtio_iodev_sqe_err(iodev_sqe, -ENOSYS);
560 return;
561 }
562 drv->submit(dev, iodev_sqe);
563}
564#endif /* CONFIG_RTIO */
565
573int pulse_io_decode_bytes(const struct pulse_io_bit_template *tmpl, uint32_t tolerance_ticks,
574 const struct pulse_symbol *in, size_t nsyms, uint8_t *out, size_t out_cap,
575 size_t *produced);
576
578
580
581#ifdef __cplusplus
582}
583#endif
584
585#include <zephyr/syscalls/pulse_io.h>
586
587#endif /* ZEPHYR_INCLUDE_DRIVERS_PULSE_IO_H_ */
APIs and macros for the Zephyr device model.
#define DEVICE_API_GET(_class, _dev)
Expands to the pointer of a device's API for a given class.
Definition device.h:1505
System error numbers.
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.
int pulse_io_channel_get(const struct device *dev, uint8_t channel_idx, struct pulse_io_channel **chan)
Reserve a channel for exclusive use.
pulse_io_dir
Direction of a configured channel.
Definition pulse_io.h:63
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_get_decoder(const struct device *dev, const struct pulse_io_decoder_api **api)
Fetch the backend decoder vtable.
int pulse_io_get_capabilities(const struct device *dev, struct pulse_io_caps *caps)
Query backend capabilities.
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_stop(const struct device *dev, struct pulse_io_channel *chan)
Stop any in-flight transmit or receive on the channel.
pulse_io_mode
Pulse stream submission modes.
Definition pulse_io.h:55
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_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.
static void pulse_io_iodev_submit(const struct device *dev, struct rtio_iodev_sqe *iodev_sqe)
Submit an RTIO request to a pulse_io device.
Definition pulse_io.h:554
int pulse_io_get_encoder(const struct device *dev, const struct pulse_io_encoder_api **api)
Fetch the backend encoder vtable.
int pulse_io_channel_release(const struct device *dev, struct pulse_io_channel *chan)
Release a channel previously obtained via pulse_io_channel_get.
@ PULSE_IO_DIR_RX
Receive (capture edges).
Definition pulse_io.h:67
@ PULSE_IO_DIR_TX
Transmit (generate edges).
Definition pulse_io.h:65
@ PULSE_IO_MODE_SYMBOL
Arbitrary {level, duration} symbol stream.
Definition pulse_io.h:57
@ PULSE_IO_MODE_CELL
Fixed-period cells with per-cell duty or level.
Definition pulse_io.h:59
static void rtio_iodev_sqe_err(struct rtio_iodev_sqe *iodev_sqe, int result)
Inform the executor of a submissions completion with error.
Definition rtio.h:738
#define BIT(n)
Unsigned integer with bit position n set (signed in assembly language).
Definition util_macro.h:44
#define ENOSYS
Function not implemented.
Definition errno.h:83
Public kernel APIs.
Real-Time IO device API for moving bytes with low effort.
__UINT32_TYPE__ uint32_t
Definition stdint.h:90
__UINT8_TYPE__ uint8_t
Definition stdint.h:88
__UINT16_TYPE__ uint16_t
Definition stdint.h:89
Runtime device structure (in ROM) per driver instance.
Definition device.h:543
Kernel timeout type.
Definition clock.h:65
One cell of a fixed-period pulse stream.
Definition pulse_io.h:96
uint16_t duty
High-time within the cell period, in ticks.
Definition pulse_io.h:98
uint16_t rsvd
Reserved; must be zero.
Definition pulse_io.h:102
uint16_t level
Line level for the cell (level-only backends).
Definition pulse_io.h:100
Per-bit template used by pulse_io_encode_bytes.
Definition pulse_io.h:443
bool msb_first
true: MSB first; false: LSB first.
Definition pulse_io.h:449
struct pulse_symbol zero[2]
Symbol pair emitted for a zero bit.
Definition pulse_io.h:445
struct pulse_symbol one[2]
Symbol pair emitted for a one bit.
Definition pulse_io.h:447
Per-instance capability descriptor.
Definition pulse_io.h:112
uint8_t num_channels
Total number of independent channels on this instance.
Definition pulse_io.h:153
uint8_t cell_duty_bits
Width of the duty field in CELL mode; 0 for level-only cells.
Definition pulse_io.h:151
bool supports_rx
Receive is supported.
Definition pulse_io.h:158
bool rx_dma_buffered
RX uses a DMA-backed ring buffer (vs.
Definition pulse_io.h:168
uint32_t tx_channel_mask
Bitmask of channels usable for TX (bit N = channel N).
Definition pulse_io.h:146
bool tx_loop_auto_stop
Hardware stops automatically at end of loop.
Definition pulse_io.h:162
uint32_t tx_loop_max
Maximum loop count for TX.
Definition pulse_io.h:134
uint32_t max_duration_ticks
Maximum duration per symbol in ticks.
Definition pulse_io.h:127
bool rx_streaming
RX supports ping-pong streaming beyond one buffer.
Definition pulse_io.h:170
uint32_t max_tick_ns
Coarsest tick with maximum prescaler, in nanoseconds.
Definition pulse_io.h:125
bool cell_period_per_chunk
Period can change between submissions in CELL mode.
Definition pulse_io.h:172
uint32_t rx_idle_threshold_max
Maximum end-of-frame idle threshold, in ticks.
Definition pulse_io.h:136
uint32_t rx_filter_max_ticks
Maximum glitch-filter width, in ticks; 0 if no filter.
Definition pulse_io.h:138
uint32_t rx_channel_mask
Bitmask of channels usable for RX (bit N = channel N).
Definition pulse_io.h:148
uint32_t min_tick_ns
Finest tick the hardware can produce, in nanoseconds.
Definition pulse_io.h:123
bool tx_sync_multi_channel
Multiple channels can start on the same clock edge.
Definition pulse_io.h:164
uint32_t modes
Bitmask of supported pulse_io_mode.
Definition pulse_io.h:121
bool supports_tx
Transmit is supported.
Definition pulse_io.h:156
bool rx_carrier_demod
Hardware carrier demodulation on RX.
Definition pulse_io.h:166
bool tx_carrier
Hardware carrier modulation on TX.
Definition pulse_io.h:160
size_t tx_min_chunk_symbols
Minimum chunk size for streaming (hardware FIFO depth).
Definition pulse_io.h:116
size_t tx_max_streaming
Maximum size of a single streaming transmit; SIZE_MAX if unbounded.
Definition pulse_io.h:118
Channel configuration.
Definition pulse_io.h:181
uint32_t resolution_hz
Tick rate in Hz.
Definition pulse_io.h:185
uint32_t cell_period_ticks
CELL mode only: cell period in ticks.
Definition pulse_io.h:187
enum pulse_io_mode mode
Submission mode for the channel.
Definition pulse_io.h:196
bool rx_carrier_demod
Enable HW carrier demodulation of the non-idle level on RX.
Definition pulse_io.h:214
bool idle_high
Line state when idle.
Definition pulse_io.h:210
uint32_t carrier_hz
TX carrier frequency in Hz.
Definition pulse_io.h:189
uint8_t carrier_duty_pct
TX carrier duty cycle in percent.
Definition pulse_io.h:201
enum pulse_io_dir dir
Channel direction.
Definition pulse_io.h:198
bool carrier_en
Enable TX carrier modulation on the non-idle level.
Definition pulse_io.h:212
uint32_t rx_idle_threshold_ticks
RX end-of-frame idle threshold in ticks; 0 to disable.
Definition pulse_io.h:191
uint32_t rx_filter_ticks
RX glitch filter width in ticks; 0 to disable.
Definition pulse_io.h:193
Decoder vtable: pulse symbols to protocol bytes.
Definition pulse_io.h:498
int(* decode)(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)
Rebuild a byte stream from captured pulse symbols.
Definition pulse_io.h:500
<span class="mlabel">Driver Operations</span> Pulse IO driver operations
Definition pulse_io.h:273
int(* stop)(const struct device *dev, struct pulse_io_channel *chan)
<span class="op-badge op-req" title="This operation MUST be implemented by the driver....
Definition pulse_io.h:297
int(* channel_release)(const struct device *dev, struct pulse_io_channel *chan)
<span class="op-badge op-req" title="This operation MUST be implemented by the driver....
Definition pulse_io.h:282
int(* 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)
<span class="op-badge op-req" title="This operation MUST be implemented by the driver....
Definition pulse_io.h:293
int(* transmit_sync)(const struct device *dev, struct pulse_io_channel *chan, const struct pulse_io_tx_req *req, k_timeout_t timeout)
<span class="op-badge op-req" title="This operation MUST be implemented by the driver....
Definition pulse_io.h:289
int(* channel_configure)(const struct device *dev, struct pulse_io_channel *chan, const struct pulse_io_config *cfg)
<span class="op-badge op-req" title="This operation MUST be implemented by the driver....
Definition pulse_io.h:285
int(* get_capabilities)(const struct device *dev, struct pulse_io_caps *caps)
<span class="op-badge op-opt" title="This operation MAY optionally be implemented by the driver....
Definition pulse_io.h:275
int(* get_encoder)(const struct device *dev, const struct pulse_io_encoder_api **api)
<span class="op-badge op-opt" title="This operation MAY optionally be implemented by the driver....
Definition pulse_io.h:302
int(* get_decoder)(const struct device *dev, const struct pulse_io_decoder_api **api)
<span class="op-badge op-opt" title="This operation MAY optionally be implemented by the driver....
Definition pulse_io.h:304
int(* channel_get)(const struct device *dev, uint8_t channel_idx, struct pulse_io_channel **chan)
<span class="op-badge op-req" title="This operation MUST be implemented by the driver....
Definition pulse_io.h:278
void(* submit)(const struct device *dev, struct rtio_iodev_sqe *iodev_sqe)
<span class="op-badge op-opt" title="This operation MAY optionally be implemented by the driver....
Definition pulse_io.h:300
Encoder vtable: protocol bytes to pulse symbols.
Definition pulse_io.h:485
int(* encode)(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.
Definition pulse_io.h:487
RX submission descriptor.
Definition pulse_io.h:253
size_t capacity
Capacity of the destination buffer in entries.
Definition pulse_io.h:262
struct pulse_symbol * symbols
SYMBOL mode destination.
Definition pulse_io.h:257
struct pulse_cell * cells
CELL mode destination.
Definition pulse_io.h:259
TX submission descriptor.
Definition pulse_io.h:236
const struct pulse_cell * cells
CELL mode source.
Definition pulse_io.h:242
const struct pulse_symbol * symbols
SYMBOL mode source.
Definition pulse_io.h:240
uint32_t loop_count
0 = single shot; 1..tx_loop_max = finite; UINT32_MAX = infinite.
Definition pulse_io.h:247
size_t count
Number of entries in the source buffer.
Definition pulse_io.h:245
One symbol of a pulse stream.
Definition pulse_io.h:79
uint32_t duration
Duration in ticks of the configured resolution.
Definition pulse_io.h:81
uint32_t level
Line level for the duration (0 or 1).
Definition pulse_io.h:83
IO device submission queue entry.
Definition sqe.h:468
Misc utilities.