Pipeline Stage Definition
Pipeline stages are implemented as C or C++ language procedures with predefined argument and return-value interfaces. Almost all pipeline stages accept a packet address (Packet* datatype) as their sole argument. As mentioned earlier, the TDA fields of the packet that is passed in are used as a vehicle for conveying information back to the Simulation Kernel as well as to subsequent pipeline stages.
Each pipeline stage has a user-provided name, usually selected to be representative of its features. For example, a pipeline stage responsible for calculating the transmission delay over a point-to-point link may be called “tx_delay”. The selected name must be used to name the pipeline stage procedure as well as the source code file that contains it. Pipeline stage object code files can only be recognized by Modeler if they carry the suffix .ps.o; therefore pipeline stage source code files usually have the suffix .ps.c for C files and .ps.cpp for C++ files. Therefore, the signal-to-noise ratio pipeline stage may be implemented by a C procedure defined as tx_delay() within a file called tx_delay.ps.c, which when compiled generates the object code file tx_delay.ps.o. Custom pipeline stages may also be created by the user as C or C++ files and then compiled to .ps.o files with the op_mko utility. For further information on the op_mko utility, see Chapter 3 “Program Descriptions” on page 143.
The Simulation Kernel contains a package of procedures to support the assignment to and extraction from transmission data attributes. This package is called the Transmission Data package (Td) and the procedures that it includes are summarized below. For detailed explanations of their capabilities and usages, see Chapter 26 “Transmission Data Package” on page 1.
Table 103: Transmission Data Package Kernel Procedures
| Kernel Procedure | Provided Capability |
|---|---|
op_td_get_dbl() |
obtain a double-precision floating point value stored in a specified TDA of a packet |
op_td_get_int() |
obtain an integer value stored in a specified TDA of a packet |
op_td_get_ptr() |
obtain a pointer value from the specified transmission data attribute |
op_td_increment_dbl() |
add a specified amount to a TDA’s double value |
op_td_increment_int() |
add a specified amount to a TDA’s integer value |
op_td_is_set() |
determine if a specified TDA of a packet currently contains an assigned value |
op_td_set_dbl() |
assign a double-precision floating-point value to a specified TDA of a packet, replacing the previous value (if any) |
op_td_set_int() |
assign an integer value to a specified TDA of a packet, replacing the previous value (if any) |
op_td_set_ptr() |
assign a pointer value to the specified transmission data attribute |
The top-level pipeline procedure may also make use of most Kernel Procedures (KPs), user-defined or third-party procedures in other files, and the general capabilities of the C language to implement the functionality required of them. Frequently, pipeline stages do mathematical calculations that rely on the availability of the C/C++ math library, and therefore include the definitions file math.h in their source code file. A C source code example for a simple pipeline stage procedure appears below:
Figure 224: Example of a C Pipeline Stage Procedure
/* transmission_delay.ps.c */
#include <opnet.h>
#include <math.h>
void
transmission_delay (Packet * pk)
{
/* Obtain the transmission data rate (supplied by the Kernel */
/* in the packet’s TDAs). */
tx_data_rate = op_td_get_dbl (pk, OPC_TDA_RA_TX_DRATE);
/* Obtain the packet’s length (in bits). */
pk_length = op_pk_total_size_get (pk);
/* Compute the transmission delay. */
tx_delay = pk_length / tx_data_rate;
/* Place result in packet to return to Kernel. */
op_td_set_dbl (pk, OPC_TDA_RA_TX_DELAY, tx_delay);
}
In the case of a C++ pipeline stage file, the top-level pipeline procedure must be linked using the C linkage convention so that the Simulation Kernel can correctly access it. This is indicated by wrapping the prototype of the procedure in an ‘extern “C”’ linkage expression, such as:
Figure 225: Example of a C++ Pipeline Stage Procedure
/* transmission_delay.ps.cpp */
#include <opnet.h>
#include <math.h>
extern “C”{
void closure_template (Packet *);
}
void
closure_template (Packet * pk)
{
/* pipeline stage code */
}
Default Pipeline Stage Models
Modeler provides default pipeline procedures to support each type of link. These pipeline stages appear as the default assignments when new transceiver or link objects are created. The names of these stages are given below, along with the corresponding transmitter or receiver module attributes. Complete descriptions of each default stage behavior and implementation are in Chapter 4 “Pipeline Stages/Point-to-Point Links” on page 21 and Chapter 3 “Pipeline Stages/Bus Link” on page 6. These default stages can also serve as good starting points for developers wishing to create application-specific pipeline stages.
Table 104: Point-to-Point Transceiver Pipeline Default Stages
| Pipeline Stage | Attribute Name | Default Stage Name |
|---|---|---|
| Transmission Delay | txdel model | dpt_txdel |
| Propagation Delay | propdel model | dpt_propdel |
| Error Allocation | error model | dpt_error |
| Error Correction | ecc model | dpt_ecc |
Table 105: Bus Transceiver Pipeline Default Stages
| Pipeline Stage | Attribute Name | Default Stage Name |
|---|---|---|
| Transmission Delay | txdel model | dbu_txdel |
| Link Closure | closure model | dbu_closure |
| Propagation Delay | propdel model | dbu_propdel |
| Collision | coll model | dbu_coll |
| Error Allocation | error model | dbu_error |
| Error Correction | ecc model | dbu_ecc |
The “NONE” Pipeline Stage
To simulate network models with many nodes or packet transmissions, Modeler must make large numbers of pipeline stage calculations. This can cause simulations to take a long time to run. If some of the pipeline stages are not important to the goals of your simulation, you can skip these stages. To skip a pipeline stage, assign “NONE” to the corresponding pipeline stage attribute of a link object. During simulation, the Simulation Kernel skips each stage set to “NONE” and sets the corresponding TDA to a default value in place of a calculated result. The following tables list the default values used.
Table 106: Point-to-Point Transceiver Pipeline Default Values
| Pipeline Stage | TDA | Default Value |
|---|---|---|
| Transmission Delay | OPC_TDA_PT_TX_DELAY |
0 seconds |
| Propagation Delay | OPC_TDA_PT_PROP_DELAY |
0 seconds |
| Error Allocation | OPC_TDA_PT_NUM_ERRORS |
0 |
| Error Correction | OPC_TDA_PT_PK_ACCEPT |
OPC_TRUE |
Table 107: Bus Transceiver Pipeline Default Values
| Pipeline Stage | TDA | Default Value |
|---|---|---|
| Transmission Delay | OPC_TDA_BU_TX_DELAY |
0 seconds |
| Link Closure | OPC_TDA_BU_CLOSURE |
OPC_TRUE |
| Propagation Delay | OPC_TDA_BU_PROP_DELAY |
0 seconds |
| Collision | OPC_TDA_BU_NUM_COLLS |
0 |
| Error Allocation | OPC_TDA_BU_NUM_ERRORS |
0 |
| Error Correction | OPC_TDA_BU_PK_ACCEPT |
OPC_TRUE |
You can change the default value assigned by a NONE pipeline stage by setting the value of the corresponding simulation preference, as listed in the following tables.
Table 108: Simulation Preferences for Point-to-Point TDA Defaults
| Pipeline Stage | TDA | Simulation Preference |
|---|---|---|
| Transmission Delay | OPC_TDA_PT_TX_DELAY |
psnone_tda.pt.txdel.tx_delay |
| Propagation Delay | OPC_TDA_PT_PROP_DELAY |
psnone_tda.pt.propdel.prop_delay |
| Error Allocation | OPC_TDA_PT_NUM_ERRORS |
psnone_tda.pt.error.num_errors |
| Error Correction | OPC_TDA_PT_PK_ACCEPT |
psnone_tda.pt.ecc.pk_accept |
Table 109: Simulation Preferences for Bus TDA Defaults
| Pipeline Stage | TDA | Simulation Preference |
|---|---|---|
| Transmission Delay | OPC_TDA_BU_TX_DELAY |
psnone_tda.bu.txdel.tx_delay |
| Link Closure | OPC_TDA_BU_CLOSURE |
psnone_tda.bu.closure.closure |
| Propagation Delay | OPC_TDA_BU_PROP_DELAY |
psnone_tda.bu.propdel.prop_delay |
| Collision | OPC_TDA_BU_NUM_COLLS |
psnone_tda.bu.coll.num_colls |
| Error Allocation | OPC_TDA_BU_NUM_ERRORS |
psnone_tda.bu.error.num_errors |
| Error Correction | OPC_TDA_BU_PK_ACCEPT |
psnone_tda.bu.ecc.pk_accept |