Define device instances that use the cellular modem driver. More...

Data Structures
struct	modem_cellular_board_init
	Descriptor binding a board-supplied init script to a modem instance. More...

Macros
#define	MODEM_CELLULAR_INST_NAME(name, inst)
	Generate a unique C identifier for a modem instance object.
#define	MODEM_CELLULAR_DEFINE_AND_INIT_USER_PIPES(inst, ...)
	Define additional CMUX user pipes for a modem instance.
#define	MODEM_CELLULAR_COMMON_CHAT_MATCHES()
	Define common chat matches used by cellular modem scripts.
#define	MODEM_CELLULAR_COMMON_UNSOL_MATCHES
	Expand to the common unsolicited response matches.
#define	MODEM_CELLULAR_DEFINE_INSTANCE(inst, vendor_config)
	Define a cellular modem device instance.
#define	MODEM_CELLULAR_BOARD_INIT_DEFINE(node_id, _script)
	Register a board-specific init script for a modem instance.

Detailed Description

Define device instances that use the cellular modem driver.

See the cellular modem documentation for a complete out-of-tree driver example.

Macro Definition Documentation

◆ MODEM_CELLULAR_BOARD_INIT_DEFINE

#define MODEM_CELLULAR_BOARD_INIT_DEFINE	(		node_id,
			_script )

#include <zephyr/drivers/modem/modem_cellular.h>

Register a board-specific init script for a modem instance.

The script runs over the AT control channel after CMUX is established and before APN and network configuration. The driver supplies the completion callback that advances the connect sequence, so the script's own callback is unused.

Parameters

node_id	Devicetree node identifier of the modem instance.
_script	Pointer to a modem_chat_script defined with MODEM_CHAT_SCRIPT_DEFINE.

◆ MODEM_CELLULAR_COMMON_CHAT_MATCHES

#define MODEM_CELLULAR_COMMON_CHAT_MATCHES ( )

#include <zephyr/drivers/modem/modem_cellular.h>

Value:

MODEM_CHAT_MATCH_DEFINE(ok_match, "OK", "", NULL);                                         \
MODEM_CHAT_MATCHES_DEFINE(__maybe_unused allow_match,                                      \
                          MODEM_CHAT_MATCH("OK", "", NULL),                                \
                          MODEM_CHAT_MATCH("ERROR", "", NULL));                            \
MODEM_CHAT_MATCH_DEFINE(imei_match __maybe_unused,                                         \
                        "", "", modem_cellular_chat_on_imei);                              \
MODEM_CHAT_MATCH_DEFINE(cgmm_match __maybe_unused,                                         \
                        "", "", modem_cellular_chat_on_cgmm);                              \
MODEM_CHAT_MATCH_DEFINE(csq_match __maybe_unused,                                          \
                        "+CSQ: ", ",", modem_cellular_chat_on_csq);                        \
MODEM_CHAT_MATCH_DEFINE(cesq_match __maybe_unused,                                         \
                        "+CESQ: ", ",", modem_cellular_chat_on_cesq);                      \
MODEM_CHAT_MATCH_DEFINE(qccid_match __maybe_unused,                                        \
                        "+QCCID: ", "", modem_cellular_chat_on_iccid);                     \
MODEM_CHAT_MATCH_DEFINE(iccid_match __maybe_unused,                                        \
                        "+ICCID: ", "", modem_cellular_chat_on_iccid);                     \
MODEM_CHAT_MATCH_DEFINE(ccid_match __maybe_unused,                                         \
                        "+CCID: ", "", modem_cellular_chat_on_iccid);                      \
MODEM_CHAT_MATCH_DEFINE(cimi_match __maybe_unused,                                         \
                        "", "", modem_cellular_chat_on_imsi);                              \
MODEM_CHAT_MATCH_DEFINE(cgmi_match __maybe_unused,                                         \
                        "", "", modem_cellular_chat_on_cgmi);                              \
MODEM_CHAT_MATCH_DEFINE(cgmr_match __maybe_unused,                                         \
                        "", "", modem_cellular_chat_on_cgmr);                              \
MODEM_CHAT_MATCH_DEFINE(connect_match __maybe_unused,                                      \
                        "CONNECT", "", NULL);                                              \
MODEM_CHAT_MATCHES_DEFINE(__maybe_unused abort_matches,                                    \
                          MODEM_CHAT_MATCH("ERROR", "", NULL));                            \
MODEM_CHAT_MATCHES_DEFINE(__maybe_unused dial_abort_matches,                               \
                          MODEM_CHAT_MATCH("ERROR", "", NULL),                             \
                          MODEM_CHAT_MATCH("BUSY", "", NULL),                              \
                          MODEM_CHAT_MATCH("NO ANSWER", "", NULL),                         \
                          MODEM_CHAT_MATCH("NO CARRIER", "", NULL),                        \
                          MODEM_CHAT_MATCH("NO DIALTONE", "", NULL))

Define common chat matches used by cellular modem scripts.

Invoke this macro once at file scope. It defines matches for successful commands, common command failures, modem identity and signal queries, and PPP dial responses. The generated identifiers are intended for use in the modem's modem_cellular_config_scripts.

◆ MODEM_CELLULAR_COMMON_UNSOL_MATCHES

#define MODEM_CELLULAR_COMMON_UNSOL_MATCHES

#include <zephyr/drivers/modem/modem_cellular.h>

Value:

MODEM_CHAT_MATCH("+CREG: ", ",", modem_cellular_chat_on_cxreg),                            \
MODEM_CHAT_MATCH("+CEREG: ", ",", modem_cellular_chat_on_cxreg),                           \
MODEM_CHAT_MATCH("+CGREG: ", ",", modem_cellular_chat_on_cxreg),                           \
MODEM_CHAT_MATCH("+CGEV: ", ",", modem_cellular_chat_on_cgev),                             \
MODEM_CHAT_MATCH("APP RDY", "", modem_cellular_chat_on_modem_ready),                       \
MODEM_CHAT_MATCH("Ready", "", modem_cellular_chat_on_modem_ready)

Expand to the common unsolicited response matches.

Use this macro in the entry list passed to MODEM_CHAT_MATCHES_DEFINE(). Vendor drivers may add additional entries after this expansion.

◆ MODEM_CELLULAR_DEFINE_AND_INIT_USER_PIPES

#define MODEM_CELLULAR_DEFINE_AND_INIT_USER_PIPES	(		inst,
			... )

#include <zephyr/drivers/modem/modem_cellular.h>

Value:

FOR_EACH_FIXED_ARG(MODEM_CELLULAR_DEFINE_USER_PIPE_DATA_HELPER,                            \
                   (;), inst, __VA_ARGS__);                                                \
MODEM_CELLULAR_DEFINE_USER_PIPES(                                                          \
        inst,                                                                              \
        FOR_EACH_FIXED_ARG(MODEM_CELLULAR_INIT_USER_PIPE_HELPER,                           \
                           (,), inst, __VA_ARGS__)                                         \
);

Define additional CMUX user pipes for a modem instance.

Each variadic argument is a parenthesized (name, dlci_address) pair. The macro defines the receive buffers, pipe links, and user-pipe array consumed by MODEM_CELLULAR_DEFINE_INSTANCE. Invoke it once for each modem instance before invoking MODEM_CELLULAR_DEFINE_INSTANCE.

Parameters

inst	Devicetree instance number.
...	One or more (name, dlci_address) pairs.

◆ MODEM_CELLULAR_DEFINE_INSTANCE

#define MODEM_CELLULAR_DEFINE_INSTANCE	(		inst,
			vendor_config )

#include <zephyr/drivers/modem/modem_cellular.h>

Value:

BUILD_ASSERT(vendor_config != NULL, "vendor_config must be non-NULL");                     \
static const struct modem_cellular_config MODEM_CELLULAR_INST_NAME(config, inst) = {       \
        .uart = DEVICE_DT_GET(DT_INST_BUS(inst)),                                          \
        .vendor = vendor_config,                                                           \
        .power_gpio = GPIO_DT_SPEC_INST_GET_OR(inst, mdm_power_gpios, {}),                 \
        .reset_gpio = GPIO_DT_SPEC_INST_GET_OR(inst, mdm_reset_gpios, {}),                 \
        .wake_gpio = GPIO_DT_SPEC_INST_GET_OR(inst, mdm_wake_gpios, {}),                   \
        .ring_gpio = GPIO_DT_SPEC_INST_GET_OR(inst, mdm_ring_gpios, {}),                   \
        .dtr_gpio = GPIO_DT_SPEC_INST_GET_OR(inst, mdm_dtr_gpios, {}),                     \
        .autostarts = DT_INST_PROP(inst, autostarts),                                      \
        .hold_reset_on_suspend =                                                           \
                DT_INST_ENUM_HAS_VALUE(inst, zephyr_mdm_reset_behavior, hold_on_suspend),  \
        .reset_on_resume = DT_INST_ENUM_HAS_VALUE(inst, zephyr_mdm_reset_behavior,         \
                                                    toggle_on_resume),                     \
        .reset_on_recovery = DT_INST_ENUM_HAS_VALUE(inst, zephyr_mdm_reset_behavior,       \
                                                    toggle_on_recovery),                   \
        .cmux_enable_runtime_power_save =                                                  \
                DT_INST_PROP_OR(inst, cmux_enable_runtime_power_save, 0),                  \
        .cmux_close_pipe_on_power_save =                                                   \
                DT_INST_PROP_OR(inst, cmux_close_pipe_on_power_save, 0),                   \
        .cmux_no_powersave_handshake =                                                     \
                DT_INST_PROP_OR(inst, cmux_no_powersave_handshake, 0),                     \
        .use_default_pdp_context = DT_INST_PROP_OR(inst, zephyr_use_default_pdp_ctx, 0),   \
        .use_default_apn = DT_INST_PROP_OR(inst, zephyr_use_default_apn, 0),               \
        .cmux_idle_timeout = K_MSEC(DT_INST_PROP_OR(inst, cmux_idle_timeout_ms, 0)),       \
        .user_pipes = MODEM_CELLULAR_GET_USER_PIPES(inst),                                 \
        .user_pipes_size = ARRAY_SIZE(MODEM_CELLULAR_GET_USER_PIPES(inst)),                \
};                                                                                         \
                                                                                           \
PM_DEVICE_DT_INST_DEFINE(inst, modem_cellular_pm_action);                                  \
                                                                                           \
DEVICE_DT_INST_DEFINE(inst, modem_cellular_init, PM_DEVICE_DT_INST_GET(inst),              \
                      &MODEM_CELLULAR_INST_NAME(data, inst),                               \
                      &MODEM_CELLULAR_INST_NAME(config, inst), POST_KERNEL,                \
                      CONFIG_MODEM_CELLULAR_INIT_PRIORITY, &modem_cellular_api);

Define a cellular modem device instance.

This macro creates the immutable device configuration, power-management object, and Zephyr device for a devicetree instance. Before invoking it, define the instance's PPP object, initialize a modem_cellular_data object, and invoke MODEM_CELLULAR_DEFINE_AND_INIT_USER_PIPES().

Parameters

inst	Devicetree instance number.
vendor_config	Pointer to a constant modem_cellular_vendor_config object. Must not be NULL and must remain valid for the lifetime of the device.

◆ MODEM_CELLULAR_INST_NAME

#define MODEM_CELLULAR_INST_NAME	(		name,
			inst )

#include <zephyr/drivers/modem/modem_cellular.h>

Value:

CONCAT(name, _, DT_DRV_COMPAT, inst)

CONCAT

#define CONCAT(...)

Concatenate input arguments.

Definition util.h:308

Generate a unique C identifier for a modem instance object.

Parameters

name	Base object name.
inst	Devicetree instance number.

Returns: The generated C identifier.

Data Structures

Macros

Detailed Description

Macro Definition Documentation

◆ MODEM_CELLULAR_BOARD_INIT_DEFINE

◆ MODEM_CELLULAR_COMMON_CHAT_MATCHES

◆ MODEM_CELLULAR_COMMON_UNSOL_MATCHES

◆ MODEM_CELLULAR_DEFINE_AND_INIT_USER_PIPES

◆ MODEM_CELLULAR_DEFINE_INSTANCE

◆ MODEM_CELLULAR_INST_NAME