General Sub-Package

Packets are dynamic simulation entities, with a life cycle: they are created, exist for some amount of time, and then destroyed to recycle their memory for use by other packets. The three types of packets (formatted, unformatted, and value vector) are created by separate KPs, because they are fundamentally different. The act of creation consists of dynamic memory allocation of the packet data structure, and assignment of default values. The KP op_pk_create() creates an unformatted packet, with a specified initial bulk size. The KP op_pk_create_fmt() creates a formatted packet, based on a specified packet format created via the Packet Format Editor. The KP op_pk_create_vvec() creates a value vector packet that can contain only binary value vectors. All of these KPs return pointers to the same Packet data structure, because the packets are only internally different. All packets can be destroyed using the same KP, op_pk_destroy(). The type of a packet (formatted, unformatted, or value vector) can be determined by calling the KP op_pk_type().

Another method for creating a packet is to copy an existing packet. Copying a packet via the KP op_pk_copy() creates a clone of the original packet header, with all the same data except for the creation time and module. The packet copy references the fields in the original packet. Later, if a field of either the original packet or the copy is to be changed, all of the packet fields are copied to the packet copy. The KP op_pk_transfer() does a similar function, except that it transfers the contents of one packet into an existing packet.

Each packet is an individual entity, with its own unique identifier. Packet IDs are integer values that serve as serial numbers; they are useful in debugging since the debugger prints out the IDs of packets involved in operations being traced. The ID of a packet is assigned when the packet is first created (either through directly creating it, copying it from another packet, or statically declaring it). A packet ID can be obtained using the KP op_pk_id(). Packets carry an additional identifier called a tree ID. A packet tree begins with a single original packet when it is first created or statically declared. When any packet in a tree is copied, the copy is also given the same tree ID. This identifier is useful for tracing packets when they are copied for retransmission or flooding, for example. A packet tree ID may be obtained through the KP op_pk_tree_id().

The concept of a time-stamp is common in data communications: time stamps serve as references for operations performed on data. Packet stamps are provided by the Simulation Kernel for both time and location, so that a packet operation performed by a process can be documented. The kernel procedure op_pk_stamp() stamps the specified packet with the current simulation time and the object identifier of the processor or queue running the invoking process. After a packet has been stamped, any process that the packet travels to can extract the stamp information, and use it to determine the last time and place that a particular operation was performed on the packet. The KP op_pk_stamp_mod_get() extracts the object identifier of the module where the packet was stamped, and the KP op_pk_stamp_time_get() extracts the time when the packet was stamped. Packets can be repeatedly stamped, with each successive stamp overriding the previous stamp. Cosimulations needing to set the automatic stamp for packets received from another simulation can use op_pk_stamp_mod_set() and op_pk_stamp_time_set().

In addition to elective packet stamping, there is an automatic stamp which occurs when a packet is created. The creation stamp consists of the time when the packet was created, and the module which created the packet. Two KPs are used to extract the creation stamp data: op_pk_creation_mod_get() extracts the creating module, and op_pk_creation_time_get() extracts the creation time. Items such as packet stamps and packet IDs remain intact while a packet is transferred among Riverbed Modeler objects. Cosimulations needing to set the automatic stamp for packets received from another simulation can use op_pk_creation_mod_set() and op_pk_creation_time_set().

Note: If the “sim_time_quantum“ preference has a value other than 0.0, all time stamps will be a multiple of the specified quantum.

Transfer of packets is a major activity of simulations. There are two modes of packet transfer between modules, each with a unique name: sending a packet transfers a packet through a packet stream connecting the source and destination modules; delivering a packet transfers a packet without involving a packet stream (i.e., via direct transfer to the remote module’s input). The two modes of transfer are useful for different applications. Packet sends can only occur over output streams which are directly connected to modules. There are four methods of sending packets:

  • The regular send operation is scheduled (i.e., it occurs only after the invoking process has released control, and any higher priority events scheduled for that time have completed). However, regular sends are not delayed; the packet arrival at the destination module occurs at the same simulation time that the packet is sent. When a packet arrives at the destination module, it causes a corresponding stream interrupt. The KP op_pk_send() performs the regular send operation.
  • The delayed send operation is scheduled like the regular send operation, but it is delayed until a specified time in the future. Delayed sends also cause stream interrupts at the destination module. The KP op_pk_send_delayed() performs the delayed send operation.
  • The quiet send operation is not scheduled; it occurs while its associated KP has control. Quiet sends do not cause stream interrupts at the destination module; indeed, they are designed so that the arriving packets can be obtained by the destination module through synchronous polling instead of asynchronous interrupts. The KP op_pk_send_quiet() performs the quiet send operation.
  • The forced send operation is also not scheduled; it occurs while its associated KP has control. Forced sends do cause stream interrupts at the destination module, however. If a forced send has a processor or queue destination, the interrupted process must release control before the forced send KP releases control. Forced sends must be used with care, and should never be performed by modules connected in a cyclic configuration (this can result in an infinite interrupt loop). The KP op_pk_send_forced() performs the forced send operation.

The second mode of packet transfer in simulations is called delivery. Packet delivery is a connectionless transfer of a packet from a process to an unconnected input stream of some module. The target module can be the originating module, another module in the same node, or a remote module in some other node. Like sending, there are also four methods of delivering packets. Packet deliveries can be:

Packets can be sent or delivered to four module types (queues, processors, esys modules, and transmitters). When the destination is an esys module, queue or processor, the packet resides in an input stream until the associated process extracts the packet from the stream. The KP op_pk_get() performs the extraction operation; a specified argument is the stream which should be accessed for the operation. When a process is interrupted by a stream interrupt, it can determine the stream on which to operate by calling the KP op_intrpt_strm().

Packets arriving at radio or bus transmitters will be broadcast using the radio or bus link models. There is a special property of packets that affects the manner in which such broadcasts are performed. Broadcasts can be general, in which case the packet reaches every eligible radio or bus receiver. Broadcasts can also be unique, in which case the “broadcast” is constrained to only reaching eligible receivers within a single specified node. The KP op_pk_bcast_general() sets the broadcast property of a packet to be general, while op_pk_bcast_unique() sets it to be unique. The KP op_pk_bcast_get() obtains a pointer to the information that was broadcast.

Packets arriving at a radio receiver potentially experience interference from other packets. Several radio pipeline stages (SNR, BER, and Error Allocation) are invoked both for a packet (P₁) being received and for each valid packet (Pₙ) also being received, to allow Pₙ to adjust to the start or end of any interference from P₁. There are two KPs that can be called from these pipeline stages to provide information about the packet being received. The KP op_pk_interfering_pk_get() returns a pointer to the packet being received (P₁). The KP op_pk_transmission_phase_get() obtains the current transmission phase of packet P₁.

Queues and esys modules execute process models to implement various queueing strategies. One of the most common types of queueing strategies is based on prioritization of packets within a queue. The information used to prioritize packets is stored in a special property of the packet, rather than a data field, so that it can accompany the packet without affecting the structure of the data. The KP op_pk_priority_set() sets the priority value of a packet, and the KP op_pk_priority_get() obtains this value.

There are three types of bit sizes associated with formatted and unformatted packets. Each field within a packet has a size, which is either determined from a predefined packet format (formatted packets) or set along with the field (unformatted packets). Field sizes can be obtained via the op_pk_fd_size() and op_pk_nfd_size() KPs. Packets have a second type of bit size, which is called the bulk data size. Bulk data bits are simply simulated filler that represents unstructured data in real packets. The bulk data size of a packet can be determined by calling the KP op_pk_bulk_size_get(), or set by the KP op_pk_bulk_size_set(). The final type of bit size is the total size of a packet, which is the sum of the sizes of each packet field and the bulk data size. The total size of a packet can be determined by the KP op_pk_total_size_get(), or directly modified by the KP op_pk_total_size_set().

Value vector packets do not have field sizes, but they do have a bulk size and a total size. Their total size equals the bulk size plus the size of the value vector contained in the packet.

Formatted packets are based on a packet format model that is defined in the Packet Format Editor. Processes that deal with several types of packets might need to determine the format of a packet when it arrives. The KP op_pk_is_format() tests the name of the packet format against a string. The KP op_pk_format() obtains the name of the packet format.

During debugging of process operations in a simulation, it is important to get as much information as possible about what is happening. The trace capability of the simulation debug mode is a key tool to follow the flow of process logic. Another way to gain insight is to print the contents of incoming packets, via the KPs op_pk_print() and op_pk_print_options(). The first KP produces a detailed listing of a packet’s contents on the Windows console or the Linux standard output device. The second KP adds the ability to include TDA and VVEC information in the output.

When packets with unknown structures are being processed, it may be necessary for a process to determine the maximum index of any field in a packet in order to loop through the packet’s fields and investigate field properties or content. The maximum field index can be obtained by calling the KP op_pk_fd_max_index(). The number of fields in a packet can be obtained with op_pk_num_fds(), or the number of formatted and unformatted fields can be obtained with op_pk_num_fields_get().

Four KPs enable you to work with packets that have been or will be encapsulated. The KP op_pk_encap_pk_access() gets a reference to an encapsulated packet. The KP op_pk_encap_pk_get() creates a copy of an encapsulated packet without having to decapsulate it first. The KPs op_pk_encap_flag_set() and op_pk_encap_flag_is_set() create and check for flags on packets that are inherited by any encapsulating packets.

Items such as packet stamps and packet IDs remain intact while a packet is transferred among Riverbed Modeler objects, but a Riverbed Modeler packet cannot be passed into an external system. Several strategies for preserving such information when sending data through external systems are discussed in Chapter 8 “External System Domain” on page 331.