| 199 | |
| 200 | |
| 201 | There 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 | |
| 203 | Note: 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 | |
| 207 | The 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 | {{{ |
| 210 | monitor task |
| 211 | |
| 212 | The monitor task is an optional task that knows about RTEMS |
| 213 | data structures and can print out information about them. |
| 214 | It is a work-in-progress and needs many more commands, but |
| 215 | is useful now. |
| 216 | |
| 217 | The monitor works best when it is the highest priority task, |
| 218 | so all your other tasks should ideally be at some priority |
| 219 | greater than 1. |
| 220 | |
| 221 | To 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 | |
| 241 | Monitor 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 | |
| 283 | Sample 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 | |
| 304 | Note 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 | {{{ |
| 307 | rtems $ help |
| 308 | config - Show the system configuration. |
| 309 | itask - List init tasks for the system |
| 310 | mpci - Show the MPCI system configuration, if configured. |
| 311 | pause - 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] |
| 315 | continue - Put the monitor to sleep waiting for an explicit wakeup from |
| 316 | the program running. |
| 317 | go - Alias for 'continue' |
| 318 | node - Specify default node number for commands that take id's. |
| 319 | node [ node number ] |
| 320 | symbol - Display value associated with specified symbol. Defaults to |
| 321 | displaying all known symbols. |
| 322 | symbol [ symbolname [symbolname ... ] ] |
| 323 | extension - Display information about specified extensions. Default is to |
| 324 | display information about all extensions on this node. |
| 325 | extension [id [id ...] ] |
| 326 | task - Display information about the specified tasks. Default is to |
| 327 | display information about all tasks on this node. |
| 328 | task [id [id ...] ] |
| 329 | queue - Display information about the specified message queues. |
| 330 | Default is to display information about all queues on this |
| 331 | node. |
| 332 | queue [id [id ... ] ] |
| 333 | object - Display information about specified RTEMS objects. Object id's |
| 334 | must include 'type' information. (which may normally be |
| 335 | defaulted) |
| 336 | object [id [id ...] ] |
| 337 | driver - Display the RTEMS device driver table. |
| 338 | driver [ major [ major ... ] ] |
| 339 | dname - Displays information about named drivers. |
| 340 | exit - Invoke 'rtems_fatal_error_occurred' with 'status' (default is |
| 341 | RTEMS_SUCCESSFUL) |
| 342 | exit [status] |
| 343 | fatal - 'exit' with fatal error; default error is RTEMS_TASK_EXITTED |
| 344 | fatal [status] |
| 345 | quit - Alias for 'exit' |
| 346 | help - Provide information about commands. Default is show basic |
| 347 | command summary. |
| 348 | help [ command [ command ] ] |
| 349 | - 'i"a |
| 350 | rtems $ |
| 351 | }}} |
| 352 | = Capture Engine = |
| 353 | |
| 354 | |
| 355 | The [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 | |
| 359 | There is a CPU usage monitoring facility available in cpukit/libmisc/cpuuse. Again, from the README: |
| 360 | |
| 361 | This directory contains code to report and reset per-task CPU usage. |
| 362 | If the BSP supports nanosecond timestamp granularity, this this information |
| 363 | is very accurate. Otherwise, it is dependendent on the tick granularity. |
| 364 | |
| 365 | It 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 | |
| 379 | This directory contains a stack bounds checker. It provides two |
| 380 | primary 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 | |
| 387 | Add the stack checker extension to the initial user extension set. |
| 388 | If using confdefs.h to build your configuration table, this is |
| 389 | as simple as adding -DSTACK_CHECK_ON to the gcc command line which |
| 390 | compiles the file defining the configuration table. In the RTEMS |
| 391 | test 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 | |
| 398 | The stack overflow check at context switch works by looking for |
| 399 | a 16 byte pattern at the logical end of the stack to be corrupted. |
| 400 | The "guesser" assumes that the entire stack was prefilled with a known |
| 401 | pattern and assumes that the pattern is still in place if the memory |
| 402 | has not been used as a stack. |
| 403 | |
| 404 | Both of these can be fooled by pushing large holes onto the stack |
| 405 | and not writing to them... or (much more unlikely) writing the |
| 406 | magic patterns into memory. |
| 407 | |
| 408 | This code has not been extensively tested. It is provided as a tool |
| 409 | for RTEMS users to catch the most common mistake in multitasking |
| 410 | systems ... 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. |