You can specify which level of logging to implement, but data is collected only when events are generated by the instrumented VxWorks kernel and libraries. Your application will make many calls to VxWorks routines, but sometimes you will want information on some of your application routines as well. There are two ways to do this: by setting eventpoints dynamically from the Tornado shell with the e( )routine, or by inserting event-generating function calls into application source code.

The simplest type of user-generated event is the eventpoint, which can be set from the shell with the e( ) routine. Eventpoints are analogous to breakpoints; they are program locations that display the defaultUser event icon ( ) when the instruction at that location executes. (To design your own event icons, see F.4 Creating Icons for User-Defined Events.)

The e( ) routine has the following syntax:

STATUS e 
    ( 
    INSTR *  addr,         /* address to set eventpoint; */ 
                           /* NULL = all eventpoints and */ 
                           /* breakpoints are raised */ 
    event_t  eventNo,      /* event number */ 
    int      taskNameOrId, /* task in which to raise event- */ 
                           /* point; 0 = all tasks */ 
    FUNCPTR  evtRtn,       /* function to be called when */ 
                           /* eventpoint encountered; NULL */ 
                           /* = no function, so eventpoint */ 
                           /* always raised */ 
    int      arg           /* argument to evtRtn function */ 
    )

	NOTE: Eventpoints follow the same rules as breakpoints, including the following: (1) Eventpoints in unbreakable tasks are not executed and thus do not appear in the view graph. (2) Eventpoints cannot be set at interrupt level.

To see how a log looks when you set an eventpoint with e( ), follow these steps:

1. To set an eventpoint with an ID of 10 at the address of the sin( ) routine, click the Launch Shell button ( ) and type:

-> e sin, 10, 0, 0, 0 
value - 1 = 0x1

1. Click to start logging. (You can use any logging level.)

1. In the shell window type:

-> sin 1 
value = 1 = 0x1

1. Click to stop logging and to upload data.

1. Click , locate the numeral 10, and click, drag, and zoom in over this area of the graph repeatedly until you can see your user event icon with the numeral 10 beside it. Your graph will look something like Figure 7-2.    

   Figure 7-2:  View Graph with User Event

   

The wvEvent( ) routine provides a generic event function which is always available and which has more flexibility than e( ).

The wvEvent( ) routine is declared as follows:

STATUS wvEvent 
    ( 
    event_t   eventNo,       /* event ID */ 
    char *    buffer,        /* user-supplied buffer */ 
    size_t    bufSize        /* buffer size */ 
    )

The wvEvent( ) routine can be called from unbreakable tasks or from interrupt level.¹ Thus it is more flexible than the e( ) routine. For example, you can use user-generated events for error checking, as shown in the following example:

if (something) 
    { 
    ...    /* run this code */ 
    }

 
else 
    { 
    ... /* we should never get here, but if we do, load any values */ 
        /* of interest into event1Buff, then log using wvEvent     */ 
 
        return = wvEvent (EVENT_1_ID, &event1Buff, EVENT_1_BUFSIZE); 
    }

If this event is ever encountered, the defaultUser event icon ( ) is displayed in the view graph, with the event number just to the right of the icon. You can double-click on this icon to bring up the Show Event dialog box, which shows the timestamp at which the user event occurred, the context in which it occurred, and the user event number. If you customize the Show Event dialog box, you can also display information held in the user event buffer (buffer argument to wvEvent( )).²

To see how a log looks when an eventpoint is raised by wvEvent( ), do the following:

1. Click to start logging. (You can use any logging level.)

1. In the shell window type:

-> wvEvent (99, 0, 0) 
value = 0= 0x0

1. Click to stop logging and to upload data.

Figure 7-3 shows an example of what this might look like in the view graph. The target-agent task, tWdbTask, spawns ( ) and then resumes ( ) task t44. Task t44 makes a transition from the suspended state ( ) to the ready state ( ). Near time 1.66664, t44 makes a transition to the executing state ( ) and user event 99 is encountered ( ).

Figure 7-3:  User-Generated Event

  

1:  Unbreakable tasks are those that are created with the VX_UNBREAKABLE bit set in the options argument of the taskInit( ) or taskSpawn( ) routine.

2:  For information on using Show Event, see The Show Event Dialog Box. For information on customizing the Show Event dialog box, see F.3 Customizing the Show Event Dialog Box for User Events. For information on designing your own user event icons, see F.4 Creating Icons for User-Defined Events.