Package Overview
The Vvec (Value Vector) package is a collection of Kernel Procedures used during cosimulation to manipulate value vectors and prepare data in value vectors for use with external systems. A value vector is a collection of values referred to by a single name. They are similar to arrays in that they can be thought of as a sequence of values, and each position in the sequence is referred to by an index number. They are different from arrays in that an element of a value vector does not necessarily correspond to a specific location in memory. The Kernel Procedures in this package make working with value vectors easier and more convenient than working with arrays. The values that a value vector stores may be any standard C data type.
WARNING: For data types of boolean and bit, do not use the literal values 0 and 1. Instead, use the corresponding symbolic constants:
– OpC_Bool_F and OpC_Bool_T for boolean
– OpC_Bit_0 and OpC_Bit_1 for bit
One of the reasons that value vectors are used is to make it convenient to convert values from their C data types into bit representations, which can be passed easily to an external system during cosimulation. Two procedures handle these transformations. The first, op_vvec_from_value(), takes a value and produces a bit representation of the value and places the representation into a value vector. The other procedure, op_vvec_to_value(), produces a standard C data type value from a bit representation of the value.
Like packets, value vectors must be created and destroyed. When a creating a value vector, the Simulation Kernel assigns memory to the vector. Destroying the value vector releases that memory. If a simulation consistently creates value vectors, but does not destroy them when they are no longer needed, memory may fill up, which results in a system crash. The procedure used to create value vectors is op_vvec_create(), and the procedure used to destroy them is op_vvec_destroy(). Typically, when creating value vectors, they are assigned to a variable name for future access.
Two other procedures also create value vectors. op_vvec_copy() returns a new value vector that consists of all or part of an existing value vector. op_vvec_remove() produces a new value vector that consists of values removed from an existing value vector. Value vectors created using these procedures must also be destroyed, just as those created with op_vvec_create().
Value vectors created with op_vvec_create() contain no values. Unlike arrays, the size of a value vector (in number of elements) does not need to be specified at creation. The size can grow and shrink as needed over the lifetime of the value vector. Individual elements in a value vector are assigned a value with the procedure op_vvec_value_set(). Elements in a value vector do not need to be set in order. If the fifth element in a new vector is assigned a value, the preceding four values are automatically set to 0. To find out the value of a specific element in a value vector, use the procedure op_vvec_value_get().
The remaining procedures in the Vvec package allow you to work with value vectors in various ways. op_vvec_insert(), for example, allows you to insert one value vector into another at the beginning, middle, or end. op_vvec_valid() determines whether a value vector is valid. op_vvec_type_get() tells you the value vector’s type as specified when it was created, and op_vvec_print() sends the contents of the value vector to the standard output device. Finally, op_vvec_size_get() returns the number elements in the value vector.