snap.h

Go to the documentation of this file.

/*
Copyright (c) 2022 Lucas Jadilo
 
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
 
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
 
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
*/
 
#ifndef SNAP_H_
#define SNAP_H_
 
#ifdef __cplusplus
    extern "C" {
#endif
 
/******************************************************************************/
/*  Public Includes                                                           */
/******************************************************************************/
 
 
#include <stdint.h>
#include <stdbool.h>
 
 
/******************************************************************************/
/*  Public Macros                                                             */
/******************************************************************************/
 
 
#define SNAP_ERROR_NULL_FRAME       (-1)    
#define SNAP_ERROR_NULL_BUFFER      (-2)    
#define SNAP_ERROR_SHORT_BUFFER     (-3)    
#define SNAP_ERROR_UNKNOWN_FORMAT   (-4)    
#define SNAP_ERROR_FRAME_FORMAT     (-5)    
#define SNAP_ERROR_SHORT_FRAME      (-6)    
#define SNAP_ERROR_FIELD_TYPE       (-7)    
#define SNAP_HDB2_DAB_MASK  (0x03U) 
#define SNAP_HDB2_DAB_POS   (6U)    
#define SNAP_HDB2_SAB_MASK  (0x03U) 
#define SNAP_HDB2_SAB_POS   (4U)    
#define SNAP_HDB2_PFB_MASK  (0x03U) 
#define SNAP_HDB2_PFB_POS   (2U)    
#define SNAP_HDB2_ACK_MASK  (0x03U) 
#define SNAP_HDB2_ACK_POS   (0U)    
#define SNAP_HDB1_CMD_MASK  (0x01U) 
#define SNAP_HDB1_CMD_POS   (7U)    
#define SNAP_HDB1_EDM_MASK  (0x07U) 
#define SNAP_HDB1_EDM_POS   (4U)    
#define SNAP_HDB1_NDB_MASK  (0x0FU) 
#define SNAP_HDB1_NDB_POS   (0U)    
#define SNAP_GET_BITS(integer, mask, pos)   (((unsigned int)(integer) >> (pos)) & (mask))   
#define SNAP_HDB2(pByteArray)   ((pByteArray)[SNAP_INDEX_HDB2]) 
#define SNAP_HDB1(pByteArray)   ((pByteArray)[SNAP_INDEX_HDB1]) 
#define SNAP_HDB2_DAB(pByteArray)   (SNAP_GET_BITS(SNAP_HDB2(pByteArray), SNAP_HDB2_DAB_MASK, SNAP_HDB2_DAB_POS))   
#define SNAP_HDB2_SAB(pByteArray)   (SNAP_GET_BITS(SNAP_HDB2(pByteArray), SNAP_HDB2_SAB_MASK, SNAP_HDB2_SAB_POS))   
#define SNAP_HDB2_PFB(pByteArray)   (SNAP_GET_BITS(SNAP_HDB2(pByteArray), SNAP_HDB2_PFB_MASK, SNAP_HDB2_PFB_POS))   
#define SNAP_HDB2_ACK(pByteArray)   (SNAP_GET_BITS(SNAP_HDB2(pByteArray), SNAP_HDB2_ACK_MASK, SNAP_HDB2_ACK_POS))   
#define SNAP_HDB1_CMD(pByteArray)   (SNAP_GET_BITS(SNAP_HDB1(pByteArray), SNAP_HDB1_CMD_MASK, SNAP_HDB1_CMD_POS))   
#define SNAP_HDB1_EDM(pByteArray)   (SNAP_GET_BITS(SNAP_HDB1(pByteArray), SNAP_HDB1_EDM_MASK, SNAP_HDB1_EDM_POS))   
#define SNAP_HDB1_NDB(pByteArray)   (SNAP_GET_BITS(SNAP_HDB1(pByteArray), SNAP_HDB1_NDB_MASK, SNAP_HDB1_NDB_POS))   
#define SNAP_SIZE_SYNC              (1U)                                                    
#define SNAP_SIZE_HDB2              (1U)                                                    
#define SNAP_SIZE_HDB1              (1U)                                                    
#define SNAP_SIZE_HEADER            (SNAP_SIZE_HDB2 + SNAP_SIZE_HDB1)                       
#define SNAP_SIZE_DATA(pByteArray)  (snap_getDataSizeFromNdb(SNAP_HDB1_NDB(pByteArray)))    
#define SNAP_SIZE_HASH(pByteArray)  (snap_getHashSizeFromEdm(SNAP_HDB1_EDM(pByteArray)))    
#define SNAP_MIN_SIZE_FRAME         (SNAP_SIZE_SYNC + SNAP_SIZE_HEADER)                     
#define SNAP_MAX_SIZE_FRAME         (528U)                                                  
#ifdef SNAP_SIZE_USER_HASH
    #if (SNAP_SIZE_USER_HASH < 0) || (SNAP_SIZE_USER_HASH > 4)
        #error Invalid user hash size! It must be an integer from 0 to 4 (bytes).
    #endif
#else
    #define SNAP_SIZE_USER_HASH (0U)    
#endif
 
#define SNAP_INDEX_SYNC             (0U)                                                        
#define SNAP_INDEX_HDB2             (1U)                                                        
#define SNAP_INDEX_HDB1             (2U)                                                        
#define SNAP_INDEX_DAB              (3U)                                                        
#define SNAP_INDEX_SAB(pByteArray)  (SNAP_INDEX_DAB + SNAP_HDB2_DAB(pByteArray))                
#define SNAP_INDEX_PFB(pByteArray)  (SNAP_INDEX_SAB(pByteArray) + SNAP_HDB2_SAB(pByteArray))    
#define SNAP_INDEX_DATA(pByteArray) (SNAP_INDEX_PFB(pByteArray) + SNAP_HDB2_PFB(pByteArray))    
#define SNAP_INDEX_HASH(pByteArray) (SNAP_INDEX_DATA(pByteArray) +  SNAP_SIZE_DATA(pByteArray)) 
#define SNAP_BROADCAST_ADDRESS  (0U)    
#define SNAP_SYNC               (0x54U) 
#define SNAP_PADDING            (0x00U) 
#define snap_getSync()                              (SNAP_SYNC)                                                     
#define snap_getHdb2(pFrame)                        (SNAP_HDB2((pFrame)->buffer))                                   
#define snap_getHdb1(pFrame)                        (SNAP_HDB1((pFrame)->buffer))                                   
#define snap_getDab(pFrame)                         (SNAP_HDB2_DAB((pFrame)->buffer))                               
#define snap_getSab(pFrame)                         (SNAP_HDB2_SAB((pFrame)->buffer))                               
#define snap_getPfb(pFrame)                         (SNAP_HDB2_PFB((pFrame)->buffer))                               
#define snap_getAck(pFrame)                         (SNAP_HDB2_ACK((pFrame)->buffer))                               
#define snap_getCmd(pFrame)                         (SNAP_HDB1_CMD((pFrame)->buffer))                               
#define snap_getEdm(pFrame)                         (SNAP_HDB1_EDM((pFrame)->buffer))                               
#define snap_getNdb(pFrame)                         (SNAP_HDB1_NDB((pFrame)->buffer))                               
#define snap_getHeader(pFrame, pHeader)             (snap_getField(pFrame, pHeader, SNAP_FIELD_HEADER))             
#define snap_getDestAddress(pFrame, pDestAddr)      (snap_getField(pFrame, pDestAddr, SNAP_FIELD_DEST_ADDRESS))     
#define snap_getSourceAddress(pFrame, pSourceAddr)  (snap_getField(pFrame, pSourceAddr, SNAP_FIELD_SOURCE_ADDRESS)) 
#define snap_getProtocolFlags(pFrame, pFlags)       (snap_getField(pFrame, pFlags, SNAP_FIELD_PROTOCOL_FLAGS))      
#define snap_getData(pFrame, pData)                 (snap_getField(pFrame, pData, SNAP_FIELD_DATA))                 
#define snap_getHash(pFrame, pHash)                 (snap_getField(pFrame, pHash, SNAP_FIELD_HASH))                 
#define snap_getDataPtr(pFrame)                     ((pFrame)->buffer + SNAP_INDEX_DATA((pFrame)->buffer))          
#define snap_getBufferPtr(pFrame)                   ((pFrame)->buffer)                                              
#define snap_getStatus(pFrame)                      ((pFrame)->status)                                              
#define snap_getSyncIndex()             (SNAP_INDEX_SYNC)                   
#define snap_getHdb2Index()             (SNAP_INDEX_HDB2)                   
#define snap_getHdb1Index()             (SNAP_INDEX_HDB1)                   
#define snap_getHeaderIndex()           (SNAP_INDEX_HDB2)                   
#define snap_getDestAddrIndex()         (SNAP_INDEX_DAB)                    
#define snap_getSourceAddrIndex(pFrame) (SNAP_INDEX_SAB((pFrame)->buffer))  
#define snap_getProtFlagsIndex(pFrame)  (SNAP_INDEX_PFB((pFrame)->buffer))  
#define snap_getDataIndex(pFrame)       (SNAP_INDEX_DATA((pFrame)->buffer)) 
#define snap_getHashIndex(pFrame)       (SNAP_INDEX_HASH((pFrame)->buffer)) 
#define snap_getSyncSize()              (SNAP_SIZE_SYNC)                                                        
#define snap_getHdb2Size()              (SNAP_SIZE_HDB2)                                                        
#define snap_getHdb1Size()              (SNAP_SIZE_HDB1)                                                        
#define snap_getHeaderSize()            (SNAP_SIZE_HEADER)                                                      
#define snap_getDestAddrSize(pFrame)    (SNAP_HDB2_DAB((pFrame)->buffer))                                       
#define snap_getSourceAddrSize(pFrame)  (SNAP_HDB2_SAB((pFrame)->buffer))                                       
#define snap_getProtFlagsSize(pFrame)   (SNAP_HDB2_PFB((pFrame)->buffer))                                       
#define snap_getDataSize(pFrame)        (SNAP_SIZE_DATA((pFrame)->buffer))                                      
#define snap_getHashSize(pFrame)        (SNAP_SIZE_HASH((pFrame)->buffer))                                      
#define snap_getFrameSize(pFrame)       ((pFrame)->size)                                                        
#define snap_getBufferSize(pFrame)      ((pFrame)->maxSize)                                                     
#define snap_getFullFrameSize(pFrame)   (SNAP_INDEX_HASH((pFrame)->buffer) + SNAP_SIZE_HASH((pFrame)->buffer))  
/******************************************************************************/
/*  Public Types                                                              */
/******************************************************************************/
 
 
typedef enum snap_fieldType_t
{
    SNAP_FIELD_HEADER         = 0,  
    SNAP_FIELD_DEST_ADDRESS   = 1,  
    SNAP_FIELD_SOURCE_ADDRESS = 2,  
    SNAP_FIELD_PROTOCOL_FLAGS = 3,  
    SNAP_FIELD_DATA           = 4,  
    SNAP_FIELD_HASH           = 5   
} snap_fieldType_t;
 
typedef enum snap_hdb2_dab_t
{
    SNAP_HDB2_DAB_NO_DEST_ADDRESS    = 0,   
    SNAP_HDB2_DAB_1BYTE_DEST_ADDRESS = 1,   
    SNAP_HDB2_DAB_2BYTE_DEST_ADDRESS = 2,   
    SNAP_HDB2_DAB_3BYTE_DEST_ADDRESS = 3    
} snap_hdb2_dab_t;
 
typedef enum snap_hdb2_sab_t
{
    SNAP_HDB2_SAB_NO_SOURCE_ADDRESS    = 0, 
    SNAP_HDB2_SAB_1BYTE_SOURCE_ADDRESS = 1, 
    SNAP_HDB2_SAB_2BYTE_SOURCE_ADDRESS = 2, 
    SNAP_HDB2_SAB_3BYTE_SOURCE_ADDRESS = 3  
} snap_hdb2_sab_t;
 
typedef enum snap_hdb2_pfb_t
{
    SNAP_HDB2_PFB_NO_PROTOCOL_FLAGS    = 0, 
    SNAP_HDB2_PFB_1BYTE_PROTOCOL_FLAGS = 1, 
    SNAP_HDB2_PFB_2BYTE_PROTOCOL_FLAGS = 2, 
    SNAP_HDB2_PFB_3BYTE_PROTOCOL_FLAGS = 3  
} snap_hdb2_pfb_t;
 
typedef enum snap_hdb2_ack_t
{
    SNAP_HDB2_ACK_NOT_REQUESTED = 0,    
    SNAP_HDB2_ACK_REQUESTED     = 1,    
    SNAP_HDB2_ACK_RESPONSE_ACK  = 2,    
    SNAP_HDB2_ACK_RESPONSE_NACK = 3     
} snap_hdb2_ack_t;
 
typedef enum snap_hdb1_cmd_t
{
    SNAP_HDB1_CMD_MODE_DISABLED = 0,    
    SNAP_HDB1_CMD_MODE_ENABLED  = 1     
} snap_hdb1_cmd_t;
 
typedef enum snap_hdb1_edm_t
{
    SNAP_HDB1_EDM_NO_ERROR_DETECTION = 0,   
    SNAP_HDB1_EDM_3_RETRANSMISSION   = 1,   
    SNAP_HDB1_EDM_8BIT_CHECKSUM      = 2,   
    SNAP_HDB1_EDM_8BIT_CRC           = 3,   
    SNAP_HDB1_EDM_16BIT_CRC          = 4,   
    SNAP_HDB1_EDM_32BIT_CRC          = 5,   
    SNAP_HDB1_EDM_FEC                = 6,   
    SNAP_HDB1_EDM_USER_SPECIFIED     = 7    
} snap_hdb1_edm_t;
 
typedef enum snap_hdb1_ndb_t
{
    SNAP_HDB1_NDB_NO_DATA        =  0,  
    SNAP_HDB1_NDB_1BYTE_DATA     =  1,  
    SNAP_HDB1_NDB_2BYTE_DATA     =  2,  
    SNAP_HDB1_NDB_3BYTE_DATA     =  3,  
    SNAP_HDB1_NDB_4BYTE_DATA     =  4,  
    SNAP_HDB1_NDB_5BYTE_DATA     =  5,  
    SNAP_HDB1_NDB_6BYTE_DATA     =  6,  
    SNAP_HDB1_NDB_7BYTE_DATA     =  7,  
    SNAP_HDB1_NDB_8BYTE_DATA     =  8,  
    SNAP_HDB1_NDB_16BYTE_DATA    =  9,  
    SNAP_HDB1_NDB_32BYTE_DATA    = 10,  
    SNAP_HDB1_NDB_64BYTE_DATA    = 11,  
    SNAP_HDB1_NDB_128BYTE_DATA   = 12,  
    SNAP_HDB1_NDB_256BYTE_DATA   = 13,  
    SNAP_HDB1_NDB_512BYTE_DATA   = 14,  
    SNAP_HDB1_NDB_USER_SPECIFIED = 15   
} snap_hdb1_ndb_t;
 
typedef enum snap_status_t
{
    SNAP_STATUS_IDLE           =  0,    
    SNAP_STATUS_INCOMPLETE     =  1,    
    SNAP_STATUS_VALID          =  2,    
    SNAP_STATUS_ERROR_HASH     = -1,    
    SNAP_STATUS_ERROR_OVERFLOW = -2     
} snap_status_t;
 
typedef struct snap_header_t
{
    // HDB2
    unsigned int dab : 2;   
    unsigned int sab : 2;   
    unsigned int pfb : 2;   
    unsigned int ack : 2;   
    // HDB1
    unsigned int cmd : 1;   
    unsigned int edm : 3;   
    unsigned int ndb : 4;   
} snap_header_t;
 
typedef struct snap_fields_t
{
    uint8_t       *data;            
    uint32_t      destAddress;      
    uint32_t      sourceAddress;    
    uint32_t      protocolFlags;    
    snap_header_t header;           
    uint16_t      dataSize;         
    bool          paddingAfter;     
} snap_fields_t;
 
typedef struct snap_frame_t
{
    uint8_t  *buffer;   
    uint16_t maxSize;   
    uint16_t size;      
    int8_t   status;    
} snap_frame_t;
 
/******************************************************************************/
/*  Public Function Declarations                                              */
/******************************************************************************/
 
 
int16_t snap_init(snap_frame_t *frame, uint8_t *buffer, uint16_t maxSize);
 
void snap_reset(snap_frame_t *frame);
 
int8_t snap_decode(snap_frame_t *frame, uint8_t newByte);
 
int8_t snap_encapsulate(snap_frame_t *frame, snap_fields_t *fields);
 
int16_t snap_getField(const snap_frame_t *frame, void *fieldContent, uint8_t fieldType);
 
int8_t snap_calculateHash(const snap_frame_t *frame, uint32_t *hash);
 
uint16_t snap_removePaddingBytes(uint8_t *data, uint16_t size, bool paddingAfter);
 
uint8_t snap_getNdbFromDataSize(uint16_t dataSize);
 
uint16_t snap_getDataSizeFromNdb(uint8_t ndb);
 
uint8_t snap_getHashSizeFromEdm(uint8_t edm);
 
uint8_t snap_calculateChecksum8(const uint8_t *data, uint16_t size);
 
uint8_t snap_calculateCrc8(const uint8_t *data, uint16_t size);
 
uint16_t snap_calculateCrc16(const uint8_t *data, uint16_t size);
 
uint32_t snap_calculateCrc32(const uint8_t *data, uint16_t size);
 
uint32_t snap_calculateUserHash(const uint8_t *data, uint16_t size);
 
#ifdef __cplusplus
    }
#endif
 
#endif  // SNAP_H_
 
/******************************** END OF FILE *********************************/