Creating Custom Packet-Translation Functions

If you want to write your own packet-translation functions, you must do the following:

  1. In Riverbed Modeler, choose File > New… and select External Source from the pull-down menu.

    • The External Source editor opens.
  2. Create a new external source file. The external source file must include sitl_packet_translation.h and define the following functions:

    • Translation function/test function pair (or pairs, if you are converting multiple packet formats). See Packet Translation Details for details on how to write these functions.

    • One real-to-simulated packet translation entry point. On Windows, you must export the function symbol using the keyword DLLEXPORT. Here is the prototype for this function:

      DLLEXPORT int
      my_real_to_simulated_packet_translation(OP_SIM_CONTEXT_ARG_OPT_COMMA SitlT_SCDB* scdb_ptr)
      
    • One simulated-to-real packet translation entry point. On Windows, you must export the function symbol using the keyword DLLEXPORT. Here is the prototype for this function:

      DLLEXPORT int
      my_simulated_to_real_packet_translation(OP_SIM_CONTEXT_ARG_OPT_COMMA SitlT_SCDB* scdb_ptr)
      
    • One initialization function. On Windows, you must export the function symbol using the keyword DLLEXPORT. Here is the prototype for this function:

      DLLEXPORT int 
      my_translation_initialization_function (OP_SIM_CONTEXT_ARG_OPT_COMMA void)
      

    For more information about how to parse packets, see the Pcap documentation at http://www.tcpdump.org or the WinPcap documentation at http://www.winpcap.org.

    For more information on how to write your translation and initialization functions, see Packet Translation Details and the custom translation example in Figure 5.

  3. Choose File > Save As… and save the source file in one of your Riverbed model directories, such as op_models. The filename must end with “.ex”.

  4. Click the Compile button to compile the source file. Close the External Source editor when finished.

  5. In Riverbed Modeler, associate the file with the project (using File > Declare External Files… in the Project Editor).

  6. On the SITL gateway node, edit the following attributes to specify the external module name and the custom functions you created:

    • From Real Packet Translation Function
    • To Real Packet Translation Function
    • Translation Initialization Function

Figure 5: Sample Packet Translation Function

/**********************************/
/*       Copyright (c) 2013       */
/*   Riverbed Technology, Inc.    */
/*      All Rights Reserved.      */
/**********************************/

// This file contains an example of how to write SITL custom translation
// functions using RTP, the Real-time Transport Protocol.
// These translation functions do not handle all possible options present
// in RTP. Also, in order to have a functioning RTP system, you would
// need to implement translation functions for the sister protocol, RTCP.
// This code will only work in SITL 14.5 and later. 

#include <opnet.h>
#include <udp_dgram_sup.h>

#include "winsock.h"
#include "sitl_packet_translation.h"

// Real RTP packet structure as per RFCs 1889, and 3550
typedef struct SitlT_RTP_Header {
    OpT_uInt8     V_P_X_CC;
    OpT_uInt8     M_PT;
    OpT_uInt16    sequence_number;
    OpT_uInt32    timestamp;
    OpT_uInt32    SSRC_identifier;
    } SitlT_RTP_Header;

#define SITL_RTP_HEADER_LENGTH 12

// This is one of the recommended RTP port numbers. A single port is used
// here for simplicity. A range would have worked as well.
#define RTP_PORT_NUMBER 6980

int sitl_translate_from_real_to_simulated_rtp (OP_SIM_CONTEXT_ARG_PTR_COMMA SitlT_SCDB* scdb_ptr);
int sitl_translate_from_simulated_to_real_rtp (OP_SIM_CONTEXT_ARG_PTR_COMMA SitlT_SCDB* scdb_ptr);
int sitl_test_from_real_to_simulated_rtp (OP_SIM_CONTEXT_ARG_PTR_COMMA SitlT_SCDB* scdb_ptr);

// The three functions declared DLLEXPORT below need to be set as attributes
// on the SITL node where the translation needs to take place

// Initialization function registers the RTP translation functions with SITL
DLLEXPORT int sitl_translation_initialization_rtp(OP_SIM_CONTEXT_ARG_OPT_COMMA void)
    {
    FIN_MT (sitl_translation_initialization_rtp ());
    op_pk_sitl_packet_translation_init();
    op_pk_sitl_register_translation_function (
        SITL_TRANSLATION_DIRECTION_REAL_TO_SIM,      // direction
        sitl_translate_from_real_to_simulated_rtp,   // translation function
        sitl_test_from_real_to_simulated_rtp,        // test function
        "udp_dgram_v2",                              // base packet format
        10);                                         // priority
    op_pk_sitl_register_translation_function (
        SITL_TRANSLATION_DIRECTION_SIM_TO_REAL,      // direction
        sitl_translate_from_simulated_to_real_rtp,   // translation function
        sitl_test_from_real_to_simulated_rtp,        // test function
        "udp_dgram_v2",                              // base packet format
        10);                                         // priority
    FRET (1);
    }

// The following two translation functions delegate the work
// to the standard SITL translation functions.
// They are included here as an example. Alternatively, you can
// use the OPNET KPs directly.
DLLEXPORT int sitl_from_real_all_supported_rtp (OP_SIM_CONTEXT_ARG_OPT_COMMA SitlT_SCDB* scdb_ptr)
    {
    int  result;
    FIN_MT (sitl_from_real_all_supported_rtp (scdb_ptr));
    result = op_pk_sitl_from_real_all_supported (scdb_ptr);
    FRET (result);
    }

DLLEXPORT int sitl_to_real_all_supported_rtp (OP_SIM_CONTEXT_ARG_OPT_COMMA SitlT_SCDB* scdb_ptr)
    {
    int result;
    FIN_MT (sitl_to_real_all_supported_rtp(scdb_ptr));
    result = op_pk_sitl_to_real_all_supported (scdb_ptr);
    FRET (result);
    }

// This function tests the applicability of the RTP translation 
// function to a given packet by looking for a specific signature
int sitl_test_from_real_to_simulated_rtp (OP_SIM_CONTEXT_ARG_OPT_COMMA SitlT_SCDB* scdb_ptr)
    {
    UdpT_Dgram_Fields* udp_dgram_fd_ptr = OPC_NIL;
    FIN_MT (sitl_test_from_real_to_simulated_rtp (scdb_ptr));
    op_pk_nfd_access (scdb_ptr->sim_pk_ptr, "fields", &udp_dgram_fd_ptr);
    FRET (udp_dgram_fd_ptr->dest_port == RTP_PORT_NUMBER);
    }

// This function implements the translation of an RTP packet from real to simulated
int sitl_translate_from_real_to_simulated_rtp (OP_SIM_CONTEXT_ARG_OPT_COMMA SitlT_SCDB* scdb_ptr)
    {
    SitlT_RTP_Header* rtp_hdr_ptr = OPC_NIL;
    Packet* rtp_sim_ptr = OPC_NIL;
    Packet* rtp_sim_data_ptr = OPC_NIL;
    unsigned char* data_ptr = OPC_NIL;
    int options, sequence_number, timestamp, SSRC_identifier, data_size;

    FIN_MT (translate_from_real_to_simulated_rtp (scdb_ptr));

    // Get pointer to real packet
    rtp_hdr_ptr = (SitlT_RTP_Header*)(scdb_ptr->real_pk_ptr + scdb_ptr->real_pk_offset);

    // Create simulated RTP packet
    rtp_sim_ptr = op_pk_create_fmt ("sitl_rtp");

    // Get fields from real packet and set them in the simulated packet

    options = (rtp_hdr_ptr->M_PT)<<8 | (rtp_hdr_ptr->V_P_X_CC);
    op_pk_nfd_set (rtp_sim_ptr, "options", options);

    sequence_number = ntohs (rtp_hdr_ptr->sequence_number);
    op_pk_nfd_set (rtp_sim_ptr, "sequence_number", sequence_number);

    timestamp = ntohl (rtp_hdr_ptr->timestamp);
    op_pk_nfd_set (rtp_sim_ptr, "timestamp", timestamp);

    SSRC_identifier = ntohl (rtp_hdr_ptr->SSRC_identifier);
    op_pk_nfd_set (rtp_sim_ptr, "SSRC_identifier", SSRC_identifier);

    // Advance the real packet read pointer
    scdb_ptr->real_pk_offset += SITL_RTP_HEADER_LENGTH;

    // Get the RTP payload
    data_size = scdb_ptr->real_pk_size - scdb_ptr->real_pk_offset;
    data_ptr = op_prg_mem_alloc (data_size);
    op_prg_mem_copy (scdb_ptr->real_pk_ptr + scdb_ptr->real_pk_offset, data_ptr, data_size);

    // and put it in an unformatted packet in a structure field
    rtp_sim_data_ptr = op_pk_create (0);
    op_pk_fd_set_ptr (rtp_sim_data_ptr, 0, data_ptr, data_size*8, op_prg_mem_copy_create, op_prg_mem_free, data_size);
    op_pk_nfd_set (rtp_sim_ptr, "data", rtp_sim_data_ptr);

    // Advance the real packet read pointer
    scdb_ptr->real_pk_offset += data_size;

    // Save newly converted simulated packet
    scdb_ptr->sim_pk_ptr = rtp_sim_ptr;

    // Return success indication
    FRET (1);
    }

// This function implements the translation of an RTP packet from simulated to real
int sitl_translate_from_simulated_to_real_rtp (OP_SIM_CONTEXT_ARG_OPT_COMMA SitlT_SCDB* scdb_ptr)
    {
    SitlT_RTP_Header* rtp_hdr_ptr = OPC_NIL;
    Packet* udp_dgram_pkptr;
    Packet* rtp_sim_ptr = OPC_NIL;
    Packet* rtp_sim_data_ptr = OPC_NIL;
    unsigned char* data_ptr;
    int options, sequence_number, timestamp, SSRC_identifier, data_size;

    FIN_MT (translate_from_simulated_to_real_rtp (scdb_ptr));

    // Get pointer to begining of the real packet memory area
    rtp_hdr_ptr = (SitlT_RTP_Header*)(scdb_ptr->real_pk_ptr + scdb_ptr->real_pk_offset);

    // Get simulated UDP and RTP packet pointers
    udp_dgram_pkptr = scdb_ptr->sim_pk_ptr;
    op_pk_nfd_get_pkt (udp_dgram_pkptr, "data", &rtp_sim_ptr);

    // Get packet fields from simulated packet
    op_pk_nfd_get (rtp_sim_ptr, "options", &options);
    op_pk_nfd_get (rtp_sim_ptr, "sequence_number", &sequence_number);
    op_pk_nfd_get (rtp_sim_ptr, "timestamp", &timestamp);
    op_pk_nfd_get (rtp_sim_ptr, "SSRC_identifier", &SSRC_identifier);

    // Set packet fields in real packet
    rtp_hdr_ptr->V_P_X_CC = options & 0x00FF;
    rtp_hdr_ptr->M_PT = (options & 0xFF00)>>8;
    rtp_hdr_ptr->sequence_number = htons(sequence_number);
    rtp_hdr_ptr->timestamp = htonl(timestamp);
    rtp_hdr_ptr->SSRC_identifier = htonl(SSRC_identifier);

    // Advance the real packet write pointer
    scdb_ptr->real_pk_offset += SITL_RTP_HEADER_LENGTH;

    // Get the packet payload from the simulated packet and copy
    // it to the real packet
    op_pk_nfd_get_pkt (rtp_sim_ptr, "data", &rtp_sim_data_ptr);
    data_size = op_pk_total_size_get (rtp_sim_data_ptr)/8;
    op_pk_fd_get_ptr (rtp_sim_data_ptr, 0, (void**)&data_ptr);
    op_prg_mem_copy (data_ptr, scdb_ptr->real_pk_ptr + scdb_ptr->real_pk_offset, data_size);

    // Advance the real packet write pointer
    scdb_ptr->real_pk_offset += data_size;

    // Free simulated packet memory
    op_prg_mem_free (data_ptr);
    op_pk_destroy (rtp_sim_ptr);
    scdb_ptr->sim_pk_ptr = OPC_NIL;

    // Return success indication
    FRET (1);
    }