Vous êtes sur la page 1sur 4

Recorder Library

www.percepio.com FreeRTOS+Trace Introduction System Overview Using FreeRTOS+Trace Example Uses Requirements Recorder Library Using the Trace Recorder Hardware Timer Porting FreeRTOS Integration Uploading the trace data Terminology Main Window Trace View Menu options Finder window Actor Instances Tab Kernel Service Calls Tab User Events Tab Time Point Tab Horizontal Trace View CPU Load Graph Kernel Object Utilization Scheduling Intensity Kernel Service Call Intensity

Using the Trace Recorder


The trace recorder library is the embedded runtime component of FreeRTOS+Trace. The recorder library is integrated in FreeRTOS and stores the event data in a RAM buffer, which is uploaded on request to the host PC using your existing debugger connection. The recorder library builds on experiences from several earlier recorder implementations on different RTOS platforms since 2004. It is fast, configurable and very memory efficient. Its RAM buffer can be scaled down to use only a few KB of RAM, which allows for use in micro-controller systems with on-chip RAM only. The trace data is typically uploaded to your host PC by taking a RAM dump using your debugger. This is a very common feature available in most debuggers. You typically open the memory view in your debugger and select a "Save" option. Another method is to interface your hardware debugger directly, which is often possible to script. For instance, Segger J-Link/J-Trace allows this through J-Link Commander (use the savebin command). Trace data files in binary format and in Intel Hex format can be opened directly using FreeRTOS+Trace, if the files are named ".bin" or ".hex" respectively. The RAM dump does not need to match the particular memory area of trace data. As long as the recorder data is included somewhere in the RAM dump, FreeRTOS+Trace will automatically located it due to a special numeric signature found in the beginning and end of the trace data.

The recorder has two modes of operation: Stop-when-full mode Ring-buffer mode The stop-when-full mode stops the recorder when the buffer gets full. This is suitable when you want to capture the events following a particular point in your code, where you call uiTraceStart() to start the recorder. The ring-buffer mode allows you to have the recorder active continuously, as it overwrites the oldest events with new events and thereby always keeps the latest history up until the point where vTraceStop() is called to stop the recorder, e.g., on a detected error state, or until the system is halted by the debugger. The recorder library has several settings which you should inspect before using it, such as the two modes described above. The settings are found in the header file trcConfig.h, together with detailed documentation. For further information about the recorder library, see trcUser.h (and trcUser.c, if you want to study the detailed implementation).

Hardware Timer Porting


The recorder library needs a hardware timer port in order to give accurate timestamps on the recorded events. This is the only hardware dependency of the recorder library. Some hardware architectures are

already supported in the recorder library, such as ARM Cortex M3 and M4 (all chips using such cores), and other ports are in development. However, there are many chips that we do not yet have direct support for, with respect to hardware timestamping. In case your chip is not yet directly supported, the recorder library includes a hardware independent fallback option providing low resolution time stamping equivalent to the FreeRTOS tick, typically 1 ms. However, it is strongly recommended to use to a hardware timer for any serious use of this tool. Fortunatly, developing a hardware timer port yourself is quite easy. Read more in the "Developing a Hardware Timer Port" section below. Provide a Hardware Timer Port, and Get a Free License! Percepio has an attractive offer for silicon companies and non-corporate users such as students, academic researchers, hobbyists and early-phase startups: If you create a hardware timer port for an architecture that is not yet directly supported, and your port is validated by Percepio as being correct, then Percepio will provide a free single user license for FreeRTOS+Trace Professional Edition in exchange for ownership rights of your port! That means Percepio will also take responsibility for the code, and you will not be liable for any customer support issues. Developing a Hardware Timer Port Developing a hardware timer port is quite easy if you already have a FreeRTOS environment up and running. The recorder library file trcPort.c contains a function uiTracePortGetTimeStamp that is expected to return the current time, based on the hardware timer/counter that drives the FreeRTOS tick. This function is based on a set of macros (prefixed "HWTC") that you define according to your specific hardware in trcPort.h. Please refer to the comments in trcPort.h for detailed instructions. Note that it is typically not necessary to change the timestamp function in trcPort.c, since the HWTC macros typically provides sufficent hardware abstraction. Note The hardware timer/counter used that drives the FreeRTOS tick can be identified in FreeRTOS file port.c, where it is initialized. Using hardware timers other than the one driving the OS tick is possible, but is a less generic solution which is usually not accepted for the "Free Licence" offer, since such a solution might not work for other FreeRTOS users that might be using the timer/counter for other purposes and in other configurations. However, if the hardware timer/counter used by your FreeRTOS port does not fit our assumptions (e.g., that the current value can be read), another timer solution is of course necessary and accepted. But in that case, please highlight this issue when submitting your port. When you have identified the right hardware feature, you need to study the data sheet for your specific hardware to find the right registers to use. Make sure to read the timer/counter value is a way that does not also reset the timer/counter. For instance, the AT91SAM7 has two registers for accessing the PIT counter value, one just reads the value while the other also resets it. The latter is used in the FreeRTOS tick handler. When defining the HWTC_PERIOD macro, please use the timer/counter reload register, if possible, rather than a literal constant. This is to make the solution more portable between different versions of the same chip family. For questions about hardware timer ports of the trace library and this offer, please contact support@percepio.se

FreeRTOS Integration
To integrate the recorder trace library in your FreeRTOS build, the following steps are recommended: Check that your FreeRTOS version is v7.1.0 or later. Otherwise you need to upgrade your FreeRTOS installation. Download the recorder library HERE and extract the contents (library source code and demo project) to a suitable location in your development directory. Add the following lines to the end of your FreeRTOSConfig.h #define configUSE_TRACE_FACILITY 1 #include "trcHooks.h" For IAR Embedded Workbench, you may need to use a conditional include as follows: #define configUSE_TRACE_FACILITY 1 #ifdef __ICCARM__ #include "trcHooks.h" #endif

Include the trace library source code (trcUser.c, trcBase.c, trcKernel.c and trcPort.c) in your build project and add the "percepio/include" directory to your compiler "include" path. Check the settings in trcConfig.h and modify when needed to match your system (e.g., the number of tasks, the event buffer size, etc.).

If desired, call vTraceStartStatusMonitor in your startup to start the recorder status monitor task. This periodically reports the recorder status using console prints. This is not required. To enable console prints from the recorder library (e.g., to see any error message, warning, or status print), you need to define the macro vTraceConsoleMessage in trcPort.h. It should be mapped to your debug console print function (e.g., "printf"). Call uiTraceStart at the point you wish to begin recording, in the startup or at some later point in the application code. Remember to check the return value - a value of zero indicates that the recorder could not start since vTraceError has been called. This means that there is an internal error in the recorder library, probably to to insufficient values for the Nxxx constants in trcConfig.h (e.g., NTask, NQueue, etc). The error message is in that case displayed when opening the trace file, but can also be obtained from the recorder API by calling xTraceGetLastError. Select the right hardware timer port in trcPort.h. If your CPU/MCU is not yet directly supported with respect to hardware timestamping, you need to update the HWTC macros in trcPort.h to match your hardware. However, a hardware independend ready-to-run fallback option is available, with a lower resolution equivalent to the FreeRTOS tick rate - typically 1 millisecond. Read more in section Hardware Timer Porting. If your CPU/MCU has on-chip RAM only, we recommend that you check your CPU/MCU data sheet if there is a secondary RAM bank. This is the case for NXP LPC17xx (16 KB or 32 KB primarily intended for DMA transfers) and probably many other chips as well. If a secondary RAM bank exists, you can instruct your compiler/linker to place the RecorderData structure there. This can allow for a significant increase of EVENT_BUFFER_SIZE, i.e., longer traces, without using the main RAM where the heap and stacks typically are located. Further instructions are available in trcBase.c at the definition of the RecorderData structure. For further information about the recorder library, see trcUser.h (and trcUser.c, if you want to study the detailed implementation).

Uploading the trace data


This section decribes how to upload the trace data from the target system to FreeRTOS+Trace. Your existing debugger is used to upload the trace data from the chip RAM. This is a plain RAM dump, that is done whenever you want to look at the trace buffer contents. This means it works with essentially with any debug probe and debugger IDE on the market, since saving the RAM contents is a commonly available function. Built-in support for Segger J-Link/J-Trace and Atmel SAM-ICE Since v2.3, FreeRTOS+Trace supports Segger J-Link and J-Link compatible debuggers directly, without any debugger IDE involved. Using other debug probes is also possible, but requires some extra steps in the debugger IDE, as described below. If you have a Segger J-Link/J-Trace debug probe or another JLink compatible debug probe, just select "Read Trace" in the "J-Link" menu. Note The built-in J-Link integration does not work together with Renesas HEW, since this locks the JLink interface. Renesas HEW users are recommended to use the "Save Memory" function of Renesas HEW to save a RAM dump, as described below. This opens a dialog where you get to enter the memory region where the recorder data structure is located. Normally you select the entire internal RAM according to the datasheet of your MCU, but the exact address can be found can by inspecting the "RecorderData" struct or the "RecorderDataPtr" pointer with your debugger. Typical values are 0x0, 0x10000000 or 0x20000000 as start address and 0x10000 or 0x20000 as size (64 KB or 128 KB). This makes FreeRTOS+Trace reads the chip RAM and locate the trace data. Note that this option is only available if a compatible debug probe is found. J-Link compatible debug probes also include Atmel SAM-ICE and many built-in debug interfaces on demonstration/evaluation boards (where there is a USB connection directly to the board). Look for a Segger J-Link label on the board. Atmel Studio 6 Integration using MemoryLogger If you are using Atmel Studio 6, Atmel's new MemoryLogger extension provides a superb integration with FreeRTOS+Trace. Look for "MemoryLogger" in Atmel Gallery. This extension automatically detects the path to FreeRTOS+Trace, if installed, and gives you a single-click upload/refresh. You can use it while debugging and optionally get an automatic refresh eash time the MCU is halted, e.g., on each breakpoint. Using other development environments and debug probes Most debuggers are able to save the RAM contents to a file. FreeRTOS+Trace supports the following common formats: Binary (.bin or .dump), supporting gdb, J-Link and Renesas HEW. Intel Hex (.hex), supporting IAR Embedded Workbench and Atmel MemoryLogger. MCH (.mch), supporting Microchip MPLAB. When you store the RAM dump, you must also make sure to select the right region, i.e., start address and size. The recorder data is stored in a single data block, identified by the pointer RecorderDataPtr. It is not necessary to match the begin and end of the recorder data, as long as it is fully included by the

dumped memory region. FreeRTOS+Trace automatically finds the trace data in the RAM dump, thanks to special signatures. For chips with on-chip RAM only, we therefore recommend to dump the entire RAM. This is usually very fast. For chips with larger amounts of (external) RAM, it is typically possible to dump a limited region where the data is typically found. Using IAR Embedded Workbench for ARM, version 6.3 In the debugger view, when stopped on a breakpoint: Select "Debug" menu, "Memory" submenu, "Save..." (keyboard shortcut: ALT,d,y,s) In the Save dialog Zone: Memory Start Adress: 10000000 (for NXP LPC1766 in the demo project) End Adress: 1000FFFF (for NXP LPC1766 in the demo project) File format: Intel Extended Filename: "name.hex" Press "Save" button and open "name.hex" in FreeRTOS+Trace. To find the right Start and End addresses, check the address of the symbol "RecorderData". The addresses does not need to match this symbol exactly, as long as the whole data is included. Using Renesas High-performance Embedded Workshop v4.09 In the debugger view, when stopped on a breakpoint: Select "Debug" menu, "Save Memory..." (keyboard shortcut: ALT,d,a) In the Save dialog Format: Binary Filename: "name.bin" Start Address: 00000000 (For RX62N in the demo project) End Address: 0000FFFF (For RX62N in the demo project) Access size: 1 Press "Save" button and open "name.bin" in FreeRTOS+Trace. Using Microchip MPLAB v8.86 Select "View" -> "File Registers". This shows you the memory contents. Make sure "Hex" is selected in the bottom left (instead of "Symbolic"). Hex mode seems to be default. Right click in the view and select "Export Table...". In the dialog ("Export As"), make sure "Single Column Output" is selected (seems to be default). Select start address 0x0000 and make sure the end address is beyond the RecorderData structure. The default values seems to be the whole RAM, so you probably don't need to change this. Save as a .mch file and open this file in FreeRTOS+Trace. Using STM32 ST-Link Start "ST-Link Utility" Connect to the device and view the device memory. Set the view to display the entire RAM, or at least the section containing the RecorderData structure. Select "Save as" and choose binary (.bin) or Intel Hex (.hex) format. Open the resulting file in FreeRTOS+Trace. Copyright Percepio AB 2012, all rights reserved.

Vous aimerez peut-être aussi