RTOS Debugger for MQX

Transcription

1 RTOS Debugger for MQX TRACE32 Online Help TRACE32 Directory TRACE32 Index TRACE32 Documents... RTOS Debuggers... RTOS Debugger for MQX... 1 Overview... 3 Brief Overview of Documents for New Users... 4 Supported Versions... 4 Configuration... 5 Manual Configuration 5 Automatic Configuration 5 Quick Configuration Guide 6 Hooks & Internals in MQX 6 Features... 7 Display of Kernel Resources 7 Task Stack Coverage 7 Task Related Breakpoints 8 Task Context Display 9 Dynamic Task Performance Measurement 9 Task Runtime Statistics 10 Task State Analysis 10 Function Runtime Statistics 11 MQX specific Menu 13 MQX Commands TASK.EVent Display events 14 TASK.KLog Display kernel log 14 TASK.LWEvent Display light weight events 15 TASK.LWMEMPool Display light weight memory pools 16 TASK.LWMsgQ Display light weight message queues 16 TASK.LWSem Display light weight semaphores 16 TASK.MEMPool Display memory pools 17 TASK.MeSsaGe.POOL Display message pools 17 TASK.MeSsaGe.QUEUE Display message queues 18 TASK.MuteX Display mutexes 19 TASK.SEMaphore Display semaphores 19 RTOS Debugger for MQX 1

2 TASK.TASK Display tasks 20 TASK.TASKQueue Display task queues 20 TASK.TASKState Mark task state words 21 MQX PRACTICE Functions Frequently-Asked Questions RTOS Debugger for MQX 2

3 RTOS Debugger for MQX Version 06-Nov-2017 Overview The RTOS Debugger for MQX contains special extensions to the TRACE32 Debugger. This manual describes the additional features, such as additional commands and statistic evaluations. RTOS Debugger for MQX 3

4 Brief Overview of Documents for New Users Architecture-independent information: Debugger Basics - Training (training_debugger.pdf): Get familiar with the basic features of a TRACE32 debugger. T32Start (app_t32start.pdf): T32Start assists you in starting TRACE32 PowerView instances for different configurations of the debugger. T32Start is only available for Windows. General Commands (general_ref_<x>.pdf): Alphabetic list of debug commands. Architecture-specific information: Processor Architecture Manuals : These manuals describe commands that are specific for the processor architecture supported by your debug cable. To access the manual for your processor architecture, proceed as follows: - Choose Help menu > Processor Architecture Manual. RTOS Debuggers (rtos_<x>.pdf): TRACE32 PowerView can be extended for operating systemaware debugging. The appropriate RTOS manual informs you how to enable the OS-aware debugging. Supported Versions Currently MQX is supported for the following versions: MQX 2.x on 68k, ColdFire, ARM and PowerPC MQX 3.6 to MQX 4.0 on ARM, ColdFire and PowerPC. RTOS Debugger for MQX 4

5 Configuration The TASK.CONFIG command loads an extension definition file called mqx.t32 (directory ~~/demo/<processor>/kernel/mqx ). It contains all necessary extensions. Automatic configuration tries to locate the MQX internals automatically. For this purpose all symbol tables must be loaded and accessible at any time the RTOS debugger is used. If a system symbol is not available or if another address should be used for a specific system variable then the corresponding argument must be set manually with the appropriate address. In this case, use the manual configuration, which can require some additional arguments. If you want do use the display functions On The Fly, i.e. displaying the OS objects, while the target is running, you need to have access to memory while running. In case of a ICE or FIRE, you have to map emulation or shadow memory to the address space of all used system tables. In case of ICD, you have to enable SYStem.MemAccess or SYStem.CpuAccess (CPU dependent). Manual Configuration Manual configuration is not necessary for the MQX RTOS debugger. Automatic Configuration For system resource display and trace functionality, you can do an automatic configuration of the RTOS debugger. For this purpose it is necessary that all system internal symbols are loaded and accessible at any time, the RTOS debugger is used. Each of the task.config arguments can be substituted by '0', which means, that this argument will be searched and configured automatically. For a full automatic configuration omit all arguments: TASK.CONFIG mqx If a system symbol is not available, or if another address should be used for a specific system variable, then the corresponding argument must be set manually with the appropriate address. RTOS Debugger for MQX 5

6 Quick Configuration Guide To access all features of the RTOS debugger you should follow this roadmap: 1. Read carefully the demo startup script (~~/demo/<processor>/kernel/mqx/mqx.cmm). 2. Make a copy of the PRACTICE script file mqx.cmm. 3. Modify the file according to your application. 4. Run the modified version in your application. This should allow you to display the kernel resources and use the trace functions (if available). Hooks & Internals in MQX No hooks are used in the kernel. To retrieve all information, the pointers in the initialization structure are used. RTOS Debugger for MQX 6

7 Features The RTOS debugger for MQX supports the following features. Display of Kernel Resources The extension defines new PRACTICE commands to display various kernel resources. The following information can be displayed: TASK.TASK TASK.MEMPool TASK.MeSsaGe.QUEUE TASK.MeSsaGe.POOL TASK.SEMaphore TASK.EVent TASK.MuteX TASK.KLog TASK.LWSem TASK.LWEvent TASK.LWMsgQ TASK.LWMEMPool TASK.TASKQueue Tasks Memory pools Message queues Message pools Semaphores Events Mutexes Kernel log Light weight semaphores Light weight events Light weight message queues Light weight memory pools Task queues For a detailed description of each command refer to the chapter MQX Commands. If your hardware allows accessing the memory, while the target is running, these resources can be displayed On The Fly, i.e. while the application is running, without any intrusion to the application. Without this capability, the information will only be displayed, if the target application is stopped. Task Stack Coverage For stack usage coverage of the tasks, you can use the TASK.STacK command. Without any parameter, this command will set up a window with all active tasks. If you specify only a magic number as parameter, the stack area of this task will be automatically calculated. To use the calculation of the maximum stack usage, flag memory must be mapped to the task stack areas, when working with the emulation memory. When working with the target memory, a stack pattern must be defined with the command TASK.STacK.PATtern (default value is zero). RTOS Debugger for MQX 7

8 To add/remove one task to/from the task stack coverage, you can either call the TASK.STacK.ADD rsp. TASK.STacK.ReMove commands with the task magic number as parameter, or omit the parameter and select from the task list window. It is recommended, to display only the tasks, that you are interested in, because the evaluation of the used stack space is very time consuming and slows down the debugger display. Task Related Breakpoints Any breakpoint set in the debugger can be restricted to fire only, if a specific task hits that breakpoint. This is especially useful, when debugging code which is shared between several tasks. To set a task related breakpoint, use the command: Break.Set <address> <range> [/<option>] /TASK <task> Set task related breakpoint. Use a magic number, task ID, or task name for <task>. For information about the parameters, see What to know about Magic Numbers, Task IDs and Task Names (general_ref_t.pdf). By default, the task related breakpoint will be implemented by a conditional breakpoint inside the debugger. I.e., the target will always halt at that breakpoint, but the debugger immediately resumes execution, if the current running task is not equal to the specified task. NOTE: Task related breakpoints impact the real-time behavior of the application On some architectures it is possible to set a task related breakpoint with on-chip debug logic that is less intrusive. Specify additionally the option /Onchip to use this. The debugger then uses the on-chip resources to reduce the number of breaks to the minimum, by pre-filtering the tasks. E.g. on ARM architectures, if the RTOS serves the ContextID register at task switches, and if the debug logic provides the ContextID comparison, you may use this register for less intrusive task related breakpoints: TrOnchip.ContextID ON will enable the comparison to the whole ContextID register. TrOnchip.ASID ON will enable the comparison to the ASID part only. If TASK.List.tasks provides a trace ID (traceid column), the debugger will use this ID for comparison. Without the trace ID, it uses the magic number (magic column) for comparison. For a general description of the Break.Set command, please see its documentation. When single stepping, the debugger halts on the next instruction, regardless which task hits this breakpoint. When debugging shared code, stepping over an OS function may lead to a task switch and coming back to the same place - but with a different task. If you want to stick the debugging within the current task you can set up the debugger with SETUP.StepWithinTask ON to use task related breakpoints for single stepping. In this case, single stepping will always stay within the current task. Other tasks using the same code will not be halted on these events. RTOS Debugger for MQX 8

9 If you want to halt program execution as soon as a specific task is scheduled to run by the OS, you can use the Break.SetTask command. Task Context Display You are able to switch the whole viewing context to a currently not executing task. This means, that all register and stack related information (such as Register, Data.List, Frame etc.) will be shown according to this task. Be aware that this is only for displaying information. When continuing debugging the application (Step or Go), the debugger will switch back to the current context. For displaying a specific task context, use the command: Frame.TASK [<task>] Display task context. Use a magic number, task ID, or task name for <task>. For information about the parameters, see What to know about Magic Numbers, Task IDs and Task Names (general_ref_t.pdf). To switch back to the current context, omit all parameters. For displaying the call stack of a specific task, you can use the following command: Frame /Task <task> Display call stack of a task. If you d like to see the application code, where the task was preempted, execute the command Frame /Caller /Task <task> to open a window of the same name. Double click on the line showing the OS service call. Dynamic Task Performance Measurement The debugger may execute a dynamic performance measurement by evaluating the current running task in changing time intervals. Start the measurement with the commands PERF.Mode TASK and PERF.Arm, and view the contents with PERF.ListTASK. The evaluation is done by reading the magic location (= current running task) in memory. This memory read may be non-intrusive or intrusive, depending on the PERF.METHOD used. If PERF collects the PC for function profiling of processes in MMU based operating systems (SYStem.Option MMUSPACES ON), then you need to set PERF.MMUSPACES, too. For a general description of the PERF command, refer to General Commands Reference Guide P (general_ref_p.pdf). RTOS Debugger for MQX 9

10 Task Runtime Statistics Out of the recordings done by the Trace (if available), the debugger is able to evaluate the time spent in a task and display it statistically and graphically. Using this feature requires that the on-chip trace generation logic can generated task information. For details refer to OS-aware Tracing (glossary.pdf). To evaluate the contents of the trace buffer, use these commands: Trace.List List.TASK DEFault Trace.STATistic.TASK Trace.Chart.TASK Trace.PROfileSTATistic.TASK Trace.PROfileChart.TASK Trace.FindAll Address task.config(magic) Trace.FindAll CYcle owner OR CYcle context Display trace buffer and task switches Display task runtime statistic evaluation Display task runtime timechart Display task runtime within fixed time intervals statistically Display task runtime within fixed time intervals as colored graph Display all data access records to the magic location Display all context ID records The start of the recording time, when the calculation doesn t know, which task is running, is calculated as (unknown). TRACE32-ICE and TRACE32-FIRE use a completely different mechanism to record task information. See the trigger program below: ; Mark the magic location with an Alpha breakpoint Break.Set TASK.CONFIG(magic)++(TASK.CONFIG(magicsize)-1) /Alpha ; Program the Analyzer to record only task switches Analyzer.ReProgram ( Sample.Enable if AlphaBreak&&Write ) Task State Analysis NOTE: This feature is only available, if your debugger equipment is able to trace memory data accesses (program flow trace is not sufficient). The time different tasks are in a certain state (running, ready, suspended or waiting) can be evaluated statistically or displayed graphically. RTOS Debugger for MQX 10

11 This feature needs recording of all accesses to the status words of all tasks. Additionally, the accesses to the current task pointer (=magic) are needed. Adjust your trace logic to record all data write accesses, or limit the recorded data to the area where all TCBs are located (plus the current task pointer). To do a selective recording on task states with state analyzers (ICE or FIRE), use TASK.TASKState, if available, to mark the status words with Alpha breakpoints. Run the following PRACTICE script: ; Mark the magic location with an Alpha breakpoint Break.Set task.config(magic)++(task.config(magicsize)-1) /Alpha ; Mark all task state words with Alpha breakpoints TASK.TASKState ; Program the Analyzer to record task state transitions Analyzer.ReProgram ( Sample.Enable if AlphaBreak&&Write ) To do a selective recording on task states with flow traces (ICD, e.g. ETM and NEXUS trace), just enable the recording of all data write cycles. To evaluate the contents of the trace buffer, use these commands: Trace.STATistic.TASKState Trace.Chart.TASKState Display task state statistic Display task state timechart The start of the recording time, when the calculation doesn t know, which task is running, is calculated as (unknown). Function Runtime Statistics NOTE: This feature is only available, if your debugger equipment is able to trace memory data accesses (program flow trace is not sufficient). All function related statistic and timechart evaluations can be used with task specific information. The function timings will be calculated dependent on the task, that called this function. To do this, additionally to the function entries and exits, the task switches must be recorded. To do a selective recording on task related function runtimes with state analyzers (ICE and FIRE), use the following PRACTICE commands: RTOS Debugger for MQX 11

12 ; Mark the magic location with an Alpha breakpoint Break.Set TASK.CONFIG(magic)++(TASK.CONFIG(magicsize)-1) /Alpha ; Mark the function entries/exits with Alpha/Beta breakpoints Break.SetFunc ; Program the Analyzer to record function entries/exits and task switches Analyzer.ReProgram ( Sample.Enable if AlphaBreak BetaBreak Mark.A if AlphaBreak Mark.B if BetaBreak ) To do a selective recording on task related function runtimes with flow traces (ICD, e.g. ETM and NEXUS trace), based on the data accesses, use the following PRACTICE command: ; Enable flow trace an accesses to the magic location Break.Set TASK.CONFIG(magic) /TraceData To do a selective recording on task related function runtimes with flow traces, based on the context ID, user the following PRACTICE command: ; Enable flow trace with context ID (e.g. 32bit) ETM.ContextID 32 To evaluate the contents of the trace buffer, use these commands: Trace.ListNesting Trace.STATistic.Func Trace.STATistic.TREE Trace.STATistic.sYmbol /SplitTASK Trace.Chart.Func Trace.Chart.sYmbol /SplitTASK Display function nesting Display function runtime statistic Display functions as call tree Display flat runtime analysis Display function timechart Display flat runtime timechart The start of the recording time, when the calculation doesn t know, which task is running, is calculated as (unknown). RTOS Debugger for MQX 12

13 MQX specific Menu The file mqx.men contains an alternate menu with MQX specific topics. Load this menu with the MENU.ReProgram command. You will find a new menu called MQX. The Display menu options launch the kernel resource display windows. The Stack Coverage submenu starts and resets the MQX specific stack coverage, and provide an easy way to add or remove tasks from the stack coverage window. The Trace menu is extended. In the List submenu, you can choose for a trace list window showing only task switches (if any) or task switches together with default display. The Perf menu contains additional submenus for task runtime statistics and statistics on task states. RTOS Debugger for MQX 13

14 MQX Commands TASK.EVent Display events TASK.EVent <event> Displays a table with the MQX events. Specifying an event magic number will show you the waiting tasks of that event. E::w.task.ev magic bitmask waiting valid name yes demo waiting tasks: magic name B0 Responder TASK.KLog Display kernel log TASK.KLog Displays a table with the MQX kernel log. Each log entry contains a sequence number, a time stamp and information about one of the following entry types: Function entry (with up to 4 parameters) Function exit (with return value) Interrupt (with interrupt number) Interrupt end Context switch (with name of new task). The task name field for the context switch is mouse sensitive. Double clicking on it will show the corresponding TASK.TASK <name> window. RTOS Debugger for MQX 14

15 The log entries are displayed in chronological order, with the oldest entry first. If the first entry is not sequence number 1, the oldest entries are being overwritten. The time stamp is obtained from the kernel time when the entry is logged. B::TASK.KL Klog enabled overwrite? current/max size yes no / Entries seq no time stamp(us) description _msg_alloc (00202DE4, , , ) interrupt _task_ready ( , , , _task_ready returns , , , _task_ready (002002B0, , , _task_ready returns , , , _task_ready (002004B0, , , _task_ready returns , , , _task_ready (002006B0, , , _task_ready returns , , , _task_ready ( , , , _task_ready returns , , , interrupt 5 end context switch to BTimeSliceTask _time_delay returns , , , interrupt interrupt 5 end _time_delay ( F, , , _task_execute_scheduler ( , , context switch to ATimeSliceTask TASK.LWEvent Display light weight events TASK.LWEvent <lwevent> Displays a table with the MQX light weight events. Specifying a light weight event magic number will show you detailed information about the waiting tasks. RTOS Debugger for MQX 15

16 TASK.LWMEMPool Display light weight memory pools TASK.LWMEMPool <lwmempool> Displays a table with the MQX light weight memory pools. Specifying a light weight memory pool magic number will show you detailed information about the blocks in the memory pool. TASK.LWMsgQ Display light weight message queues TASK.LWMsgQ <lwmsgq> Displays a table with the MQX light weight message queues. Specifying a light weight msg queue magic number will show you detailed information about the waiting tasks. TASK.LWSem Display light weight semaphores TASK.LWSem <lwsem> Displays a table with the MQX light weight semaphores. Specifying a light weight semaphore magic number will show you detailed information about the waiting tasks. B::task.lws 200AA0 magic valid value waiting 00200AA0 yes waiting tasks: magic name RTOS Debugger for MQX 16

17 TASK.MEMPool Display memory pools TASK.MEMPool <mempool> Displays the task memory pool table of MQX or detailed information about one specific memory pool. Without any arguments, a table with all created memory pools will be shown. Specify a magic number to display detailed information on that memory pool. magic is a unique ID, used by the RTOS Debugger to identify a specific memory pool (address of the memory pool object). The field magic is mouse sensitive, double clicking on it opens an appropriate window. Right clicking on it will show a local menu. TASK.MeSsaGe.POOL Display message pools TASK.MeSsaGe.POOL <msg_p> Displays a table with the MQX message pools. Specifying a message pool magic number will show you the messages in that pool. E::w.task.msg.pool magic size total free grow limit type valid 00001CEB 003C named yes 00001D named yes E::w.task.msg.pool 1D08 magic size total free grow limit type valid 00001CEB 003C named yes messages in queue: magic status valid message size target p/q source p/q 00003E78 queued yes 00003E / / 0A 00003EB0 free yes 00003EC / / 00 The fields 'magic' and 'message' are mouse sensitive. Double-clicking on them will perform the appropriate action. RTOS Debugger for MQX 17

18 TASK.MeSsaGe.QUEUE Display message queues TASK.MeSsaGe.QUEUE <msg_q> Displays a table with the MQX message queues. Specifying a message queue magic number will show you the messages in that queue. E::w.task.msg.queue magic id entries max type owner/function 0001E5C 0001 none infinite normal _LTM 0001F5C 0009 none infinite normal Main 0001F7C 000A none infinite normal Responder C infinite normal Sender E::w.task.msg.queue 233C magic id entries max type owner/function C infinite normal Sender messages in queue: magic status valid message size target p/q source p/q 00003E78 queued yes 00003E / / 0A The fields 'magic' and 'message' are mouse sensitive. Double-clicking on them will perform the appropriate action. RTOS Debugger for MQX 18

19 TASK.MuteX Display mutexes TASK.MuteX <mutex> Displays a table with the MQX mutexes. Specifying a mutex magic number will show you detailed information about that mutex. E::w.task.mx magic locked wait status policy wait,spin policy priority locked spin only Inheritance valid desroy boost yes no 0. waiting tasks: magic name B0 Responder TASK.SEMaphore Display semaphores TASK.SEMaphore <sem> Displays a table with the MQX semaphores. Specifying a semaphore magic number will show you the owning and waiting tasks of that semaphore. E::w.task.sem magic owning waiting count max valid destroy policy name yes no queue demo owning tasks: magic name Sender waiting tasks: magic name B0 Responder RTOS Debugger for MQX 19

20 TASK.TASK Display tasks TASK.TASK <task> Displays the task table of MQX or detailed information about one specific task. Without any arguments, a table with all created tasks will be shown. Specify a task name, ID or magic number to display detailed information on that task. E::w.task.task magic name id state prio msgs B0 _LTM Rcv Any Blocked _Idle Ready B0 Main Rcv Any Blocked Sender Ready B0 Responder Active E::w.task.task magic name id state prio msgs B0 _LTM Rcv Any Blocked father SR disabled boost message timeout timeslice error E / 0032 OK Template: index entry parameter prio stksize timeslice C 0000E6D C 0000 Attributes: NO AUTO_START, NO FLOATING_POINT magic is a unique ID, used by the RTOS Debugger to identify a specific task (address of the task object). The fields magic, name and id are mouse sensitive, double clicking on them opens appropriate windows. Right clicking on them will show a local menu. TASK.TASKQueue Display task queues TASK.TASKQueue <task_queue> Displays a table with the task queues. Specifying a task queue magic number will show you detailed information about this queue. RTOS Debugger for MQX 20

21 TASK.TASKState Mark task state words TASK.TASKState This command sets Alpha breakpoints on all task status words. The statistic evaluation of task states (see Task State Analysis) requires recording of the accesses to the task state words. By setting Alpha breakpoints to this words, and selectively recording Alpha s, you can do a selective recording of task state transitions. Because setting the Alpha breakpoints by hand is very hard to do, this utility command sets automatically the Alpha s to the status words of all tasks currently created. It does NOT set breakpoints to tasks, that terminated or haven t yet been created. RTOS Debugger for MQX 21

22 MQX PRACTICE Functions There are special definitions for MQX specific PRACTICE functions. TASK.CONFIG(magic) Returns the address for the magic number TASK.CONFIG(magicsize) Returns the size of the magic number (1, 2 or 4) TASK.STRUCT(<item>) TASK.STRUCT(td) Reports the name of the according structure. Returns the name of the task descriptor structure Frequently-Asked Questions No information available RTOS Debugger for MQX 22