Difference between revisions of "MTB specifics"
(17 intermediate revisions by one other user not shown) | |||
Line 3: | Line 3: | ||
The ARM Micro Trace Buffer (MTB) is an on-chip trace buffer that allows to do post-mortem instruction trace via a regular J-Link with no need of a specific J-Trace unit. The MTB will use a specific amount of the on-chip RAM to store trace data while the core executes instructions. MTB is mainly used on smaller MCUs like Cortex-M0+/M23/M33 based ones. |
The ARM Micro Trace Buffer (MTB) is an on-chip trace buffer that allows to do post-mortem instruction trace via a regular J-Link with no need of a specific J-Trace unit. The MTB will use a specific amount of the on-chip RAM to store trace data while the core executes instructions. MTB is mainly used on smaller MCUs like Cortex-M0+/M23/M33 based ones. |
||
− | = |
+ | = Features = |
− | MTB is a |
+ | MTB is a stripped down version of trace that has the following features: |
− | * Instruction |
+ | * Instruction backtrace |
+ | |||
− | * No streaming trace possible |
||
+ | The following is NOT supported by MTB |
||
− | * A portion of the target RAM may not be used by the application if MTB is used |
||
+ | * Streaming trace |
||
+ | * Complete code coverage |
||
= RAM usage = |
= RAM usage = |
||
− | Most MTBs have a trace buffer between 2 |
+ | Most MTBs have a trace buffer between 2 KiB and 8 KiB. |
+ | By default, J-Link uses 512 bytes for MTB, starting at the MTB_BASE addr (device specific). |
||
− | = Configuration options provided by J-Link = |
||
− | An MTB consists of the following registers / bit fields that allow configuration of the MTB and the amount of RAM it uses: |
||
− | {| class="wikitable" |
||
− | !Register / Bit field |
||
− | !Description |
||
− | |- |
||
− | |MTB_BASE |
||
− | |32-bit read-only register that specifies the base address of the MTB buffer |
||
− | |- |
||
− | |MTB_POINTER |
||
− | |32-bit R/W register that specifies the offset (rel. to BASE) where the next trace packet will be stored by the HW |
||
− | |- |
||
− | |MTB_MASTER.MASK |
||
− | |5-bit R/W bitfield that specifies the wrap-around point for MTB buffer. |
||
− | |} |
||
+ | '''Note:''' The RAM assigned to the MTB must not be used by the application while MTB tracing is active |
||
− | == MTB_MASTER.MASK bit field == |
||
− | Specifies the wrap-around for the MTB buffer to be used. C-like logic for this field is as follows: |
||
− | Bit = (POINTER >> MASK) & 1; |
||
− | v = POINTER + 8; |
||
− | BitAfter = (POINTER >> MASK) & 1; |
||
− | if (Bit == BitAfter) { |
||
− | POINTER = v; |
||
− | } else { |
||
− | v = (1 << MASK) - 1; // Wrap-around |
||
− | POINTER = ~v; |
||
− | } |
||
+ | = Configuration options provided by J-Link = |
||
− | |||
− | point for the auto-inc logic of the MTB, on packet store. MASK specifies the MSB that exists in the buffer. A MASK Value of 7 means that bits 0-7 exist in the buffer, which means a max. value (buffer size) of 0xFF + 1 = 0x100. If the increment causes POINTER[MASK:MASK] to change from 1 to 0, POINTER[MASK:0] will be changed to 0, while leaving the rest of POINTER untouched(!). The MASK value is stored as MASK - 4 because the MTB buffer size has to be a multiple of 16 bytes anyhow. |
||
− | |||
− | Example calculation: |
||
− | * 1 KB of RAM shall be used |
||
− | * 1 KB = 0x400 (MSB == bit 9, counting starts at bit 0) |
||
− | * MASK = 9 (Stored in register as: 9 - 4 = 5) |
||
− | * Buffer usage: 0x0 - 0x3FF |
||
− | |||
− | == Default J-Link config == |
||
− | # J-Link reads out MTB_BASE to determine the base addr. of the MTB buffer |
||
− | # J-Link writes the POINTER register to find out the MTB buffer size |
||
− | # J-Link sets the POINTER register to 0 to start using the MTB buffer at MTB_BASE |
||
− | # J-Link sets the MTB_MASTER.MASK to 4 to provide a 512 byte wrap-around (setting the RAM usage to 512 bytes, starting at MTB_BASE) |
||
== Command strings for MTB configuration == |
== Command strings for MTB configuration == |
||
Line 64: | Line 29: | ||
|CORESIGHT_SetMTBBaseAddr |
|CORESIGHT_SetMTBBaseAddr |
||
|V5.10m |
|V5.10m |
||
− | |Specifies where to find the MTB in the debug address space. Only needed in case |
+ | |Specifies where to find the MTB in the debug address space. Only needed in case the device provides incorrect CoreSight info (like the NXP LPC84x series) |
|- |
|- |
||
|CORESIGHT_SetMTBBufBaseAddr |
|CORESIGHT_SetMTBBufBaseAddr |
||
Line 72: | Line 37: | ||
|CORESIGHT_SetMTBBufUseAddr |
|CORESIGHT_SetMTBBufUseAddr |
||
|V6.33i |
|V6.33i |
||
− | |Specifies where the MTB shall start using the RAM. This address may be greater than MTB_BASE but must be within the bound of MTB_BASE |
+ | |Specifies where the MTB shall start using the RAM. This address may be greater than MTB_BASE but must be within the bound of MTB_BASE and MTB_BASE + MaxBufSize |
|- |
|- |
||
|CORESIGHT_SetMTBBufUsageSize |
|CORESIGHT_SetMTBBufUsageSize |
||
|V6.33i |
|V6.33i |
||
− | |Specifies max. RAM usage for MTB |
+ | |Specifies max. RAM usage for MTB (must be a power of 2). This must not exceed MaxBufSize |
|} |
|} |
||
'''Notes:''' |
'''Notes:''' |
||
Line 88: | Line 53: | ||
* J-Link can detect the max. RAM usage of MTB via the MTB_POINTER register |
* J-Link can detect the max. RAM usage of MTB via the MTB_POINTER register |
||
− | Target RAM = 0x20000000-0x20005FFF (24 |
+ | Target RAM = 0x20000000-0x20005FFF (24 KiB)<br> |
MTB_BASE = 0x20004000<br> |
MTB_BASE = 0x20004000<br> |
||
MTB max. RAM usage = 0x2000 |
MTB max. RAM usage = 0x2000 |
||
− | === |
+ | === Valid configurations === |
− | MTB |
+ | *MTB use: 0x20004000 - 0x200041FF (Default. CORESIGHT_SetMTBBufUseAddr: 0x20004000, CORESIGHT_SetMTBBufUsageSize: 0x200) |
+ | *MTB use: 0x20004000 - 0x2000401F (CORESIGHT_SetMTBBufUseAddr: 0x20004000, CORESIGHT_SetMTBBufUsageSize: 0x10) |
||
+ | *MTB use: 0x20004100 - 0x2000417F (CORESIGHT_SetMTBBufUseAddr: 0x20004100, CORESIGHT_SetMTBBufUsageSize: 0x80) |
||
− | === |
+ | === Invalid configurations === |
+ | *MTB use: 0x20004000 - 0x20004017 (UsageSize = 0x18 which is not a power of 2) |
||
− | {| class="wikitable" |
||
+ | *MTB use: 0x20004010 - 0x2000402F (UsageSize = 0x20 which is O.K., but buffer start address is not aligned to usage size. Next possible start addresses for a UsageSize of 0x20: 0x20004000 and 0x20004020) |
||
− | !Command string |
||
− | !Value |
||
− | |- |
||
− | |CORESIGHT_SetMTBBufUsageSize |
||
− | |0x400 |
||
− | |} |
||
− | MTB RAM usage: 0x20004000 - 0x200043FF (1 KB) |
||
+ | = MTB internals = |
||
− | === Change RAM usage and start address === |
||
+ | An MTB consists of the following registers / bit fields that allow configuration of the MTB and the amount of RAM it uses: |
||
{| class="wikitable" |
{| class="wikitable" |
||
+ | !Register / Bit field |
||
− | !Command string |
||
+ | !Description |
||
− | !Value |
||
|- |
|- |
||
+ | |MTB_BASE |
||
− | |CORESIGHT_SetMTBBufUseAddr |
||
+ | |32-bit read-only register that specifies the base address of the MTB buffer |
||
− | |0x20005C00 |
||
|- |
|- |
||
+ | |MTB_POINTER |
||
− | |CORESIGHT_SetMTBBufUsageSize |
||
+ | |32-bit R/W register that specifies the offset (rel. to BASE) where the next trace packet will be stored by the HW |
||
− | |0x400 |
||
+ | |- |
||
+ | |MTB_MASTER.MASK |
||
+ | |5-bit R/W bitfield that specifies the wrap-around point for MTB buffer. |
||
|} |
|} |
||
+ | |||
− | MTB RAM usage: 0x20005C00 - 0x20005FFF (1 KB) |
||
+ | == MTB_MASTER.MASK bit field == |
||
+ | Specifies the wrap-around (buffer size) for the MTB buffer to be used. Only power of 2 wrap-around options are supported. |
||
+ | The actual value stored in HW is MASK - 4 because 16 bytes is the minimum buffer size anyhow. |
||
+ | |||
+ | C-like logic for this field is as follows: |
||
+ | Bit = (POINTER >> MASK) & 1; |
||
+ | v = POINTER + 8; |
||
+ | BitAfter = (POINTER >> MASK) & 1; |
||
+ | if (Bit == BitAfter) { |
||
+ | POINTER = v; |
||
+ | } else { |
||
+ | v = (1 << MASK) - 1; // Wrap-around |
||
+ | POINTER = ~v; |
||
+ | } |
||
+ | |||
+ | Initial: |
||
+ | BASE = 0x20000000 |
||
+ | POINTER = 0x00000000 |
||
+ | MASK = 8 => MSB[8] => 0x100 |
||
+ | Trace session, POINTER change: |
||
+ | 0x00 |
||
+ | 0x08 |
||
+ | 0x10 |
||
+ | 0x18 |
||
+ | 0x20 |
||
+ | 0x28 |
||
+ | ... |
||
+ | 0xF0 |
||
+ | 0xF8 => increment to 0x100 not possible due to MASK. Therefore, POINTER wrapped around |
||
+ | 0x00 |
||
+ | 0x08 |
||
+ | |||
+ | Initial: |
||
+ | BASE = 0x20000000 |
||
+ | POINTER = 0x00000F00 |
||
+ | MASK = 8 => MSB[8] => 0x100 |
||
+ | Trace session, POINTER change: |
||
+ | 0xF00 |
||
+ | 0xF08 |
||
+ | 0xF10 |
||
+ | 0xF18 |
||
+ | 0xF20 |
||
+ | 0xF28 |
||
+ | ... |
||
+ | 0xFF0 |
||
+ | 0xFF8 => increment to 0x1000 not possible due to MASK. Therefore, POINTER wrapped around |
||
+ | 0xF00 |
||
+ | 0xF08 |
||
+ | |||
+ | == Default behavior of J-Link == |
||
+ | # J-Link reads out MTB_BASE to determine the base addr. of the MTB buffer |
||
+ | # J-Link writes the POINTER register to find out the MTB buffer size |
||
+ | # J-Link sets the POINTER register to 0 to start using the MTB buffer at MTB_BASE |
||
+ | # J-Link sets the MTB_MASTER.MASK to 4 to provide a 512 byte wrap-around (setting the RAM usage to 512 bytes, starting at MTB_BASE) |
Latest revision as of 09:02, 27 May 2021
Contents
The ARM Micro Trace Buffer (MTB) is an on-chip trace buffer that allows to do post-mortem instruction trace via a regular J-Link with no need of a specific J-Trace unit. The MTB will use a specific amount of the on-chip RAM to store trace data while the core executes instructions. MTB is mainly used on smaller MCUs like Cortex-M0+/M23/M33 based ones.
Features
MTB is a stripped down version of trace that has the following features:
- Instruction backtrace
The following is NOT supported by MTB
- Streaming trace
- Complete code coverage
RAM usage
Most MTBs have a trace buffer between 2 KiB and 8 KiB.
By default, J-Link uses 512 bytes for MTB, starting at the MTB_BASE addr (device specific).
Note: The RAM assigned to the MTB must not be used by the application while MTB tracing is active
Configuration options provided by J-Link
Command strings for MTB configuration
The following J-Link command strings are available for MTB configuration:
Command string | Min. J-Link software version | Description |
---|---|---|
CORESIGHT_SetMTBBaseAddr | V5.10m | Specifies where to find the MTB in the debug address space. Only needed in case the device provides incorrect CoreSight info (like the NXP LPC84x series) |
CORESIGHT_SetMTBBufBaseAddr | V6.20g | Specifies the base address of the MTB buffer (RAM that may be used by MTB). This is only needed for devices where the MTB_BASE register returns an incorrect address. (E.g. on the NXP KL26Z series devices) |
CORESIGHT_SetMTBBufUseAddr | V6.33i | Specifies where the MTB shall start using the RAM. This address may be greater than MTB_BASE but must be within the bound of MTB_BASE and MTB_BASE + MaxBufSize |
CORESIGHT_SetMTBBufUsageSize | V6.33i | Specifies max. RAM usage for MTB (must be a power of 2). This must not exceed MaxBufSize |
Notes:
- For more information about how to use J-Link command strings, please refer to Using J-Link Command Strings
- All command strings from above may only be passed after a connection to the target has been established successfully
Example configurations
In the following, some example configurations for different MTB configurations are given. The examples assume that:
- J-Link can auto-discover the MTB component in the debug address space
- J-Link can detect the base address of the MTB buffer via MTB_BASE register
- J-Link can detect the max. RAM usage of MTB via the MTB_POINTER register
Target RAM = 0x20000000-0x20005FFF (24 KiB)
MTB_BASE = 0x20004000
MTB max. RAM usage = 0x2000
Valid configurations
- MTB use: 0x20004000 - 0x200041FF (Default. CORESIGHT_SetMTBBufUseAddr: 0x20004000, CORESIGHT_SetMTBBufUsageSize: 0x200)
- MTB use: 0x20004000 - 0x2000401F (CORESIGHT_SetMTBBufUseAddr: 0x20004000, CORESIGHT_SetMTBBufUsageSize: 0x10)
- MTB use: 0x20004100 - 0x2000417F (CORESIGHT_SetMTBBufUseAddr: 0x20004100, CORESIGHT_SetMTBBufUsageSize: 0x80)
Invalid configurations
- MTB use: 0x20004000 - 0x20004017 (UsageSize = 0x18 which is not a power of 2)
- MTB use: 0x20004010 - 0x2000402F (UsageSize = 0x20 which is O.K., but buffer start address is not aligned to usage size. Next possible start addresses for a UsageSize of 0x20: 0x20004000 and 0x20004020)
MTB internals
An MTB consists of the following registers / bit fields that allow configuration of the MTB and the amount of RAM it uses:
Register / Bit field | Description |
---|---|
MTB_BASE | 32-bit read-only register that specifies the base address of the MTB buffer |
MTB_POINTER | 32-bit R/W register that specifies the offset (rel. to BASE) where the next trace packet will be stored by the HW |
MTB_MASTER.MASK | 5-bit R/W bitfield that specifies the wrap-around point for MTB buffer. |
MTB_MASTER.MASK bit field
Specifies the wrap-around (buffer size) for the MTB buffer to be used. Only power of 2 wrap-around options are supported. The actual value stored in HW is MASK - 4 because 16 bytes is the minimum buffer size anyhow.
C-like logic for this field is as follows:
Bit = (POINTER >> MASK) & 1; v = POINTER + 8; BitAfter = (POINTER >> MASK) & 1; if (Bit == BitAfter) { POINTER = v; } else { v = (1 << MASK) - 1; // Wrap-around POINTER = ~v; } Initial: BASE = 0x20000000 POINTER = 0x00000000 MASK = 8 => MSB[8] => 0x100 Trace session, POINTER change: 0x00 0x08 0x10 0x18 0x20 0x28 ... 0xF0 0xF8 => increment to 0x100 not possible due to MASK. Therefore, POINTER wrapped around 0x00 0x08 Initial: BASE = 0x20000000 POINTER = 0x00000F00 MASK = 8 => MSB[8] => 0x100 Trace session, POINTER change: 0xF00 0xF08 0xF10 0xF18 0xF20 0xF28 ... 0xFF0 0xFF8 => increment to 0x1000 not possible due to MASK. Therefore, POINTER wrapped around 0xF00 0xF08
Default behavior of J-Link
- J-Link reads out MTB_BASE to determine the base addr. of the MTB buffer
- J-Link writes the POINTER register to find out the MTB buffer size
- J-Link sets the POINTER register to 0 to start using the MTB buffer at MTB_BASE
- J-Link sets the MTB_MASTER.MASK to 4 to provide a 512 byte wrap-around (setting the RAM usage to 512 bytes, starting at MTB_BASE)