hl78xx_apis.h

Go to the documentation of this file.

/*
 * Copyright (c) 2025 Netfeasa Ltd.
 *
 * SPDX-License-Identifier: Apache-2.0
 */

 
#ifndef ZEPHYR_INCLUDE_DRIVERS_HL78XX_APIS_H_
#define ZEPHYR_INCLUDE_DRIVERS_HL78XX_APIS_H_
 
#include <zephyr/types.h>
#include <zephyr/device.h>
#include <zephyr/kernel.h>
#include <errno.h>
#include <stddef.h>
#include <stdint.h>
#include <time.h>
#include <zephyr/drivers/cellular.h>
#include <zephyr/sys/util_macro.h>
#ifdef __cplusplus
extern "C" {
#endif

/* clang-format off */
#define CSQ_RSSI_UNKNOWN  (99)
#define CSQ_RSSI_MAX      (31)
#define CESQ_RSRP_UNKNOWN (255)
#define CESQ_RSRP_MAX     (97)
#define CESQ_RSRQ_UNKNOWN (255)
#define CESQ_RSRQ_MAX     (34)

#define HL78XX_MODEM_AT_ERROR     1
#define HL78XX_MODEM_AT_CME_ERROR 2
#define HL78XX_MODEM_AT_CMS_ERROR 3

#define CSQ_RSSI_TO_DB(v)  (-113 + (2 * (v)))
#define CESQ_RSRP_TO_DB(v) (-141 + (v))
#define CESQ_RSRQ_TO_DB(v) (((v) == 0U) ? -21 : (-20 + ((v) / 2)))

#define PAUSED 1
#define ACTIVE 0
#define MDM_MANUFACTURER_LENGTH        20
#define MDM_MODEL_LENGTH               32
#define MDM_REVISION_LENGTH            64
#define MDM_IMEI_LENGTH                16
#define MDM_IMSI_LENGTH                23
#define MDM_ICCID_LENGTH               22
#define MDM_APN_MAX_LENGTH             64
#define MDM_MAX_CERT_LENGTH            4096
#define MDM_MAX_HOSTNAME_LEN           128
#define MDM_SERIAL_NUMBER_LENGTH       32
#define HL78XX_CTZEU_UTIME_MAX_LEN     32
#define HL78XX_CEREG_TIMER_STR_LEN     9
#define HL78XX_NETWORK_ADDRESS_MAX_LEN 46
#define MDM_HL78XX_EOF_PATTERN         "--EOF--Pattern--"
#define MDM_HL78XX_TERMINATION_PATTERN "+++"
#define MDM_HL78XX_CONNECT_STRING      "CONNECT"
#define MDM_HL78XX_NO_CARRIER_STRING   "NO CARRIER"
#define MDM_HL78XX_CME_ERROR_STRING    "+CME ERROR: "
#define MDM_HL78XX_CMS_ERROR_STRING    "+CMS ERROR: "
#define MDM_HL78XX_ERROR_STRING        "ERROR"
#define MDM_HL78XX_OK_STRING           "OK"

#define HL78XX_MONITOR_ACTIVE false

#define HL78XX_MONITOR_PAUSED true

#define HL78XX_MONITOR_INITIAL_PAUSED(...) \
        COND_CODE_1(IS_EMPTY(__VA_ARGS__), (false), (__VA_ARGS__))
 
/* clang-format on */

#define HL78XX_EVT_MONITOR(name, _handler, ...)                                                    \
        static STRUCT_SECTION_ITERABLE(hl78xx_evt_monitor_entry, name) = {                         \
                .handler = _handler,                                                               \
                .next = NULL,                                                                      \
                .flags = {                                                                         \
                        .direct = false,                                                           \
                        .paused = HL78XX_MONITOR_INITIAL_PAUSED(__VA_ARGS__),                      \
                }}

#define HL78XX_AT_MONITOR_ANY NULL

#define HL78XX_AT_MONITOR(name, _filter, _handler, ...)                                            \
        static STRUCT_SECTION_ITERABLE(hl78xx_at_monitor_entry, name) = {                          \
                .filter = _filter,                                                                 \
                .handler = _handler,                                                               \
                .next = NULL,                                                                      \
                .flags = {                                                                         \
                        .direct = false,                                                           \
                        .paused = HL78XX_MONITOR_INITIAL_PAUSED(__VA_ARGS__),                      \
                }}

#define HL78XX_AT_MONITOR_DIRECT(name, _filter, _handler, ...)                                     \
        static STRUCT_SECTION_ITERABLE(hl78xx_at_monitor_entry, name) = {                          \
                .filter = _filter,                                                                 \
                .handler = _handler,                                                               \
                .next = NULL,                                                                      \
                .flags = {                                                                         \
                        .direct = true,                                                            \
                        .paused = HL78XX_MONITOR_INITIAL_PAUSED(__VA_ARGS__),                      \
                }}

enum hl78xx_cell_rat_mode {
        HL78XX_RAT_CAT_M1 = 0,
        HL78XX_RAT_NB1,
#ifdef CONFIG_MODEM_HL78XX_12
        HL78XX_RAT_GSM,
#ifdef CONFIG_MODEM_HL78XX_12_FW_R6
        HL78XX_RAT_NBNTN,
#endif /* CONFIG_MODEM_HL78XX_12_FW_R6 */
#endif /* CONFIG_MODEM_HL78XX_12 */
#ifdef CONFIG_MODEM_HL78XX_AUTORAT
        HL78XX_RAT_MODE_AUTO,
#endif
        HL78XX_RAT_MODE_NONE,
        HL78XX_RAT_COUNT = HL78XX_RAT_MODE_NONE
};

enum hl78xx_kselacq_rat {
        HL78XX_KSELACQ_RAT_CLEAR = 0,
        HL78XX_KSELACQ_RAT_CAT_M1 = 1,
        HL78XX_KSELACQ_RAT_NB1 = 2,
        HL78XX_KSELACQ_RAT_GSM = 3,
};

struct kselacq_syntax {
        bool mode;
        enum hl78xx_kselacq_rat rat1;
        enum hl78xx_kselacq_rat rat2;
        enum hl78xx_kselacq_rat rat3;
};

typedef bool (*hl78xx_runtime_band_provider_t)(const struct device *dev,
                                               enum hl78xx_cell_rat_mode rat, uint16_t *band,
                                               void *user_data);

enum hl78xx_phone_functionality {
        HL78XX_SIM_POWER_OFF,
        HL78XX_FULLY_FUNCTIONAL,
        HL78XX_AIRPLANE = 4,
};

enum hl78xx_sim_slot {
        HL78XX_SIM_SLOT_1 = 0,
        HL78XX_SIM_SLOT_2 = 1,
};

enum hl78xx_modem_restart_mode {
        HL78XX_MODEM_RESTART_HARD = 0,
        HL78XX_MODEM_RESTART_SOFT,
};

enum hl78xx_module_status {
        HL78XX_MODULE_READY = 0,
        HL78XX_MODULE_WAITING_FOR_ACCESS_CODE,
        HL78XX_MODULE_SIM_NOT_PRESENT,
        HL78XX_MODULE_SIMLOCK,
        HL78XX_MODULE_UNRECOVERABLE_ERROR,
        HL78XX_MODULE_UNKNOWN_STATE,
        HL78XX_MODULE_INACTIVE_SIM
};

enum hl78xx_modem_info_type {
        HL78XX_MODEM_INFO_SERIAL_NUMBER,
        HL78XX_MODEM_INFO_CURRENT_BAUD_RATE,
};

enum hl78xx_operator_format {
        HL78XX_OPERATOR_FORMAT_LONG_ALPHANUMERIC = 0,
        HL78XX_OPERATOR_FORMAT_SHORT_ALPHANUMERIC,
        HL78XX_OPERATOR_FORMAT_NUMERIC,
};

struct hl78xx_cxreg_status {
        enum cellular_registration_status reg_status;
        bool has_tac;
        uint32_t tac;
        bool has_cell_id;
        uint32_t cell_id;
        bool has_rat_mode;
        enum hl78xx_cell_rat_mode rat_mode;
        bool has_cause_type;
        int cause_type;
        bool has_reject_cause;
        int reject_cause;
        bool has_active_time;
        char active_time[HL78XX_CEREG_TIMER_STR_LEN];
        bool has_tau;
        char tau[HL78XX_CEREG_TIMER_STR_LEN];
};

enum hl78xx_network_info_type {
        HL78XX_NETWORK_INFO_APN,
        HL78XX_NETWORK_INFO_CURRENT_RAT,
        HL78XX_NETWORK_INFO_NETWORK_OPERATOR_LONG_ALPHA,
        HL78XX_NETWORK_INFO_NETWORK_OPERATOR_SHORT_ALPHA,
        HL78XX_NETWORK_INFO_NETWORK_OPERATOR_NUMERIC,
        HL78XX_NETWORK_INFO_OPERATOR_FORMAT,
        HL78XX_NETWORK_INFO_TAC,
        HL78XX_NETWORK_INFO_MCC,
        HL78XX_NETWORK_INFO_MNC,
        HL78XX_NETWORK_INFO_CELL_ID,
        HL78XX_NETWORK_INFO_IP_ADDRESS,
        HL78XX_NETWORK_INFO_DNS_PRIMARY,
        HL78XX_NETWORK_INFO_ACTIVE_BAND,
        HL78XX_NETWORK_INFO_SINR,
};

struct hl78xx_network_operator {
        bool has_operator;
        char operator_name[MDM_MODEL_LENGTH];
        bool has_mcc;
        uint16_t mcc;
        bool has_mnc;
        uint16_t mnc;
        enum hl78xx_operator_format format;
};

struct hl78xx_network_info {
        struct hl78xx_network_operator operator_info;
        char ip_address[HL78XX_NETWORK_ADDRESS_MAX_LEN];
        char dns_primary[HL78XX_NETWORK_ADDRESS_MAX_LEN];
};

enum nmea_output_port {
        NMEA_OUTPUT_NONE = 0x00,
        NMEA_OUTPUT_USB_NMEA_PORT = 0x01,
        NMEA_OUTPUT_UART1 = 0x03,
        NMEA_OUTPUT_SAME_PORT = 0x04,
        NMEA_OUTPUT_CMUX_DLC1 = 0x05,
        NMEA_OUTPUT_CMUX_DLC2 = 0x06,
        NMEA_OUTPUT_CMUX_DLC3 = 0x07,
        NMEA_OUTPUT_CMUX_DLC4 = 0x08
};
 
#if defined(CONFIG_HL78XX_GNSS_SUPPORT_ASSISTED_MODE) || defined(__DOXYGEN__)
enum hl78xx_agnss_mode {
        HL78XX_AGNSS_MODE_INVALID = 0,
        HL78XX_AGNSS_MODE_VALID = 1,
};

enum hl78xx_agnss_days {
        HL78XX_AGNSS_DAYS_1 = 1,
        HL78XX_AGNSS_DAYS_2 = 2,
        HL78XX_AGNSS_DAYS_3 = 3,
        HL78XX_AGNSS_DAYS_7 = 7,
        HL78XX_AGNSS_DAYS_14 = 14,
        HL78XX_AGNSS_DAYS_28 = 28,
};

struct hl78xx_agnss_status {
        enum hl78xx_agnss_mode mode;
        uint8_t days;
        uint8_t hours;
        uint8_t minutes;
};
#endif /* CONFIG_HL78XX_GNSS_SUPPORT_ASSISTED_MODE */
 
#ifdef CONFIG_MODEM_HL78XX_LOW_POWER_MODE
#ifdef CONFIG_MODEM_HL78XX_POWER_DOWN
enum power_down_event {
        POWER_DOWN_EVENT_ENTER = 0,
        POWER_DOWN_EVENT_EXIT,
        POWER_DOWN_EVENT_NONE,
};

enum hl78xx_power_down_response {
        HL78XX_POWER_DOWN_RESPONSE_IMMEDIATE = 0,
        HL78XX_POWER_DOWN_RESPONSE_RESCHEDULE,
};
#endif /* CONFIG_MODEM_HL78XX_POWER_DOWN */
 
#ifdef CONFIG_MODEM_HL78XX_EDRX
enum hl78xx_edrx_event {
        HL78XX_EDRX_EVENT_IDLE_EXIT = 0,
        HL78XX_EDRX_EVENT_IDLE_ENTER,
        HL78XX_EDRX_EVENT_IDLE_NONE,
};
#endif /* CONFIG_MODEM_HL78XX_EDRX */
#ifdef CONFIG_MODEM_HL78XX_PSM
enum hl78xx_psmev_event {
        HL78XX_PSM_EVENT_EXIT = 0,
        HL78XX_PSM_EVENT_ENTER,
        HL78XX_PSM_EVENT_NONE,
};
#endif /* CONFIG_MODEM_HL78XX_PSM */
#endif /* CONFIG_MODEM_HL78XX_LOW_POWER_MODE */

struct k_cellmeas_signal_info {
        int16_t rsrp;
};

struct hl78xx_network {
        enum hl78xx_cell_rat_mode technology;
        uint16_t *bands;
        uint16_t size;
};

struct hl78xx_ctzeu_update {
        int tz;
        int dst;
        bool has_utime;
        int64_t date_time_ms;
        struct tm utc_time;
};

enum hl78xx_evt_type {
        HL78XX_LTE_RAT_UPDATE,
        HL78XX_LTE_REGISTRATION_STAT_UPDATE,
        HL78XX_LTE_SIM_REGISTRATION,
        HL78XX_LTE_MODEM_STARTUP,
        HL78XX_LTE_FOTA_UPDATE_STATUS,
        HL78XX_LTE_DNS_READY,
        HL78XX_LTE_AT_CMD_READY,
        HL78XX_LTE_PHONE_FUNCTIONALITY_UPDATE,
        HL78XX_LTE_CTZEU_UPDATE,
#ifdef CONFIG_HL78XX_GNSS
        HL78XX_GNSS_ENGINE_READY,
        HL78XX_GNSS_EVENT_INIT,
        HL78XX_GNSS_EVENT_START,
        HL78XX_GNSS_EVENT_STOP,
        HL78XX_GNSS_EVENT_POSITION,
        HL78XX_GNSS_EVENT_START_BLOCKED,
        HL78XX_GNSS_EVENT_SEARCH_TIMEOUT,
        HL78XX_GNSS_EVENT_MODE_EXITED,
#endif /* CONFIG_HL78XX_GNSS */
#ifdef CONFIG_MODEM_HL78XX_LOW_POWER_MODE
#ifdef CONFIG_MODEM_HL78XX_EDRX
        HL78XX_EDRX_IDLE_UPDATE,
#endif /* CONFIG_MODEM_HL78XX_EDRX */
#ifdef CONFIG_MODEM_HL78XX_PSM
        HL78XX_LTE_PSMEV_UPDATE,
#endif /* CONFIG_MODEM_HL78XX_PSM */
#ifdef CONFIG_MODEM_HL78XX_POWER_DOWN
        HL78XX_POWER_DOWN_UPDATE,
#endif /* CONFIG_MODEM_HL78XX_POWER_DOWN */
        HL78XX_VGPIO_LOW,
        HL78XX_VGPIO_HIGH,
        HL78XX_GPIO6_LOW,
        HL78XX_GPIO6_HIGH,
#endif /* CONFIG_MODEM_HL78XX_LOW_POWER_MODE */
        HL78XX_CELLMEAS_UPDATE,
        HL78XX_EVT_TYPE_COUNT
};
#ifdef CONFIG_MODEM_HL78XX_AIRVANTAGE
enum wdsi_indication {
        WDSI_BOOTSTRAP_CREDENTIALS_PRESENT = 0,
        WDSI_USER_AGREEMENT_REQUEST = 1,
        WDSI_FIRMWARE_DOWNLOAD_REQUEST = 2,
        WDSI_FIRMWARE_INSTALL_REQUEST = 3,
        WDSI_AUTHENTICATION_START = 4,
        WDSI_AUTHENTICATION_FAILED = 5,
        WDSI_AUTHENTICATION_SUCCESS = 6,
        WDSI_CONNECTION_DENIED = 7,
        WDSI_DM_SESSION_CLOSED = 8,
        WDSI_FIRMWARE_AVAILABLE = 9,
        WDSI_FIRMWARE_DOWNLOADED = 10,
        WDSI_FIRMWARE_DOWNLOAD_ISSUE = 11,
        WDSI_PACKAGE_VERIFIED_CERTIFIED = 12,
        WDSI_PACKAGE_VERIFIED_NOT_CERTIFIED = 13,
        WDSI_FIRMWARE_UPDATE_START = 14,
        WDSI_FIRMWARE_UPDATE_FAILED = 15,
        WDSI_FIRMWARE_UPDATE_SUCCESS = 16,
        WDSI_DOWNLOAD_IN_PROGRESS = 18,
        WDSI_SESSION_STARTED = 23
};
#endif /* CONFIG_MODEM_HL78XX_AIRVANTAGE */
 
#ifdef CONFIG_HL78XX_GNSS
enum hl78xx_gnss_event_type {
        HL78XX_GNSSEV_INITIALISATION = 0,
        HL78XX_GNSSEV_START = 1,
        HL78XX_GNSSEV_STOP = 2,
        HL78XX_GNSSEV_POSITION = 3
};
enum hl78xx_event_status {
        HL78XX_STATUS_FAILED = 0,
        HL78XX_STATUS_SUCCESS = 1
};
enum gnss_position_events {
        GNSS_FIX_LOST_OR_UNAVAILABLE = 0,
        GNSS_ESTIMATED_POSITION_AVAILABLE = 1,
        GNSS_2D_POSITION_AVAILABLE = 2,
        GNSS_3D_POSITION_AVAILABLE = 3,
        GNSS_FIX_CHANGED_TO_INVALID = 4
};
#endif /* CONFIG_HL78XX_GNSS */

struct hl78xx_evt {
        enum hl78xx_evt_type type;

        union {
                enum cellular_registration_status reg_status;
                enum hl78xx_cell_rat_mode rat_mode;
#ifdef CONFIG_MODEM_HL78XX_AIRVANTAGE
                enum wdsi_indication wdsi_indication;
#endif /* CONFIG_MODEM_HL78XX_AIRVANTAGE */
#ifdef CONFIG_HL78XX_GNSS
                enum hl78xx_event_status event_status;
                enum gnss_position_events position_event;
#endif /* CONFIG_HL78XX_GNSS */
#ifdef CONFIG_MODEM_HL78XX_LOW_POWER_MODE
#ifdef CONFIG_MODEM_HL78XX_PSM
                /* PSM event */
                enum hl78xx_psmev_event psm_event;
#endif /* CONFIG_MODEM_HL78XX_PSM */
#ifdef CONFIG_MODEM_HL78XX_EDRX
                /* eDRX event */
                enum hl78xx_edrx_event edrx_event;
#endif /* CONFIG_MODEM_HL78XX_EDRX */
#ifdef CONFIG_MODEM_HL78XX_POWER_DOWN
                /* Power-down event */
                enum power_down_event power_down_event;
#endif /* CONFIG_MODEM_HL78XX_POWER_DOWN */
#endif /* CONFIG_MODEM_HL78XX_LOW_POWER_MODE */
                struct k_cellmeas_signal_info cellmeas;
                struct hl78xx_ctzeu_update ctzeu;
                bool status;
                int value;
        } content;
};

struct nmea_match_gsa_data {
        int32_t fix_type;
        int64_t pdop;
        int64_t hdop;
        int64_t vdop;
};

struct nmea_match_gst_data {
        int32_t i32;
        uint32_t gst_utc;
        int64_t rms;
        int64_t sd_major;
        int64_t sd_minor;
        int64_t orient;
        int64_t lat_err;
        int64_t lon_err;
        int64_t alt_err;
};

struct nmea_match_epu_data {
        int64_t pos_3d;
        int64_t pos_2d;
        int64_t pos_lat;
        int64_t pos_lon;
        int64_t pos_alt;
        int64_t vel_3d;
        int64_t vel_2d;
        int64_t vel_hdg;
        int64_t vel_east;
        int64_t vel_north;
        int64_t vel_up;
};

struct hl78xx_gnss_nmea_aux_data {
        struct nmea_match_gsa_data gsa;
        struct nmea_match_gst_data gst;
        struct nmea_match_epu_data epu;
};

struct modem_chat_match;

typedef void (*hl78xx_gnss_aux_data_callback_t)(const struct device *dev,
                                                const struct hl78xx_gnss_nmea_aux_data *aux_data,
                                                uint16_t size);

struct hl78xx_gnss_aux_data_callback {
        const struct device *dev;
        hl78xx_gnss_aux_data_callback_t callback;
};

#define GNSS_AUX_DATA_CALLBACK_DEFINE(_dev, _callback)                                             \
        static const STRUCT_SECTION_ITERABLE(hl78xx_gnss_aux_data_callback,                        \
                                             _hl78xx_gnss_aux_data_callback__##_callback) = {      \
                .dev = _dev,                                                                       \
                .callback = _callback,                                                             \
        }

#define GNSS_DT_AUX_DATA_CALLBACK_DEFINE(_node_id, _callback)                                      \
        static const STRUCT_SECTION_ITERABLE(hl78xx_gnss_aux_data_callback,                        \
                                             _CONCAT_4(_hl78xx_gnss_aux_data_callback_,            \
                                                       DT_DEP_ORD(_node_id), _, _callback)) = {    \
                .dev = DEVICE_DT_GET(_node_id),                                                    \
                .callback = _callback,                                                             \
        }

typedef int (*hl78xx_api_configure_networks)(const struct device *dev,
                                             const struct hl78xx_network *networks, uint8_t size);

typedef int (*hl78xx_api_get_supported_networks)(const struct device *dev,
                                                 const struct hl78xx_network **networks,
                                                 uint8_t *size);

typedef int (*hl78xx_api_get_signal)(const struct device *dev, const enum cellular_signal_type type,
                                     int16_t *value);

typedef int (*hl78xx_api_get_modem_info)(const struct device *dev,
                                         const enum cellular_modem_info_type type, char *info,
                                         size_t size);

typedef int (*hl78xx_api_get_registration_status)(const struct device *dev,
                                                  enum cellular_access_technology tech,
                                                  enum cellular_registration_status *status);

typedef int (*hl78xx_api_set_phone_functionality)(const struct device *dev,
                                                  enum hl78xx_phone_functionality functionality,
                                                  bool reset);

typedef int (*hl78xx_api_get_phone_functionality)(const struct device *dev,
                                                  enum hl78xx_phone_functionality *functionality);

typedef int (*hl78xx_api_send_at_cmd)(const struct device *dev, const char *cmd, uint16_t cmd_size,
                                      const struct modem_chat_match *response_matches,
                                      uint16_t matches_size);

struct hl78xx_at_notification {
        const char *pattern;
        const char *const *argv;
        uint16_t argc;
};

struct hl78xx_at_monitor_entry;

typedef void (*hl78xx_at_monitor_handler_t)(const struct hl78xx_at_notification *notif,
                                            struct hl78xx_at_monitor_entry *mon);

typedef void (*hl78xx_at_monitor_release_t)(struct hl78xx_at_monitor_entry *mon);

struct hl78xx_at_monitor_entry {
        const char *filter;
        const hl78xx_at_monitor_handler_t handler;
        hl78xx_at_monitor_release_t release;
        struct hl78xx_at_monitor_entry *next;
        atomic_t refcnt;
        struct k_work release_work;
        struct {
                uint8_t paused: 1;
                uint8_t direct: 1;
        } flags;
};

struct hl78xx_evt_monitor_entry;

typedef void (*hl78xx_evt_monitor_dispatcher_t)(struct hl78xx_evt *notif);

typedef void (*hl78xx_evt_monitor_handler_t)(struct hl78xx_evt *notif,
                                             struct hl78xx_evt_monitor_entry *mon);

typedef void (*hl78xx_evt_monitor_release_t)(struct hl78xx_evt_monitor_entry *mon);

struct hl78xx_evt_monitor_entry {
        const hl78xx_evt_monitor_handler_t handler;
        hl78xx_evt_monitor_release_t release;
        struct hl78xx_evt_monitor_entry *next;
        atomic_t refcnt;
        struct k_work release_work;
        struct {
                uint8_t paused: 1;
                uint8_t direct: 1;
        } flags;
};

int hl78xx_api_func_set_phone_functionality(const struct device *dev,
                                            enum hl78xx_phone_functionality functionality,
                                            bool reset);

int hl78xx_api_func_restart(const struct device *dev, enum hl78xx_modem_restart_mode mode);

int hl78xx_api_func_get_phone_functionality(const struct device *dev,
                                            enum hl78xx_phone_functionality *functionality);

int hl78xx_api_func_get_signal(const struct device *dev, const enum cellular_signal_type type,
                               int16_t *value);

int hl78xx_api_func_get_modem_info(const struct device *dev, enum hl78xx_modem_info_type type,
                                   void *info, size_t size);

int hl78xx_api_func_get_modem_info_standard(const struct device *dev,
                                            enum cellular_modem_info_type type, char *info,
                                            size_t size);

int hl78xx_api_func_get_network_info(const struct device *dev, enum hl78xx_network_info_type type,
                                     void *info, size_t size);

int hl78xx_api_func_get_rsrp_validity(const struct device *dev, bool *is_valid);

int hl78xx_api_func_get_rsrq_validity(const struct device *dev, bool *is_valid);

int hl78xx_api_func_get_sinr_validity(const struct device *dev, bool *is_valid);

int hl78xx_api_func_set_network_operator_format(const struct device *dev,
                                                enum hl78xx_operator_format format);
 
#ifdef CONFIG_MODEM_HL78XX_AUTORAT
int hl78xx_api_func_set_prl(const struct device *dev, const struct kselacq_syntax kselacq_rats);

int hl78xx_api_func_get_prl(const struct device *dev, struct kselacq_syntax *kselacq_rats);
#endif /* CONFIG_MODEM_HL78XX_AUTORAT */

int hl78xx_set_runtime_band_provider(const struct device *dev,
                                     hl78xx_runtime_band_provider_t provider, void *user_data);

int hl78xx_api_func_modem_dynamic_cmd_send(const struct device *dev, const char *cmd,
                                           uint16_t cmd_size,
                                           const struct modem_chat_match *response_matches,
                                           uint16_t matches_size);

int hl78xx_modem_at_send(const struct device *dev, const char *cmd);

int hl78xx_modem_at_cmd(const struct device *dev, char *response, size_t response_size,
                        const char *cmd);

static inline int hl78xx_get_modem_info(const struct device *dev,
                                        const enum hl78xx_modem_info_type type, void *info,
                                        size_t size)
{
        return hl78xx_api_func_get_modem_info(dev, type, info, size);
}

static inline int hl78xx_get_network_info(const struct device *dev,
                                          enum hl78xx_network_info_type type, void *info,
                                          size_t size)
{
        return hl78xx_api_func_get_network_info(dev, type, info, size);
}

static inline int hl78xx_get_rsrp_validity(const struct device *dev, bool *is_valid)
{
        return hl78xx_api_func_get_rsrp_validity(dev, is_valid);
}

static inline int hl78xx_get_rsrq_validity(const struct device *dev, bool *is_valid)
{
        return hl78xx_api_func_get_rsrq_validity(dev, is_valid);
}

static inline int hl78xx_get_sinr_validity(const struct device *dev, bool *is_valid)
{
        return hl78xx_api_func_get_sinr_validity(dev, is_valid);
}
 
#ifdef CONFIG_MODEM_HL78XX_AUTORAT
static inline int hl78xx_set_prl(const struct device *dev, struct kselacq_syntax prl)
{
        return hl78xx_api_func_set_prl(dev, prl);
}
#endif /* CONFIG_MODEM_HL78XX_AUTORAT */

static inline int hl78xx_set_phone_functionality(const struct device *dev,
                                                 enum hl78xx_phone_functionality functionality,
                                                 bool reset)
{
        return hl78xx_api_func_set_phone_functionality(dev, functionality, reset);
}

static inline int hl78xx_restart_modem(const struct device *dev,
                                       enum hl78xx_modem_restart_mode mode)
{
        return hl78xx_api_func_restart(dev, mode);
}

static inline int hl78xx_get_phone_functionality(const struct device *dev,
                                                 enum hl78xx_phone_functionality *functionality)
{
        return hl78xx_api_func_get_phone_functionality(dev, functionality);
}

static inline int hl78xx_modem_cmd_send(const struct device *dev, const char *cmd,
                                        uint16_t cmd_size,
                                        const struct modem_chat_match *response_matches,
                                        uint16_t matches_size)
{
 
        return hl78xx_api_func_modem_dynamic_cmd_send(dev, cmd, cmd_size, response_matches,
                                                      matches_size);
}

static inline int hl78xx_modem_at_err_type(int error)
{
        return (error & 0x00ff0000U) >> 16;
}

static inline int hl78xx_modem_at_err(int error)
{
        return (error & 0xff00ffffU);
}

static inline int hl78xx_parse_rssi(uint8_t rssi, int16_t *value)
{
        /* AT+CSQ returns a response +CSQ: <rssi>,<ber> where:
         * - rssi is a integer from 0 to 31 whose values describes a signal strength
         *   between -113 dBm for 0 and -51dbM for 31 or unknown for 99
         * - ber is an integer from 0 to 7 that describes the error rate, it can also
         *   be 99 for an unknown error rate
         */
        if ((rssi == CSQ_RSSI_UNKNOWN) || (rssi > CSQ_RSSI_MAX)) {
                return -EINVAL;
        }
 
        *value = (int16_t)CSQ_RSSI_TO_DB(rssi);
        return 0;
}

static inline int hl78xx_parse_rsrp(uint8_t rsrp, int16_t *value)
{
        /* AT+CESQ returns a response
         * +CESQ: <rxlev>,<ber>,<rscp>,<ecn0>,<rsrq>,<rsrp> where:
         * rsrq is a integer from 0 to 34 whose values describes the Reference
         * Signal Receive Quality between -20 dB for 0 and -3 dB for 34
         * (0.5 dB steps), or unknown for 255
         * rsrp is an integer from 0 to 97 that describes the Reference Signal
         * Receive Power between below -140 dBm for 0 and -44 dBm for 97
         * (1 dBm steps), or unknown for 255. Return a conservative lower-bound
         * integer so threshold comparisons do not treat code 0 as valid for a
         * -140 dBm minimum.
         */
        if ((rsrp == CESQ_RSRP_UNKNOWN) || (rsrp > CESQ_RSRP_MAX)) {
                return -EINVAL;
        }
 
        *value = (int16_t)CESQ_RSRP_TO_DB(rsrp);
        return 0;
}

static inline int hl78xx_parse_rsrq(uint8_t rsrq, int16_t *value)
{
        /* AT+CESQ encodes RSRQ in 0.5 dB steps. Return a conservative integer dB
         * representative so code 0 stays below a -20 dB threshold.
         */
        if ((rsrq == CESQ_RSRQ_UNKNOWN) || (rsrq > CESQ_RSRQ_MAX)) {
                return -EINVAL;
        }
 
        *value = (int16_t)CESQ_RSRQ_TO_DB(rsrq);
        return 0;
}

static inline void hl78xx_evt_monitor_pause(struct hl78xx_evt_monitor_entry *mon)
{
        mon->flags.paused = true;
}

static inline void hl78xx_evt_monitor_resume(struct hl78xx_evt_monitor_entry *mon)
{
        mon->flags.paused = false;
}

static inline void hl78xx_at_monitor_pause(struct hl78xx_at_monitor_entry *mon)
{
        mon->flags.paused = true;
}

static inline void hl78xx_at_monitor_resume(struct hl78xx_at_monitor_entry *mon)
{
        mon->flags.paused = false;
}

int hl78xx_at_monitor_register(struct hl78xx_at_monitor_entry *mon);

int hl78xx_at_monitor_unregister(struct hl78xx_at_monitor_entry *mon);

int hl78xx_evt_notif_handler_set(hl78xx_evt_monitor_dispatcher_t handler);

int hl78xx_evt_monitor_register(struct hl78xx_evt_monitor_entry *mon);

int hl78xx_evt_monitor_unregister(struct hl78xx_evt_monitor_entry *mon);

enum cellular_access_technology hl78xx_rat_to_access_tech(enum hl78xx_cell_rat_mode rat_mode);

enum hl78xx_cell_rat_mode hl78xx_access_tech_to_rat(enum cellular_access_technology access_tech);
#ifdef CONFIG_MODEM_HL78XX_AIRVANTAGE
int hl78xx_start_airvantage_dm_session(const struct device *dev);

int hl78xx_stop_airvantage_dm_session(const struct device *dev);
#endif /* CONFIG_MODEM_HL78XX_AIRVANTAGE */

int hl78xx_set_wake_pin_low(const struct device *dev);

int hl78xx_set_wake_pin_high(const struct device *dev);

int hl78xx_set_active_sim(const struct device *dev, enum hl78xx_sim_slot sim_slot);
 
#ifdef CONFIG_MODEM_HL78XX_LOW_POWER_MODE
int hl78xx_wakeup_modem(const struct device *dev);
 
#ifdef CONFIG_MODEM_HL78XX_EDRX
int hl78xx_edrx_get_time_to_sleep(const struct device *dev);
#endif /* CONFIG_MODEM_HL78XX_EDRX */
#endif /* CONFIG_MODEM_HL78XX_LOW_POWER_MODE */
 
#ifdef CONFIG_HL78XX_GNSS
int hl78xx_enter_gnss_mode(const struct device *dev);

int hl78xx_exit_gnss_mode(const struct device *dev);

int hl78xx_queue_gnss_search(const struct device *dev);

int hl78xx_gnss_set_nmea_output(const struct device *dev, enum nmea_output_port port);

int hl78xx_gnss_set_search_timeout(const struct device *dev, uint32_t timeout_ms);

int hl78xx_gnss_get_latest_known_fix(const struct device *dev);
 
#ifdef CONFIG_HL78XX_GNSS_SUPPORT_ASSISTED_MODE
int hl78xx_gnss_assist_data_get_status(const struct device *dev,
                                       struct hl78xx_agnss_status *status);

int hl78xx_gnss_assist_data_download(const struct device *dev, enum hl78xx_agnss_days days);

int hl78xx_gnss_assist_data_delete(const struct device *dev);
#endif /* CONFIG_HL78XX_GNSS_SUPPORT_ASSISTED_MODE */
 
#endif /* CONFIG_HL78XX_GNSS */
 
#ifdef CONFIG_MODEM_HL78XX_POWER_DOWN
int hl78xx_power_down_trigger(const struct device *dev, k_timeout_t delay);

int hl78xx_power_down_cancel(const struct device *dev);

int hl78xx_power_down_respond(const struct device *dev, enum hl78xx_power_down_response response,
                              uint32_t timeout_s);

void hl78xx_power_down_confirm(const struct device *dev);
#endif /* CONFIG_MODEM_HL78XX_POWER_DOWN */
 
#ifdef __cplusplus
}
#endif

 
#endif /* ZEPHYR_INCLUDE_DRIVERS_HL78XX_APIS_H_ */