Changes between Version 11 and Version 12 of TBR/Review/Debugging/Start


Ignore:
Timestamp:
08/07/07 18:10:08 (17 years ago)
Author:
Rsg
Comment:

Brief introduction to optional (yet highly useful) RTEMS debugging and monitoring tools

Legend:

Unmodified
Added
Removed
Modified
  • TBR/Review/Debugging/Start

    v11 v12  
    197197RTEMS has very tight default configuration limits.  Not being able to open a file or create a socket is a common error which indicates that you need to configure enough open file descriptors.  By default, the constant CONFIGURE_LIBIO_MAXIMUM_DESCRIPTORS is set to 3 for stdin, stdout, and stderr.  You will need to set it to the appropriate value for your application.
    198198=  Optional Debugging Tools Provided by RTEMS  =
     199
     200
     201There are a number of optional debugging tools available with RTEMS that are not too well documented (yet!).  These tools (and other goodies) can be found under cpukit/libmisc, and are well worth investigating.
     202
     203Note: Most of what follows has been gleaned from the associated README files; I haven't added much original content, partly due to sloth, but more justifiably because I haven't yet used these tools extensively enough to be able to do any better!  My primary purpose, at this point, in including these is so others, especially "nuBees" are aware of them.
     204=  RTEMS Monitor  =
     205
     206
     207The RTEMS Monitor is run as a high-priority task, and provides a useful window into the operation of your system.  From the README:
     208
     209{{{
     210monitor task
     211
     212The monitor task is an optional task that knows about RTEMS
     213data structures and can print out information about them.
     214It is a work-in-progress and needs many more commands, but
     215is useful now.
     216
     217The monitor works best when it is the highest priority task,
     218so all your other tasks should ideally be at some priority
     219greater than 1.
     220
     221To use the monitor:
     222-------------------
     223
     224    #include <rtems/monitor.h>
     225
     226    ...
     227
     228    rtems_monitor_init(0);
     229
     230    The parameter to rtems_monitor_init() tells the monitor whether
     231    to suspend itself on startup.  A value of 0 causes the monitor
     232    to immediately enter command mode; a non-zero value causes the
     233    monitor to suspend itself after creation and wait for explicit
     234    wakeup.
     235
     236
     237    rtems_monitor_wakeup();
     238   
     239    wakes up a suspended monitor and causes it to reenter command mode.
     240
     241Monitor commands
     242----------------
     243
     244    The monitor prompt is 'rtems> '.
     245    Can abbreviate commands to "uniquity"
     246    There is a 'help' command.  Here is the output from various
     247    help commands:
     248
     249        Commands (may be abbreviated)
     250
     251          help      -- get this message or command specific help
     252          task      -- show task information
     253          queue     -- show message queue information
     254          symbol    -- show entries from symbol table
     255          pause     -- pause monitor for a specified number of ticks
     256          fatal     -- invoke a fatal RTEMS error
     257
     258        task [id [id ...] ]
     259          display information about the specified tasks.
     260          Default is to display information about all tasks on this node
     261
     262        queue [id [id ... ] ]
     263          display information about the specified message queues
     264          Default is to display information about all queues on this node
     265
     266        symbol [ symbolname [symbolname ... ] ]
     267          display value associated with specified symbol.
     268          Defaults to displaying all known symbols.
     269
     270        pause [ticks]
     271          monitor goes to "sleep" for specified ticks (default is 1)
     272          monitor will resume at end of period or if explicitly awakened
     273
     274        fatal [status]
     275          Invoke 'rtems_fatal_error_occurred' with 'status'
     276          (default is RTEMS_INTERNAL_ERROR)
     277
     278        continue
     279          put the monitor to sleep waiting for an explicit wakeup from the
     280          program running.
     281
     282
     283Sample output from 'task' command
     284---------------------------------
     285
     286    rtems> task
     287      ID       NAME   PRIO   STAT   MODES  EVENTS   WAITID  WAITARG  NOTES
     288    ------------------------------------------------------------------------
     289    00010001   UI1     2    READY    P:T:nA    NONE15: 0x40606348
     290    00010002   RMON    1    READY    nP    NONE15: 0x40604110
     291
     292    'RMON' is the monitor itself, so we have 1 "user" task.
     293    Its modes are P:T:nA which translate to:
     294
     295        preemptable
     296        timesliced
     297        no ASRS
     298
     299    It has no events.
     300    It has a notepad value for notepad 15 which is 0x40606348
     301    (this is the libc thread state)
     302}}}
     303
     304Note that this README is quite dated - it hasn't been changed in 11 '''years'''!  In fact, it provides much more information; here is the output from the help command on a recent (July 2007 HEAD) session:
     305
     306{{{
     307rtems $ help
     308config     - Show the system configuration.
     309itask      - List init tasks for the system
     310mpci       - Show the MPCI system configuration, if configured.
     311pause      - Monitor goes to "sleep" for specified ticks (default is 1).
     312             Monitor will resume at end of period or if explicitly
     313             awakened
     314              pause [ticks]
     315continue   - Put the monitor to sleep waiting for an explicit wakeup from
     316             the program running.
     317go         - Alias for 'continue'
     318node       - Specify default node number for commands that take id's.
     319              node [ node number ]
     320symbol     - Display value associated with specified symbol. Defaults to
     321             displaying all known symbols.
     322              symbol [ symbolname [symbolname ... ] ]
     323extension  - Display information about specified extensions. Default is to
     324             display information about all extensions on this node.
     325              extension [id [id ...] ]
     326task       - Display information about the specified tasks. Default is to
     327             display information about all tasks on this node.
     328              task [id [id ...] ]
     329queue      - Display information about the specified message queues.
     330             Default is to display information about all queues on this
     331             node.
     332              queue [id [id ... ] ]
     333object     - Display information about specified RTEMS objects. Object id's
     334             must include 'type' information. (which may normally be
     335             defaulted)
     336              object [id [id ...] ]
     337driver     - Display the RTEMS device driver table.
     338              driver [ major [ major ... ] ]
     339dname      - Displays information about named drivers.
     340exit       - Invoke 'rtems_fatal_error_occurred' with 'status' (default is
     341             RTEMS_SUCCESSFUL)
     342              exit [status]
     343fatal      - 'exit' with fatal error; default error is RTEMS_TASK_EXITTED
     344              fatal [status]
     345quit       - Alias for 'exit'
     346help       - Provide information about commands. Default is show basic
     347             command summary.
     348            help [ command [ command ] ]
     349           - 'i"a
     350rtems $
     351}}}
     352=  Capture Engine  =
     353
     354
     355The [wiki:TBR/UserManual/Capture_Engine Capture Engine] is another neat tool.  Unlike the RTEMS Monitor, this one is already documented on the Wiki, though you have to know to search for it.  Check it out!
     356=  CPU Usage Monitoring  =
     357
     358
     359There is a CPU usage monitoring facility available in cpukit/libmisc/cpuuse.  Again, from the README:
     360
     361This directory contains code to report and reset per-task CPU usage.
     362If the BSP supports nanosecond timestamp granularity, this this information
     363is very accurate.  Otherwise, it is dependendent on the tick granularity.
     364
     365It provides two primary features:
     366
     367 * Generate a CPU Usage Report
     368 * Reset CPU Usage Information
     369==  NOTES  ==
     370
     371
     372#If configured for tick granularity, CPU usage is "docked" by a clock tick at each context switch.
     373#If configured for nanosecond granularity, no work is done at each clock tick.  All bookkeeping is done as part of a context switch.
     374=  Stack Checker  =
     375
     376==  Introduction  ==
     377
     378
     379This directory contains a stack bounds checker.  It provides two
     380primary features:
     381
     382#check for stack overflow at each context switch
     383#provides an educated guess at each task's stack usage
     384==  Enabling  ==
     385
     386
     387Add the stack checker extension to the initial user extension set.
     388If using confdefs.h to build your configuration table, this is
     389as simple as adding -DSTACK_CHECK_ON to the gcc command line which
     390compiles the file defining the configuration table.  In the RTEMS
     391test suites and samples, this is always init.c.  Another way to enable it is to include the following prior to including confdefs.h:
     392{{{
     393#define STACK_CHECKER_ON
     394}}}
     395==  Background  ==
     396
     397
     398The stack overflow check at context switch works by looking for
     399a 16 byte pattern at the logical end of the stack to be corrupted.
     400The "guesser" assumes that the entire stack was prefilled with a known
     401pattern and assumes that the pattern is still in place if the memory
     402has not been used as a stack.
     403
     404Both of these can be fooled by pushing large holes onto the stack
     405and not writing to them... or (much more unlikely) writing the
     406magic patterns into memory.
     407
     408This code has not been extensively tested.  It is provided as a tool
     409for RTEMS users to catch the most common mistake in multitasking
     410systems ... too little stack space.  Suggestions and comments are appreciated.
     411==  NOTES  ==
     412
     413#Stack usage information is questionable on CPUs which push large holes on stack.
     414#The stack checker has a tendency to generate a fault when trying to print the helpful diagnostic message.  If it comes out, congratulations. If not, then the variable Stack_check_Blown_task contains a pointer to the TCB of the offending task.  This is usually enough to go on.
     415=  = FUTURE ====
     416
     417#Determine how/if gcc will generate stack probe calls and support that.