op_td_set_ptr()
Abstract
Assigns a pointer value to the specified transmission data attribute.
Syntax
op_td_set_ptr (pkptr, tda_index, value)
| Argument | Type | Description |
|---|---|---|
pkptr |
Packet* |
pointer to the packet-of-interest [This KP must be invoked within the context of a Transceiver Pipeline stage. In this context, the packet-of-interest is the packet that is passed into the stage procedure as an argument.] |
tda_index |
int |
numeric index of the transmission data attribute-of-interest. The TDA must be a pointer. [This value is an integer code which specifies the transmission data attribute to be accessed. Predefined values for this argument appear in “Transmission Data Attribute“ on page 28. User-defined transmission information can be assigned to any attribute index greater than the largest index occupied by a predefined attribute. The largest predefined attribute indices are OPC_TDA_PT_MAX_INDEX (for the point-to-point pipeline), OPC_TDA_BU_MAX_INDEX (for the bus pipeline), and OPC_TDA_RA_MAX_INDEX (for the radio pipeline).] |
value |
Vartype |
value to assign to the specified transmission data attribute |
Return Type
void
No return value.
Example
/* Determine distance between Tx and Rx */
dist = op_td_get_dbl (pkptr, OPC_TDA_RA_START_DIST);
/* Determine coefficients for path-loss calculation. */
path_loss_coeffs (pkptr, &pl0, &pl1, &pl2);
/* Set up path loss info. data structure. */
pl_info_ptr = (Path_Loss_Info*) op_prg_mem_alloc (sizeof (Path_Loss_Info));
pl_info_ptr->distance = dist;
pl_info_ptr->coeff0 = pl0;
pl_info_ptr->coeff1 = pl1;
pl_info_ptr->coeff2 = pl2;
/* Reference the path loss info. data structure into the packet. */
/* This allows subsequent stages to access the path loss data. */
op_td_set_ptr (pkptr, PATH_LOSS_INFO_TDA, pl_info_ptr);
Details
Transmission data attributes are used to convey link modeling data between the Simulation Kernel and successive Transceiver Pipeline stages. The Td package KPs provide primitive operations (set and get) for operating on transmission data attributes. The basic format of a Pipeline stage model is a C file which contains a single function with the same name (for instance, the base Pipeline stage model dra_power is stored in the file dra_power.ps.c, and is implemented as the C function dra_power()). In most stages, the single argument of the function is a pointer to the packet on which the stage operates. The statements in the C function generally perform the following sequence of activities:
- Extract attributes from the packet’s transmission data (via the KPs op_td_get_dbl(), op_td_get_int(), op_td_get_int64(), and op_td_get_ptr()).
- Perform calculations which characterize the corresponding stage of the link model (typically a combination of numerical and symbolic processing).
- Assign newly computed attributes to the packet’s transmission data (via the KPs op_td_set_dbl(), op_td_set_int(), op_td_set_int64(), and op_td_get_ptr()).
Pointer values stored in TDAs can reference arbitrarily complex data structures stored outside the packet. However, unlike structure fields of packets, pointer TDAs benefit from no special memory handling by the Simulation Kernel. Thus, when a packet is destroyed, memory referenced by pointer-type TDAs is not deallocated. Also, when packets are copied, pointers are copied as simple values, and there is no automatic mechanisms for duplicating the referenced data structures.
Purpose
Provides a mechanism to assign a value to an attribute of the transmission data which is associated with each packet passing through the stages of the Transceiver Pipeline of a link model. This KP is used to assign a single pointer attribute value within the specified packet’s transmission data block. Typically pointer TDA values are used to associate complex information, such as tables or compound data structures, with packets.
Errors
- Recoverable Error:
<type>TDA (<name>) cannot be set using 'op_td_set_ptr'. - Program Abort: Segmentation violation. (due to an invalid packet pointer or malformed packet)
- Program Abort: KP cannot be called from process context.
- Program Abort: Packet pointer is NIL.
- Program Abort: Packet pointer references destroyed packet (
<pk_id>). - Program Abort: Read-only TDA (
<tda_name>) cannot be assigned in (<pk_id>). - Program Abort: Tda index (
<tda_index>) is out-of-range for packet (<pk_id>). - Program Abort: Tda (
<tda_name>) is unassigned in packet (<pk_id>).
Reference
- Use the KP op_td_set_int() or op_td_set_int64() to assign the value of an integer transmission data attribute
- Use the KP op_td_set_dbl() to assign the value of a double transmission data attribute
- Use the KP op_td_get_int() or op_td_get_int64() to obtain the value of an integer transmission data attribute
- Use the KP op_td_get_dbl() to obtain the value of a double transmission data attribute
- Use the KP op_td_get_ptr() to obtain the value of a pointer transmission data attribute