Table of Contents

1. Introduction
2. Syntax
3. Example use of the monitor option
4. On the use of the monitor option

1. Introduction

The --monitor option enables you to monitor the value of a global variable or a memory space when reading or writing it.

You can record the trace of a set of variables separated by commas. The number of variables you can monitor is quite high and you can verify in the WSim log file that your variables are found in wsim by looking at the section Memory.

[Important]
  • You can use any C global variable from your program, but hardware registers cannot be monitored by this way.
  • Compiler optimization can allocate a variable to a register. In case the generated trace does not contain modifications for you monitored variable you have to make sure the the writes to memory are actually done. This can be used by looking at the assembly code. To force a variable to be written in memory you can use the C keyword volatile that will take care of the register allocation optimization by forcing real writes to memory.
  • Local variables cannot be traced using this scheme as their address is not constant accross function calls and more than one instance of a variable can exist at the same time during the application lifetime.

A trace is recorded each time the concerning memory address (variable or hex. address) is read, written, or both. Traces are stored in the *.trc file generated by WSim in a section called monitor.

[Note]The --trace option

To make the monitor option active, you must use at the same time the --trace parameter on the command line. Otherwise the trace file will be empty!

2. Syntax

	       
        --monitor=[symbol1]:[options1],[addr2]:[size2]:[options2], ...,[argN]:[optionsN] 
	

  • symbol is a global variable name.
  • addr is a memory address. In that case you have to specify with its size in byte (for instance 0xabcd:2).
  • options are r for "read" or/and w for "write". options are mandatory.

[Note]Variables names

Case is sensitive for variable names and corresponds to the name used in your program. If the names is misspelled a warning will be issued at run time stated that your variable is reported to have a size 0 and won't be traced.

[Note]Memory space

Adresses are in hexadecimal, so they must be prefixed with 0x. Size may be ommited, in this case, the default size is 1 byte.

3. Example use of the monitor option

The following simple example is a run of the following program:

      
        volatile int my_global_variable;
        
        int main(void)
        {  
          WDTCTL = WDTPW | WDTHOLD;
          int i;
          for(i=0; i<1000; i++)
            {
              my_global_variable = i;
            }
          return 0;
        }
         
    

The simulation is then run using the command

      
	wsim-wsn430 --verbose=6 --mode=time --modearg=1s --logfile=wsim.log --trace=wsim.trc --monitor=my_global_variable:w example.elf
      
    

If the variable name is mistyped (with a capital G in that case), the following warning message is written in WSim output logs

monitor: cannot find symbol "my_Global_variable"

The trace generated by Wsim can be converted using wtracer in a VCD file format or to a raw timeline. The following screenshot show the GtkWave software showing the generated trace along with the timeline.

Trace view of the my_global_variable changes

Figure II.1. Trace view of the my_global_variable changes


4. On the use of the monitor option

The --monitor can be used to trace variables values in a program. This first method allows to easily find errors on complex algorithms ported to micro-controllers withou using a tedious GDB step by step process. The way to use the monitor output is to have reference test vectors from a version that works on a desktop computer such that the iteration that differs on the controller can be easily pinpointed.

Another use of the monitor variable is to track buffer overflows and stack overflow using monitor address set at the end of arrays or on top of the heap.