src/EPTF_COAP_LocalTransport_Definitions.ttcn

///////////////////////////////////////////////////////////////////////////////
//
// Copyright (c) 2000-2021 Ericsson Telecom AB
//
// All rights reserved. This program and the accompanying materials
// are made available under the terms of the Eclipse Public License v2.0
// which accompanies this distribution, and is available at
// https://www.eclipse.org/org/documents/epl-2.0/EPL-2.0.html
///////////////////////////////////////////////////////////////////////////////
//  File:               EPTF_COAP_LocalTransport_Definitions.ttcn
//  Description:
//  Rev:                R1B
//  Prodnr:             CNL 113 858
//  Updated:            2021-02-03
//  Contact:            http://ttcn.ericsson.se
///////////////////////////////////////////////////////////////////////////////

///////////////////////////////////////////////////////////
//  Module: EPTF_COAP_LocalTransport_Definitions
// 
//  Purpose:
//    This module contains the definitions for the COAP load generator component
//
//  Module depends on:
//    - <EPTF_COAP_Transport_Definitions>
//    - <EPTF_CLL_Base_Definitions>
//    - <EPTF_CLL_Logging_Definitions>
//    - <EPTF_CLL_FBQ_Definitions>
//    - <EPTF_CLL_TransportIPL4_Definitions>
//    - <EPTF_CLL_RBTScheduler_Definitions>
//    - <IPL4asp_Types>
// 
//  Module Parameters:
//    tsp_EPTF_COAP_LocalTransport_debug - <tsp_EPTF_COAP_LGen_debug> - *boolean* - Enabled/disable debug logging
//    tsp_EPTF_COAP_LocalTransport_debugVerbose - <tsp_EPTF_COAP_LGen_debugVerbose> - *boolean* - Enable/disable verbose debug logging
//
//  Class Diagram:
//   (see EPTF_COAP_LocalTransport_Definitions.classes.jpg)
//
///////////////////////////////////////////////////////////////
module EPTF_COAP_LocalTransport_Definitions
{
  import from EPTF_COAP_Transport_Definitions all;
  import from EPTF_CLL_Base_Definitions all;
  import from EPTF_CLL_Logging_Definitions all;
  import from EPTF_CLL_FBQ_Definitions all;
  import from EPTF_CLL_TransportIPL4_Definitions all;
  import from EPTF_CLL_RBTScheduler_Definitions all;
  import from IPL4asp_Types all;

  modulepar boolean tsp_EPTF_COAP_LocalTransport_debug := false;
  modulepar boolean tsp_EPTF_COAP_LocalTransport_debugVerbose := false;

  const charstring c_COAP_Transport_LGenType := "COAP_Transport";

  const integer c_COAP_LocalTransport_Logging_WARNING := 0;
  const integer c_COAP_LocalTransport_Logging_DEBUG := 1;
  const integer c_COAP_LocalTransport_Logging_DEBUGV := 2;
  const integer c_COAP_LocalTransport_Logging_ERROR := 3;

 /*****************************************************************
   @startuml EPTF_COAP_LocalTransport_Definitions.classes.jpg
 
   class EPTF_COAP_LocalTransport_CT {
     boolean v_EPTF_COAP_LocalTransport_initialized
     integer v_EPTF_COAP_LocalTransport_loggingMaskId
     SocketEntry   v_COAP_LocalTransport_currentSocket
     SocketDB      v_COAP_LocalTransport_localSocketDB
     EPTF_COAP_Transport_Statistics v_EPTF_COAP_Transport_stats
     f_EPTF_COAP_LocalTransport_init()
     f_EPTF_COAP_LocalTransport_initLogging()
     f_EPTF_COAP_LocalTransport_cleanup()
     f_EPTF_COAP_IPL4asp_getMsgLen(in octetstring stream, inout ro_integer args)
     f_EPTF_COAP_IPL4asp_handleEvent(...)
     f_EPTF_COAP_IPL4asp_handleMessage(...)
     f_EPTF_COAP_LocalTransport_send(in EPTF_COAP_PDU pl_msg)
     f_EPTF_COAP_LocalTransport_transportApiRequest(EPTF_COAP_Transport_Request pl_req)
     f_EPTF_COAP_LocalTransport_startSocket(in Socket p_sock, in ProtoTuple p_proto, in integer p_eIdx, inout integer p_idx)
     f_EPTF_COAP_LocalTransport_startDTLS(in EPTF_COAP_Transport_dtlsConnect p_params, in integer p_eIdx, inout integer p_idx)
     f_EPTF_COAP_LocalTransport_IPL4_sendTo(...)
     f_EPTF_COAP_LocalTransport_IPL4_send(in integer pl_connId,in ProtoTuple  pl_proto,in octetstring pl_msg)
   }
   EPTF_COAP_LocalTransport_CT "1" --> "1\n.v_COAP_LocalTransport_localSocketDB" SocketDB
   EPTF_COAP_LocalTransport_CT "1" --> "0..1\n.v_COAP_LocalTransport_currentSocket" SocketEntry
   EPTF_COAP_LocalTransport_CT "1" --> "1\n.v_EPTF_COAP_Transport_stats" EPTF_COAP_Transport_Statistics
  
   class SocketEntry {  
     Socket          addr
     DTLSConnection  dtls
     ProtoTuple      proto
     ConnectionId    connId
     SocketState     state
     integer         eIdx
     f_EPTF_COAP_SocketEntry_hash(in SocketEntry p_entry)
     f_EPTF_COAP_Socket_hash(Socket p_sock)
   }
   SocketEntry "1" --> "0..1\n.dtls" DTLSConnection
  
   class SocketDB {
     EPTF_FreeBusyQueue queue
     SocketEntry_List data
     integer hashRef
     integer connId2eIdx_hashRef
     f_EPTF_COAP_LocalTransport_socketDB_init()
     f_EPTF_COAP_LocalTransport_socketDB_cleanUp()
     f_EPTF_COAP_LocalTransport_socketDB_add(in SocketEntry p_entry)
     f_EPTF_COAP_LocalTransport_socketDB_lookUp_localAddr(in Socket p_localAddr)
     f_EPTF_COAP_LocalTransport_socketDB_lookUp_dtlsConnection(in Socket p_local, in Socket p_remote)
     f_EPTF_COAP_LocalTransport_socketDB_lookUp_connId(in integer p_connId)
     f_EPTF_COAP_LocalTransport_socketDB_get(in integer p_idx, inout SocketEntry p_sock)
     f_EPTF_COAP_LocalTransport_socketDB_remove(in integer p_idx)
   }
   SocketDB "1" --> "*\n.data" SocketEntry
  
   class DTLSConnection {
    Socket          remoteAddr
    charstring      pskIndetity
    charstring      pskKey
    f_EPTF_COAP_DTLSConnection_hash(in Socket p_local, in Socket p_remote)
   }
  
   class EPTF_COAP_Transport_Statistics {
    integer   nofOpenConnections
    integer   nofTransportWarnings
    float     nofReceivedMessages
    float     nofSentMessages
    float     nofReceivedBytes
    float     nofSentBytes
   }
   @enduml
  ******************************************************************/
 /*****************************************************************
   @startuml EPTF_COAP_LocalTransport_Definitions.EPTF_COAP_LocalTransport_CT.jpg
     class EPTF_COAP_LocalTransport_CT {
       boolean v_EPTF_COAP_LocalTransport_initialized
       integer v_EPTF_COAP_LocalTransport_loggingMaskId
       SocketEntry   v_COAP_LocalTransport_currentSocket
       SocketDB      v_COAP_LocalTransport_localSocketDB
       EPTF_COAP_Transport_Statistics v_EPTF_COAP_Transport_stats
       f_EPTF_COAP_LocalTransport_init()
       f_EPTF_COAP_LocalTransport_initLogging()
       f_EPTF_COAP_LocalTransport_cleanup()
       f_EPTF_COAP_IPL4asp_getMsgLen(in octetstring stream, inout ro_integer args)
       f_EPTF_COAP_IPL4asp_handleEvent(...)
       f_EPTF_COAP_IPL4asp_handleMessage(...)
       f_EPTF_COAP_LocalTransport_send(in EPTF_COAP_PDU pl_msg)
       f_EPTF_COAP_LocalTransport_transportApiRequest(EPTF_COAP_Transport_Request pl_req)
       f_EPTF_COAP_LocalTransport_startSocket(in Socket p_sock, in ProtoTuple p_proto, in integer p_eIdx, inout integer p_idx)
       f_EPTF_COAP_LocalTransport_startDTLS(in EPTF_COAP_Transport_dtlsConnect p_params, in integer p_eIdx, inout integer p_idx)
       f_EPTF_COAP_LocalTransport_IPL4_sendTo(...)
       f_EPTF_COAP_LocalTransport_IPL4_send(in integer pl_connId,in ProtoTuple  pl_proto,in octetstring pl_msg)
     }
   @enduml
  ******************************************************************/
  ///////////////////////////////////////////////////////////
  // Type: EPTF_COAP_LGen_CT
  //
  // Purpose:
  //   COAP local transport component
  //
  // Class:
  //   (see EPTF_COAP_LocalTransport_Definitions.EPTF_COAP_LocalTransport_CT.jpg)
  //
  // Extensions:
  //  - <EPTF_COAP_Transport_Provider_CT>
  //  - <EPTF_TransportIPL4_CT>
  //  - <EPTF_Base_CT>
  //  - <EPTF_Logging_CT>
  //  - <EPTF_Scheduler_CT>
  //
  // Ports:
  //   -
  //
  // Timers:
  //   -
  //
  // Variables:
  //   v_EPTF_COAP_LocalTransport_initialized  - *boolean* - Flag to indicate if the init function was already called
  //   v_EPTF_COAP_LocalTransport_loggingMaskId - *integer* - logging mask id
  //   v_EPTF_COAP_Transport_stats - <EPTF_COAP_Transport_Statistics> - Counters for transport statistics
  // 
  // Instance databases:
  //   v_COAP_LocalTransport_localSocketDB - <SocketDB> - Storing the managed transport endpoints
  //
  // Related Functions:
  //   - <f_EPTF_COAP_LocalTransport_init> ()
  //   - <f_EPTF_COAP_LocalTransport_initLogging> ()
  //   - <f_EPTF_COAP_LocalTransport_cleanup> ()
  //   - <f_EPTF_COAP_IPL4asp_getMsgLen> (in *octetstring* stream, inout <ro_integer> args)
  //   - <f_EPTF_COAP_IPL4asp_handleEvent> (...)
  //   - <f_EPTF_COAP_IPL4asp_handleMessage> (...)
  //   - <f_EPTF_COAP_LocalTransport_send> (in <EPTF_COAP_PDU> pl_msg)
  //   - <f_EPTF_COAP_LocalTransport_transportApiRequest> (<EPTF_COAP_Transport_Request> pl_req)
  //   - <f_EPTF_COAP_LocalTransport_startSocket> (in <Socket> p_sock, in <ProtoTuple> p_proto, in *integer* p_eIdx, inout *integer* p_idx)
  //   - <f_EPTF_COAP_LocalTransport_startDTLS> (in <EPTF_COAP_Transport_dtlsConnect> p_params, in *integer* p_eIdx, inout *integer* p_idx)
  //   - <f_EPTF_COAP_LocalTransport_IPL4_sendTo> (...)
  //   - <f_EPTF_COAP_LocalTransport_IPL4_send> (in *integer* pl_connId,in <ProtoTuple>  pl_proto, in *octetstring* pl_msg)
  ///////////////////////////////////////////////////////////
  type component EPTF_COAP_LocalTransport_CT
    extends EPTF_COAP_Transport_Provider_CT, EPTF_Base_CT, 
    EPTF_Logging_CT, EPTF_TransportIPL4_CT, EPTF_Scheduler_CT
  {
    var boolean       v_EPTF_COAP_LocalTransport_initialized := false;
    var integer       v_EPTF_COAP_LocalTransport_loggingMaskId;

    var SocketEntry   v_COAP_LocalTransport_currentSocket;

    // database:
    var SocketDB      v_COAP_LocalTransport_localSocketDB;

    // statistics:
    var EPTF_COAP_Transport_Statistics  v_EPTF_COAP_Transport_stats;
  }

 /*****************************************************************
   @startuml EPTF_COAP_LocalTransport_Definitions.SocketEntry.jpg
   class SocketEntry {  
     Socket          addr
     DTLSConnection  dtls
     ProtoTuple      proto
     ConnectionId    connId
     SocketState     state
     integer         eId
     f_EPTF_COAP_SocketEntry_hash(in SocketEntry p_entry)
     f_EPTF_COAP_Socket_hash(Socket p_sock)
   }
   @enduml
  ******************************************************************/
  ///////////////////////////////////////////////////////////
  //  Type: SocketEntry
  //
  //  Purpose:
  //    Storing the transport related data of a COAP transport endpoint
  //
  //  Class:
  //    (see EPTF_COAP_LocalTransport_Definitions.SocketEntry.jpg)
  //
  //  Elements:
  //    addr  - <Socket> - local address and local port
  //    dtls  - <DTLSConnection> - in case DTLS (PSK) is used, the remote address and port with keys are stored here
  //    proto  - <ProtoTuple> - transport protocol description
  //    connId  - <ConnectionId> - connection id from the IPL4 transport layer
  //    state  - <SocketState> - state of the socket
  //    eIdx  - <integer> - the index of the entity (COAP device) who owns this socket
  //
  //  Related Functions:
  //    - <f_EPTF_COAP_SocketEntry_hash> (in <SocketEntry> p_entry)
  //    - <f_EPTF_COAP_Socket_hash> (<Socket> p_sock)
  ///////////////////////////////////////////////////////////  
  type record SocketEntry
  {
    Socket          addr,
    DTLSConnection  dtls optional,
    ProtoTuple      proto,
    ConnectionId    connId,
    SocketState     state,
    integer         eIdx
  }

  ///////////////////////////////////////////////////////////
  //  Enum: SocketState
  //
  //  Purpose:
  //    States of a <SocketEntry>
  //
  //  Elements:
  //    - UNUSED
  //    - CLOSED
  //    - OPENED
  //    - TEMPORARY_UNAVAILABLE
  ///////////////////////////////////////////////////////////
  type enumerated SocketState
  {
    UNUSED,
    CLOSED,
    OPENED,
    TEMPORARY_UNAVAILABLE
  }

  const SocketEntry c_SocketEntry_init :=
  {
    addr := {
      hostName := "",
      portNumber := -1
    },
    dtls := omit,
    proto := { udp := {} },
    connId := -1,
    state := UNUSED,
    eIdx := -1
  }

  ///////////////////////////////////////////////////////////
  //  Type: SocketEntry_List
  //
  //  Purpose:
  //    List of <SocketEntry>
  ///////////////////////////////////////////////////////////
  type record of SocketEntry SocketEntry_List;

 /*****************************************************************
   @startuml EPTF_COAP_LocalTransport_Definitions.SocketDB.jpg
   class SocketDB {
     EPTF_FreeBusyQueue queue
     SocketEntry_List data
     integer hashRef
     integer connId2eIdx_hashRef
     f_EPTF_COAP_LocalTransport_socketDB_init()
     f_EPTF_COAP_LocalTransport_socketDB_cleanUp()
     f_EPTF_COAP_LocalTransport_socketDB_add(in SocketEntry p_entry)
     f_EPTF_COAP_LocalTransport_socketDB_lookUp_localAddr(in Socket p_localAddr)
     f_EPTF_COAP_LocalTransport_socketDB_lookUp_dtlsConnection(in Socket p_local, in Socket p_remote)
     f_EPTF_COAP_LocalTransport_socketDB_lookUp_connId(in integer p_connId)
     f_EPTF_COAP_LocalTransport_socketDB_get(in integer p_idx, inout SocketEntry p_sock)
     f_EPTF_COAP_LocalTransport_socketDB_remove(in integer p_idx)
   }
   @enduml
  ******************************************************************/
  ///////////////////////////////////////////////////////////
  //  Type: SocketDB
  //
  //  Purpose:
  //    Storing <SocketEntry> instances
  //
  //  Class:
  //    (see EPTF_COAP_LocalTransport_Definitions.SocketDB.jpg)
  //
  //  Elements:
  //    queue  - <EPTF_FreeBusyQueue> - FBQ for the stored elements
  //    data  - <COAP_Transaction_List> - elements
  //    hashRef - *integer* - hash id of the hash map
  //    connId2eIdx_hashRef - *integer* - hash id of the int2int hash map where key: connId -> value: eIdx
  //
  //  Related Functions:
  //   - <f_EPTF_COAP_LocalTransport_socketDB_init> ()
  //   - <f_EPTF_COAP_LocalTransport_socketDB_cleanUp> ()
  //   - <f_EPTF_COAP_LocalTransport_socketDB_add> (in <SocketEntry> p_entry)
  //   - <f_EPTF_COAP_LocalTransport_socketDB_lookUp_localAddr> (in <Socket> p_localAddr)
  //   - <f_EPTF_COAP_LocalTransport_socketDB_lookUp_dtlsConnection> (in <Socket> p_local, in <Socket> p_remote)
  //   - <f_EPTF_COAP_LocalTransport_socketDB_lookUp_connId> (in *integer* p_connId)
  //   - <f_EPTF_COAP_LocalTransport_socketDB_get> (in *integer* p_idx, inout <SocketEntry> p_sock)
  //   - <f_EPTF_COAP_LocalTransport_socketDB_remove> (in *integer* p_idx)
  ///////////////////////////////////////////////////////////  
  type record SocketDB
  {
    EPTF_FreeBusyQueue queue,
    SocketEntry_List data,
    integer hashRef,
    integer connId2eIdx_hashRef
  }
  const charstring c_EPTF_COAP_LocalTransport_SocketDB := "EPTF_COAP_LocalTransport_SocketDB";
  const charstring c_EPTF_COAP_LocalTransport_SocketDB_connId2eIdx_hashRef := "EPTF_COAP_LocalTransport_SocketDB_connId2eIdx_hashRef";

 /*****************************************************************
   @startuml EPTF_COAP_LocalTransport_Definitions.DTLSConnection.jpg
   class DTLSConnection {
    Socket          remoteAddr
    charstring      pskIndetity
    charstring      pskKey
    f_EPTF_COAP_DTLSConnection_hash(in Socket p_local, in Socket p_remote)
   }
   @enduml
  ******************************************************************/
  ///////////////////////////////////////////////////////////
  //  Type: DTLSConnection
  //
  //  Purpose:
  //    Storing the DTLS transport related data of a COAP transport endpoint
  //
  //  Class:
  //    (see EPTF_COAP_LocalTransport_Definitions.DTLSConnection.jpg)
  //
  //  Elements:
  //    remoteAddr  - <Socket> - remote address and remote port of the DTLS connection
  //    pskIndetity  - *charstring* - identity used for PSK authnetication
  //    pskKey  - *charstring* - key used for PSK authnetication
  //
  //  Related Functions:
  //   - <f_EPTF_COAP_DTLSConnection_hash> (in <Socket> p_local, in <Socket> p_remote)
  ///////////////////////////////////////////////////////////  
  type record DTLSConnection
  {
    Socket          remoteAddr,
    charstring      pskIndetity optional,
    charstring      pskKey optional
  }
  
  const DTLSConnection c_DTLSConnection_init :=
  {
    remoteAddr := {hostName := "", portNumber := -1 },
    pskIndetity := omit,
    pskKey := omit
  }

 /*****************************************************************
   @startuml EPTF_COAP_LocalTransport_Definitions.EPTF_COAP_Transport_Statistics.jpg
   class EPTF_COAP_Transport_Statistics {
    integer   nofOpenConnections
    integer   nofTransportWarnings
    float     nofReceivedMessages
    float     nofSentMessages
    float     nofReceivedBytes
    float     nofSentBytes
   }
   @enduml
  ******************************************************************/
  ///////////////////////////////////////////////////////////
  //  Type: EPTF_COAP_Transport_Statistics
  //
  //  Purpose:
  //    Storing counters for transport related statistics
  //
  //  Class:
  //    (see EPTF_COAP_LocalTransport_Definitions.EPTF_COAP_Transport_Statistics.jpg)
  //
  //  Elements:
  //    nofOpenConnections  - *integer* - number of open connection
  //    nofTransportWarnings  - *integer* - number of transport warnings issued so far during the execution
  //    nofReceivedMessages  - *float* - number of received messages
  //    nofSentMessages  - *float* - number of sent messages
  //    nofReceivedBytes  - *float* - number of received bytes
  //    nofSentBytes  - *float* - number of sent bytes
  /////////////////////////////////////////////////////////// 
  type record EPTF_COAP_Transport_Statistics
  {
    integer   nofOpenSockets,
    integer   nofTransportWarnings,
    float     nofReceivedMessages,
    float     nofSentMessages,
    float     nofReceivedBytes,
    float     nofSentBytes
  }

  const EPTF_COAP_Transport_Statistics c_EPTF_COAP_Transport_Statistics_empty :=
  {
    nofOpenSockets := 0,
    nofTransportWarnings := 0,
    nofReceivedMessages := 0.0,
    nofSentMessages := 0.0,
    nofReceivedBytes := 0.0,
    nofSentBytes := 0.0
  }
}