can_corex_isotp.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: Jan 22, 2026
 */
 
#ifndef CAN_COREX_CAN_COREX_ISOTP_H_
#define CAN_COREX_CAN_COREX_ISOTP_H_
 
#include "can_corex.h"
 
#ifdef __cplusplus
extern "C"
{
#endif


#ifndef CCX_ISOTP_MAX_CLASSIC_DATA_SIZE
#define CCX_ISOTP_MAX_CLASSIC_DATA_SIZE 4095U
#endif

#if CCX_ENABLE_CANFD
#ifndef CCX_ISOTP_MAX_FD_DATA_SIZE
#define CCX_ISOTP_MAX_FD_DATA_SIZE UINT32_MAX
#endif
#endif

#ifndef CCX_ISOTP_MAX_DATA_SIZE
#if CCX_ENABLE_CANFD
#define CCX_ISOTP_MAX_DATA_SIZE CCX_ISOTP_MAX_FD_DATA_SIZE
#else
#define CCX_ISOTP_MAX_DATA_SIZE CCX_ISOTP_MAX_CLASSIC_DATA_SIZE
#endif
#endif
 
#if CCX_ENABLE_CANFD
    typedef uint32_t CCX_ISOTP_Length_t;
#else
typedef uint16_t CCX_ISOTP_Length_t;
#endif


    typedef enum
    {
        CCX_ISOTP_PCI_SF = 0x00, /* Single Frame: [0x0N | data] */
        CCX_ISOTP_PCI_FF = 0x10, /* First Frame: [0x1L LL | data] */
        CCX_ISOTP_PCI_CF = 0x20, /* Consecutive Frame: [0x2N | data] */
        CCX_ISOTP_PCI_FC = 0x30  /* Flow Control: [0x30 | FS | BS | STmin] */
    } CCX_ISOTP_PCI_t;
 
    typedef enum
    {
        CCX_ISOTP_LENGTH_FORMAT_STANDARD = 0,
        CCX_ISOTP_LENGTH_FORMAT_EXTENDED
    } CCX_ISOTP_LengthFormat_t;
 
#if CCX_ENABLE_CANFD
    typedef enum
    {
        CCX_ISOTP_TX_DL_8 = 8,
        CCX_ISOTP_TX_DL_12 = 12,
        CCX_ISOTP_TX_DL_16 = 16,
        CCX_ISOTP_TX_DL_20 = 20,
        CCX_ISOTP_TX_DL_24 = 24,
        CCX_ISOTP_TX_DL_32 = 32,
        CCX_ISOTP_TX_DL_48 = 48,
        CCX_ISOTP_TX_DL_64 = 64
    } CCX_ISOTP_TxDL_t;
#endif


    typedef enum
    {
        CCX_ISOTP_FC_CTS = 0x00,  /* Continue To Send */
        CCX_ISOTP_FC_WAIT = 0x01, /* Wait */
        CCX_ISOTP_FC_OVFLW = 0x02 /* Overflow */
    } CCX_ISOTP_FC_FS_t;

    typedef enum
    {
        CCX_ISOTP_OK = 0,
        CCX_ISOTP_ERROR_NULL_PTR,
        CCX_ISOTP_ERROR_INVALID_ARG,
        CCX_ISOTP_ERROR_TIMEOUT_FC,                           /* Timeout while waiting for Flow Control (`N_Bs`) */
        CCX_ISOTP_ERROR_TIMEOUT = CCX_ISOTP_ERROR_TIMEOUT_FC, /* Legacy alias */
        CCX_ISOTP_ERROR_OVERFLOW,
        CCX_ISOTP_ERROR_BUSY,
        CCX_ISOTP_ERROR_SEQUENCE, /* Unexpected PCI / Flow Status / CF sequence number; may occur before any timeout if
                                     a later frame arrives in time */
        CCX_ISOTP_ERROR_BUFFER_TOO_SMALL,
        CCX_ISOTP_ERROR_ABORTED,
        CCX_ISOTP_ERROR_WAIT_EXCEEDED, /* Too many `FC.WAIT` frames received */
        CCX_ISOTP_ERROR_TIMEOUT_CF_TX, /* Timeout while scheduling/sending next CF (`N_Cs`) */
        CCX_ISOTP_ERROR_TIMEOUT_CF_RX, /* Timeout while waiting for next received CF (`N_Cr`) */
        CCX_ISOTP_ERROR_MISSING_TIMEBASE,
#if CCX_ENABLE_CANFD
        CCX_ISOTP_ERROR_FD_NOT_SUPPORTED, /* Reserved for legacy compatibility */
#endif
    } CCX_ISOTP_Status_t;

    typedef enum
    {
        CCX_ISOTP_TX_STATE_IDLE = 0,
        CCX_ISOTP_TX_STATE_WAIT_FC,
        CCX_ISOTP_TX_STATE_SENDING_CF
    } CCX_ISOTP_TX_State_t;

    typedef enum
    {
        CCX_ISOTP_RX_STATE_IDLE = 0,
        CCX_ISOTP_RX_STATE_RECEIVING_CF
    } CCX_ISOTP_RX_State_t;
 
    typedef enum
    {
        CCX_ISOTP_PADDING_DISABLED = 0,
        CCX_ISOTP_PADDING_ENABLED = 1
    } CCX_ISOTP_PaddingEnable_t;

    typedef struct
    {
        CCX_ISOTP_PaddingEnable_t Enable; /* Enable or disable ISO-TP frame padding */
        uint8_t PaddingByte;              /* Byte value used for padding (e.g., 0xAA, 0xCC, 0x55) */
    } CCX_ISOTP_Padding_t;
 
#define CCX_ISOTP_NO_PADDING ((CCX_ISOTP_Padding_t){.Enable = CCX_ISOTP_PADDING_DISABLED, .PaddingByte = 0U})
 
#define CCX_ISOTP_PADDING(byte)                                                                                        \
    ((CCX_ISOTP_Padding_t){.Enable = CCX_ISOTP_PADDING_ENABLED, .PaddingByte = (uint8_t)(byte)})
 
#define CCX_ISOTP_STMIN_100US 0xF1U
#define CCX_ISOTP_STMIN_200US 0xF2U
#define CCX_ISOTP_STMIN_300US 0xF3U
#define CCX_ISOTP_STMIN_400US 0xF4U
#define CCX_ISOTP_STMIN_500US 0xF5U
#define CCX_ISOTP_STMIN_600US 0xF6U
#define CCX_ISOTP_STMIN_700US 0xF7U
#define CCX_ISOTP_STMIN_800US 0xF8U
#define CCX_ISOTP_STMIN_900US 0xF9U
 
    typedef struct CCX_ISOTP_TX_t CCX_ISOTP_TX_t;
    typedef struct CCX_ISOTP_RX_t CCX_ISOTP_RX_t;

    typedef struct
    {
        uint32_t TxID;        /* CAN ID for transmitting data */
        uint8_t IDE_TxID : 1; /* use CCX_ide_t values: CCX_ID_STANDARD / CCX_ID_EXTENDED */
#if CCX_ENABLE_CANFD
        CCX_frame_format_t FrameFormat : 2; /* Session transport format: CLASSIC / FD / FD_BRS */
        uint8_t TxDL;                       /* FD only: link-layer payload 8,12,16,20,24,32,48,64 */
#endif
        CCX_TIME_t N_Bs;             /* Timeout for reception of FC after FF/CF in base ticks */
        CCX_TIME_t N_Cs;             /* Timeout between CF transmissions in base ticks */
        uint8_t MaxWaitFrames;       /* Number of FC.WAIT frames tolerated before aborting (0 = default 10) */
        CCX_ISOTP_Padding_t Padding; /* Padding configuration */
 
        void *UserData; /* User context pointer passed to callbacks */
 
        /* Callbacks */
        void (*OnTransmitComplete)(CCX_ISOTP_TX_t *Instance, void *UserData);
        void (*OnError)(CCX_ISOTP_TX_t *Instance, CCX_ISOTP_Status_t Error, void *UserData);
    } CCX_ISOTP_TX_Config_t;

    typedef struct
    {
        uint32_t TxID;        /* CAN ID for transmitting Flow Control */
        uint8_t IDE_TxID : 1; /* use CCX_ide_t values: CCX_ID_STANDARD / CCX_ID_EXTENDED */
#if CCX_ENABLE_CANFD
        CCX_frame_format_t FrameFormat : 2; /* Expected transport format of received ISO-TP frames */
        uint8_t FC_TxDL;                    /* FD only: link-layer payload used for transmitted FC frames */
#endif
        uint8_t BS;      /* Block Size to request in FC (0 = no limit) */
        uint8_t STmin;   /* Separation Time minimum to request in FC */
        CCX_TIME_t N_Cr; /* Timeout between received CF in base ticks. Detects silence, not correctness: if a later CF
                            arrives before `N_Cr` expires, RX may fail with `CCX_ISOTP_ERROR_SEQUENCE` instead of
                            `CCX_ISOTP_ERROR_TIMEOUT_CF_RX` */
        CCX_ISOTP_Padding_t Padding; /* Padding configuration */
 
        uint8_t *RxBuffer;               /* Buffer for received data */
        CCX_ISOTP_Length_t RxBufferSize; /* Size of RX buffer */
        CCX_ISOTP_Length_t
            ProgressCallbackInterval; /* Call progress callback every N newly received bytes (0 = disabled) */
 
        void *UserData; /* User context pointer passed to callbacks */
 
        /* Callbacks */
        void (*OnReceiveStart)(CCX_ISOTP_RX_t *Instance, CCX_ISOTP_Length_t TotalLength, void *UserData);
        void (*OnReceiveComplete)(CCX_ISOTP_RX_t *Instance, const uint8_t *Data, CCX_ISOTP_Length_t Length,
                                  void *UserData);
        void (*OnReceiveProgress)(CCX_ISOTP_RX_t *Instance, CCX_ISOTP_Length_t BytesReceived,
                                  CCX_ISOTP_Length_t TotalLength, void *UserData);
        void (*OnError)(CCX_ISOTP_RX_t *Instance, CCX_ISOTP_Status_t Error, void *UserData);
    } CCX_ISOTP_RX_Config_t;

    struct CCX_ISOTP_TX_t
    {
        CCX_instance_t *CanInstance; /* Bound CAN instance for this ISO-TP TX session */
        CCX_ISOTP_TX_Config_t Config;
        CCX_ISOTP_TX_State_t State;
 
        const uint8_t *TxData;           /* Pointer to data being transmitted */
        CCX_ISOTP_Length_t TxDataLength; /* Total length of data to transmit */
        CCX_ISOTP_Length_t TxDataOffset; /* Current offset in TxData */
        uint8_t SequenceNumber;          /* CF sequence number (0-15) */
        uint8_t BlockCounter;            /* Counter for BS */
        CCX_TIME_t LastTick;             /* Last activity timestamp in base ticks */
        CCX_HR_TIME_t LastHighResTick;   /* Last CF scheduling timestamp for sub-millisecond STmin */
        uint8_t WaitFramesRemaining;     /* Number of WAIT FC frames we can tolerate */
        CCX_TIME_t STminTicks;           /* STmin value from FC converted to base ticks */
        CCX_HR_TIME_t STminHighResTicks; /* STmin value from FC converted to HR ticks when sub-millisecond */
        uint8_t STminUsesHighRes;        /* 1 when STmin must be enforced in HR domain */
        uint8_t ActiveTxDL;              /* Active link-layer payload for TX */
        uint8_t MaxWaitFrames;           /* Effective FC.WAIT tolerance for this instance */
        uint8_t InitValid;               /* Successful init state */
        CCX_ISOTP_LengthFormat_t LengthFormat;
    };

    struct CCX_ISOTP_RX_t
    {
        CCX_instance_t *CanInstance; /* Bound CAN instance for this ISO-TP RX session */
        CCX_ISOTP_RX_Config_t Config;
        CCX_ISOTP_RX_State_t State;
 
        CCX_ISOTP_Length_t RxDataLength;         /* Total expected length */
        CCX_ISOTP_Length_t RxDataOffset;         /* Current offset in RxBuffer */
        uint8_t SequenceNumber;                  /* Expected CF sequence number (0-15) */
        uint8_t BlockCounter;                    /* Counter for BS */
        CCX_TIME_t LastTick;                     /* Last activity timestamp in base ticks */
        CCX_ISOTP_Length_t LastProgressCallback; /* Offset at last progress callback */
        uint8_t ActiveRxDL;                      /* CAN_DL announced by FF */
        uint8_t InitValid;                       /* Successful init state */
        CCX_ISOTP_LengthFormat_t LengthFormat;
    };

    void CCX_ISOTP_TX_Config_Init(CCX_ISOTP_TX_Config_t *Config, uint32_t TxID, uint8_t IDE_TxID, CCX_TIME_t N_Bs,
                                  CCX_TIME_t N_Cs, CCX_ISOTP_Padding_t Padding, void *UserData,
                                  void (*OnTransmitComplete)(CCX_ISOTP_TX_t *Instance, void *UserData),
                                  void (*OnError)(CCX_ISOTP_TX_t *Instance, CCX_ISOTP_Status_t Error, void *UserData));
 
#if CCX_ENABLE_CANFD
    void CCX_ISOTP_TX_Config_InitFD(CCX_ISOTP_TX_Config_t *Config, uint32_t TxID, uint8_t IDE_TxID,
                                    CCX_frame_format_t FrameFormat, uint8_t TxDL, CCX_TIME_t N_Bs, CCX_TIME_t N_Cs,
                                    CCX_ISOTP_Padding_t Padding, void *UserData,
                                    void (*OnTransmitComplete)(CCX_ISOTP_TX_t *Instance, void *UserData),
                                    void (*OnError)(CCX_ISOTP_TX_t *Instance, CCX_ISOTP_Status_t Error,
                                                    void *UserData));
#endif

    CCX_ISOTP_Status_t CCX_ISOTP_TX_Init(CCX_ISOTP_TX_t *Instance, CCX_instance_t *CanInstance,
                                         const CCX_ISOTP_TX_Config_t *Config);

    CCX_ISOTP_Status_t CCX_ISOTP_TX_Abort(CCX_ISOTP_TX_t *Instance);

    CCX_ISOTP_Status_t CCX_ISOTP_Transmit(CCX_ISOTP_TX_t *Instance, const uint8_t *Data, CCX_ISOTP_Length_t Length);

    void CCX_ISOTP_TX_Poll(CCX_ISOTP_TX_t *Instance);

    void CCX_ISOTP_TX_FC_Parser(const CCX_instance_t *CanInstance, CCX_message_t *Msg, uint16_t Slot, void *UserData);

    void CCX_ISOTP_RX_Config_Init(CCX_ISOTP_RX_Config_t *Config, uint32_t TxID, uint8_t IDE_TxID, uint8_t BS,
                                  uint8_t STmin, CCX_TIME_t N_Cr, uint8_t *RxBuffer, CCX_ISOTP_Length_t RxBufferSize,
                                  CCX_ISOTP_Padding_t Padding, CCX_ISOTP_Length_t ProgressCallbackInterval,
                                  void *UserData,
                                  void (*OnReceiveStart)(CCX_ISOTP_RX_t *Instance, CCX_ISOTP_Length_t TotalLength,
                                                         void *UserData),
                                  void (*OnReceiveComplete)(CCX_ISOTP_RX_t *Instance, const uint8_t *Data,
                                                            CCX_ISOTP_Length_t Length, void *UserData),
                                  void (*OnReceiveProgress)(CCX_ISOTP_RX_t *Instance, CCX_ISOTP_Length_t BytesReceived,
                                                            CCX_ISOTP_Length_t TotalLength, void *UserData),
                                  void (*OnError)(CCX_ISOTP_RX_t *Instance, CCX_ISOTP_Status_t Error, void *UserData));
 
#if CCX_ENABLE_CANFD
    void CCX_ISOTP_RX_Config_InitFD(
        CCX_ISOTP_RX_Config_t *Config, uint32_t TxID, uint8_t IDE_TxID, CCX_frame_format_t FrameFormat, uint8_t FC_TxDL,
        uint8_t BS, uint8_t STmin, CCX_TIME_t N_Cr, uint8_t *RxBuffer, CCX_ISOTP_Length_t RxBufferSize,
        CCX_ISOTP_Padding_t Padding, CCX_ISOTP_Length_t ProgressCallbackInterval, void *UserData,
        void (*OnReceiveStart)(CCX_ISOTP_RX_t *Instance, CCX_ISOTP_Length_t TotalLength, void *UserData),
        void (*OnReceiveComplete)(CCX_ISOTP_RX_t *Instance, const uint8_t *Data, CCX_ISOTP_Length_t Length,
                                  void *UserData),
        void (*OnReceiveProgress)(CCX_ISOTP_RX_t *Instance, CCX_ISOTP_Length_t BytesReceived,
                                  CCX_ISOTP_Length_t TotalLength, void *UserData),
        void (*OnError)(CCX_ISOTP_RX_t *Instance, CCX_ISOTP_Status_t Error, void *UserData));
#endif

    CCX_ISOTP_Status_t CCX_ISOTP_RX_Init(CCX_ISOTP_RX_t *Instance, CCX_instance_t *CanInstance,
                                         const CCX_ISOTP_RX_Config_t *Config);

    CCX_ISOTP_Status_t CCX_ISOTP_RX_Abort(CCX_ISOTP_RX_t *Instance);

    void CCX_ISOTP_RX_Parser(const CCX_instance_t *CanInstance, CCX_message_t *Msg, uint16_t Slot, void *UserData);

    void CCX_ISOTP_RX_Poll(CCX_ISOTP_RX_t *Instance);

#if CCX_ENABLE_CANFD
#define CCX_ISOTP_RX_TABLE_ENTRY(isotp_rx_ptr, can_id, ide_flag)                                                       \
    {                                                                                                                  \
        .ID = (can_id), .DLC = CCX_DLC_ANY, .IDE_flag = (ide_flag), .FrameFormat = CCX_FRAME_FORMAT_CLASSIC,           \
        .UserData = (isotp_rx_ptr), .TimeOut = 0, .Parser = CCX_ISOTP_RX_Parser, .TimeoutCallback = NULL,              \
        .LastTick = 0                                                                                                  \
    }

#define CCX_ISOTP_TX_FC_TABLE_ENTRY(isotp_tx_ptr, fc_can_id, ide_flag)                                                 \
    {                                                                                                                  \
        .ID = (fc_can_id), .DLC = CCX_DLC_ANY, .IDE_flag = (ide_flag), .FrameFormat = CCX_FRAME_FORMAT_CLASSIC,        \
        .UserData = (isotp_tx_ptr), .TimeOut = 0, .Parser = CCX_ISOTP_TX_FC_Parser, .TimeoutCallback = NULL,           \
        .LastTick = 0                                                                                                  \
    }
 
#define CCX_ISOTP_RX_TABLE_ENTRY_EX(isotp_rx_ptr, can_id, ide_flag, frame_format)                                      \
    {                                                                                                                  \
        .ID = (can_id), .DLC = CCX_DLC_ANY, .IDE_flag = (ide_flag), .FrameFormat = (frame_format),                     \
        .UserData = (isotp_rx_ptr), .TimeOut = 0, .Parser = CCX_ISOTP_RX_Parser, .TimeoutCallback = NULL,              \
        .LastTick = 0                                                                                                  \
    }
 
#define CCX_ISOTP_TX_FC_TABLE_ENTRY_EX(isotp_tx_ptr, fc_can_id, ide_flag, frame_format)                                \
    {                                                                                                                  \
        .ID = (fc_can_id), .DLC = CCX_DLC_ANY, .IDE_flag = (ide_flag), .FrameFormat = (frame_format),                  \
        .UserData = (isotp_tx_ptr), .TimeOut = 0, .Parser = CCX_ISOTP_TX_FC_Parser, .TimeoutCallback = NULL,           \
        .LastTick = 0                                                                                                  \
    }
#else
#define CCX_ISOTP_RX_TABLE_ENTRY(isotp_rx_ptr, can_id, ide_flag)                                                       \
    {                                                                                                                  \
        .ID = (can_id), .DLC = CCX_DLC_ANY, .IDE_flag = (ide_flag), .UserData = (isotp_rx_ptr), .TimeOut = 0,          \
        .Parser = CCX_ISOTP_RX_Parser, .TimeoutCallback = NULL, .LastTick = 0                                          \
    }
 
#define CCX_ISOTP_TX_FC_TABLE_ENTRY(isotp_tx_ptr, fc_can_id, ide_flag)                                                 \
    {                                                                                                                  \
        .ID = (fc_can_id), .DLC = CCX_DLC_ANY, .IDE_flag = (ide_flag), .UserData = (isotp_tx_ptr), .TimeOut = 0,       \
        .Parser = CCX_ISOTP_TX_FC_Parser, .TimeoutCallback = NULL, .LastTick = 0                                       \
    }
#endif

 
#ifdef __cplusplus
}
#endif
 
#endif /* CAN_COREX_CAN_COREX_ISOTP_H_ */