Skip to main content


Eclipse Community Forums
Forum Search:

Search      Help    Register    Login    Home
Home » Eclipse Projects » Eclipse Titan » Eclipse Titan product structure part 1(test port, protocol module, protocol emulation, SCTP)
Eclipse Titan product structure part 1 [message #1823292] Tue, 24 March 2020 12:05
Elemer Lelik is currently offline Elemer LelikFriend
Messages: 1061
Registered: January 2015
Senior Member
Dear all,

while collecting information for the SCTP posts it dawned on me that SCTP is represented also in Titan product categories that have been little (or at all) talked about; so I will take the opportunity and go through the existence and reason of such product categories. Please bear with me; I know that by now you are saturated with SCTP, but -although I will exemplify the product categories with SCTP-related products -the emphasis will not be on SCTP, but on product structure.

For the sake of completeness, let's recap:

Test ports are typically pieces of glue code that allow access to the respective protocol stacks of the OS (or in some cases, stacks in userspace); hence , all services and performance will originate in those stacks.


Protocol modules are also a common Titan product category;
they offer a description of the information format used by the protocol in messaging, or, in a different formulation, a static description of the protocol.

An SCTP-related example of such a protocol module can be found at:
https://git.eclipse.org/c/titan/titan.ProtocolModules.SCTP

This protocol module consists of a module SCTP_Types.ttcn, decorated with RAW (binary) encoding instructions, and an SCTP_EncDec.cc file
detailing the RAW encoding/decoding.

module SCTP_Types{

  external function f_SCTP_enc(in SCTP_Packet pl_pdu) return octetstring
  with {
    extension "prototype(convert)"
  }
  external function f_SCTP_dec(in octetstring pl_stream, out SCTP_Packet pl_pdu) return integer
  with {
    extension "prototype(backtrack)"
  }

:
:
  type record SCTP_Packet{
    SCTP_Common_header    common_header,
    SCTP_Chunk_List       chunks
  } with {
    variant ""
  }
  
  type record of SCTP_Chunk SCTP_Chunk_List;
  
  type union SCTP_Chunk{
    SCTP_Data_chunk      data,
    SCTP_Init_chunk      init,
    SCTP_InitAck_chunk   init_ack,
    SCTP_SAck_chunk      sack,
    SCTP_Heartbeat_chunk heartbeat,
    SCTP_Heartbeat_ack_chunk heartbeat_ack,
    SCTP_abort_chunk     abort,
    SCTP_Shutdown_chunk  shutdown,
    SCTP_Shutdown_ack_chunk shutdown_ack,
    SCTP_error_chunk     error_,
    SCTP_CookieEcho_chunk cookie_echo,
    SCTP_Cookie_ack_chunk cookie_ack,
    SCTP_ShutdownComplete_chunk shutdown_complete,
    SCTP_Auth_chunk      auth,
    SCTP_IData_chunk     idata,
    SCTP_ASCONF_ack_chunk asconf_ack,
    SCTP_Re_Config_chunk re_config,
    SCTP_Padding_chunk   padding,
    SCTP_Forward_TSN_chunk forward_tsn,
    SCTP_ASCONF_chunk    asconf,
    SCTP_IForward_TSN_chunk iforward_tsn,
    SCTP_Unknown_chunk   unknown_chunk
  } with {
    variant "PADDING(dword32)"
    variant "TAG( data, chunk_type = 0;
                  init, chunk_type = 1;
                  init_ack, chunk_type = 2;
                  sack, chunk_type = 3;
                  heartbeat, chunk_type = 4;
                  heartbeat_ack, chunk_type = 5;
                  abort, chunk_type = 6;
                  shutdown, chunk_type = 7;
                  shutdown_ack, chunk_type = 8;
                  error_, chunk_type = 9;
                  cookie_echo, chunk_type = 10;
                  cookie_ack, chunk_type = 11;
                  shutdown_complete, chunk_type = 14;
                  auth, chunk_type = 15;
                  idata, chunk_type = 64;
                  asconf_ack, chunk_type = 128;
                  re_config, chunk_type = 130;
                  padding, chunk_type = 132;
                  forward_tsn, chunk_type = 192;
                  asconf, chunk_type = 193;
                  iforward_tsn, chunk_type = 194;
                  unknown_chunk, OTHERWISE;
                )"
  }
  
:
:
:



One may ask, what such an SCTP protocol module is good for? So far we have seen examples of (fictional) user protocols
communicating over SCTP as transport layer; where an SCTP protocol module fits into this picture?
The use case targeted here becomes apparent if the system under test is an SCTP implementation itself; but for such a test
the existence of a protocol module is necessary but not sufficient: a dynamic description (and implementation ) of the protocol
(state machine, timers, dynamic behaviour in general) is also needed, description that will allow us to send arbitrary messages
to the remote SCTP layer in order to challenge the implementation.
So the whole complexity of the dynamic behaviour of the SCTP will have to be replicated in TTCN-3 code; this code
is, in Titan-speak, named Protocol emulation, a rather less common product category.

For SCTP, such a protocol emulation can be found at:
https://git.eclipse.org/c/titan/titan.ProtocolEmulations.SCTP

Naturally, this emulation will import the static definitions from the SCTP protocol module.

A few observations here:

-by adding negative testing/fuzzing encoding variants, challenging the message formats becomes also possible
-by using the protocol emulation, we bypass the SCTP layer of the OS protocol stack; this means that our message sending
to the remote SCTP layer will not be restricted by the (likely standard-compliant) OS-resident implementation, meaning that we can send message
successions that are illegal from the point of view of the standard (which can be a pursued angle of testing);
-bypassing the OS stack (or at least a layer of the stack) could also make sense of we are not happy with one or more
performance indicators (memory consumption, speed etc. ) of the resident stack and we need to replace said layer with
our performance-optimized implementation. Yes, it happened.


Besides SCTP, three more protocol emulations have been published so far:

http://git.eclipse.org/c/titan/titan.ProtocolEmulations.M3UA
http://git.eclipse.org/c/titan/titan.ProtocolEmulations.SCCP
http://git.eclipse.org/c/titan/titan.ProtocolEmulations.SUA



Let's look a little bit into the architecture of the above-quoted SCTP protocol emulation.

It has an interface towards the upper layer ("Client") in the form of two procedure-based ports
and the respective signatures:

module SCTP_Engine_PortTypes {


// Upper side test port. Provides the SCTP API

// Signature definitions of the procedure calls
// Client -> SCTP Engine component

// If the requested operation was executed successfully all
// procedures returns SCTP_Engine_result
// If something went wrong an exception will be raised.

// The assoc-id of the listen port is returned.
// A separate assoc_id will be created for the accepted connections
signature S_SCTP_Listen(in SCTP_Listen_data pl_arg) 
          return SCTP_Engine_result
          exception (SCTP_operation_exception)

signature S_SCTP_Connect(in SCTP_Connect_data pl_arg) 
          return SCTP_Engine_result
          exception (SCTP_operation_exception)


// The shutdown procedure and the release of the assoc_id shoud be done as:
//
//  User initiated shutdown is a 3 step procedure:
//     call    S_SCTP_Shutdown
//     receive S_SCTP_Shutdown_ind
//     call    S_SCTP_Shutdown_conf
//
//  Remote side initiated shutdown
//     receive S_SCTP_Shutdown_ind
//     call    S_SCTP_Shutdown_conf
//
// The assoc_id is released only after the call of the S_SCTP_Shutdown_conf

signature S_SCTP_Shutdown(in SCTP_Shutdown_data pl_arg) 
          return SCTP_Engine_result
          exception (SCTP_operation_exception)


signature S_SCTP_Shutdown_conf(in integer assoc_id) 
          return SCTP_Engine_result
          exception (SCTP_operation_exception)


// Request sending of user data

signature S_SCTP_Send_req(in SCTP_MSG_data pl_arg)
          return SCTP_Engine_result
          exception (SCTP_operation_exception)


// Set options
signature S_SCTP_options(in SCTP_Options_data pl_arg)
          return SCTP_Engine_result
          exception (SCTP_operation_exception)

// Reconfiguration request
signature S_SCTP_reconfig(in SCTP_Reconfiguration_req pl_arg)
          return SCTP_Engine_result
          exception (SCTP_operation_exception)


// SCTP engine -> Client

// Shutdown indication
signature S_SCTP_Shutdown_ind(in SCTP_Shutdown_data pl_arg) 

// Connected indication. 
// called by the SCTP engine, when accepting a new client connection
signature S_SCTP_Connected_ind(in SCTP_Connected_data pl_arg) 

// Receive data indication
signature S_SCTP_Received_ind(in SCTP_MSG_data pl_arg) 

// Notification indication
signature S_SCTP_Notification_ind(in SCTP_Notification_data pl_arg) 

:
:
:
// Why procedure based?
// Because the each operation is a request to execute some operation:
// S_SCTP_Listen: means please start to
// listen for an incoming association request
// 
// The result of the operation should be syncronized and paired with the 
// request. The result should be available immediately without delay
//
// The procedure based port are represents a client-server connections
// That is why we need 2 ports.
//  SCTP_Engine_API_request_PT : The SCTP user calls the operation of the 
//                               SCTP engine component
//  SCTP_Engine_API_indication_PT: The SCTP engine notifies the user via this
//
// Using only one test port can mix up the result of the ongoing operation and 
// of the incoming indication calls

// The SCTP API test port
type port SCTP_Engine_API_request_PT procedure {
  inout S_SCTP_Listen, S_SCTP_Connect, S_SCTP_Shutdown,S_SCTP_Shutdown_conf
  inout S_SCTP_Send_req, S_SCTP_options, S_SCTP_reconfig
} with {
  extension "internal"
}

type port SCTP_Engine_API_indication_PT procedure {
  inout S_SCTP_Shutdown_ind, S_SCTP_Connected_ind, S_SCTP_Received_ind
  inout S_SCTP_Notification_ind
} with {
  extension "internal"
}





The southbound interface circulates the binary-coded sctp packets:



module SCTP_Engine_PortTypes {

:
:

//******************************************************************************
// Lower side port. Exchanges the encoded SCTP packets

// Used to represent a SCTP packet in encoded form
type record SCTP_Engine_packet {
  integer        transport_id,  // The identifier used to identify the transport connection
                                // The identifier is specified in a Listen/Connect operation
                                // The associations using the same transport id are distinguished by the SCTP port numbers
  octetstring    sctp_packet    // The SCTP packet 
}

type record SCTP_Addr_change_notification{
  integer        transport_id  // The identifier used to identify the transport connection
}

// used only between components
type port SCTP_Engine_packet_PT message {
  inout SCTP_Engine_packet
  inout SCTP_Addr_change_notification
} with {
  extension "internal"
}

:
:






Of course this interface will have to be appropriately plugged in into an IP layer.

I tried to summarize the above in the following schematic:


                                   +-----------------------+
                                   |                       |
                                   |     User protocol     |
                                   +-------^--^------------+
+-----------------+ +-------------------+  |  |  +-------------------+
|SCTP             | |SCTP               |  |  |  |                   |
|protocol         +->protocol           |  |  |  |   SCTP test port  |
|module           | |emulation          <--+  +-->                   |
+-----------------+ +-------+-----------+        +--------^----------+
                            |                             |    kernel stack
                            |                    +--------v----------+
                            |                    |                   |
                            |                    |     SCTP          |
                            |                    +-------------------+
                            |                    |                   |
                            +-------------------->       IP          |
                                                 |                   |
                                                 +-------------------+
                                                 |     ...           |
                                                 |                   |
                                                 +-------------------+





In the following, and final, part we will explore yet another new category, of the protocol daemons.


Best regards
Elemer


[Updated on: Tue, 31 March 2020 10:25]

Report message to a moderator

Previous Topic:SCTP support in Eclipse Titan part 4
Next Topic:Eclipse Titan product structure part 2
Goto Forum:
  


Current Time: Mon Jul 06 18:19:28 GMT 2020

Powered by FUDForum. Page generated in 0.02061 seconds
.:: Contact :: Home ::.

Powered by: FUDforum 3.0.2.
Copyright ©2001-2010 FUDforum Bulletin Board Software

Back to the top