Вы находитесь на странице: 1из 34

8Interface Control Information Package

Interface Control Information Package

Function List
The ICI package contains the following KPs. op_ici_attr_exists() on page DES-8-4 Determines whether an attribute specified by name is defined within an ICIs format. op_ici_attr_get() on page DES-8-6 Obtains the value of an attribute in the specified ICI. op_ici_attr_get_dbl() on page DES-8-9 Obtains the value of a double attribute in the specified ICI. op_ici_attr_get_int32() on page DES-8-10 Obtains the value of an integer attribute in the specified ICI. op_ici_attr_get_ptr() on page DES-8-11 Obtains the value of a pointer attribute in the specified ICI. op_ici_attr_set() on page DES-8-12 Assigns the value of an attribute in the specified ICI. op_ici_attr_set_dbl() on page DES-8-14 Assigns the value of a double attribute in the specified ICI. op_ici_attr_set_int32() on page DES-8-16 Assigns the value of an integer attribute in the specified ICI. op_ici_attr_set_ptr() on page DES-8-18 Assigns the value of a pointer attribute in the specified ICI. op_ici_create() on page DES-8-20 Creates a new ICI with a predefined structure described by the specified ICI format. op_ici_destroy() on page DES-8-22 Deallocates the specified ICI, releasing associated memory resources for other purposes. op_ici_format() on page DES-8-24 Obtains the name of the ICI format associated with the specified ICI. op_ici_format_print_proc_set() on page DES-8-26 Sets a custom print procedure for the named structure field of ICIs with the given format. op_ici_id() on page DES-8-28 Gets the ID of an ICI. op_ici_id_str_get() on page DES-8-29 Gets a string representation of an ICI ID.

Modeler/Release 14.0

DES-8-1

8Interface Control Information Package

op_ici_install() on page DES-8-30 Establishes the specified ICI as the installed ICI, which is automatically associated with outgoing interrupts scheduled by the invoking process. op_ici_print() on page DES-8-32 Prints the contents of the specified ICI onto the standard output device. See Package Overview for a general description of this KP package.

Package Overview
The ICI (Interface Control Information) package is a collection of Kernel Procedures concerned with the ICI simulation entity, which is an acronym for Interface Control Information. An ICI is a structured collection of data that is transferred between processes, as a form of inter-process communication. An ICI becomes associated with an interrupt if a process installs the ICI prior to taking the action that causes the interrupt. Layered protocol interfacing is the main application of ICIs, but they can also be used to associate information with sophisticated self interrupts or peer-to-peer remote interrupts. ICIs are dynamic simulation entities, since they are created and destroyed as needed during the execution of a process. The KP op_ici_create() is used to create ICIs, based on a specified ICI format. An ICI format, which has been created using the ICI Format Editor, determines the list of attribute names and data types supported by the newly created ICI. After an ICI is created, op_ici_create() returns a pointer to the ICI, which is used to reference the ICI in most Ici package KPs. When an existing ICI is no longer necessary, it can be destroyed using the KP op_ici_destroy(). Destruction entails the deallocation of the ICIs memory resources. ICIs are usually destroyed by the process that receives them, because the receiving process is most aware of when they have fulfilled their function. A newly created ICI has no information contained within it; this must be added on a per-attribute basis. The KPs op_ici_attr_set(), op_ici_attr_set_dbl(), op_ici_attr_set_int32(), and op_ici_attr_set_ptr() are used to set the value of a single ICI attribute. All of the data types supported by ICI attributes (integer, double, and data structure pointer) can be assigned using op_ici_attr_set(). However, the type-specific KPs are more efficient and allow the compiler to catch potential argument errors.

DES-8-2

Modeler/Release 14.0

8Interface Control Information Package

Multiple ICIs can be created by a process, assigned attribute values, and maintained by storing their pointers in state or temporary variables. However, only one ICI per process will be actively associated with outgoing interrupts. In order to install an ICI as the one that should be associated with interrupts, the KP op_ici_install() should be invoked with a pointer to the ICI. An ICI will stay installed until another ICI is installed using the same method. When an ICI has been received by a process, a pointer to it can be obtained by the KP op_intrpt_ici(). The ICIs attribute values can then be obtained via the KP op_ici_attr_get() and its type-specific versions, which are similar in interface style to the op_ici_attr_set KPs. Because some process models might have to accept ICIs of several different formats containing different attributes, it might be necessary to verify that an attribute is present with op_ici_attr_exists() prior to extracting values. When a sophisticated process expects that interrupts will arrive that are associated with different types of ICIs, it can identify the format of a received ICI via the KP op_ici_format(). While debugging process models, you can print the contents of an ICI with the KP op_ici_print(). With the KP op_ici_format_print_proc_set() you can print custom ICI structure fields. You can get the ID of an ICI in numeric or string format by using op_ici_id() or op_ici_id_str_get(), respectively.

Function Descriptions
Detailed descriptions of the Interface Control Information package functions follow.

Modeler/Release 14.0

DES-8-3

8Interface Control Information Package

op_ici_attr_exists()
Abstract

Determines whether an attribute specified by name is defined within an ICIs format. op_ici_attr_exists (iciptr, attr_name)
Argument iciptr Type Ici * Description pointer to the ICI-of-interest [A pointer to an ICI can be obtained from three KPs: op_ici_create() returns a pointer to a newly allocated ICI (in an ICI-sending process); op_intrpt_ici() returns a pointer to an ICI associated with an incoming interrupt (in an ICI-receiving process; and op_ev_ici() returns the ICI associated with a particular event.] attr_name const char * name of the attribute-of-interest

Syntax

Return Type

Boolean

Boolean value indicating if the specified attribute is present within the specified ICI. The constant OPC_FALSE will be returned if the attribute is not present or if a recoverable error occurs. The constant OPC_TRUE will be returned if the attribute does exist.

Example

Excerpt from: example model (models\std\fddi); process model (fddi_mac_v4); state (ENCAP); enter execs.
/* /* /* if A frame has arrived from a higher layer. */ If in encap_decap mode, encapsulation is to be*/ to be performed. Place the frame in 'pdu_ptr'.*/ (encap_decap == OPC_TRUE) { pdu_ptr = op_pk_get (op_intrpt_strm ()); if (pdu_ptr == OPC_NIL) { fddi_mac_error ("Unable to get packet from higher layer.", OPC_NIL, OPC_NIL); } /* Also get the interface control information*/ /* associated with the new frame.*/ ici_ptr = op_intrpt_ici (); if (ici_ptr == OPC_NIL) { fddi_mac_error ("Did not receive ICI with packet from higher layer.", OPC_NIL, OPC_NIL); } /* Extract the requested service class: synchronous or asynchronous. */ if (op_ici_attr_exists (ici_ptr, "svc_class")) { if (op_ici_attr_get (ici_ptr, "svc_class", &svc_class) == OPC_COMPCODE_FAILURE) { fddi_mac_error ("Unable to get service class field from ICI.", "The field does exist, but the get call failed.", OPC_NIL); } } else svc_class = FDDI_SVC_ASYNC; . . .

DES-8-4

Modeler/Release 14.0

8Interface Control Information Package

Details

Unlike formatted packet fields, ICI attributes defined within an ICI format exist from the moment that the ICI is created, and always have an initial value. There is no notion of an ICI attribute being set or unset; therefore this KP has only to do with the existence of a particular attribute within an ICIs format, rather than within an ICI instance. Attempting to set or get an ICI attribute via the KPs op_ici_attr_set() or op_ici_attr_get() will cause an error if the specified attribute name is not one of those defined in the ICIs format. In order to avoid such errors and still support interfaces where several types of ICIs and possibly unknown ICI formats are used, process models need to be able to test for the existence of attributes before accessing them. The KP op_ici_attr_exists() provides this capability. Program Abort: Segmentation violation. (due to an illegal ICI address, malformed ICI data structure, or malformed attr_name argument) Recoverable Error: ICI pointer is NIL.

Purpose

Errors

Reference

Use the KP op_intrpt_ici() to obtain the ICI pointer associated with an incoming interrupt Use the KP op_ici_attr_get() to obtain the value of an ICI attribute Use the KP op_ici_attr_set() to modify the value of an ICI attribute

Modeler/Release 14.0

DES-8-5

8Interface Control Information Package

op_ici_attr_get()
Abstract Syntax

Obtains the value of an attribute in the specified ICI. op_ici_attr_get (iciptr, attr_name, value_ptr)
Argument iciptr Type Ici * Description pointer to the ICI-of-interest [A pointer to an ICI can be obtained from two KPs: op_ici_create() returns a pointer to a newly allocated ICI (in an ICI-sending process), and op_intrpt_ici() returns a pointer to an ICI associated with an incoming interrupt (in an ICI-receiving process).] attr_name value_ptr const char * void * name of the attribute-of-interest pointer to a variable to be filled in with the specified attributes value [This argument can accept a pointer to an integer, a double, or a data structure pointer. The data type of the argument pointer must match the data type of the specified attribute.]

Return Type

Compcode

Completion code indicating if the requested attribute value was successfully obtained from the ICI. The value OPC_COMPCODE_FAILURE will be returned if any of the recoverable errors listed in the Errors section for this KP occur.

Example

Excerpt from: example model (models\std\fddi); process model (fddi_mac_v4); state (ENCAP); enter execs.
/* Extract the requested service class: synchronous or asynchronous. */ if (op_ici_attr_exists (ici_ptr, "svc_class")) { if (op_ici_attr_get (ici_ptr, "svc_class", &svc_class) == OPC_COMPCODE_FAILURE) { fddi_mac_error ("Unable to get service class field from ICI.", "The field does exist, but the get call failed.", OPC_NIL); } } else svc_class = FDDI_SVC_ASYNC; /* Extract the destination address. */ if (op_ici_attr_get (ici_ptr, "dest_addr", &dest_addr) == OPC_COMPCODE_FAILURE) { fddi_mac_error ("Unable to get destination address field from ICI.", OPC_NIL, OPC_NIL); }

Details

The specified attribute name must be one of the attributes defined in the ICI format which is the basis of the ICI pointed to by the iciptr argument. Note that the value obtained by this KP is the current contents of the specified attribute in the ICI; it is not the contents of the attribute when the ICI was installed nor when the associated interrupt was scheduled.

DES-8-6

Modeler/Release 14.0

8Interface Control Information Package

Process models manipulate ICIs via their pointers and unlike packets, there is no notion of ownership for an ICI. This means that several process models may concurrently have legitimate access to the same ICI data structure and interfere with each others use of the attributes. Another common problem occurs when the same ICI is used in association with multiple events. It is important to realize that while an ICI may be associated with multiple events, modifications to the ICI that are made in preparation for the later events may also affect the use of that ICI during earlier events, if these have not yet occurred at the time of the modification. For instance, if a process creates an ICI, assigns its attributes, installs it, sends out a packet, and then modifies an attribute of the ICI before the packet is received, the later value will be the one provided when the process model receiving the packet accesses the ICI via op_ici_attr_get(). Care must be taken in properly declaring the value_ptr argument. For integers and doubles, this must be a valid pointer to a usable area of memory; for pointers, it should be a pointer to a pointer of the correct datatype. Therefore, this argument is usually written using the C address operator (&) applied to a declared variable of the appropriate type, as shown in the Example section.
Purpose

Provides a mechanism for a process that has received an interrupt with an associated ICI to determine the values of the ICIs attributes. This capability forms the receive side of ICI-based communications between processes. Note also that, because a single ICI can be shared by multiple processes, it can be used for multi-way communication where a process that receives an interrupt obtains certain control information from the ICI, but also returns information by setting attributes in the same ICI. This is a particularly useful technique when used in combination with forced interrupts, since the return value can be accessed immediately by the originating process. Data-type-specific versions of this KP exist. These alternate KPs are more efficient than this variable argument version. In addition, they allow the compiler to catch argument errors that are missed with this KP. For details, refer to op_ici_attr_get_dbl(), op_ici_attr_get_int32(), and op_ici_attr_get_ptr().

Errors

Program Abort: Segmentation violation (due to an invalid ICI pointer, malformed ICI data structure, or incorrectly declared value_ptr argument). Recoverable Error: Attribute name (<attr_name>) is unrecognized in ICI with format (<format_name>).

Reference

Use the KP op_intrpt_ici() to obtain the ICI pointer associated with an incoming interrupt Use the KP op_ici_attr_exists() to determine if an ICI attribute is present within an ICI format Use the KP op_ici_attr_set() to perform the inverse operation and set an attribute of an ICI

Modeler/Release 14.0

DES-8-7

8Interface Control Information Package

Use the KP op_ici_destroy() to deallocate an ICI that is no longer necessary Use the KP op_ici_print() to print the contents of an ICI on the standard output device

DES-8-8

Modeler/Release 14.0

8Interface Control Information Package

op_ici_attr_get_dbl()
dbl

Abstract Syntax

Obtains the value of a double attribute in the specified ICI. op_ici_attr_get_dbl (iciptr, attr_name, value_ptr)
Argument iciptr Type Ici * Description pointer to the ICI-of-interest [A pointer to an ICI can be obtained from two KPs: op_ici_create() returns a pointer to a newly allocated ICI (in an ICI-sending process), and op_intrpt_ici() returns a pointer to an ICI associated with an incoming interrupt (in an ICI-receiving process).] attr_name value_ptr const char * double * name of the attribute-of-interest pointer to a variable to be filled in with the specified attributes value

Return Type

Compcode

OPC_COMPCODE_SUCCESS if the attribute value was successfully obtained; OPC_COMPCODE_FAILURE otherwise.

Example

dbl

AAL2_Peak_Cell_Rate;

/* Copy the contents of the ICI into the created data structure. */ op_ici_attr_get_dbl (aal_params_iciptr, "max bit rate", &(aal_params_struct_ptr->AAL2_Peak_Cell_Rate));

Details Purpose

None. Provides a mechanism to enable a process that has received an interrupt with an associated ICI to determine the values of the ICIs attributes. This KP works identically to op_ici_attr_get(), but applies only to ICI attributes of data type double. Refer to op_ici_attr_get() on page DES-8-6 for full purpose and details. Same as op_ici_attr_get(). Use the KP op_intrpt_ici() to obtain the ICI pointer associated with an incoming interrupt Use the KP op_ici_attr_get_int32() to obtain the value of an integer attribute in a specified ICI Use the KP op_ici_attr_get_ptr() to obtain the value of a pointer attribute in a specified ICI

Errors Reference

Modeler/Release 14.0

DES-8-9

8Interface Control Information Package

op_ici_attr_get_int32()
int32

Abstract Syntax

Obtains the value of an integer attribute in the specified ICI. op_ici_attr_get_int32 (iciptr, attr_name, value_ptr)
Argument iciptr Type Ici * Description pointer to the ICI-of-interest [A pointer to an ICI can be obtained from two KPs: op_ici_create() returns a pointer to a newly allocated ICI (in an ICI-sending process), and op_intrpt_ici() returns a pointer to an ICI associated with an incoming interrupt (in an ICI-receiving process).] attr_name value_ptr const char * int * name of the attribute-of-interest pointer to a variable to be filled in with the specified attributes value

Return Type

Compcode

OPC_COMPCODE_SUCCESS if the attribute value was successfully obtained; OPC_COMPCODE_FAILURE otherwise.

Example

int

AAL1_Structured_Data_Size;

/* Copy the contents of the ICI into the created data structure. */ op_ici_attr_get_int32 (aal_params_iciptr, "SDT block size", &AAL1_Structured_Data_Size);

Details Purpose

None. Provides a mechanism to enable a process that has received an interrupt with an associated ICI to determine the values of the ICIs attributes. This KP works identically to op_ici_attr_get(), but applies only to ICI attributes of data type integer. Refer to op_ici_attr_get() on page DES-8-6 for full purpose and details. Same as op_ici_attr_get(). Use the KP op_intrpt_ici() to obtain the ICI pointer associated with an incoming interrupt Use the KP op_ici_attr_get_dbl() to obtain the value of a double attribute in a specified ICI Use the KP op_ici_attr_get_ptr() to obtain the value of a pointer attribute in a specified ICI

Errors Reference

DES-8-10

Modeler/Release 14.0

8Interface Control Information Package

op_ici_attr_get_ptr()
ptr

Abstract Syntax

Obtains the value of a pointer attribute in the specified ICI. op_ici_attr_get_ptr (iciptr, attr_name, value_ptr)
Argument iciptr Type Ici * Description pointer to the ICI-of-interest [A pointer to an ICI can be obtained from two KPs: op_ici_create() returns a pointer to a newly allocated ICI (in an ICI-sending process), and op_intrpt_ici() returns a pointer to an ICI associated with an incoming interrupt (in an ICI-receiving process).] attr_name value_ptr const char * void ** name of the attribute-of-interest pointer to a variable to be filled in with the specified attributes value

Return Type

Compcode

OPC_COMPCODE_SUCCESS if the attribute value was successfully obtained; OPC_COMPCODE_FAILURE otherwise.

Example

/* Get the list Hard PVXs from the ICI. */ if (op_ici_attr_get_ptr (intrpt_iciptr, "Hard PVX Node Description", &hard_pvx_lptr) == OPC_COMPCODE_FAILURE) { ams_call_control_error ("The Hard PVX List field in the ICI oms_atm_pvx_config has not been set", OPC_NIL, OPC_NIL); }

Details Purpose

None. Provides a mechanism to enable a process that has received an interrupt with an associated ICI to determine the values of the ICIs attributes. This KP works identically to op_ici_attr_get(), but applies only to ICI attributes of data type pointer. Refer to op_ici_attr_get() on page DES-8-6 for full purpose and details. Same as op_ici_attr_get(). Use the KP op_intrpt_ici() to obtain the ICI pointer associated with an incoming interrupt Use the KP op_ici_attr_get_dbl() to obtain the value of a double attribute in a specified ICI Use the KP op_ici_attr_get_int32() to obtain the value of an integer attribute in a specified ICI

Errors Reference

Modeler/Release 14.0

DES-8-11

8Interface Control Information Package

op_ici_attr_set()
Abstract Syntax

Assigns the value of an attribute in the specified ICI. op_ici_attr_set (iciptr, attr_name, value)
Argument iciptr Type Ici * Description pointer to the ICI-of-interest [A pointer to an ICI can be obtained from two KPs: op_ici_create() returns a pointer to a newly allocated ICI (in an ICI-sending process), and op_intrpt_ici() returns a pointer to an ICI associated with an incoming interrupt (in an ICI-receiving process).] attr_name value const char * void * name of the attribute-of-interest new value to assign to the specified attribute [This argument can accept an integer, a double, or a data structure pointer. The data type of the argument pointer must match the data type of the specified attribute.]

Return Type

Compcode

Completion code indicating if the requested attribute value was successfully modified in the ICI. The value OPC_COMPCODE_FAILURE will be returned if any of the recoverable errors listed in the Errors section for this KP occur.

Example

Excerpt from: example model (models\std\fddi); process model (fddi_mac_v4); state (FR_REPEAT); enter execs.
/* /* /* /* /* /* Check whether the received packet is tagged. If yes, then the tag will */ contain VLAN classification information of the packet, which we also */ need to pass to higher layer later within the MAC indication ICI */ (unless the MAC is operating in a bridge/switch node, since, in that case, */ the bridge module itself will decide the VLAN classification of the */ message either from its tag it may have or from its arrival port). */

if (mac_is_bridge_port == OPC_FALSE) { if (op_pk_nfd_is_set (tmp_pkptr, "tag") == OPC_TRUE) { /* The packet is tagged. Get the VLAN information */ /* and insert into the ICI. */ op_pk_nfd_access (tmp_pkptr, "tag", &tag_ptr); op_ici_attr_set (to_llc_ici_ptr, "vlan_id", tag_ptr->VID); } else op_ici_attr_set (to_llc_ici_ptr, "vlan_id", OMSC_VLAN_NULL_VID); }

DES-8-12

Modeler/Release 14.0

8Interface Control Information Package

Details

The specified attribute name must be one of the attributes defined in the ICI format which is the basis of the ICI pointed to by iciptr. Note that the value assigned by this KP will overwrite any value previously assigned to the attribute. In addition, the new value assigned to the attribute will be accessible to any other process which maintains a pointer to the ICI. Provides a mechanism for a process to set the contents of an ICI for communication to another process. This capability forms the transmit side of ICI-based communications between processes. Attributes can be set in a freshly created ICI (as in the case of a per-packet communication of parameters) or in an ICI that has already been sent to one or more target processes (as in the case of a persistent shared memory arrangement). Because the modified ICI may still be pointed to by its originating process, op_ici_attr_set() may be used to return results that the originating process can then obtain via op_ici_attr_get(). This type of two-way communication implemented with an ICI is typically implemented with the ICI accompanying a forced interrupt so that the originating process can obtain results immediately. Data-type-specific versions of this KP exist. These alternate KPs are more efficient than this variable argument version. In addition, they allow the compiler to catch argument errors that are missed with this KP. For details, refer to op_ici_attr_set_dbl(), op_ici_attr_set_int32(), and op_ici_attr_set_ptr().

Purpose

Errors

Program Abort: Segmentation violation. (due to an invalid ICI pointer, malformed ICI data structure, or incorrectly declared value argument). Program Abort: KP requires process context. Recoverable Error: Attribute name (<attr_name>) is unrecognized in ICI with format (<format_name>).

Reference

Use the KP op_ici_attr_get() to perform the inverse operation and access the value of an ICI attribute Use the KP op_ici_create() to obtain a newly created ICI Use the KP op_ici_install() to install an ICI for association with outgoing interrupts Use the KP op_ici_attr_exists() to determine if an attribute is present in an ICIs format

Modeler/Release 14.0

DES-8-13

8Interface Control Information Package

op_ici_attr_set_dbl()
dbl

Abstract Syntax

Assigns the value of a double attribute in the specified ICI. op_ici_attr_set_dbl (iciptr, attr_name, value)
Argument iciptr Type Ici * Description pointer to the ICI-of-interest [A pointer to an ICI can be obtained from two KPs: op_ici_create() returns a pointer to a newly allocated ICI (in an ICI-sending process), and op_intrpt_ici() returns a pointer to an ICI associated with an incoming interrupt (in an ICI-receiving process).] attr_name value const char * double name of the attribute-of-interest new value to assign to the specified attribute

Return Type

Compcode

OPC_COMPCODE_SUCCESS if the attribute value was successfully obtained; OPC_COMPCODE_FAILURE otherwise.

Example

dbl

tx_bandwidth;

/* Insert xmtr bandwidth in ICI. */ op_ici_attr_set_dbl (iciptr, "xmtr_bandwidth", tx_bandwidth);

Details Purpose

None. Provides a mechanism for a process to set the contents of an ICI for communication with another process. This KP works identically to op_ici_attr_set(), but applies only to ICI attributes of data type double. Refer to op_ici_attr_set() on page DES-8-12 for full purpose and details. Same as op_ici_attr_set(). Use the KPs op_ici_attr_get(), op_ici_attr_get_dbl(), op_ici_attr_get_int32(), and op_ici_attr_get_ptr() to perform the inverse operation and access the value of an ICI attribute Use the KP op_ici_attr_set_int32() to set the value of an integer attribute in a specified ICI Use the KP op_ici_attr_set_ptr() to set the value of a pointer attribute in a specified ICI Use the KP op_ici_create() to obtain a newly created ICI

Errors Reference

DES-8-14

Modeler/Release 14.0

8Interface Control Information Package

Use the KP op_ici_install() to install an ICI for association with outgoing interrupts Use the KP op_ici_attr_exists() to determine if an attribute is present in an ICIs format

Modeler/Release 14.0

DES-8-15

8Interface Control Information Package

op_ici_attr_set_int32()
int32

Abstract Syntax

Assigns the value of an integer attribute in the specified ICI. op_ici_attr_set_int32 (iciptr, attr_name, value)
Argument iciptr Type Ici * Description pointer to the ICI-of-interest [A pointer to an ICI can be obtained from two KPs: op_ici_create() returns a pointer to a newly allocated ICI (in an ICI-sending process), and op_intrpt_ici() returns a pointer to an ICI associated with an incoming interrupt (in an ICI-receiving process).] attr_name value const char * int name of the attribute-of-interest new value to assign to the specified attribute

Return Type

Compcode

OPC_COMPCODE_SUCCESS if the attribute value was successfully obtained; OPC_COMPCODE_FAILURE otherwise.

Example

int

dst_addr, src_addr, protocol_type;

/* Port is ready to receive the entity for transmission. */ op_ici_attr_set_int32 (mac_req_ici_ptr, "dest_addr", dst_addr); op_ici_attr_set_int32 (mac_req_ici_ptr, "src_addr", src_addr); op_ici_attr_set_int32 (mac_req_ici_ptr, "protocol_type", protocol_type); op_ici_install (mac_req_ici_ptr);

Details Purpose

None. Provides a mechanism for a process to set the contents of an ICI for communication with another process. This KP works identically to op_ici_attr_set(), but applies only to ICI attributes of data type integer. Refer to op_ici_attr_set() on page DES-8-12 for full purpose and details. Same as op_ici_attr_set(). Use the KPs op_ici_attr_get(), op_ici_attr_get_dbl(), op_ici_attr_get_int32(), and op_ici_attr_get_ptr() to perform the inverse operation and access the value of an ICI attribute Use the KP op_ici_attr_set_dbl() to set the value of a double attribute in a specified ICI Use the KP op_ici_attr_set_ptr() to set the value of a pointer attribute in a specified ICI Use the KP op_ici_create() to obtain a newly created ICI

Errors Reference

DES-8-16

Modeler/Release 14.0

8Interface Control Information Package

Use the KP op_ici_install() to install an ICI for association with outgoing interrupts Use the KP op_ici_attr_exists() to determine if an attribute is present in an ICIs format

Modeler/Release 14.0

DES-8-17

8Interface Control Information Package

op_ici_attr_set_ptr()
ptr

Abstract Syntax

Assigns the value of a pointer attribute in the specified ICI. op_ici_attr_set_ptr (iciptr, attr_name, value)
Argument iciptr Type Ici * Description pointer to the ICI-of-interest [A pointer to an ICI can be obtained from two KPs: op_ici_create() returns a pointer to a newly allocated ICI (in an ICI-sending process), and op_intrpt_ici() returns a pointer to an ICI associated with an incoming interrupt (in an ICI-receiving process).] attr_name value const char * void * name of the attribute-of-interest new value to assign to the specified attribute

Return Type

Compcode

OPC_COMPCODE_SUCCESS if the attribute value was successfully obtained; OPC_COMPCODE_FAILURE otherwise.

Example

/* Create a call description for this call. */ call_desc_ptr = ams_atm_call_desc_create (); /* Set the VPI, VCI and to_dest_port values in the call descriptor. */ call_desc_ptr->dest_atm_addr = atm_conn_handle->called_party_address; call_desc_ptr->to_dest_vpi = atm_conn_handle->vpi_value = vpi; call_desc_ptr->to_dest_vci = atm_conn_handle->vci_value = vci; call_desc_ptr->to_dest_port = atm_conn_handle->port_value = port; /* Set the call descriptor in the vc handle */ op_ici_attr_set_ptr (atm_conn_handle->vc_handle_ptr, "call desc pointer", call_desc_ptr);

Details Purpose

None. Provides a mechanism for a process to set the contents of an ICI for communication with another process. This KP works identically to op_ici_attr_set(), but applies only to ICI attributes of data type pointer. Refer to op_ici_attr_set() on page DES-8-12 for full purpose and details. Same as op_ici_attr_set(). Use the KPs op_ici_attr_get(), op_ici_attr_get_dbl(), op_ici_attr_get_int32(), and op_ici_attr_get_ptr() to perform the inverse operation and access the value of an ICI attribute Use the KP op_ici_attr_set_dbl() to set the value of a double attribute in a specified ICI

Errors Reference

DES-8-18

Modeler/Release 14.0

8Interface Control Information Package

Use the KP op_ici_attr_set_int32() to set the value of an integer attribute in a specified ICI Use the KP op_ici_create() to obtain a newly created ICI Use the KP op_ici_install() to install an ICI for association with outgoing interrupts Use the KP op_ici_attr_exists() to determine if an attribute is present in an ICIs format

Modeler/Release 14.0

DES-8-19

8Interface Control Information Package

op_ici_create()
Abstract

Creates a new ICI with a predefined structure described by the specified ICI format. op_ici_create (fmt_name)
Argument fmt_name Type const char * Description name of the ICI format to use as the basis for the created ICI [This value must be the name of a defined ICI format, or an error will occur.]

Syntax

Return Type

Ici *

Pointer to the newly created ICI. The constant OPC_NIL will be returned if any recoverable errors occur.

Example

Excerpt from: example model (models\std\x25); process model (x25_dce_ch); function block procedure (x25_dce_handle_ack).
/* Loop through saved packets that have been acked, discarding them. */ for (i = send_window_low; i != rcv_seq; INC(i)) { if (window [i].format & x25C_GFI_D_BIT) { /* The D bit was set on this packet when we sent it, so this represents and */ /* end-to-end confirmation; notify the higher layer. */ iciptr = op_ici_create ("x25_data"); op_ici_attr_set (iciptr, "primitive", OSIC_N_DATA_ACK_INDICATION); op_ici_attr_set (iciptr, "src address", chan_vars->local_addr); op_ici_attr_set (iciptr, "dest address", chan_vars->remote_addr); op_ici_attr_set (iciptr, "confirmation request",1); op_ici_attr_set (iciptr, "confirmation tag", window[i].tag); op_ici_install (iciptr); op_pk_send (op_pk_create (0), chan_vars->application); x25_dce_trace_msg ("Notifying higher layer of end-to-end confirmation"); window [i].format = 0; } }

Details

A new ICI is allocated by the Simulation Kernel, and its pointer is returned by this KP to allow assignment of ICI attributes in the originating process. The ICI has a predetermined and fixed structure based on an ICI format, consisting of an ordered list of attribute names and types. The newly created ICI does not automatically affect future scheduled interrupts; this can only be accomplished via installation using the KP op_ici_install().

DES-8-20

Modeler/Release 14.0

8Interface Control Information Package

Purpose

Provides a mechanism for a process model to introduce new ICIs for communicating with neighboring processes. If a process model varies ICI attributes each time it schedules an interrupt, and it schedules additional interrupts before some of its previously scheduled interrupts are delivered, then it should create a new ICI for each scheduled interrupt. If, on the other hand, two process models communicate using a series of undelayed ICI-bearing interrupts, then only one ICI need be created for unidirectional communication (or two for bidirectional), at the beginning of the simulation. Program Abort: Allocation of memory failed. (due to insufficient memory to hold new ICI or its attributes) Program Abort: KP requires process context. Recoverable Error: ICI format (<fmt_name>) is unrecognized.

Errors

Reference

Use the KP op_ici_destroy() to perform the inverse operation and deallocate an ICI Use the KP op_ici_attr_set() to assign the value of an ICI attribute Use the KP op_ici_install() to install an ICI for association with outgoing interrupts Use the KP op_ici_format_print_proc_set() to specify a custom print procedure for the named structure fields of ICIs with a given format

Modeler/Release 14.0

DES-8-21

8Interface Control Information Package

op_ici_destroy()
Abstract

Deallocates the specified ICI, releasing associated memory resources for other purposes. op_ici_destroy (iciptr)
Argument iciptr Type Ici * Description pointer to the ICI-of-interest [A pointer to an ICI can be obtained from two KPs: op_ici_create() returns a pointer to a newly allocated ICI (in an ICI-sending process), and op_intrpt_ici() returns a pointer to an ICI associated with an incoming interrupt (in an ICI-receiving process).]

Syntax

Return Type Example

void

no return value

Excerpt from: example model (models\std\x25); process model (x25_dte_rt); state startup
/* The DTE is trying to open the data link. */ switch (op_intrpt_type ()) { case OPC_INTRPT_REMOTE: /* Check for ICI indicating link established. */ if ((iciptr = op_intrpt_ici ()) != OPC_NIL); { op_ici_attr_get (iciptr, "primitive", &primitive); if (primitive == OSIC_DL_CONNECT_INDICATION) { x25_dte_trace_msg ("Data link connection established"); timer_stop (&timer); link_alive = 1; timer.delay = mod_vars.mv_timer_value [X25C_T20]; timer.code = X25C_T20; } /* The ICIs contents have been extracted so it can be discarded. */ op_ici_destroy (iciptr); }

Details

When a specific ICI will no longer be accessed or installed, memory resources allocated for it should be released for re-use in the creation of new ICIs. A failure to release unused ICI memory to the Simulation Kernel can result in a build up of outstanding ICIs. This may eventually cause a simulation to halt if it attains maximum virtual memory usage and it can no longer satisfy allocation requests for new objects. Provides a mechanism for recycling memory associated with ICIs which will no longer be used. The Simulation Kernel is free to assign this memory to other dynamic objects as needed by the progressing simulation. This KP should be invoked whenever an ICI is to be removed from access by processes. After invocation of this KP, the specified ICI pointer should be considered invalid (i.e., it can no longer be referenced or passed to KPs).
Modeler/Release 14.0

Purpose

DES-8-22

8Interface Control Information Package

Errors

Program Abort: Segmentation violation. (due to an invalid ICI pointer or malformed ICI data structure) Recoverable Error: ICI pointer is NIL

Reference

Use the KP op_ici_create() to perform the inverse operation and create an ICI Use the KP op_intrpt_ici() to obtain the pointer to an ICI associated with an incoming interrupt Use the KP op_ici_attr_set() to assign the value of an ICI attribute Use the KP op_ici_install() to install an ICI for association with outgoing interrupts

Modeler/Release 14.0

DES-8-23

8Interface Control Information Package

op_ici_format()
Abstract Syntax

Obtains the name of the ICI format associated with the specified ICI. op_ici_format (iciptr, format_name)
Argument iciptr Type Ici * Description pointer to the ICI-of-interest [A pointer to an ICI can be obtained from two KPs: op_ici_create() returns a pointer to a newly allocated ICI (in an ICI-sending process), and op_intrpt_ici() returns a pointer to an ICI associated with an incoming interrupt (in an ICI-receiving process).] format_name char * name of the ICI format on which the specified ICI is based [This value should be a statically declared character array, or a character pointer which points to dynamically allocated memory; either way, it must point to a string large enough to hold the format name for the specified packet.]

Return Type Example

void

no return value

Excerpt adapted from: example model (models\std\x25); process (cloud_encap); state (ENCAP); enter execs.
/* Get the ICI associated with the new arrival. */ iciptr = op_intrpt_ici (); /* Extract the addressing information from the ICI and insert it into the */ /* network packet. */ op_ici_attr_get (iciptr, "primitive", &primitive);

/* Obtain the ICI format name and interpret its contents accordingly. */ op_ici_format (iciptr, format_name); if (strcmp (name, "X25_connect") == 0) { /* ... */ } else { /* ... */ }

Details

This KP places the specified ICIs format name in the character string pointed to by format_name. The ICIs contents or installation status is not affected by invoking this KP.

DES-8-24

Modeler/Release 14.0

8Interface Control Information Package

Purpose

Provides a mechanism to determine the format associated with an ICI. This is useful for process models that receive ICIs of several different types: using this KP, they can distinguish between the different ICIs and then perform appropriate ICI operations. Program Abort: Segmentation violation. (due to an invalid ICI pointer or an invalid or insufficiently sized fmt_name argument) Recoverable Error: ICI pointer is NIL.

Errors

Reference

Use the KP op_intrpt_ici() to obtain the pointer to an ICI associated with an incoming interrupt Use the KP op_ici_attr_get() to obtain the value of an ICI attribute Use the KP op_pk_format() to obtain the format of a packet

Modeler/Release 14.0

DES-8-25

8Interface Control Information Package

op_ici_format_print_proc_set()
Abstract

Sets a custom print procedure for the named structure field of ICIs with the given format. op_ici_format_print_proc_set (format_name, field_name, print_proc)
Argument format_name field_name Type const char * const char * Description Name of the ICI format-of-interest. Name of the field-of-interest. [This name must be a defined structure field within the ICI format.] print_proc Ici_Struct_Print_Meth User-defined print procedure to be called when an ICI with the specified format and field is printed. See the Details section for the function prototype.

Syntax

Return Type

Compcode

Completion code indicating if the print procedure was successfully set. The value OPC_COMPCODE_FAILURE will be returned if any of the recoverable errors listed in the Errors section for this KP occur.
*/ */ */ */ */ */ */ */ */ */ */ */ */ */ */ */ */

Example

/* /* /* /* /* /* /* /* /* /* /* /* /* /* /* /* /*

Install a print procedure for the "address" field of all ICIs with the "ip_info" packet format. address_print_proc is defined in the function block as follows: void address_print_proc (void *structure_ptr, PrgT_List *dest_lptr) { char *char_line; ReqT_Address *addr_ptr; addr_ptr = (ReqT_Address *) structure_ptr; char_line = op_prg_mem_alloc (sizeof (char) * 60); sprintf (char_line, "subnet: %d", addr_ptr->subnet); op_prg_list_insert (dest_lptr, char_line, OPC_LISTPOS_TAIL); char_line = op_prg_mem_alloc (sizeof (char) * 60); sprintf (char_line, "node : %s", addr_ptr->node_name); op_prg_list_insert (dest_lptr, char_line, OPC_LISTPOS_TAIL); }

op_ici_format_print_proc_set ("ip_info", "address", address_print_proc);

Details

Use this KP to specify a function to be used for creating a textual representation of a data structure stored inside a structure type ICI field. Such data structures may be complex, so a representation is useful in debugging. When the ICI is printed (using iciprint_ev or iciprint_pk in ODB, or op_ici_print()), the specified print_proc will be called by the Simulation Kernel to obtain a textual representation of the particular structure field in the ICI.

DES-8-26

Modeler/Release 14.0

8Interface Control Information Package

The print_proc must have the following prototype:


typedef void (*Ici_Struct_Print_Meth) (void *structure_ptr, PrgT_List *dest_lptr);

The print_proc must add new entries to *dest_lptr. The contents of the structure field are passed in *structure_ptr. Use prg_mem_alloc() to allocate strings for addition to the list. The Simulation Kernel automatically deallocates all memory.
Purpose

Sets print_proc as the function to be called when the specified field (field_name) is printed for any ICI with the specified format (format_name). field_name must identify a structure field. Allows you to specify how structures unknown to the Simulation Kernel will be displayed when using iciprint_ev or iciprint_pk in ODB, or the op_ici_print() KP.

Errors

Recoverable Error: Field <field name> is not a structure field Recoverable Error: ICI format (<format_name>) is unrecognized. Recoverable Error: Attribute name (<field_name>) is unrecognized in ICI with format (<format_name>).

Reference

Use the KP op_ici_print() to print the contents of an ICI on the standard output device

Modeler/Release 14.0

DES-8-27

8Interface Control Information Package

op_ici_id()
Abstract Syntax

Gets the ID of an ICI. op_ici_id (iciptr)


Argument iciptr Type Ici * Description pointer to the ICI-of-interest [A pointer to an ICI can be obtained from two KPs: op_ici_create() returns a pointer to a newly allocated ICI (in an ICI-sending process), and op_intrpt_ici() returns a pointer to an ICI associated with an incoming interrupt (in an ICI-receiving process).]

Return Type Example

OpT_Ici_Id

ID of the specified ICI.

/* Get the ICI associated with the current interrupt */ iciptr = op_intrpt_ici (); /* Get the ICI ID */ ici_id = op_ici_id (iciptr);

Details

The format of the ICI ID varies depending on whether the ID is serialized globally (typical in sequential simulations) or by module (typical in parallel simulations). The serialization scheme is set by the op_runsim preference fully_serialized_event_ids. Provides a way to obtain the ID of an ICI. None. Use the KP op_ici_id_str_get() to obtain a string representation of an ICI ID

Purpose Errors Reference

DES-8-28

Modeler/Release 14.0

8Interface Control Information Package

op_ici_id_str_get()
Abstract Syntax

Gets a string representation of an ICI ID. op_ici_id_str_get (iciptr, buffer)


Argument iciptr Type Ici * Description pointer to the ICI-of-interest [A pointer to an ICI can be obtained from two KPs: op_ici_create() returns a pointer to a newly allocated ICI (in an ICI-sending process), and op_intrpt_ici() returns a pointer to an ICI associated with an incoming interrupt (in an ICI-receiving process).] buffer char * pointer to area to be filled with the string representation of the ICI ID (must be large enough to hold the string).

Return Type Example

void
char

No return value.
ici_id_str[20];

/* Get the ICI associated with the current interrupt */ iciptr = op_intrpt_ici (); /* Get the ICI ID as a string */ op_ici_id_str_get (iciptr, ici_id_str);

Details

If the simulation uses module-based ID generation, the string returned in buffer consists of the ID of the module in which the ICI was created and the creation index in that module. Otherwise, it is simply the global ICI creation index. Provides a way to obtain a well-formed string representation of an ICI ID, regardless of whether ID generation is module-based or global. None. Use the KP op_ici_id() to obtain an ICI ID

Purpose

Errors Reference

Modeler/Release 14.0

DES-8-29

8Interface Control Information Package

op_ici_install()
Abstract

Establishes the specified ICI as the installed ICI, which is automatically associated with outgoing interrupts scheduled by the invoking process. op_ici_install (iciptr)
Argument iciptr Type Ici * Description pointer to the ICI-of-interest [A pointer to an ICI can be obtained from two KPs: op_ici_create() returns a pointer to a newly allocated ICI (in an ICI-sending process), and op_intrpt_ici() returns a pointer to an ICI associated with an incoming interrupt (in an ICI-receiving process).]

Syntax

Return Type Example

Ici *

Previously installed ICI, or OPC_NIL if none.

Excerpt from: example model (models\std\eth_net); process model (eth_gen); state (ARRIVAL); enter execs.
/* determine the length of the packet to be generated */ pklen = op_dist_outcome (len_dist_ptr); /* determine the destination of the packet... */ gen_packet: dest_addr = op_dist_outcome (dest_dist_ptr); if (dest_addr != -1 && dest_addr == station_addr) goto gen_packet; /* create an unformatted packet to send to mac */ pkptr = op_pk_create (pklen); /* place the destination address into the ICI... */ op_ici_attr_set (mac_iciptr, "dst_addr", dest_addr); /* send the packet coupled with the ICI. Then deinstall the ICI to prevent */ /* it from being associated with other interrupts scheduled by this process.*/ op_ici_install (mac_iciptr); op_pk_send (pkptr, MAC_LAYER_OUT_STREAM); op_ici_install (OPC_NIL);

Details

At any time, at most one ICI is installed for a given process. Installed ICIs are maintained separately for each process residing in a queue/processor module. The operation of installation informs the Simulation Kernel that all interrupts scheduled by the invoking process should be tagged with the specified ICI pointer. This permits many scheduled interrupts to automatically have associated ICIs, instead of having to create an ICI and tag for each individual interrupt.

DES-8-30

Modeler/Release 14.0

8Interface Control Information Package

Scheduled interrupts that have an associated ICI will maintain that association regardless of any transformation that an ICI undergoes during the time between interrupt scheduling and interrupt delivery. This includes modifications of the ICI contents or even ICI destruction. In such circumstances, the process that receives the interrupt may receive information other than that which was intended. In order to avoid such situations, it is recommended that interrupt recipients always be responsible for ICI destruction, and that in general a new ICI be created and installed by the originating process for each individual interrupt. Deinstallation is not explicitly provided for because it is not generally harmful to have an ICI associated with an interrupt, if the processing of that interrupt does not make use of associated ICIs. Thus it is a common practice to leave ICIs installed until it is necessary to associate a different ICI with an outgoing interrupt. However, this KP does provide the ability to deinstall an ICI and thus prevent its further association with outgoing interrupts, by passing the constant OPC_NIL for the argument iciptr.
Purpose

Provides a mechanism for associating prepared ICIs and outgoing interrupts. Each process maintains an internal pointer which references the installed ICI. Thus the currently installed ICI is persistent across unforced states and multiple process invocations. Program Abort: Segmentation violation. (due to an invalid ICI pointer or malformed ICI data structure) Program Abort: KP requires process context.

Errors

Reference

Use the KP op_ici_create() to create an ICI Use the KP op_ici_attr_get() to obtain the value of an ICI attribute Use the KP op_ici_attr_set() to assign the value of an ICI attribute

Modeler/Release 14.0

DES-8-31

8Interface Control Information Package

op_ici_print()
Abstract Syntax

Prints the contents of the specified ICI onto the standard output device. op_ici_print (iciptr)
Argument iciptr Type Ici * Description pointer to the ICI-of-interest [A pointer to an ICI can be obtained from two KPs: op_ici_create() returns a pointer to a newly allocated ICI (in an ICI-sending process), and op_intrpt_ici() returns a pointer to an ICI associated with an incoming interrupt (in an ICI-receiving process).]

Return Type Example

void

No return value.

/* obtain incoming ICI */ iciptr = op_intrpt_ici(); /* determine if the ICI is of the appropriate type; */ /* if so, print its contents onto the terminal */ op_ici_format (pkptr, ici_name); if (strcmp (ici_name, "fddi_mac_fr_llc") == 0) op_ici_print (iciptr);

example output as it appears on the standard output device:


------------- ICI (34) ------------format (fddi_mac_fr_llc) svc_class : (2) dst_addr : (13) pri : (1) tk_class : (0) ------------------------------------

Details

By default, the standard output device for a simulation is the command shell that spawned the simulation process. If the simulation process was spun off by the application GUI, the standard output device is the command shell that spawned the application process. If the simulation process was spawned from a window system window, the default standard output device will be associated with that window. The standard output can be redirected to a file, using the > I/O redirection operator on the simulation command line. The format of the ICI information generated by this KP is shown in the Example section. Note that the unique numeric ID of the ICI is printed in the banner. This KP does not affect the contents or installation status of ICIs on which it operates.

DES-8-32

Modeler/Release 14.0

8Interface Control Information Package

For ICI pointers equal to the constant OPC_NIL, this KP simply prints a message to the effect that the ICI has a NIL address, but no errors are generated.
Purpose

Provides a mechanism for a user to monitor the contents of ICIs from a terminal, or to log the ICI contents into a file for later investigation. Printing out ICI contents can be very useful in the simulation debugger, when arriving ICIs contain values that are used in process computations or that influence the flow of process logic. Statements to print out ICIs can be added to state executives (for event-driven printing), or to the diagnostic block (for user-driven printing of packet information whenever the prodiag command is issued from the debugger). (ICIs also can be printed directly from the simulation debugger using the iciprint_ev and iciprint_pk commands.) Program Abort: Segmentation violation. (due to an invalid ICI pointer or malformed ICI data structure) Use the KP op_intrpt_ici() to obtain the pointer to an ICI associated with an incoming interrupt Use the KP op_pk_format() to obtain the format of a packet Use the KP op_ici_format_print_proc_set() to specify a custom print procedure for the named structure fields of ICIs with a given format

Errors

Reference

Modeler/Release 14.0

DES-8-33

8Interface Control Information Package

DES-8-34

Modeler/Release 14.0