pulse_io.h

Go to the documentation of this file.

/*
 * Copyright (c) 2026 Espressif Systems (Shanghai) Co., Ltd.
 *
 * SPDX-License-Identifier: Apache-2.0
 */
 
#ifndef ZEPHYR_INCLUDE_DRIVERS_PULSE_IO_H_
#define ZEPHYR_INCLUDE_DRIVERS_PULSE_IO_H_

 
#include <errno.h>
#include <stddef.h>
#include <stdbool.h>
#include <stdint.h>
 
#include <zephyr/device.h>
#include <zephyr/kernel.h>
#include <zephyr/rtio/rtio.h>
#include <zephyr/sys/util.h>
 
#ifdef __cplusplus
extern "C" {
#endif


enum pulse_io_mode {
        PULSE_IO_MODE_SYMBOL = BIT(0),
        PULSE_IO_MODE_CELL = BIT(1),
};

enum pulse_io_dir {
        PULSE_IO_DIR_TX,
        PULSE_IO_DIR_RX,
};

struct pulse_symbol {
        uint32_t duration: 31;
        uint32_t level: 1;
};

struct pulse_cell {
        uint16_t duty;
        uint16_t level: 1;
        uint16_t rsvd: 15;
};

struct pulse_io_caps {
        /* Fields are ordered widest-first to pack without padding holes. */

        size_t tx_min_chunk_symbols;
        size_t tx_max_streaming;

        uint32_t modes;
        uint32_t min_tick_ns;
        uint32_t max_tick_ns;
        uint32_t max_duration_ticks;
        uint32_t tx_loop_max;
        uint32_t rx_idle_threshold_max;
        uint32_t rx_filter_max_ticks;

        uint32_t tx_channel_mask;
        uint32_t rx_channel_mask;

        uint8_t cell_duty_bits;
        uint8_t num_channels;

        bool supports_tx;
        bool supports_rx;
        bool tx_carrier;
        bool tx_loop_auto_stop;
        bool tx_sync_multi_channel;
        bool rx_carrier_demod;
        bool rx_dma_buffered;
        bool rx_streaming;
        bool cell_period_per_chunk;
};

struct pulse_io_config {
        /* Fields are ordered widest-first to pack without padding holes. */

        uint32_t resolution_hz;
        uint32_t cell_period_ticks;
        uint32_t carrier_hz;
        uint32_t rx_idle_threshold_ticks;
        uint32_t rx_filter_ticks;

        enum pulse_io_mode mode;
        enum pulse_io_dir dir;

        uint8_t carrier_duty_pct;

        bool idle_high;
        bool carrier_en;
        bool rx_carrier_demod;
};

struct pulse_io_channel;
 
/* Forward declarations for the RTIO codec vtables (defined below). */
struct pulse_io_encoder_api;
struct pulse_io_decoder_api;

struct pulse_io_tx_req {
        union {
                const struct pulse_symbol *symbols;
                const struct pulse_cell *cells;
        };
        size_t count;
        uint32_t loop_count;
};

struct pulse_io_rx_req {
        union {
                struct pulse_symbol *symbols;
                struct pulse_cell *cells;
        };
        size_t capacity;
};

__subsystem struct pulse_io_driver_api {
        int (*get_capabilities)(const struct device *dev, struct pulse_io_caps *caps);

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

        int (*channel_release)(const struct device *dev, struct pulse_io_channel *chan);

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

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

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

        int (*stop)(const struct device *dev, struct pulse_io_channel *chan);

        void (*submit)(const struct device *dev, struct rtio_iodev_sqe *iodev_sqe);
        int (*get_encoder)(const struct device *dev, const struct pulse_io_encoder_api **api);
        int (*get_decoder)(const struct device *dev, const struct pulse_io_decoder_api **api);
};

__syscall int pulse_io_get_capabilities(const struct device *dev, struct pulse_io_caps *caps);
 
static inline int z_impl_pulse_io_get_capabilities(const struct device *dev,
                                                   struct pulse_io_caps *caps)
{
        const struct pulse_io_driver_api *api = DEVICE_API_GET(pulse_io, dev);
 
        if (api->get_capabilities == NULL) {
                return -ENOSYS;
        }
        return api->get_capabilities(dev, caps);
}

__syscall int pulse_io_channel_get(const struct device *dev, uint8_t channel_idx,
                                   struct pulse_io_channel **chan);
 
static inline int z_impl_pulse_io_channel_get(const struct device *dev, uint8_t channel_idx,
                                              struct pulse_io_channel **chan)
{
        return DEVICE_API_GET(pulse_io, dev)->channel_get(dev, channel_idx, chan);
}

__syscall int pulse_io_channel_release(const struct device *dev, struct pulse_io_channel *chan);
 
static inline int z_impl_pulse_io_channel_release(const struct device *dev,
                                                  struct pulse_io_channel *chan)
{
        return DEVICE_API_GET(pulse_io, dev)->channel_release(dev, chan);
}

__syscall int pulse_io_channel_configure(const struct device *dev, struct pulse_io_channel *chan,
                                         const struct pulse_io_config *cfg);
 
static inline int z_impl_pulse_io_channel_configure(const struct device *dev,
                                                    struct pulse_io_channel *chan,
                                                    const struct pulse_io_config *cfg)
{
        return DEVICE_API_GET(pulse_io, dev)->channel_configure(dev, chan, cfg);
}

__syscall 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);
 
static inline int z_impl_pulse_io_transmit_sync(const struct device *dev,
                                                struct pulse_io_channel *chan,
                                                const struct pulse_io_tx_req *req,
                                                k_timeout_t timeout)
{
        return DEVICE_API_GET(pulse_io, dev)->transmit_sync(dev, chan, req, timeout);
}

__syscall 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);
 
static inline int z_impl_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)
{
        return DEVICE_API_GET(pulse_io, dev)->receive_sync(dev, chan, req, count, timeout);
}

__syscall int pulse_io_stop(const struct device *dev, struct pulse_io_channel *chan);
 
static inline int z_impl_pulse_io_stop(const struct device *dev, struct pulse_io_channel *chan)
{
        return DEVICE_API_GET(pulse_io, dev)->stop(dev, chan);
}


struct pulse_io_bit_template {
        struct pulse_symbol zero[2];
        struct pulse_symbol one[2];
        bool msb_first;
};

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



struct pulse_io_encoder_api {
        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);
};

struct pulse_io_decoder_api {
        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);
};

__syscall int pulse_io_get_encoder(const struct device *dev,
                                   const struct pulse_io_encoder_api **api);
 
static inline int z_impl_pulse_io_get_encoder(const struct device *dev,
                                              const struct pulse_io_encoder_api **api)
{
        const struct pulse_io_driver_api *drv = DEVICE_API_GET(pulse_io, dev);
 
        if (drv->get_encoder == NULL) {
                return -ENOSYS;
        }
        return drv->get_encoder(dev, api);
}

__syscall int pulse_io_get_decoder(const struct device *dev,
                                   const struct pulse_io_decoder_api **api);
 
static inline int z_impl_pulse_io_get_decoder(const struct device *dev,
                                              const struct pulse_io_decoder_api **api)
{
        const struct pulse_io_driver_api *drv = DEVICE_API_GET(pulse_io, dev);
 
        if (drv->get_decoder == NULL) {
                return -ENOSYS;
        }
        return drv->get_decoder(dev, api);
}
 
#ifdef CONFIG_RTIO
static inline void pulse_io_iodev_submit(const struct device *dev, struct rtio_iodev_sqe *iodev_sqe)
{
        const struct pulse_io_driver_api *drv = DEVICE_API_GET(pulse_io, dev);
 
        if (drv->submit == NULL) {
                rtio_iodev_sqe_err(iodev_sqe, -ENOSYS);
                return;
        }
        drv->submit(dev, iodev_sqe);
}
#endif /* CONFIG_RTIO */

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


 
#ifdef __cplusplus
}
#endif
 
#include <zephyr/syscalls/pulse_io.h>
 
#endif /* ZEPHYR_INCLUDE_DRIVERS_PULSE_IO_H_ */