The Cheops Ramlog system allows for debugging information to be obtained in a real time application. The use of printf(), whether to the serial console or SCSI, seriously affects the timing of an application. In Ramlog, debugging events are generated by the operating system, the resource manager (Norman), and the user's application and are stored in a compressed format in a circular queue in memory. The queue overflows gracefully, discarding the oldest events when space is needed.
The logging of events into the queue may be enabled and disabled either directly by an application, or manually by the user. After one or more "runs" have been completed, the ramlog may be printed out for examination. Even if Cheops crashed during execution, the ramlog may usually still be printed out immediately upon reboot (before re-initializing the ramlog.)
There are currently two interfaces for controlling the ramlog :
The ramlog events are grouped into sets, which may be individually included or excluded from a ramlog dump. If sets are specified for inclusion, it is assumed that all sets not mentioned are to be excluded. Similarly, if sets are specified for exclusion, all other sets are included. In addition, events may be "compressed". Compressed events are normally included in the printout, but portions of a dump that consist only of compressed or excluded sets are summarized by a total count of summarized events.
A typical ramlog session begins by initializing the ramlog. This must be done after every reboot of Magic7.
host> chex ramlog init
Let's assume that we are debugging an application that uses the resource manager, and we want to trace it's processing and transfers to the screen. We need to pre-load the resource manager and enable some debugging options (which are ramlogged by default) :
host> chex -ser 0 norman -debug nile general
Now we start ramlogging and the user's application, using one of two methods :
Optionally (and usually much better), the application under test can enable and disable the ramlog. There are two ways to manually stop the ramlogging :
Once stopped, you need to dump the ramlog to view it. The dump routine may optionally filter the data before printing it out (the options shown will exclude SCSI events, and summarize Norman interrupt events) :
host> chex ramlog dump -e scsi -c n_ints > dump
An unfiltered printout of a ramlog can be quite large -- a typical ramlog uses a circular queue of 64K tokens. The average event requires three token, and generates one line of printout, giving dump sizes up to 20K lines long.
To use ramlog from within your application, first make sure you are linking with the -lcheops_ramlog library
Include cheops_ramlog.h into your source file.
To start the log, use: start_log();
To stop the log, use: stop_log();
There are several events defined for general debugging:
To log an event, insert lines like the following :
log_event( RL_TEXT, "I'm here" ); /* and/or */ log_event( RL_DEC(2), x, y );
You can also log new, user specific events. The first argument to log_event() is a token identifying the message, and the number of optional arguments. For example, a first argument of 0x1000 0002 would be printed as an unknown event, with two arguments.
It isn't hard to extend the ramlog system with new event tokens for application specific events. Just follow these steps :