op_radio_txch_rxgroup_compute()
Note: Requires Wireless functionality
Abstract
Computes the receiver group of a transmitter channel by filtering the set of possible receiver channels.
Syntax
op_radio_txch_rxgroup_compute (txch_objid, rxgroup_proc)
| Argument | Type | Description |
|---|---|---|
txch_objid |
Objid |
the object ID of the transmitter channel whose receiver group is being computed (or recomputed). If the object ID is OPC_OBJID_UNIVERSAL, all the transmitter channels in the simulation have their receiver groups recomputed. |
rxgroup_proc |
Txch_Rxgroup_Proc |
function invoked for a transmitter/receiver channel object ID pair to decide if the receiver should be part of the transmitter channel’s receiver group. If the function is OPC_TXCH_RXGROUP_PS, the receiver group pipeline stage for the transmitter is used. |
Return Type
Compcode
Completion code indicating success or failure in recomputing receiver groups. The procedure returns OPC_COMPCODE_SUCCESS if the receiver groups were successfully recomputed; otherwise it returns OPC_COMPCODE_FAILURE.
Example
static int
check_rxch (Objid txch, Objid rxch)
{
/* Okay if not part of the same node */
return (op_topo_parent (op_topo_parent (txch))!=
op_topo_parent (op_topo_parent (rxch)))
}
static void
reset_txch_rxgroup (Objid txch)
{
op_radio_txch_rxgroup_compute (txch, check_rxch);
}
Details
If not set to OPC_TXCH_RXGROUP_PS, rxgroup_proc should be a function that takes two arguments (the object IDs of a transmitter and a receiver channel for the first and second arguments, respectively) and returns OPC_TRUE or OPC_FALSE.
To compute the receiver group of a transmitter, this kernel procedure iterates through the set of receiver channels in the simulation. For each receiver channel, the application calls the filter procedure (or the rxgroup pipeline stage for the transmitter if rxgroup_proc is OPC_TXCH_RXGROUP_PS) with the object IDs of the transmitter and the receiver. If the filter returns OPC_TRUE, then the receiver will be included in the receiver group.
If the transmitter channel ID is OPC_OBJID_UNIVERSAL, then all transmitter channels in the simulation have their receiver groups recomputed using either the specified procedure or the appropriate rxgroup pipeline stage for each transmitter.
An rxgroup pipeline stage can detect if it is being called by this KP (rather than at the start of a simulation) by calling op_sim_time(). The KP op_sim_time() returns -1 during the initial invocation of the rxgroup pipeline stage, which occurs before the begin sim interrupt. Subsequent calls to the rxgroup pipeline stage by op_radio_txch_rxgroup_compute() will have a simulation time greater than or equal to 0.
Purpose
Provides a mechanism to compute the receiver group of a transmitter by testing all possible receivers using a filter procedure.
Errors
- Recoverable Error: Object ID (
<objid>) does not correspond to a transmitter channel. - Recoverable Error: Transmitter object ID (
<objid>) refers to a restricted object. - Recoverable Error: Internal memory allocation error, receiver group unchanged.
- Program Abort: Segmentation violation. (due to an invalid function pointer)
Reference
- Use the KP op_radio_txch_rxgroup_get() to obtain the current receiver group
- Use the KP op_radio_txch_rxgroup_set() to set the receiver group to a provided array of object IDs
- Use the KP op_radio_txch_rxch_add() to add one receiver channel to a transmitter channel’s group
- Use the KP op_radio_txch_rxch_remove() to remove one receiver channel from a transmitter channel’s group