Packet Translation Details
This section describes components of the packet translation process, then describes the overall translation process in detail.
Conversion Descriptor Block
This is the most important data structure used in the translation process. It is passed as a parameter to most functions used in the translation process, such as translation functions and test functions. The declaration, which can be found in sitl_packet_translation.h, looks like this:
typedef struct Sitl_Conversion_Descriptor_Block
{
SitlT_Translation_Direction direction;
Packet* sim_pk_ptr;
unsigned char* real_pk_ptr;
unsigned int real_pk_size;
unsigned int real_pk_offset;
unsigned int max_conv_level;
unsigned int max_conv_level_passthrough;
unsigned int cur_conv_level;
unsigned int drop_unsup_packets;
unsigned char* user_data_ptr;
void* current_tfe_ptr;
int passthrough;
int link_layer_type;
int next_protocol;
VosT_uInt8 BSS_IS [6];
Packet* sim_pk_ptr_arr [SITL_MAX_CONV_LEVEL];
unsigned char* real_pk_ptr_arr [SITL_MAX_CONV_LEVEL];
} SitlT_SCDB;
Let’s look at the fields in more detail.
direction
This field specifies the direction of the translation. It can have one of two values, as defined in the following typedef:
typedef enum {
SITL_TRANSLATION_DIRECTION_REAL_TO_SIM = 0,
SITL_TRANSLATION_DIRECTION_SIM_TO_REAL = 1
} SitlT_Translation_Direction;
This parameter is set by SITL and you should not change it.
sim_pk_ptr
This field holds a pointer to the simulated packet. It can be an input parameter for sim-to-real translations or it can be an output parameter in real-to-sim translations.
real_pk_ptr
This field holds a pointer to the real packet. It will hold a pointer to the incoming real packet for real-to-sim translations and a pointer to a memory area to receive the translated real packet for sim-to-real translations. This is always set by SITL and you should not change it except in very advanced situations.
real_pk_size
This field holds the size of the real packet, in bytes. It is set by SITL and you should not change it.
real_pk_offset
This field holds the offset from the beginning of the real packet at which the translation will be processing data next. It is the place where the next data will be read in the real-to-sim case, or the place where the data will be written in the sim-to-real case. You should increment this parameter as the translation process progresses.
max_conv_level
This field is the maximum packet nesting level to convert. It is set by SITL based on a parameter on the SITL node. You can change this if necessary.
max_conv_level_passthrough
This field is the maximum packet nesting level to convert for pass-through packets. For example, when set to 2, SITL will only translate up to and including the IP level. This field is set by SITL based on a parameter on the SITL node. You can change this if necessary.
cur_conv_level
This field is the current nesting level the translation process has reached. You should increment this in your custom translation functions.
drop_unsup_packets
This field tells SITL whether to drop packets it cannot convert from real to simulated. If set to 0, SITL will encapsulate the packet data in an unformatted packet. The default value is 1, which means SITL will drop all packets that it cannot convert.
user_data_ptr
This field can hold a pointer to custom user data. You can set this as needed.
current_tfe_ptr
This field holds information about the current format and translation function. It is an internal SITL field and you should not change it.
passthrough
This field is set to 1 if the packet destination is outside the simulation and to 0 otherwise. It is set by SITL and you should not change it.
link_layer_type
This field contains the data link layer type, as described in the WinPcap/libpcap documentation.
next_protocol
This field is set to the protocol of the payload packet, where applicable (for example, Ethernet or IP tunneling). When not applicable, it is set to 0.
BSS_ID
This field contains the BSS ID of the wireless network. It is used only for WLAN interfaces and should be left blank in all other cases.
sim_pk_ptr_arr
This field holds an array of pointers to simulated packets translated so far. Therefore, sim_pk_ptr_arr[cur_conv_level] is the same as sim_pk_ptr and real_pk_ptr_arr[cur_conv_level] is the same as real_pk_ptr. This field can be used to access simulated packets lower in the protocol stack.
real_pk_ptr_arr
This field holds an array of pointers to real packets translated so far. Therefore, real_pk_ptr_arr[cur_conv_level] is the same as real_pk_ptr. This field can be used to access real packets lower in the protocol stack.
Translation Functions
These functions do the actual translation of the packet. They look like this:
int sitl_translation_function (SitlT_SCDB* scdb_ptr)
They take a Conversion Descriptor Block as an argument and return 1 for success or 0 for failure. See Figure 5 for an example of a translation function.
Translation functions must be registered with SITL, as described in Function Registration.
Function Registration
All translation functions and test functions must be registered with SITL. The built-in functions are registered by the initialization function op_pk_sitl_packet_translation_init(). You should register custom functions with op_pk_sitl_register_translation_function().
When you register a translation function, you need to specify several things:
- the direction for the translation
- a pointer to the translation function
- a pointer to the associated test function
You can also specify the base packet format, which determines the protocol on top of which your packet is carried as a payload. This is useful when SITL looks for a translation function to apply to a packet. Only translation functions for packets that can actually occur at that nesting level are considered. You can pass a NULL pointer for this argument, but this is less efficient and it is highly unlikely that your packet is carried by multiple protocols.
The last argument to specify is the priority. This is used to determine which translation function to consider first. SITL uses the first translation function whose associated test function returns true. Higher priority functions are considered first. The priority can be used to make the translation more efficient by giving higher priority to translation functions corresponding to more common packets.
Note: You can register the same translation function more than once if you pair it with a different test function.
Test Functions
Test functions determine the packet format (protocol) based on a signature they find in the packet. This signature is a combination of field values that uniquely determines the format. Test functions look like this:
int sitl_translation_test (SitlT_SCDB* scdb_ptr)
Test functions take a descriptor block as argument and return a true/false value indicating whether the packet passed the test. The test functions must be registered with SITL.
A test function can use both the input packet (real or simulated) and the output packet that has been converted so far. Care must be taken not to alter the packets in any way. Also, it is very important not to incorrectly interpret fields in packets based on the assumption that the packet is of the desired type. For example, when using offsets from real packets, before using them make sure they point within the packet limits. If the field you are using is not an offset, it might cause your code to point outside the real packet and memory access violations can occur.
Translation Entry Points
The translation process begins with two entry-point functions, one for real-to-sim translations and one for sim-to-real. These functions should be declared as all other translation functions, but they do not need to be registered and they do not need to have corresponding test functions. They are always called first to convert a packet. These functions are specified by two SITL gateway node attributes:
- From Real Packet Translation Function
- To Real Packet Translation Function
These functions can be different for different SITL nodes, although currently there might be no use for setting them to different values because all SITL packets have to have Ethernet at the lowest level. Registered translation functions are global, however. They are shared by all SITL nodes.
SITL provides two built-in functions to use as entry points for the standard translation functions—op_pk_sitl_from_real_all_supported() and op_pk_sitl_to_real_all_supported(). If you write your custom translation functions in addition to the built-in ones, you can use these built-in entry points. Once you register your translation functions, they will be invoked at the appropriate time. However, you will have to create your wrapper function that calls the built-in entry points due to the fact that the entry points and the initialization functions have to be exported by your custom module. Your wrappers could look like this:
DLLEXPORT int my_from_real_all_supported (SitlT_SCDB* scdb_ptr)
{
int result;
FIN (my_from_real_all_supported (scdb_ptr));
result = op_pk_sitl_from_real_all_supported (scdb_ptr);
FRET (result);
}
DLLEXPORT int my_to_real_all_supported (SitlT_SCDB* scdb_ptr)
{
int result;
FIN (my_to_real_all_supported(scdb_ptr));
result = op_pk_sitl_to_real_all_supported (scdb_ptr);
FRET (result);
}
These examples simply invoke the built-in entry-point functions.
Initialization Function
Translations need to have some initialization done before the actual translation process can begin. At a minimum, the translation functions and the test functions need to be registered with SITL. They have the following form:
int sitl_translation_initialization (void)
They take no arguments and return success or failure.
SITL provides an initialization function for its built-in translation process called op_pk_sitl_packet_translation_init(). This function registers all built-in translation and test functions. If you write your own set of translation functions in addition to the built-in ones, you should call this function from your own initialization function. If your set of translation functions completely replaces the ones provided by SITL, you don’t need to call the built-in initialization function in your initialization function.
The initialization function is specified on the SITL node by the Translation Initialization Function attribute.
Memory Allocation and De-allocation
Packets are passed in and out of translation functions. Let’s look at who creates packets and who destroys packets.
Real packet memory is always handled by SITL. In very advanced translation functions, you can manipulate real packet memory, but this is not recommended unless absolutely necessary.
real_pk_offset starts at zero, when the first translation function is invoked, and it should be identical to real_pk_size after the last translation function ends.
For real-to-sim translations, real_pk_ptr is an input parameter and translation functions use real_pk_offset to determine where the next data to be converted can be found.
For sim-to-real translations, real_pk_ptr points to a memory block allocated by SITL that will hold the converted packet. real_pk_offset should be used to point to a memory area within the real packet right after the last converted data. This is where the next data will be written as it is converted.
Simulated packets are input parameters in sim-to-real situations and the user is responsible for destroying the packet. Care must be taken not to destroy the packet before higher nesting levels had a chance to convert their packets as these packets are fields of the lower level packets.
In real-to-sim situations, the translation functions are responsible for creating the simulated packets that will be returned in the descriptor block at the end of the translation.
Payload Translation Functions
Two payload translation functions are provided:
SITL calls these two functions to convert the inner packet (the payload) of the packet it is currently converting. These functions work as follows.
Real-to-Sim Payload Translation
op_pk_sitl_translate_payload_from_real_to_sim() checks whether the maximum translation level as specified in the corresponding node attribute has been reached. If so, the payload is encapsulated in an unformatted packet and the translation ends. If not, SITL looks for an appropriate translation function for the payload packet. SITL does this by calling test functions that are applicable at this nesting level in decreasing order of priority. If none is found, test functions that have no base level specified are tried next. If a translation function is found, that function is invoked to continue the translation process. If no function is found, the payload is encapsulated in an unformatted packet and the translation ends.
Note: Packets that are not destined for nodes inside the simulation are handled differently. See Pass-through Packets for details.
Sim-to-Real Payload Translation
op_pk_sitl_translate_payload_from_sim_to_real() checks whether the inner packet is an unformatted packet. If so, it extracts the encapsulated data and copies it to the real packet unchanged. Otherwise, it checks whether the maximum translation level has been reached and exits if it has. If not, the function looks for an appropriate translation function. SITL does that by calling test functions that are applicable at this nesting level in decreasing order of priority. If none is found, test functions that have no base level specified are tried next. If a translation function is found, that function is invoked to continue the translation. If no function is found, the translation ends.
Pass-through Packets
Incoming real packets that are not destined for a node in the simulation are translated only to the IP level. There is no need to try to convert them further because they are only passing through and would have to be translated back in the outbound SITL node. Not doing a full translation allows packets belonging to unsupported protocols on top of IP to transit a simulation without the need for custom translation functions. It is also more efficient to avoid translating packets back and forth.
If you need to fully convert pass-through packets, set the Limit Pass-through Translation To IP Level attribute to “disabled” on the appropriate SITL gateway nodes.
Limiting the Translation for All Packets
You can use the Maximum Packet Translation Level attribute to specify the maximum nesting level for converted packets, both real-to-sim and sim-to-real. This attribute is set to 9 by default, so as to not impose a limit. You can set it to a lower value to prevent translation above a certain level. This might be useful if you want to process the raw packet data in some internal process model. Note that SITL encapsulates all unconverted data in a structure field of an unformatted packet.
Queue Size
The incoming packet queue has a default size of 1000 packets. This is sufficient for most cases, but you can set this to any number from 100 to 1000000 using the SITL Queue Size (packets) attribute. This is a global (simulation) attribute that can be set on the Inputs > Global Attributes page of the Configure/Run DES dialog box.
Keep in mind that the queue acts as a buffer for the incoming packets, to smooth out spikes in traffic. If the simulation is slow and cannot keep up with the traffic, a larger buffer will not make it faster. The buffer will fill up at some point. When that happens, incoming packets will be dropped and a message will be printed in the simulation console using the character “@” for each dropped packet.
How the Translation Process Works
Let's put everything together now. When the simulation is initialized, SITL calls the packet translation initialization function. This function registers all translation/test function pairs. When a packet arrives, SITL calls the translation entry points to convert the packet. This entry point typically calls the translation function for the base packet format, which is Ethernet. Each translation function will convert the data for its own packet format. Then, if that format carries other packets as payload, the translation function calls one of the two payload translation functions to convert the inner packet. These payload functions in turn will call other translation functions and the process proceeds recursively until the top of the packet nesting is reached.
The translation process might stop prematurely in some cases. For real-to-sim translations, the payload data is encapsulated in an unformatted simulated packet in the following cases:
-
The maximum translation level is reached.
-
The packet is a pass-through packet and the Limit Pass-through Translation to IP Level attribute is set to Enabled.
-
No appropriate translation function is found or the translation fails for any reason.
This case applies only if the Drop Real Packet if Translation Fails attribute is set to Disabled. By default, this attribute is set to Enabled, which causes the packet to be dropped.
The unformatted packet will have as its only field a structure containing the payload data.
In the sim-to-real case, the translation might end in the same cases as above. However, before making a decision, SITL extracts any data encapsulated in unformatted packets. Note that you can use this feature if you generate simulated packets that you want converted to real packets without writing your own translation functions. Simply encapsulate your custom packet as the payload of a supported protocol and send it to SITL. SITL will not touch this data; it will simply copy it to the real packet.