When carrying out Instruction Trace via the MTB (Micro Trace Buffer) on Cortex-M0+ systems (such as the Freescale Kinetis L series and NXP LPC8xx series), both the size and the position in memory of the MTB’s buffer are user configurable, within certain size and alignment bounds. This flexibility allows the developer to balance the trade off between the amount of memory required by their code/data and the length of instruction trace that the MTB is able to capture before getting overwritten or needing to be drained.
Since the MTB uses the same RAM as is used for global variables, the heap and the stack, care must be taken to ensure that the target is configured so that the MTB’s memory and the memory used by your code do not overlap. Code Red IDE v5.1.2 introduced a new mechanism to make reserving the MTB buffer memory more straightforward.
Setting up the MTB buffer in your code
The Instruction Trace MTB support within the debugger now looks for a global array called __mtb_buffer__ in your application. The MTB will then be configured to use this space as its buffer allowing it to record execution trace without overwriting user code or data. The array __mtb_buffer__ should not be used within your code since the MTB will overwrite any data entered into it.
In order to allow the easy creation of this array in an appropriate manner within your code base, the tools provide a new header file called cr_mtb_buffer.h, which includes macros that when used will create an appropriate array.
For example, with an NXP LPC812 part which has a single 4KB bank of RAM defined, then to create a 512 byte buffer, you could add the following to your codebase...
#include <cr_mtb_buffer.h> __CR_MTB_BUFFER(512);
Or with a Freescale KL25Z part, which has a second bank of RAM defined (of 4KB in size), then to use the whole of this second RAM bank as the buffer for the MTB, you could add the following to your codebase...
#include <cr_mtb_buffer.h> __CR_MTB_BUFFER_EXT(4096, RAM2);
Note - the size of the MTB buffer must be a power of 2, and it will also be aligned into memory on its size boundary.
Project Wizard Support
In Code Red IDE v5.2.2 and later, the NXP LPC8xx project wizards contain support for automatically adding an MTB buffer to your application. This is done by the project wizard creating the file mtb.c within the application, with the size of the buffer controlled by the project define __MTB_BUFFER_SIZE. In addition the MTB buffer can be excluded from a build by defining __MTB_DISABLE.
Debugger Messages related to buffer setup
If, when debugging, you try to enable the "Record Continuous" icon in the Instruction Trace view, without the required buffer being defined in your application, then a pop up error box will be displayed:
Unable to configure continuous instruction trace because the trace buffer memory could not be detected. Press OK to see instructions to reserve the trace buffer memory in the Instruction Trace Config view. Press Cancel to abort. Reason: Failed to detect reserved MTB buffer when trying to configure instruction trace to be continuous
You should then follow the instructions to add the buffer to your application codebase.
If you attempt to manually setup an Instruction Trace session by opening the Instruction Trace Config view, when the required buffer is not defined in your application, then you will see a set of instructions displayed on how to add the buffer to your code base.
Linker script requirements
In order to support the correct placement of the __mtb_buffer__, the managed linker script mechanism used by default by the Code Red IDE has been modified in v5.1.2 (and later) to ensure that the defined buffer is placed correctly in memory.
If you have turned off the managed linker script mechanism and are maintaining your own linker scripts, then you will need to modify your linker script appropriately.
If you are using a linker template file, then you will need to update your template using the one from the Code Red IDE v5.1.2 (or later) wizards subdirectory.