VxWorks Reference Manual : Libraries
trgLib - trigger events control library
trgLibInit( ) - initialize the triggering library
trgWorkQReset( ) - Resets the trigger work queue task and queue
trgAdd( ) - add a new trigger to the trigger list
trgDelete( ) - delete a trigger from the trigger list
trgOn( ) - set triggering on
trgOff( ) - set triggering off
trgEnable( ) - enable a trigger
trgDisable( ) - turn a trigger off
trgChainSet( ) - chains two triggers
trgEvent( ) - trigger a user-defined event
This library provides the interface for triggering events. The routines provide tools for creating, deleting, and controlling triggers. However, in most cases it is preferable to use the GUI to create and manage triggers, since all order and dependency factors are automatically accounted for there.
The event types are defined as in WindView. Triggering and WindView share the same instrumentation points. Furthermore, one of the main uses of triggering is to start and stop WindView instrumentation. Triggering is started by the routine trgOn( ), which sets the shared variable evtAction. Once the variable is set, when an instrumented point is hit, trgCheck( ) is called. The routine looks for triggers that apply to this event. The routine trgOff( ) stops triggering. The routine trgEnable( ) enables a specific trigger that was previously disabled with trgDisable( ). (At creation time all triggers are enabled by default.) This routine also checks the number of triggers currently enabled, and when this is zero, it turns triggering off.
It is important to create a trigger before calling trgOn( ). trgOn( ) checks the trigger list to see if there is at least one trigger there, and if not, it exits without setting evtAction.
trgLibP.h
trgLib, WindView User's Guide
trgLibInit( ) - initialize the triggering library
STATUS trgLibInit (void)
This routine initializes the trigger class. Triggers are VxWorks objects and therefore require a class to be initialized.
OK or ERROR.
trgWorkQReset( ) - Resets the trigger work queue task and queue
STATUS trgWorkQReset (void)
When a trigger fires, if the assocated action requires a function to be called in "safe" mode, a pointer to the required function will be placed on a queue known as the "triggering work queue". A system task "tActDef" is spawned to action these requests at task level. Should the user have need to reset this work queue (e.g. if a called task causes an exception which causes the trgActDef task to be SUSPENDED, or if the queue gets out of sync and becomes unresponsive), trgWorkQReset( ) may be called.
Its effect is to delete the trigger work queue task and its associated resources and then recreate them. Any entries pending on the triggering work queue will be lost. Calling this function with triggering on will result in triggering being turned off before the queue reset takes place. It is the responsibility of the user to turn triggering back on.
OK, or ERROR if the triggering task and its associated resources cannot be deleted and recreated.
trgAdd( ) - add a new trigger to the trigger list
TRIGGER_ID trgAdd ( event_t event, int status, int contextType, UINT32 contextId, OBJ_ID objId, int conditional, int condType, int * condEx1, int condOp, int condEx2, BOOL disable, TRIGGER * chain, int actionType, FUNCPTR actionFunc, BOOL actionDef, int actionArg )
This routine creates a new trigger and adds it to the proper trigger list. It takes the following parameters:
- event
- as defined in eventP.h for WindView, if given.
- status
- the initial status of the trigger (enabled or disabled).
- contextType
- the type of context where the event occurs.
- contextId
- the ID (if any) of the context where the event occurs.
- objectId
- if given and applicable.
- conditional
- the indicator that there is a condition on the trigger.
- condType
- the indicator that the condition is either a variable or a function.
- condEx1
- the first element in the comparison.
- condOp
- the type of operator (==, !=, <, <=, >, >=, |, &).
- condEx2
- the second element in the comparison (a constant).
- disable
- the indicator of whether the trigger must be disabled once it is hit.
- chain
- a pointer to another trigger associated to this one (if any).
- actionType
- the type of action associated with the trigger (none, func, lib).
- actionFunc
- the action associated with the trigger (the function).
- actionDef
- the indicator of whether the action can be deferred (deferred is the default).
- actionArg
- the argument passed to the function, if any.
Attempting to call trgAdd whilst triggering is enabled is not allowed and will return NULL.
TRIGGER_ID, or NULL if either the trigger ID can not be allocated, or if called whilst triggering is enabled.
trgDelete( ) - delete a trigger from the trigger list
STATUS trgDelete ( TRIGGER_ID trgId )
This routine deletes a trigger by removing it from the trigger list. It also checks that no other triggers are still active. If there are no active triggers and triggering is still on, it turns triggering off.
OK, or ERROR if the trigger is not found.
trgOn( ) - set triggering on
STATUS trgOn (void)
This routine activates triggering. From this time on, any time an event point is hit, a check for the presence of possible triggers is performed. Start triggering only when needed since some overhead is introduced.
If trgOn( ) is called when there are no triggers in the trigger list, it immediately sets triggering off again. If trgOn( ) is called with at least one trigger in the list, triggering begins. Triggers should not be added to the list while triggering is on since this can create instability.
OK or ERROR.
trgOff( ) - set triggering off
void trgOff (void)
This routine turns triggering off. From this time on, when an event point is hit, no search on triggers is performed.
N/A
trgEnable( ) - enable a trigger
STATUS trgEnable ( TRIGGER_ID trgId )
This routine enables a trigger that has been created with trgAdd( ). A counter is incremented to keep track of the total number of enabled triggers so that trgDisable( ) knows when to set triggering off. If the maximum number of enabled triggers is reached, an error is returned.
OK, or ERROR if the trigger ID is not found or if the maximum number of triggers has already been enabled.
trgLib, trgDisable( )
trgDisable( ) - turn a trigger off
STATUS trgDisable ( TRIGGER_ID trgId )
This routine disables a trigger. It also checks to see if there are triggers still active. If this is the last active trigger it sets triggering off.
OK, or ERROR if the trigger ID is not found.
trgChainSet( ) - chains two triggers
STATUS trgChainSet ( TRIGGER_ID fromId, TRIGGER_ID toId )
This routine chains two triggers together. When the first trigger fires, it calls trgEnable( ) for the second trigger. The second trigger must be created disabled in order to maintain the correct sequence.
OK or ERROR.
trgEvent( ) - trigger a user-defined event
void trgEvent ( event_t evtId /* event */ )
This routine triggers a user event. A trigger must exist and triggering must have been started with trgOn( ) or from the triggering GUI to use this routine. The evtId should be in the range 40000-65535.
N/A
INTERNAL