SWO Output - Marus/cortex-debug GitHub Wiki

Basic SWO Output Configuration

Simple SWO ascii console, CPU running at 72MHz, SWO at 2MHz, SWO data comes from probe itself (eg. ST-LINK)

"swoConfig":{
    "enabled":true,
    "source":"probe",
    "swoFrequency": 2000000,
    "cpuFrequency":72000000,
    "decoders": [
        {
            "port": 0,
            "type": "console",
            "label": "SWO output",
            "encoding":"ascii"
        }
    ]
}

Depending on the gdb-server (OpenOCD, JLink, etc.) the source can be different. The source is the method to acquire SWO data from the gdb-server. SWO data may be served using a 'probe', 'socket' (tcp), 'file', 'fifo', 'serial' (serial-port), etc. file based methods are unreliable, so a fifo is used on Unix/Mac. Where available a socket is always the preferred method. Following are the currently supported source types and how they are interpreted.

Server	SWO input methods supported
OpenOCD	`probe/file/socket` use a tcp port. `serial` also supported
pyocd	`probe/file/socket` use a tcp port. `serial` also supported
stutil	`serial`
external	`probe` implies a file (windows) and a FIFO on other platforms.
	`file`, `socket` and `serial` also supported with their intended meaning

Cortex-Debug will auto-configure the server as required, but you can provide overrides. With an external server, where a server is launched outside of this extension, all configuration has to be done manually (via overrides)

SWO is only useful if you have one or more decoders. A decoder tells this extension how to handle the data stream from SWO. Since SWO supports multiple ports, you can have each port go to a decoder. Following decoder types are available:

Decoder type	Handling of the data
`console`	Data is interpreted as human-readable text with a given encoding ('utf8' is the default). You can find the output in the `TERMINAL` tab.
`binary`	This is similar to `console` but data is interpreted as a binary stream like signed, unsigned, float, etc., and the result is displayed as hex values. Each line in the output window will contain a timestamp hex-value - decoded-value - scaled-value
`graph`	This is also interpreted as binary data but is useful for plotting graphs. Each such decoder has a `graphId` (arbitrary user-defined name) that can be later used in a graph. See Output Graphing
`advanced`	This is where you provide a custom JavaScript module to interpret the data. For each chunk of data received, an event is generated that your module can subscribe to. See source code here

SWO configuration

To get SWO working, several registers in the device have to be set to specific values. This is done with a combination of gdb commands and help with the gdb-server (OpenOCD, etc.). Rarely, you may have to add some initialization code in your FW because of how your MCU is designed. There are two aspects to getting SWO working

GDB setup. Setup the ARM CoreSight components by writing to the appropriate registers. Cortex-Debug will attempt to do this. But it may not succeed.
- Cortex-Debug does not know anything about your specific to initialize the clocks and IOs. You can do this externally by writing to the appropriate registers or from within your firmware
- The ARM trace components (TPIU, DWT, ITM) for your device may not use the default base addresses. This will cause the gdb scripts to not do the right thing. You can override the default scripts with your own as long as the name of the GDB macro (SWO_Init) is the same. You can add any device-specific settings here as well. You can find this script at https://github.com/Marus/cortex-debug/blob/master/support/gdb-swo.init. You can make a copy and use it like this

        "preLaunchCommands": [
            "source ${workspaceFolder}/mygdbscript.txt"
        ]

GDB-server setup: OpenOCD requires a bit of configuration. Because each vendor provides the OpenOCD set up a little bit differently, the default script we run may also fail. This occurs before we do any GDB setup. If you need to customize this, you can make a copy of the file/function https://github.com/Marus/cortex-debug/blob/master/support/openocd-helpers.tcl and add it as the first item in the configFiles property. Note that this file only defines functions and does not call them. Cortex-Debug will call the CDSWOConfigure TCL function with the appropriate parameters at the appropriate time.

ARM basic config

This example expects CMSIS usage

Init (ST specific, Obsolete?)

/* Select the SWO interface */
DBGMCU->CR &= DBGMCU_CR_TRACE_MODE_Msk;

/* Enable the TRACE interface */
DBGMCU->CR |= DBGMCU_CR_TRACE_IOEN;

Above is not needed if the gdb-script is initializing the SWO registers. You can also look at a C implementation at https://github.com/Marus/cortex-debug/blob/master/support/swo-init.c and not use the GDB script.

Send character

ITM_SendChar(character);

Note: Don't forget to properly configure SWO pin. Some devices may have a clock that controls the TPIU that needs to be configured

Advanced Decoder Creation

Output Graphing {#graphing}

Example of a time series graph with two lines

"graphConfig" can be used alongside with "swoConfig" or with "rttConfig". It may also work with a combination of the two as long as the graphIds are unique. See also https://github.com/Marus/cortex-debug/wiki/SEGGER-RTT-support

VSCode Cortex Debug configuration

"type": "cortex-debug",
            "request": "attach",
            "servertype": "openocd",
            "cwd": "${workspaceRoot}/build",
            "executable": "NucleoProject.elf",
            "name": "Debug (OpenOCD)",
            "device": "STM32F303",
            "svdFile": "../scripts/openOCD/STM32F303.svd",
            "showDevDebugOutput": false,
            "configFiles": [
                "board/st_nucleo_f3.cfg"
            ],
            "swoConfig": 
            {
                "enabled": true, 
                "decoders": [
                    {
                        "type": "graph",
                        "port": 0,      
                        "encoding": "unsigned",
                        "graphId": "1", 
                        "scale": 1
                    },
                    {
                        "type": "graph",
                        "port": 1,      
                        "encoding": "unsigned",
                        "graphId": "2", 
                        "scale": 1
                    },
                ],
                "cpuFrequency": 75000000,   
                "swoFrequency":  2000000,   
                "source": "probe",
            },
            "graphConfig": [
                {
                    "label": "Graph 1",
                    "timespan": 5,
                    "type": "realtime",
                    "annotate": false,
                    "maximum": 256,
                    "minimum": 0,
                    "plots": [
                        {
                            "graphId": "1", 
                            "label": "data 1",
                            "color": "#53753c"
                        },
                        {
                            "graphId": "2", 
                            "label": "data 2",
                            "color": "#955f20"
                        }
                    ]
                },
            ]
        },

Modified ITM_SendChar (CMSIS) function (added ITM port)

uint8_t ITM_SendChar(uint8_t ch, size_t const port)
{
  if (((ITM->TCR & ITM_TCR_ITMENA_Msk) != 0UL) &&      /* ITM enabled */
      ((ITM->TER & (port+1)          ) != 0UL)   )     /* ITM Port enabled */
  {
    while (ITM->PORT[port].u32 == 0UL)
    {
      __NOP();
    }
    ITM->PORT[port].u8 = (uint8_t)ch;
   }
  return (ch);
}

VSCode Cortex Debug output graph

Note that the maximum stable data rate with ST-Link/V2 is about 8kSamp/s for uint8 data, the implementation of the Graph however does limit the data rate even further. The graph will skip samples, if the data rate is too high.