cmux.h

Go to the documentation of this file.

/*
 * Copyright (c) 2022 Trackunit Corporation
 *
 * SPDX-License-Identifier: Apache-2.0
 */
 
/*
 * This library uses CMUX to create multiple data channels, called DLCIs, on a single serial bus.
 * Each DLCI has an address from 1 to 63. DLCI address 0 is reserved for control commands.
 *
 * Design overview:
 *
 *     DLCI1 <-----------+                              +-------> DLCI1
 *                       v                              v
 *     DLCI2 <---> CMUX instance <--> Serial bus <--> Client <--> DLCI2
 *                       ^                              ^
 *     DLCI3 <-----------+                              +-------> DLCI3
 *
 * Writing to and from the CMUX instances is done using the modem_pipe API.
 */
 
#include <zephyr/kernel.h>
#include <zephyr/types.h>
#include <zephyr/sys/ring_buffer.h>
#include <zephyr/sys/atomic.h>
#include <zephyr/sys/util.h>
 
#include <zephyr/modem/pipe.h>
#include <zephyr/modem/stats.h>
 
#ifndef ZEPHYR_INCLUDE_MODEM_CMUX_H_
#define ZEPHYR_INCLUDE_MODEM_CMUX_H_
 
#ifdef __cplusplus
extern "C" {
#endif

 
struct modem_cmux;
 
enum modem_cmux_event {
        MODEM_CMUX_EVENT_CONNECTED = 0,
        MODEM_CMUX_EVENT_DISCONNECTED,
};
 
typedef void (*modem_cmux_callback)(struct modem_cmux *cmux, enum modem_cmux_event event,
                                    void *user_data);

struct modem_cmux_config {
        modem_cmux_callback callback;
        void *user_data;
        uint8_t *receive_buf;
        uint16_t receive_buf_size;
        uint8_t *transmit_buf;
        uint16_t transmit_buf_size;
        bool enable_runtime_power_management;
        bool close_pipe_on_power_save;
        bool no_powersave_handshake;
        k_timeout_t idle_timeout;
};

 
#if CONFIG_MODEM_CMUX_MTU > 127
#define MODEM_CMUX_HEADER_SIZE                  7
#else
#define MODEM_CMUX_HEADER_SIZE                  6
#endif
 
/* Minimum required size for CMUX RX buffers */
#define MODEM_CMUX_RX_BUFFER_SIZE_MIN           126
 
/* Total size of the CMUX work buffers from the MTU */
#define MODEM_CMUX_WORK_BUFFER_FROM_MTU (CONFIG_MODEM_CMUX_MTU + MODEM_CMUX_HEADER_SIZE + \
                                         CONFIG_MODEM_CMUX_WORK_BUFFER_SIZE_EXTRA)
 
/* Enforce the minimum size required by CMUX */
#define MODEM_CMUX_WORK_BUFFER_SIZE MAX(MODEM_CMUX_WORK_BUFFER_FROM_MTU, \
                                        MODEM_CMUX_RX_BUFFER_SIZE_MIN)
 
enum modem_cmux_state {
        MODEM_CMUX_STATE_DISCONNECTED = 0,
        MODEM_CMUX_STATE_CONNECTING,
        MODEM_CMUX_STATE_CONNECTED,
        MODEM_CMUX_STATE_ENTER_POWERSAVE,
        MODEM_CMUX_STATE_POWERSAVE,
        MODEM_CMUX_STATE_CONFIRM_POWERSAVE,
        MODEM_CMUX_STATE_WAKEUP,
        MODEM_CMUX_STATE_DISCONNECTING,
};
 
enum modem_cmux_receive_state {
        MODEM_CMUX_RECEIVE_STATE_SOF = 0,
        MODEM_CMUX_RECEIVE_STATE_RESYNC,
        MODEM_CMUX_RECEIVE_STATE_ADDRESS,
        MODEM_CMUX_RECEIVE_STATE_ADDRESS_CONT,
        MODEM_CMUX_RECEIVE_STATE_CONTROL,
        MODEM_CMUX_RECEIVE_STATE_LENGTH,
        MODEM_CMUX_RECEIVE_STATE_LENGTH_CONT,
        MODEM_CMUX_RECEIVE_STATE_DATA,
        MODEM_CMUX_RECEIVE_STATE_DATA_CONT,
        MODEM_CMUX_RECEIVE_STATE_FCS,
        MODEM_CMUX_RECEIVE_STATE_EOF,
};
 
enum modem_cmux_dlci_state {
        MODEM_CMUX_DLCI_STATE_CLOSED,
        MODEM_CMUX_DLCI_STATE_OPENING,
        MODEM_CMUX_DLCI_STATE_OPEN,
        MODEM_CMUX_DLCI_STATE_CLOSING,
};
 
struct modem_cmux_dlci {
        sys_snode_t node;
 
        /* Pipe */
        struct modem_pipe pipe;
 
        /* Context */
        uint16_t dlci_address;
        struct modem_cmux *cmux;
 
        /* Receive buffer */
        struct ring_buf receive_rb;
        struct k_mutex receive_rb_lock;
 
        /* Work */
        struct k_work_delayable open_work;
        struct k_work_delayable close_work;
 
        /* State */
        enum modem_cmux_dlci_state state;
 
        /* Statistics */
#if CONFIG_MODEM_STATS
        struct modem_stats_buffer receive_buf_stats;
#endif
        /* Flow control */
        bool flow_control : 1;
        bool rx_full : 1;
        bool msc_sent : 1;
};
 
struct modem_cmux_frame {
        uint8_t dlci_address;
        bool cr;
        bool pf;
        uint8_t type;
        const uint8_t *data;
        const uint8_t *tx_extra;
        uint16_t data_len;
        uint16_t tx_extra_len;
};
 
struct modem_cmux_work {
        struct k_work_delayable dwork;
        struct modem_cmux *cmux;
};
 
struct modem_cmux {
        /* Bus pipe */
        struct modem_pipe *pipe;
 
        /* DLCI channel contexts */
        sys_slist_t dlcis;
 
        /* State */
        enum modem_cmux_state state;
        uint8_t retry_count;
        bool flow_control_on : 1;
        bool initiator : 1;
 
        /* Work lock */
        bool attached : 1;
        struct k_spinlock work_lock;
 
        /* Receive state*/
        enum modem_cmux_receive_state receive_state;
        int receive_buf_len;
 
        /* Transmit buffer */
        struct ring_buf transmit_rb;
        struct k_mutex transmit_rb_lock;
 
        /* Received frame */
        struct modem_cmux_frame frame;
        int frame_start;
        uint16_t frame_header_len;
 
        /* Work */
        struct k_work_delayable receive_work;
        struct k_work_delayable transmit_work;
        struct k_work_delayable connect_work;
        struct k_work_delayable disconnect_work;
        struct k_work_delayable runtime_pm_work;
 
        /* Synchronize actions */
        struct k_event event;
        k_timepoint_t t3_timepoint;
        k_timepoint_t idle_timepoint;
 
        /* Statistics */
#if CONFIG_MODEM_STATS
        struct modem_stats_buffer receive_buf_stats;
        struct modem_stats_buffer transmit_buf_stats;
#endif
        struct modem_cmux_config config;
};


void modem_cmux_init(struct modem_cmux *cmux, const struct modem_cmux_config *config);

struct modem_cmux_dlci_config {
        uint8_t dlci_address;
        uint8_t *receive_buf;
        uint16_t receive_buf_size;
};

struct modem_pipe *modem_cmux_dlci_init(struct modem_cmux *cmux, struct modem_cmux_dlci *dlci,
                                        const struct modem_cmux_dlci_config *config);

int modem_cmux_attach(struct modem_cmux *cmux, struct modem_pipe *pipe);

int modem_cmux_connect(struct modem_cmux *cmux);

int modem_cmux_connect_async(struct modem_cmux *cmux);

int modem_cmux_disconnect(struct modem_cmux *cmux);

int modem_cmux_disconnect_async(struct modem_cmux *cmux);

void modem_cmux_release(struct modem_cmux *cmux);

 
#ifdef __cplusplus
}
#endif
 
#endif /* ZEPHYR_INCLUDE_MODEM_CMUX_H_ */