libmisc/monitor/README.md

0001 Monitor task
0002 ============
0003
0004 The monitor task is an optional task that knows about RTEMS
0005 data structures and can print out information about them.
0006 It is a work-in-progress and needs many more commands, but
0007 is useful now.
0008
0009 The monitor works best when it is the highest priority task,
0010 so all your other tasks should ideally be at some priority
0011 greater than 1.
0012
0013 To use the monitor:
0014 -------------------
0015
0016     ```c
0017     #include <rtems/monitor.h>
0018
0019         ...
0020
0021     rtems_monitor_init(0);
0022     ```
0023
0024     The parameter to rtems_monitor_init() tells the monitor whether
0025     to suspend itself on startup.  A value of 0 causes the monitor
0026     to immediately enter command mode; a non-zero value causes the
0027     monitor to suspend itself after creation and wait for explicit
0028     wakeup.
0029
0030
0031     rtems_monitor_wakeup();
0032
0033     wakes up a suspended monitor and causes it to reenter command mode.
0034
0035 Monitor commands
0036 ----------------
0037
0038     The monitor prompt is 'rtems> '.
0039     Can abbreviate commands to "uniquity"
0040     There is a 'help' command.  Here is the output from various
0041     help commands:
0042
0043         Commands (may be abbreviated)
0044
0045 ```
0046           help      -- get this message or command specific help
0047           task      -- show task information
0048           queue     -- show message queue information
0049           symbol    -- show entries from symbol table
0050           pause     -- pause monitor for a specified number of ticks
0051           fatal     -- invoke a fatal RTEMS error
0052
0053         task [id [id ...] ]
0054           display information about the specified tasks.
0055           Default is to display information about all tasks on this node
0056
0057         queue [id [id ... ] ]
0058           display information about the specified message queues
0059           Default is to display information about all queues on this node
0060
0061         symbol [ symbolname [symbolname ... ] ]
0062           display value associated with specified symbol.
0063           Defaults to displaying all known symbols.
0064
0065         pause [ticks]
0066           monitor goes to "sleep" for specified ticks (default is 1)
0067           monitor will resume at end of period or if explicitly awakened
0068
0069         fatal [status]
0070           Invoke 'rtems_fatal_error_occurred' with 'status'
0071           (default is RTEMS_INTERNAL_ERROR)
0072
0073         continue
0074           put the monitor to sleep waiting for an explicit wakeup from the
0075           program running.
0076 ```
0077
0078
0079 Sample output from 'task' command
0080 ---------------------------------
0081
0082 ```
0083     rtems> task
0084       ID       NAME   PRIO   STAT   MODES  EVENTS   WAITID  WAITARG  NOTES
0085     ------------------------------------------------------------------------
0086     00010001   UI1     2    READY    P:T:nA    NONE15: 0x40606348
0087     00010002   RMON    1    READY    nP    NONE15: 0x40604110
0088
0089     'RMON' is the monitor itself, so we have 1 "user" task.
0090     Its modes are P:T:nA which translate to:
0091
0092         preemptable
0093         timesliced
0094         no ASRS
0095
0096     It has no events.
0097     (this is the libc thread state)
0098 ```