scom.h

Go to the documentation of this file.

#ifndef SCOM_H_
#define SCOM_H_
#define SCOM_VER_HI   0
#define SCOM_VER_LO       5
#ifndef SCOM_REVISION
#define SCOM_REVISION 0
#endif

#if defined __cplusplus
extern "C" {
#endif


#include "hal.h"
#include "scom_frame_queue.h"
#include "scom_ack_frame.h"
#include <stdint.h>
#include <stdbool.h>

#define SCOM_DECLARE_FRAME_BUFFER(name, txQueueSize, rxQueueSize) \
                SCOMFrameQueueItem name##_scom_tx_frame_pool[txQueueSize]; \
                SCOMFrameQueueItem name##_scom_rx_frame_pool[rxQueueSize]; \
                SCOMFrameBuffer name = {{name##_scom_tx_frame_pool, NULL, txQueueSize, NULL}, \
                                                                {name##_scom_rx_frame_pool, NULL, rxQueueSize, NULL}}


#define SCOM_DECLARE_FRAME_BUFFER_USING_HEAP(name) \
                SCOMFrameBuffer name = { {NULL,  NULL,  0, NULL}, \
                                                                { NULL,  NULL,  0, NULL}}




#if SCOM_MAX_FRAME_FILTERS > 0
typedef struct SCOMFilterFramePool SCOMFilterFramePool;
#endif

typedef struct {
        SCOMFrameQueue txFrameQueue;
        SCOMFrameQueue rxFrameQueue;
} SCOMFrameBuffer;



#if 1 == defined HAL_ENABLE_OS

typedef OSTime (*SCOMClockSource)(void);
#else

typedef uint32_t (*SCOMClockSource)(void);
#endif

typedef struct HAL_PACKED {
        uint8_t verHi; 
        uint8_t verLo; 
        uint16_t revision; 
} SCOMVersion;

typedef struct HAL_PACKED {
        SCOMVersion version; 
    uint32_t deviceClass; 
    uint8_t deviceUID[16]; 
#if SCOM_MAX_SERVICES > 0
    uint8_t serviceID[SCOM_MAX_SERVICES]; 
#endif
} SCOMIdentity;

#define SCOM_DEVICE_INFO_LEN (sizeof(((SCOMIdentity *)0)->version) + sizeof(((SCOMIdentity *)0)->deviceClass) + sizeof(((SCOMIdentity *)0)->deviceUID))

typedef enum {
        SCOM_RX_WAIT_FOR_SOF,
        SCOM_RX_ACK,
        SCOM_RX_FRAME,
        SCOM_BROKEN_LINK
} SCOMReceiverState;

typedef enum {
        SCOM_CONNECTION_UNINITIALIZED = 0,
        SCOM_CONNECTION_OPERATIONAL = 1,
        SCOM_CONNECTION_UNSYNCHRONIZED = 2,
        SCOM_CONNECTION_BROKEN = 3,
} SCOMConnectionState;

typedef struct {
        SCOMAckFrame frame; 
        SCOMFrameState state; 
} SCOMACKState;

typedef struct {
        uint32_t framesSent;
        uint32_t framesReceived;
        uint32_t retransmissionsSent;
        uint32_t retransmissionsReceived;
} SCOMStatistics;

typedef struct SCOMDataLinkDesc {
    IODevice iodevice;  
    SCOMClockSource clockSource; 
    uint32_t timeout; 
    SCOMIdentity id; 
    uint8_t serviceCount; 
    SCOMConnectionState connectionState; 
    SCOMReceiverState rxState; 
    bool monitorMode; 
    SCOMFrameBuffer *frameBuffer; 
    SCOMACKState rxAck; 
    SCOMACKState txAck; 
    SCOMFrameQueueItem *frameBeingReceived; 
    SCOMFrameQueueItem *frameBeingTransmitted; 
    uint8_t retransmissionCounter;  
    uint8_t lastFrameNumber; 
    uint16_t lastFrameCrc; 
    uint32_t sendTime; 
    uint32_t receptionTime; 
#if defined SCOM_RECEPTION_TIMEOUT_AFTER_FRAME_START
    uint32_t receptionStartTime; 
#endif
        uint32_t txCounter; 
        uint32_t multiCounter; 
        uint32_t connectivityCheckPeriod; 
        uint32_t lastConnectivityCheckTime; 
        uint32_t connectivityCheckIncommingCounter; 
        uint32_t connectivityCheckOutgoingCounter; 
    bool (*receptionHandler)(struct SCOMDataLinkDesc* scom, SCOMFrame *frame); 
    void (*ackHandler)(struct SCOMDataLinkDesc* scom, uint8_t frame_type); 
    SCOMStatistics stats; 
#if SCOM_MAX_SERVICES > 0
    struct {
        uint8_t serviceID;
        void (*handler)(struct SCOMDataLinkDesc* scom, SCOMFrame *frame);
    } serviceHandler[SCOM_MAX_SERVICES];
#endif
#if SCOM_MAX_FRAME_FILTERS > 0
    struct {
        LLSTItemDesc pool[SCOM_MAX_FRAME_FILTERS]; 
        LLSTListDesc list; 
        OSCntSem dataReady; 
        SCOMFilterFramePool *framePool; 
    } filters;
#if defined HAL_ENABLE_OS && (HAL_ENABLE_OS == 1)
    OSTask filterTask; 
#endif
#endif

#if 1 == HAL_ENABLE_OS
    OSMutex accessGuard; 
    OSTask procTask; 
#endif

} SCOMDataLinkDesc;

typedef SCOMDataLinkDesc* SCOMDataLink;

typedef bool (*SCOMFrameReceptionHandler)(SCOMDataLink scom, SCOMFrame *frame);

typedef void (*SCOMAckReceptionHandler)(SCOMDataLink scom, uint8_t frame_type);

typedef void (*SCOMServiceHandler)(SCOMDataLinkDesc* scom, SCOMFrame *frame);

typedef enum {
    SCOM_RESULT_OK = 0,
        SCOM_ERROR = 1,
        SCOM_RESULT_ERROR = 1,
    SCOM_TX_EMPTY,
    SCOM_TX_FULL,
    SCOM_INTERNAL_ERROR,
    SCOM_FRAME_RECEIVED,
    SCOM_RECEIVER_BLOCKED,
    SCOM_NO_FRAME,
    SCOM_TX_FRAME_BUFFER_OVERRUN,
    SCOM_RX_FRAME_DATA_TOO_LARGE,
    SCOM_FRAME_NOT_IN_BUFFER,
    SCOM_USART_TX_BUF_ERROR,
    SCOM_USART_RX_BUF_ERROR,
    SCOM_COMMUNICATION_ERROR,
    SCOM_TX_INTEGRITY_ERROR,
    SCOM_FILTER_LIST_FULL,
    SCOM_FILTER_TIMEOUT,
    SCOM_FILTER_ERROR,
        SCOM_SYNCHRONIZATION_ERROR,
        SCOM_NO_DEVICE,
        SCOM_RESULT_CRC_MISMATCH,
} SCOMResult;

/* Possible errors reported by SCOM (via HAL DIAG error reporting mechanism) */


#define SCOM_ERR__COMMUNICATION_ERROR   1 
#define SCOM_ERR__INTERNAL_ERROR        2 
#define SCOM_ERR__DATA_TOO_LARGE        3 
#define SCOM_ERR__TX_OVERLOAD           4 
#define SCOM_ERR__SYNCHRONIZATION_ERROR 5 


typedef struct {
        uint32_t multi_id; 
        uint32_t progress; 
} SCOMMultiFrameDesc;

// -----------------------------------------------------------------------------
//  SCOM API
// -----------------------------------------------------------------------------

SCOMDataLink SCOM_Create(void);

void SCOM_Destroy(SCOMDataLinkDesc* const scom);

SCOMFrameBuffer* SCOM_CreateFrameBuffer(size_t rxBuffSize, size_t txBuffSize);

void SCOM_DestroyFrameBuffer(SCOMFrameBuffer *frameBuffer);

SCOMResult SCOM_Init(SCOMDataLink scom, IODevice iodevice, SCOMFrameBuffer *frameBuffer,
                              SCOMClockSource clockSource, uint32_t ackTimeout,
                              uint32_t deviceClass, uint8_t* deviceUID,
                                          uint8_t numberOfServices, uint8_t* serviceIDs
                              );

SCOMResult SCOM_Deinit(SCOMDataLink scom);

SCOMResult SCOM_InitAsMonitor(SCOMDataLink scom, IODevice iodevice, SCOMFrameBuffer *frameBuffer, SCOMClockSource clockSource, uint32_t ackTimeout);

SCOMResult SCOM_RunProcessingThread(SCOMDataLink scom);

void SCOM_StopProcessingThread(SCOMDataLink scom);

SCOMResult SCOM_EnableConnectivityCheck(SCOMDataLink scom, uint32_t checkPeriod);
SCOMResult SCOM_DisableConnectivityCheck(SCOMDataLink scom);

SCOMConnectionState SCOM_GetConnectionState(const SCOMDataLinkDesc* const scom) ;

IODevice SCOM_GetIODevice(const SCOMDataLinkDesc* const scom);

SCOMResult SCOM_SendFrame(SCOMDataLink scom, uint8_t framePriority, uint8_t frameType, const void* frameData, uint8_t frameDataSize);


SCOMResult SCOM_SendFrameWithoutAck(SCOMDataLink scom, uint8_t framePriority, uint8_t frameType, const void* frameData, uint8_t frameDataSize);


SCOMResult SCOM_SendMultiFrame(SCOMDataLink scom, uint8_t framePriority, uint8_t frameType,
                               const void* frameData, uint32_t frameDataSize, SCOMMultiFrameDesc* multiFrameDesc);

SCOMResult SCOM_SendAllocatedMultiFrame(SCOMDataLink scom, SCOMFrame* frame, SCOMMultiFrameDesc* multiFrameDesc);

SCOMResult SCOM_AllocFrame(SCOMDataLink scom, SCOMFrame** framePtr);

SCOMResult SCOM_SendAllocatedFrame(SCOMDataLink scom, SCOMFrame* frame);

SCOMResult SCOM_SendAllocatedFrameWithoutACK(SCOMDataLink scom, SCOMFrame* frame);

SCOMResult SCOM_SetFrameReceptionHandlerFunc(SCOMDataLink scom, SCOMFrameReceptionHandler frameReceptionFunc);

SCOMResult SCOM_SetAckReceptionHandlerFunc(SCOMDataLink scom, SCOMAckReceptionHandler ackReceptionFunc);

SCOMResult SCOM_SetServiceHandler(SCOMDataLink scom, uint8_t serviceID, SCOMServiceHandler serviceHandlerFunc);

SCOMResult SCOM_Proc(SCOMDataLink scom);

SCOMFrame * SCOM_GetReceivedFrame(SCOMDataLink scom);

void SCOM_UnlockFrame(SCOMDataLink scom, SCOMFrame *frame);

SCOMStatistics SCOM_GetStatistics(const SCOMDataLinkDesc* const scom);

void SCOM_ResetStatistics(SCOMDataLink scom);


bool SCOM_IsBusy(SCOMDataLink scom);

#if defined __cplusplus
} // extern "C"
#endif


#endif /* SCOM_H */