VxWorks / Tornado II FAQ

SPR# 22563

DATE: Oct 01 1998
TITLE: WindView 2.0: display user event data example in F.3 of User's Guide does not correctly display "Formatted Display"

Problem_Description

User EventBase display doesnt properly format for WindView 2.0, as shown in the User's Guide, section F.3:
An FAE referred me to TSR# 142050. The method described in there is fairly good (i.e., the routine userFormatNNNNN actually gets called where the variable wvUsrEventFormat in eventbase.tcl never gets used) except there is still no instructions on how to take 'event' and format it into anything useful.

HERE IS THE TEXT PROVIDED BY TSR 142050

It seems that, at the VERY last moment someone stuck in a way of formatting user event data for display in the Show Event dialog box. It's a tad different from the way it was done before. I haven't tried it myself, but the theory goes as follows:
it is assumed either/or that

you have a HOMEDRIVE and a HOMEPATH environment variable set up, and/or

you have a HOME environment variable set up

From these is constructed a search path...

in the above search path, there should be a .wind subdirectory.

in the .wind subdirectory, create a "WindView" subdirectory and a file in that directory called "userEvents.tcl" (if they don't already exist, which they should under Unix). e.g.
if HOME=c:\cjtc the file creates should be c:\cjtc\.wind\WindView\userEvents.tcl
this file needs to be edited to contain tcl code required to format the way in which user events are displayed.
e.g. for each user event that requires data formatting, insert something like
    proc userFormat00200 {arg} {
    return "result is $arg" }
          
NB. For each user event which need custom formatting, the name of the proc which should be created is
userFormatNNNNN
          
where NNNNN is the decimal number of the user event to be formatted. e.g. for user event 200 (decimal), the name of the proc to be inserted should be
userFormat00200
          
The tcl proc should format the arg string parameter and return a string formatted as required.
The end result of all of this should be that the formatted string is shown as required in the Show Events dialog box. Note that the user data shown in the status line (when the cursor just hovers over an event icon) is still in straight hex.

After staring at the WindView tcl scripts for many hours, we finally wrote the following which works:

   proc userFormat00014 {event} {
   set data [userEventFormat $event {n1 n1 n2 n4}]
   scan [lindex $data 0] "%2x" cpuid
   #messageBox "cpuid = $cpuid, data1 = [lindex $data 3]"
   if [cpuLittleEndian $cpuid] {
   set data2 [swapTargetInt [lindex $data 3]]
   } else {
   set data2 [lindex $data 3]
   }
   scan $data2 "%8x" data3
   #messageBox "data2 = $data2, data3 = $data3"
   return "sequence number = $data3"
   }

Please file an SPR(s) for the following:

The documentation on pages 246-249 (section F.3) is completely wrong. A FAQ or app note should be written with the correct information (most of it detailed in the aforementioned TSR or below).
The tcl procedure eventFormat in WindView.win32.tcl never gets called. It's the routine that actually pays attention to wvUsrEventFormat (the data structure the manual tells you to use). This routine expects the data in one <format> (one that you can use with usrUnpack, ie, the one described in the manual). The actual <format> used is incompatible with usrUnpack - you must call userEventFormat instead. This needs documented as well.
FYI, the usr routines are mostly in %WIND_BASE%/host/resource/tcl/WindView.win32.tcl. The user routines are mostly in %WIND_BASE%/host/resource/tcl/app-config/WindView/database.tcl.
We can't use functions such as unpackint and unpackstring as the upvar causes a tcl error. We need to do the scan and swapTargetInt calls ourselves.The available calls need to be documented so we don't have to read the tcl source to find them. We also don't have the cpuId (since our events aren't in the format expected by usrUnpack).
FYI, there is a bug in unpackint (and possibly some other functions). It's goal is to format the int as a decimal representation and byte swap if necessary. However, the byte swap routine, swapTargetInt, always formats the data in hex. The scan should not be performed until after the swapTargetInt. Big endian targets will return the result as a %d, little endian targets as a %x.
In database.tcl, the routine wvLoadUserEventFormats does not look in WIND_BASE first (as the routine wvFindUserDefinedIcons does). I believe they should both look in WIND_BASE first.
Even if pages 246-249 were right, there are several typos including switching between wvUsrEventFormat and wvUserEventFormat. The routine postEvent is also mentioned but I cannot find it in a header file.

I've found one additional bug.

   proc cpuLittleEndian {cpuId} {
   # return endiannes of target based on cpuId. This doesn't
   # take ambi-endian architectures into account. In this
   # arrangement we have no direct connection to the target
   # server so we can't have authoritative data.
   return [expr $cpuId >= 20 && $cpuId <= 29 || $cpuId >= 80 && $cpuId <= 89]
   }

This does not work for the ARM or SIMNT platforms. ARM cpuid are >=120 and <=125 and are little endian. SIMNT has cpuID 100.