CLCm_TransportProtocol.h

Go to the documentation of this file.

//*********************************************************
// File:            CLCm_TransportProtocol.h
// Project:         CopperLan CHAILink SDK Common Part
//                  For Client & Server
// Version:         1.3
// Release Date:    2014/04/15
//*********************************************************

/********************************************************************
Software License Agreement:  CHAILink Client source code

The software supplied herewith by Klavis Technology (the “Company”) is intended and
supplied to you, the Company’s customer, for use solely and exclusively on embedded
CopperLan products needing a CHAILink Client. 
 The software is owned by the Company and/or its supplier, and is protected 
 under applicable copyright laws. All rights are reserved. Any use in violation of the 
 foregoing restrictions may subject the user to criminal sanctions under applicable laws,
as well as to civil liability for the breach of the terms and conditions of this license.

THIS SOFTWARE MUST REMAIN UNMODIFIED. NO WARRANTIES, WHETHER EXPRESS, 
 IMPLIED OR STATUTORY, INCLUDING, BUT NOT LIMITED TO, IMPLIED WARRANTIES OF 
 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE APPLY TO THIS SOFTWARE
IN CASE OF SOURCE CODE CHANGE BY THE CUSTOMER. IN CASE OF SUCH CHANGE, THE
COMPANY SHALL NOT BE LIABLE FOR SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES
OF ANY KIND.
********************************************************************/


#ifndef __CLCM_TRANSPORTPROTOCOL_H__
#define __CLCM_TRANSPORTPROTOCOL_H__

#include "CLCm_Message.h"
#include "CLCm_Transport.h"

#ifdef __cplusplus
extern "C" {
#endif


//=============================================================================================
// Transport protocol: perform some checks
//=============================================================================================

#if !defined(_CLTP_CLIENTMODE) && !defined(_CLTP_SERVERMODE)
#error '_CLTP_CLIENTMODE' or '_CLTP_SERVERMODE' must be defined!!
#endif

//=============================================================================================
// Transport protocol map
// Standard Endianness for serialization is Little Endian
//=============================================================================================

/*  Frame Header Format
        mm mv       : frame start (2 * 8 bit)  - mm m: Marker (0xFE 0xA_) v: version currently 1 
        cmdsize     : Transport Command / Size word (16 bit)
                    :   b15 b14 b13 b12 b11 b10 b9  b8  b7  b6  b5  b4  b3  b2  b1  b0
                        c4  c3  c2  c1  c0  s10 s9  s8  s7  s6  s5  s4  s3  s2  s1  s0
                      c[4-0] : Command
                      s[10-0] : Payload size
        PL          : Payload (s bytes). buffer start pointer is and must be 4 bytes aligned

    Details about CHAILink Message Payload -> CLCm_Message.h
*/

//=============================================================================================
// Transport protocol: frame start defines (CLTP is for CHAILink Transport Protocol)
//=============================================================================================
#define CLTP_FRAMESTART_01          (0xFE)      // marker byte 1
#define CLTP_FRAMESTART_02          (0xA1)      // Marker byte 2 with version 1
#define CLTP_FRAMESTART_SIZE        (2)
#define CLTP_FRAMESTART_POS         (0)

//=============================================================================================
// Transport protocol: command defines
//=============================================================================================

// Commands sends in handshaking step:
//
// CLC side                         CLS side                        Remarks
// -------------------------------------------------------------------------------------------------------------------------------------
//
//  CLTP_CMD_SETINITPARAMS  ->                                      Client send Init parameters (passthru ethernet, keepalive, CLTP FrameSize, CL FrameSize)
//
//                          <-       CLTP_CMD_SETINITPARAMSACK      Server respond with an error code : connection is established if errorcode  = CLTP_ErrorCode_Success
//

// Direction
#define CLTP_CMD_DIR_MASK           (0x8000)
#define CLTP_CMD_DIR_TOCLIENT       (0x0000)
#define CLTP_CMD_DIR_TOSERVER       (0x8000)

#define CLTP_CMD_OPCODE_MASK        (0xF800)                            
#define CLTP_CMD_OPCODE_POS         (11)                            
#define CLTP_CMD_PAYLOADSIZE_MASK   (0x07FF)                            

// Commands TPSS to TPCS
//      TPCS: Transport Protocol Client Side
//      TPSS: Transport Protocol Server Side
#define CLTP_CMD_SETINITPARAMSACK   ((0 << CLTP_CMD_OPCODE_POS) | CLTP_CMD_DIR_TOCLIENT)        // TPSS must send this command to confirm that it has well received init parameters from TPCS it contains 1 byte with error code
#define CLTP_CMD_KEEPALIVE          ((1 << CLTP_CMD_OPCODE_POS) | CLTP_CMD_DIR_TOCLIENT)        // If TPCS is configured to accept Keep Alive, TPSS sends periodically this command
#define CLTP_CMD_RESETCLIENTSTATE   ((2 << CLTP_CMD_OPCODE_POS) | CLTP_CMD_DIR_TOCLIENT)        // The server asks the client to reset its state
#define CLTP_CMD_CLIENTCLCMD        ((3 << CLTP_CMD_OPCODE_POS) | CLTP_CMD_DIR_TOCLIENT)        // Command sent to CHAILink Client (Notification or Asynchronous return)

// Commands TPCS to TPSS
#define CLTP_CMD_SETINITPARAMS      ((0 << CLTP_CMD_OPCODE_POS) | CLTP_CMD_DIR_TOSERVER)        // 
#define CLTP_CMD_ACKKEEPALIVE       ((1 << CLTP_CMD_OPCODE_POS) | CLTP_CMD_DIR_TOSERVER)        // Command sent when TPCS received _CLTP_CMD_KEEPALIVE from TPSS
#define CLTP_CMD_RESETSERVERSTATE   ((2 << CLTP_CMD_OPCODE_POS) | CLTP_CMD_DIR_TOSERVER)        // The Client asks the server to reset its state
#define CLTP_CMD_SERVERCLCMD        ((3 << CLTP_CMD_OPCODE_POS) | CLTP_CMD_DIR_TOSERVER)        // Payload is for CHAILink Server

#define CLTP_CMD_SIZE               (2)
#define CLTP_CMD_POS                (CLTP_FRAMESTART_POS + CLTP_FRAMESTART_SIZE)

//=============================================================================================
// Transport protocol: Client init parameters bits defines for _CLTP_CMD_SETINITPARAMS command
//=============================================================================================
#define CLTP_INITPARAMS_KEEPALIVE_MASK                  0x01
#define CLTP_INITPARAMS_PASSTHRU_MASK                   0x02

//=============================================================================================
// Transport protocol: header defines
//=============================================================================================
#define CLTP_HEADERSIZE         (CLTP_FRAMESTART_SIZE + CLTP_CMD_SIZE)

//=============================================================================================
// Transport protocol: CRC defines
//=============================================================================================
#define CLTP_CRC_SIZE           (1)

//=============================================================================================
// Transport protocol: Global defines
//=============================================================================================

// If server mode or if Ethernet Patssthru is enabled, force transport buffer to the maximum size. 
#if defined(_CLTP_SERVERMODE) || defined(ENABLE_ETHERNET_PASSTHRU)
#define CLTPRT_PAYLOADMAXSIZE                   CLMSG_MESSAGEMAXSIZE
#else
#define CLTPRT_PAYLOADMAXSIZE                   CLMSG_MESSAGESIZE
#endif

#define CLTPRT_FRAMEMAXSIZE     (CLTPRT_PAYLOADMAXSIZE + CLTP_HEADERSIZE + CLTP_CRC_SIZE)
#define CLTPRT_FRAMEMINSIZE     (CLMSG_MESSAGEMINSIZE + CLTP_HEADERSIZE + CLTP_CRC_SIZE)

//=============================================================================================
// Transport protocol: action status
//=============================================================================================
// PS: 'CLTPCS' is for CHAILink Transport Protocol Client Status
typedef enum
{
    CLTPCS_None                     = 0x0000,
    CLTPCS_KeepAliveActive          = 0x0001,
    CLTPCS_TransportConnected       = 0x0002,
    CLTPCS_Connected                = 0x0004
} CLTPCStatus;

// PS: 'CLTPSS' is for CHAILink Transport Protocol Server Status
typedef enum
{
    CLTPSS_None                     = 0x0000,
    CLTPSS_KeepAliveActive          = 0x0001,
    CLTPSS_KeepAliveSent            = 0x0002,
    CLTPSS_Connected                = 0x0004,
    CLTPSS_EthernetEnabled          = 0x0008
} CLTPSStatus;

//=============================================================================================
// Transport protocol: parser status
//=============================================================================================
// PS: 'CLTPPS' is for CHAILink Transport Protocol Parser Status
typedef enum
{
    CLTPPS_WaitingSync,
    CLTPPS_ReceivingHeader,
    CLTPPS_ReceivingPayload,
    CLTPPS_CRC,
    CLTPPS_FrameComplete
} ParserStatus;


typedef enum {
    CLTP_ErrorCode_Success = 0,
    CLTP_ErrorCode_BadParamameter,
    CLTP_ErrorCode_TransportWriteError,
    CLTP_ErrorCode_TransportCantWriteAllDatas,
    CLTP_ErrorCode_InitParamsAckTimedOut,
    CLTP_ErrorCode_FrameBadRouting,
    CLTP_ErrorCode_CLTPFrameSizeTooLong,
    CLTP_ErrorCode_CLTPFrameSizeTooShort,
    CLTP_ErrorCode_FrameParsingError
}CLTP_ErrorCode;

typedef enum {
    CLTP_ResetCode_ServerConnectionLost = 0,    
    CLTP_ResetCode_KeepAlive,                   
    CLTP_ResetCode_PeerAskResetState,           
    CLTP_ResetCode_ClientReconnection,          
    CLTP_ResetCode_StateMismatch                
}CLTP_ResetCode;


//=============================================================================================
// Transport protocol: timing
//=============================================================================================

// After transport protocol (client side) has received its ID, it sends '_CLTP_CMD_SETINITPARAMS' 
// command. If there is no answer after this timeout, transport protocol goes back to init step.
#define CLTP_WAITINITPARAMSACK_TIMEOUTMS                    2000

// Transport inactivity time after which server send keep alive to client (in milliseconds)
#define CLTP_CLSKEEPALIVE_DELAYBEFORESENDING                500
// Maximum delay waiting ACK from client after which server consider this client is down (in milliseconds)
#define CLTP_CLSKEEPALIVE_DELAYBEFORERESET                  2000
// Maximum delay between two keep alive after which a client consider the server is down (in milliseconds)
#define CLTP_CLCKEEPALIVE_DELAYBEFORERESET                  2000

//=============================================================================================
// Transport protocol Interface : Callbacks for CLTP => CL communication
//=============================================================================================

// CLTP_ERRORCB : Callback for error reporting from CLTP to CHAILink. Helpful for debugging
//      bReason : [In] Error code. see CLTP_ERRORCODE_xxx defines
//      pParam : [In] CHAILink callback param (CLTP_CALLBACKS.pParam)
typedef void (*CLTP_ERRORCB)( CLTP_ErrorCode reason, void * const pParam);
// CLTP_FRAMRECEIVEDCB : Callback for CHAILink frame reception
//      pBuffer : [In] Pointer to the received CHAILink message
//      wSize : [In] CHAILink message size
//      pParam : [In] CHAILink callback param (CLTP_CALLBACKS.pParam)
typedef void (*CLTP_FRAMRECEIVEDCB)( CPBYTE * pBuffer, CPUINT16 wSize, void * const pParam);
// CLTP_CONNECTIONSTATECHANGEDCB : Callback for CLTP connection status change.
//      fConnected : [In] TRUE if Peer is connected, FALSE if Peer is disconnected
//      wData : [In] if fConnected is TRUE, wData contains wMaxMessageSize, the maximum peer payload size.
//                   if fConnected is FALSE, wData contains the disconnection reason see CLTP_RESETCODE_xxx
//      pParam : [In] CHAILink callback param (CLTP_CALLBACKS.pParam)
typedef void (*CLTP_CONNECTIONSTATECHANGEDCB)( CPBOOLEAN fConnected, CPUINT16 wData, void * const pParam);


typedef void (*CLTP_LOCK)(CPBOOLEAN fLock, void * const pParam);

typedef struct  
{
    CLTP_ERRORCB                    pfnErrorCB;
    CLTP_FRAMRECEIVEDCB             pfnReceiveCB;
    CLTP_CONNECTIONSTATECHANGEDCB   pfnConnectionStateChangedCB;
#if defined(_CLTP_SERVERMODE)
    CLTP_LOCK                       pfnLock;
#endif
    void *                          pParam;
}CLTP_Callbacks;


//=============================================================================================
// Transport protocol: working structures
//=============================================================================================
// Will contains decoded header data and parsing informations
typedef struct
{
    volatile CPBYTE*        pbFillingCursor;                        // Pointer where to save data from transport to arbIncomingFrame
    CPUINT16                wCommand;                               // Frame's command
    CPUINT16                wPayloadSize;                           // Frame's Payload size
    CPUINT16                wStatus;                                // Parser Status
} CLTP_ParserData;

#if defined(_CLTP_CLIENTMODE)
typedef struct
{
    CPUINT32                dwConnectTimer;
    CPUINT32                dwCLCInactivityTimer;
    CLTPCStatus             eStatus;
} CLTP_CLCVariables;
#endif

#if defined(_CLTP_SERVERMODE)
typedef struct _CLTP_CLSVariables
{
    volatile CPUINT32       dwKeepAliveTimer;
    CLTPSStatus             eStatus;
} CLTP_CLSVariables, *PCLTP_CLSVariables;
#endif

// Will contains all necessary data to work on frame
typedef struct
{
    CPBYTE                  *pIncomingFrame;
    CPBYTE                  *pOutgoingFrame;
    CLT_Interface           transportInterface;                     // Interface with physical transport
    CLTP_Callbacks          Callbacks;                              // Callbacks to CHAILink for transport reset or error

    CLTP_ParserData         ParserData;                             // Contains frame header information
#if defined(_CLTP_CLIENTMODE)
    CLTP_CLCVariables       CLCVariables;                           // Contains some specific variables for CHAILink Client
#elif defined(_CLTP_SERVERMODE)
    CLTP_CLSVariables       CLSVariables;                           // Contains some specific variables for CHAILink Server
#endif
    CPBYTE                  arbIncomingFrameT[CLTPRT_PAYLOADMAXSIZE + 3];       // Buffer used to save frame being decoded
    CPBYTE                  arbOutgoingFrameT[CLTPRT_PAYLOADMAXSIZE + 3];       // Buffer used to prepare frame before sending
} CLTP_Working;

//=========================================================================
// Transport protocol: API
//=========================================================================
// CLTP_Init : Init the transport protocol
//  pWorking : [In] CLTP working data
//  pCB : [In] CHAILink callbacks for Transport protocol Interface
//  pTransportInterface : [In] Transport interface
//
//  Return : Error code (see CLTP_ErrorCode)
CLTP_ErrorCode  CLTP_Init(CLTP_Working * const pWorking, CLTP_Callbacks const * const pCB, CLT_Interface const * const pTransportInterface);

// CLTP_DoProcess : Give processing time to CLTP. Must be called periodically.
//  pWorking : [In] CLTP working data
void CLTP_DoProcess(CLTP_Working * const pWorking);

// CLTP_ProcessTransport : Give processing time only to transport DoProcess.
//  pWorking : [In] CLTP working data
void CLTP_ProcessTransport(CLTP_Working * const pWorking);

// CLTP_IsReady : Check if CLTP is ready (connected).
//  pWorking : [In] CLTP working data
//
//  Return : TRUE if Ready
CPBOOLEAN CLTP_IsReady(CLTP_Working * const pWorking);

// CLTP_GetOutgoingBuffer : Get outgoing payload buffer pointer in CLTP working data. Used to build frame in place
#define CLTP_GetOutgoingBuffer(pWorking)            ((pWorking)->pOutgoingFrame + CLTP_HEADERSIZE)

// CLTP_WritePayload : Send a CHAILink frame to the peer (TPCS => TPCC or TPCC => TPCS).
//  pWorking : [In] CLTP working data
//  pbPayload : [In] Pointer to the CHAILink frame
//  wPayloadSize : [In] CHAILink frame size in byte
//  pwWritten : [out] number of bytes effectively written
//
//  Returned : TRUE if write was successful
CPBOOLEAN CLTP_WritePayload(CLTP_Working * const pWorking, CPBYTE const * const pbPayload, CPUINT16 const wPayloadSize, CPUINT16 * const pwWritten);

#if defined(_CLTP_CLIENTMODE)
// CLTP_SetKeepAlive : Set keep alive mode for TPCC. Default is Active
//                     This function must be called just after CLTP_Init.
//  pWorking : [In] CLTP working data
//  fActive : [In] Keep alive active or not.
void CLTP_SetKeepAlive(CLTP_Working * const pWorking, CPBOOLEAN const fActive);
#endif

// CLTP_ResetPeerState : Send a Reset state command to the peer (TPCS => TPCC or TPCC => TPCS).
//                       This function also resets Transport protocol state and do not call Connection state change callback.
//  pWorking : [In] CLTP working data
void CLTP_ResetPeerState(CLTP_Working * const pWorking);

// CLTP_ComputeCRC : Compute a CRC-8.
//  pData : [In] Pointer to the data buffer
//  wDataSize : [In] The data buffer size
//
//  Returned : The CRC-8 value
CPBYTE CLTP_ComputeCRC( CPBYTE const * const pData, CPUINT16 const wDataSize );


#ifdef __cplusplus
}
#endif

#endif // __CLCM_TRANSPORTPROTOCOL_H__