Prosody installation guide: diagnostic programs: tmwatch

One of the most basic requirements of debugging is the requirement to display the contents of memory. This program allows any memory area in a Prosody processor to be examined. It can read memory once or keep reading it at fixed intervals.

Go to directory $(TiNG)/diag/tmwatch.

There is no need to have downloaded any firmware - not even the kernel. The only requirement is that the driver be loaded.

Run tmwatch with the appropriate options (the program is gen-LINUX/tmwatch, gen-SOL_32/tmwatch, or gen-WINNT/tmwatch depending on which operating system you are using).

Command line options are:

`-v`	Show the version code of tmwatch
`-c` card	Specifies the card on which is the module whose memory is to be examined
`-i` interval	the period (in mS) with which the memory is to be re-read (default is to read only once). This is a global flag, applying to all memory areas.
`-m` module	Specifies the module whose memory is to be examined (default 0).
`-z`	Display unchanged values (default is to display only values which have changed). This is a global flag, applying to all memory areas.
memory-area	memory area to examine

Numbers can be specified in three ways:

in hex, represented by 0x followed by hexadecimal digits
in octal, represented by 0 followed by octal digits
in decimal, represented by decimal digits

For example,

	gen-WINNT/tmwatch -c Prosody_123456 -i 1000 8+8 f0x30000:0x300006+2

would examine the eight locations in the range 8..15 and the three locations 0x30000, 0x30002, and 0x30004, once every 1000 mS and print any changed values, with the first eight being printed in hex and decimal and the last three also being printed as floating-point.

Each area on the list of memeory areas to examine is specified by these parts:

optional letter 'f' to produce floating point values.
the address of the first location in the memory area
optionally, the size of the memory area. The default size is one location, but it can be specified in two ways:
- a colon (:) and the address of the first location after the memory area
- a plus (+) and the length of the memory area
For example, the location at address 8 can be specified in these three ways:
- 8
- 8:9
- 8+1
if the size of the memory area has been specified, optionally, a plus (+) and the step size to use. For example, the locations 8, 10, and 12 can be specified in any of these ways:
- 8:13+2
- 8:14+2
- 8+5+2
- 8+6+2

The last -c and -m options before the specification of a memory area determine on which module and card the memory is.

By default, the contents of memory are displayed in two columns. The first shows the unsigned 32-bit integer (in hex) which the contents of the memory location might represent, and the second, shows the signed 32-bit integer (in decimal) which the contents of the memory location might represent. The 'f' causes a third column to be displayed, which shows the 32-bit floating point value which the contents of the memory location might represent.

In the absence of the -z option, when memory is read each time (at the intervals specified by the -i option) only values which have changed will be displayed. Values are assumed to start at zero (locations which are zero will not be displayed until they change to non-zero values). For the purposes of deciding whether a location has changed or not, the location is assumed to contain an integer (so different representations of the same floating point value are considered to be different).

Here is some typical output:

$ tmwatch -i 1000 -c Prosody_123456 0x30010 -m1 8 0x30000
  0.000: 0:[00030010] = 0010816c (1081708) 
         1:[00000008] = 00032747 (206663) 
         1:[00030000] = ffffffff (-1) 
  1.008: 0:[00030010] = 001081ea (1081834) 
  2.018: 0:[00030010] = 00108268 (1081960) 
User abort...

The first column is the time in seconds. As you can see, the nominal interval of 1000mS is not guaranteed to be exactly followed. The next column specifies which location is being displayed, given as a module number, a colon, and the address on that module in square brackets. The signed decimal interpretation appears in round brackets. Of course values in the range 0..2147483647 are common to both signed and unsigned representations, so the values in hex and decimal are the same except for the third line of output.

When the -i option is used, you make the program exit by sending it an input line (or EOF).

The source code for this program is provided (tmwatch.c), however it uses API facilities which not part of the published API specification and which can therefore change without notice. If you want to read memory locations in a program of your own, you should do so by running the tmwatch program, rather than by copying the technique it uses.

This is one of the Prosody diagnostic programs .