can_corex.h

Go to the documentation of this file.

/*
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/.
 *
 * Author: Adrian Pietrzak
 * GitHub: https://github.com/AdrianPietrzak1998
 * Created: Aug 20, 2025
 */
 
#ifndef CAN_COREX_CAN_COREX_H_
#define CAN_COREX_CAN_COREX_H_
 
#include <limits.h>
#include <stdint.h>
 
#ifdef __cplusplus
extern "C"
{
#endif
 
#define CCX_VERSION_MAJOR 2
#define CCX_VERSION_MINOR 3
#define CCX_VERSION_PATCH 1
#define CCX_VERSION_STRING "2.3.1"


#ifndef CCX_TICK_FROM_FUNC
#define CCX_TICK_FROM_FUNC 0
#endif

#ifndef CCX_HR_TICK_FROM_FUNC
#define CCX_HR_TICK_FROM_FUNC 0
#endif

#ifndef CCX_RX_BUFFER_SIZE
#define CCX_RX_BUFFER_SIZE 48
#endif

#ifndef CCX_TX_BUFFER_SIZE
#define CCX_TX_BUFFER_SIZE 48
#endif

#if defined(DOXYGEN)
#define CCX_ENABLE_CANFD 1
#elif !defined(CCX_ENABLE_CANFD)
#define CCX_ENABLE_CANFD 0
#endif

#if CCX_ENABLE_CANFD
#define CCX_DLC_ANY 16
#else
#define CCX_DLC_ANY 15
#endif

#ifndef CCX_RX_HASH_SIZE
#define CCX_RX_HASH_SIZE 64
#endif
 
    /* ============================================================
     * Time base type configuration
     *
     * Primary time base:
     *   - used by core CAN RX/TX logic
     *   - expressed by CCX_TIME_t / CCX_MAX_TIMEOUT
     *   - public unit is always milliseconds
     *
     * High-resolution time base:
     *   - used by HR-aware modules such as ISO-TP and bus monitor
     *   - expressed by CCX_HR_TIME_t / CCX_HR_MAX_TIMEOUT
     *   - public unit is microseconds when HR is enabled
     *   - public unit falls back to milliseconds when HR is disabled
     *
     * Configuration is width-based and unsigned only.
     * Signed tick types are intentionally not supported because the library relies
     * on wraparound subtraction for timeout arithmetic.
     *
     * If no custom width macro is defined, uint32_t is used by default.
     * ============================================================ */
 
#ifdef CCX_TIME_BASE_TYPE_CUSTOM
#error                                                                                                                 \
    "CCX_TIME_BASE_TYPE_CUSTOM is no longer supported. Define exactly one of CCX_TIME_BASE_TYPE_CUSTOM_IS_UINT8/16/32/64."
#endif
 
#ifdef CCX_HR_TIME_BASE_TYPE_CUSTOM
#error                                                                                                                 \
    "CCX_HR_TIME_BASE_TYPE_CUSTOM is no longer supported. Define exactly one of CCX_HR_TIME_BASE_TYPE_CUSTOM_IS_UINT8/16/32/64."
#endif
 
#if defined(CCX_TIME_BASE_TYPE_CUSTOM_IS_INT8) || defined(CCX_TIME_BASE_TYPE_CUSTOM_IS_INT16) ||                       \
    defined(CCX_TIME_BASE_TYPE_CUSTOM_IS_INT32) || defined(CCX_TIME_BASE_TYPE_CUSTOM_IS_INT64)
#error                                                                                                                 \
    "Signed primary time base types were a bug and must not be used. Use exactly one of CCX_TIME_BASE_TYPE_CUSTOM_IS_UINT16/32/64."
#endif
 
#if defined(CCX_HR_TIME_BASE_TYPE_CUSTOM_IS_INT8) || defined(CCX_HR_TIME_BASE_TYPE_CUSTOM_IS_INT16) ||                 \
    defined(CCX_HR_TIME_BASE_TYPE_CUSTOM_IS_INT32) || defined(CCX_HR_TIME_BASE_TYPE_CUSTOM_IS_INT64)
#error                                                                                                                 \
    "Signed high-resolution time base types were a bug and must not be used. Use exactly one of CCX_HR_TIME_BASE_TYPE_CUSTOM_IS_UINT16/32/64."
#endif
 
#if defined(CCX_TIME_BASE_TYPE_CUSTOM_IS_UINT8)
#error                                                                                                                 \
    "CCX_TIME_BASE_TYPE_CUSTOM_IS_UINT8 is not supported because uint8_t has too small a range for this library. Use exactly one of CCX_TIME_BASE_TYPE_CUSTOM_IS_UINT16/32/64."
    typedef volatile uint16_t CCX_TIME_t;
#define CCX_TIME_BASE_SCALAR uint16_t
#define CCX_MAX_TIMEOUT UINT16_MAX
#elif defined(CCX_TIME_BASE_TYPE_CUSTOM_IS_UINT16)
typedef volatile uint16_t CCX_TIME_t;
#define CCX_TIME_BASE_SCALAR uint16_t
#define CCX_MAX_TIMEOUT UINT16_MAX
#elif defined(CCX_TIME_BASE_TYPE_CUSTOM_IS_UINT32)
typedef volatile uint32_t CCX_TIME_t;
#define CCX_TIME_BASE_SCALAR uint32_t
#define CCX_MAX_TIMEOUT UINT32_MAX
#elif defined(CCX_TIME_BASE_TYPE_CUSTOM_IS_UINT64)
typedef volatile uint64_t CCX_TIME_t;
#define CCX_TIME_BASE_SCALAR uint64_t
#define CCX_MAX_TIMEOUT UINT64_MAX
#else
typedef volatile uint32_t CCX_TIME_t;
#define CCX_TIME_BASE_SCALAR uint32_t
#define CCX_MAX_TIMEOUT UINT32_MAX
#endif
 
#ifndef CCX_DISABLE_HIGH_RES_TIMEBASE
 
#if defined(CCX_HR_TIME_BASE_TYPE_CUSTOM_IS_UINT8)
#error                                                                                                                 \
    "CCX_HR_TIME_BASE_TYPE_CUSTOM_IS_UINT8 is not supported because uint8_t has too small a range for this library. Use exactly one of CCX_HR_TIME_BASE_TYPE_CUSTOM_IS_UINT16/32/64."
    typedef volatile uint16_t CCX_HR_TIME_t;
#define CCX_HR_TIME_BASE_SCALAR uint16_t
#define CCX_HR_MAX_TIMEOUT UINT16_MAX
#elif defined(CCX_HR_TIME_BASE_TYPE_CUSTOM_IS_UINT16)
    typedef volatile uint16_t CCX_HR_TIME_t;
#define CCX_HR_TIME_BASE_SCALAR uint16_t
#define CCX_HR_MAX_TIMEOUT UINT16_MAX
#elif defined(CCX_HR_TIME_BASE_TYPE_CUSTOM_IS_UINT32)
    typedef volatile uint32_t CCX_HR_TIME_t;
#define CCX_HR_TIME_BASE_SCALAR uint32_t
#define CCX_HR_MAX_TIMEOUT UINT32_MAX
#elif defined(CCX_HR_TIME_BASE_TYPE_CUSTOM_IS_UINT64)
    typedef volatile uint64_t CCX_HR_TIME_t;
#define CCX_HR_TIME_BASE_SCALAR uint64_t
#define CCX_HR_MAX_TIMEOUT UINT64_MAX
#else
    typedef volatile uint16_t CCX_HR_TIME_t;
#define CCX_HR_TIME_BASE_SCALAR uint16_t
#define CCX_HR_MAX_TIMEOUT UINT16_MAX
#endif
 
#else
 
typedef CCX_TIME_t CCX_HR_TIME_t;
#define CCX_HR_TIME_BASE_SCALAR CCX_TIME_BASE_SCALAR
#define CCX_HR_MAX_TIMEOUT CCX_MAX_TIMEOUT
 
#endif
 
#define CCX_INTERNAL_MS_FROM_US_CEIL(us) (((us) == 0U) ? 0U : (((us)-1U) / 1000U) + 1U)
 
#ifdef CCX_DISABLE_HIGH_RES_TIMEBASE
#define CCX_HR_TIME(us) ((CCX_HR_TIME_t)CCX_INTERNAL_MS_FROM_US_CEIL(us))
#else
#define CCX_HR_TIME(us) ((CCX_HR_TIME_t)(us))
#endif

    typedef enum
    {
        CCX_BUS_BUSY = 0,
        CCX_BUS_FREE
    } CCX_BusIsFree_t;

    typedef enum
    {
        CCX_ID_STANDARD = 0, 
        CCX_ID_EXTENDED = 1, 
    } CCX_ide_t;
 
#if CCX_ENABLE_CANFD
    typedef enum
    {
        CCX_FRAME_FORMAT_CLASSIC = 0, 
        CCX_FRAME_FORMAT_FD = 1,      
        CCX_FRAME_FORMAT_FD_BRS = 2,  
    } CCX_frame_format_t;
#endif

    typedef struct
    {
        uint32_t total_rx_messages; 
        uint32_t
            total_tx_messages; 
        uint32_t rx_buffer_overflows; 
        uint32_t tx_buffer_overflows; 
        uint32_t parser_calls_count;  
        uint32_t timeout_calls_count; 
        uint16_t peak_rx_depth;       
        uint16_t peak_tx_depth;       
    } CCX_GlobalStats_t;
 
    typedef enum
    {
        CCX_MSG_UNREG,
        CCX_MSG_REG
    } CCX_MsgRegStatus_t;
 
    typedef enum
    {
        CCX_OK = 0,
        CCX_NULL_PTR,
        CCX_WRONG_ARG,
        CCX_BUS_TOO_BUSY,
        CCX_MISSING_TIMEBASE
    } CCX_Status_t;

    typedef struct
    {
        uint32_t ID;
#if CCX_ENABLE_CANFD
        uint8_t Data[64];
#else
    uint8_t Data[8];
#endif
        uint8_t DLC : 4;
        uint8_t IDE_flag : 1; /* use CCX_ide_t values */
#if CCX_ENABLE_CANFD
        uint8_t FrameFormat : 2; /* use CCX_frame_format_t values */
        uint8_t ESI : 1;         /* error state indicator (set by RX hardware) */
#endif
    } CCX_message_t;
 
    typedef struct CCX_instance_t CCX_instance_t;
 
#include "can_corex_bus.h"

    typedef struct
    {
        uint32_t ID;
#if CCX_ENABLE_CANFD
        uint8_t DLC : 5;         /* 0-15 = exact FD DLC; 16 (CCX_DLC_ANY) = wildcard */
        uint8_t IDE_flag : 1;    /* use CCX_ide_t values */
        uint8_t FrameFormat : 2; /* CLASSIC→match classic frames; FD/FD_BRS→match FD frames */
#else
    uint8_t DLC : 4;
    uint8_t IDE_flag : 1; /* use CCX_ide_t values */
#endif
        void *UserData;
        CCX_TIME_t TimeOut;
        void (*Parser)(const CCX_instance_t *Instance, CCX_message_t *Msg, uint16_t Slot, void *UserData);
        void (*TimeoutCallback)(CCX_instance_t *Instance, uint16_t Slot, void *UserData);
        CCX_TIME_t LastTick;
    } CCX_RX_table_t;

    typedef struct
    {
        uint32_t ID;
        uint8_t *Data;
        uint8_t DLC : 4;
        uint8_t IDE_flag : 1; /* use CCX_ide_t values */
#if CCX_ENABLE_CANFD
        uint8_t FrameFormat : 2; /* use CCX_frame_format_t values */
#endif
        void *UserData;
        CCX_TIME_t SendFreq;
        void (*Parser)(const CCX_instance_t *Instance, uint8_t *DataToSend, uint16_t Slot, void *UserData);
        CCX_TIME_t LastTick;
    } CCX_TX_table_t;
 
    struct CCX_instance_t
    {
 
        void (*SendFunction)(const CCX_instance_t *Instance, const CCX_message_t *msg);
        CCX_BusIsFree_t (*BusCheck)(const CCX_instance_t *Instance);
 
        CCX_message_t RxBuf[CCX_RX_BUFFER_SIZE];
        CCX_message_t TxBuf[CCX_TX_BUFFER_SIZE];
        volatile uint16_t RxTail, RxHead, TxTail, TxHead;
        CCX_TIME_t RxReceivedTick[CCX_RX_BUFFER_SIZE];
 
        CCX_RX_table_t *CCX_RX_table;
        CCX_TX_table_t *CCX_TX_table;
        uint16_t RxTableSize, TxTableSize;
        void (*Parser_unreg_msg)(const CCX_instance_t *Instance, CCX_message_t *Msg);
 
        /* New fields for v1.3.0 - added at the end for compatibility */
        CCX_GlobalStats_t GlobalStats; 
        CCX_BusMonitor_t *BusMonitor;  
        void (*OnMessageTransmitted)(
            CCX_instance_t *Instance,
            const CCX_message_t *msg); 
 
#if defined(CCX_RX_SEARCH_HASH)
        uint16_t RxHashTable[CCX_RX_HASH_SIZE]; 
#endif
    };
 
    CCX_Status_t CCX_RX_PushMsg(CCX_instance_t *Instance, const CCX_message_t *msg);
    CCX_Status_t CCX_TX_PushMsg(CCX_instance_t *Instance, const CCX_message_t *msg);
    uint16_t CCX_RX_GetDepth(const CCX_instance_t *Instance);
    uint16_t CCX_TX_GetDepth(const CCX_instance_t *Instance);
    uint16_t CCX_RX_GetFree(const CCX_instance_t *Instance);
    uint16_t CCX_TX_GetFree(const CCX_instance_t *Instance);
    void CCX_FlushRx(CCX_instance_t *Instance);
    void CCX_FlushTx(CCX_instance_t *Instance);
    void CCX_Flush(CCX_instance_t *Instance);
    void CCX_Reset(CCX_instance_t *Instance);
    CCX_Status_t CCX_Poll(CCX_instance_t *Instance);
    CCX_Status_t CCX_Init(CCX_instance_t *Instance, CCX_RX_table_t *CCX_RX_table, CCX_TX_table_t *CCX_TX_table,
                          uint16_t RxTableSize, uint16_t TxTableSize,
                          void (*SendFunction)(const CCX_instance_t *Instance, const CCX_message_t *msg),
                          CCX_BusIsFree_t (*BusCheck)(const CCX_instance_t *Instance),
                          void (*ParserUnregMsg)(const CCX_instance_t *Instance, CCX_message_t *Msg));
 
#if CCX_TICK_FROM_FUNC
    void CCX_tick_function_register(CCX_TIME_BASE_SCALAR (*Function)(void));
#else
void CCX_tick_variable_register(CCX_TIME_t *Variable);
#endif
 
#ifndef CCX_DISABLE_HIGH_RES_TIMEBASE
#if CCX_HR_TICK_FROM_FUNC
    void CCX_high_res_tick_function_register(CCX_HR_TIME_BASE_SCALAR (*Function)(void));
#else
    void CCX_high_res_tick_variable_register(CCX_HR_TIME_t *Variable);
#endif
#endif
 
    uint8_t CCX_IsPrimaryTickRegistered(void);
    uint8_t CCX_IsHighResTickRegistered(void);
 
#if CCX_TICK_FROM_FUNC
    extern CCX_TIME_BASE_SCALAR (*CCX_get_tick)(void);
#define CCX_GetPrimaryTick() ((CCX_get_tick != NULL) ? (CCX_TIME_t)CCX_get_tick() : ((CCX_TIME_t)0))
#else
extern CCX_TIME_t *CCX_tick;
#define CCX_GetPrimaryTick() ((CCX_tick != NULL) ? (*CCX_tick) : ((CCX_TIME_t)0))
#endif
 
#ifdef CCX_DISABLE_HIGH_RES_TIMEBASE
#define CCX_GetHighResTick() ((CCX_HR_TIME_t)CCX_GetPrimaryTick())
#else
#if CCX_HR_TICK_FROM_FUNC
extern CCX_HR_TIME_BASE_SCALAR (*CCX_get_high_res_tick)(void);
#define CCX_GetHighResTick()                                                                                           \
    ((CCX_get_high_res_tick != NULL) ? (CCX_HR_TIME_t)CCX_get_high_res_tick() : ((CCX_HR_TIME_t)0))
#else
extern CCX_HR_TIME_t *CCX_high_res_tick;
#define CCX_GetHighResTick() ((CCX_high_res_tick != NULL) ? (*CCX_high_res_tick) : ((CCX_HR_TIME_t)0))
#endif
#endif

    const CCX_GlobalStats_t *CCX_GetGlobalStats(const CCX_instance_t *Instance);

    void CCX_ResetGlobalStats(CCX_instance_t *Instance);

    void CCX_OnMessageTransmitted(CCX_instance_t *Instance, const CCX_message_t *msg);

    void CCX_RX_RebuildHash(CCX_instance_t *Instance);
 
    /* ========================================================================
     * CAN FD API (v2.0, requires CCX_ENABLE_CANFD=1)
     * ======================================================================== */
 
#if CCX_ENABLE_CANFD

    typedef enum
    {
        CCX_FD_DLC_0B = 0,   /* 0 bytes  */
        CCX_FD_DLC_1B = 1,   /* 1 byte   */
        CCX_FD_DLC_2B = 2,   /* 2 bytes  */
        CCX_FD_DLC_3B = 3,   /* 3 bytes  */
        CCX_FD_DLC_4B = 4,   /* 4 bytes  */
        CCX_FD_DLC_5B = 5,   /* 5 bytes  */
        CCX_FD_DLC_6B = 6,   /* 6 bytes  */
        CCX_FD_DLC_7B = 7,   /* 7 bytes  */
        CCX_FD_DLC_8B = 8,   /* 8 bytes  */
        CCX_FD_DLC_12B = 9,  /* 12 bytes */
        CCX_FD_DLC_16B = 10, /* 16 bytes */
        CCX_FD_DLC_20B = 11, /* 20 bytes */
        CCX_FD_DLC_24B = 12, /* 24 bytes */
        CCX_FD_DLC_32B = 13, /* 32 bytes */
        CCX_FD_DLC_48B = 14, /* 48 bytes */
        CCX_FD_DLC_64B = 15, /* 64 bytes */
    } CCX_FD_DLC_t;

    extern const uint8_t CCX_FD_DLC_TO_LEN[16];

    uint8_t CCX_FD_LenToDLC(uint8_t len);

    static inline uint8_t CCX_MsgPayloadLen(const CCX_message_t *msg)
    {
        return (msg->FrameFormat != CCX_FRAME_FORMAT_CLASSIC) ? CCX_FD_DLC_TO_LEN[msg->DLC] : msg->DLC;
    }
 
#endif /* CCX_ENABLE_CANFD */

 
#ifdef __cplusplus
}
#endif
 
#endif /* CAN_COREX_CAN_COREX_H_ */