readme-baremetal.txt
1"Kernel Port" for Trace Recorder - for Bare Metal software
2Copyright 2021 Percepio AB
3www.percepio.com
4-------------------------------------------------------------------------
5(pre-release version, 2020-10-21)
6
7This module allows for using the Tracealyzer recorder library in bare metal software (i.e. without RTOS).
8
9Currently this bare-metal port allows for tracing ISRs (using vTraceStoreISRBegin/End), as well as User Events (using e.g. vTracePrintF).
10Unlike our RTOS integrations, this bare-metal variant only traces the events that you explicitly log by calling the recorder functions.
11
12The recorder library has been designed for single-core 32-bit processors. There is no support for multi-core tracing yet.
13Using the recorder from multiple cores will most likely result in data corruption.
14
15Getting Started:
16
17This is a pre-release version, intended for early adopters. There is no official "bare metal" support in the
18currently released versions of Tracealyzer, but this kernel port works with a license for "Tracealyzer for FreeRTOS".
19
20When integrating the trace recorder library in your build, you basically follow the normal integration guide
21found in Help, but skip the FreeRTOS-specific steps.
22
23The required steps to integrate the recorder are:
24
25- Add the three .c files to your project (trcSnapshotRecorder.c, trcStreamingRecorder.c and trcKernelPort.c) and if necessary a suitable trcStreamPort.c.
26
27- Copy all header files from the config and include directories to a suitable location in your project structure.
28
29- Set TRC_CFG_HARDWARE_PORT in trcConfig.h to reflect your system.
30
31- Add #include "trcRecorder.h" to all .c files where you like to use the trace recorder.
32
33- Call vTraceEnable(TRC_START) in your main function to initialize and start the recording.
34 This should be called after the initial hardware setup (when the system clock frequency is configured),
35 but before any other trace recorder calls are made.
36
37Additional considerations for bare metal:
38
39- Open trcKernelPort.h and update the definition of TRACE_CPU_CLOCK_HZ accordingly.
40 This should be set to match your processors clock frequency.
41
42- Note that several settings in trcConfig.h are irrelevant without FreeRTOS, such as TRC_CFG_FREERTOS_VERSION, TRC_CFG_INCLUDE_READY_EVENTS, TRC_CFG_INCLUDE_OSTICK_EVENTS, etc.
43
44- For snapshot mode, in trcSnapshotConfig.h you can set TRC_CFG_NTASK, TRC_CFG_NQUEUE, TRC_CFG_NSEMAPHORE etc. to 0 in order to reduce memory usage.
45 However, if tracing ISRs you need to set TRC_CFG_NISR to match the number of ISRs you intend to trace.
46
47To use this bare metal port in streaming mode, you also need to call vTracePeriodicControl() periodically, e.g. in the main loop.
48This function has two important jobs:
49 1: It handles any start/stop commands from Tracealyzer.
50 2: For some stream ports, this also writes the trace data to the streaming interface (from a temporary buffer).
51
52The J-Link and ITM stream ports only needs this function for starting and stopping the trace, so for those stream ports it is
53sufficient to call vTracePeriodicControl every 200 ms or so. For other stream ports, that uses the recorder's internal buffer,
54vTracePeriodicControl should be executed fairly often, e.g. every 10 ms, depending on the trace buffer size and the amount of data produced.
55
56In case of questions, contact support@percepio.com
