orbuculum | Cortex M SWO SWV Demux and Postprocess

orbuculum is a C library typically used in Internet of Things (IoT), Arduino applications. orbuculum has no bugs, it has no vulnerabilities and it has low support. However orbuculum has a Non-SPDX License. You can download it from GitHub.

Orbuculum is a set of tools for decoding and presenting output flows from the Debug pins of a CORTEX-M CPU. Originally it only used the SWO pin but it now also supports hardware for parallel tracing through the TRACE pins too using the iCE40HX-8K FPGA Breakout Board. Numerous types of data can be output through these pins, from multiple channels of text messages through to Program Counter samples. Processing these data gives you a huge amount of insight into what is really going on inside your CPU. The current tools are;. A few simple use cases are documented in the last section of this document, as are example outputs of using orbtop to report on the activity of BMP while emitting SWO packets. More will be added. The data flowing from the SWO pin can be encoded either using NRZ (UART) or RZ (Manchester) formats. The pin is a dedicated one that would be used for TDO when the debug interface is in JTAG mode. The data flowing from the TRACE pins is clocked using a separate TRACECLK pin. There can be 1-4 TRACE pins which obviously give you much higher bandwidth than the single SWO. Orbuculum takes this output and makes it accessible to tools on the host PC. At its core it takes the data from the source, decodes it and presents it to a set of unix fifos which can then be used as the input to other programs (e.g. cat, or something more sophisticated like gnuplot, octave or whatever). Orbuculum itself doesn’t care if the data originates from a RZ or NRZ port, or at what speed…​.that’s the job of the interface. At the present time Orbuculum supports nine devices for collecting trace from the target;. Information about using each individual interface can be found in the docs directory. gdb setup files for each device type can be found in the Support directory. When using SWO Orbuculum can use, or bypass, the TPIU. The TPIU adds (a small amount of) overhead to the datastream, but provides better synchronisation if there is corruption on the link. To include the TPIU in decode stack, provide the -t option on the command line. If you don’t provide it, and the ITM decoder sees TPIU syncs in the datastream, it will complain and barf out. This is deliberate after I spent two days trying to find an obscure bug 'cos I’d left the -t option off…​. Beware that in parallel trace the TPIU is mandatory, so therefore so is the -t option. When in NRZ mode the SWO data rate that comes out of the chip must match the rate that the debugger expects. On the BMP speeds of 2.25Mbps are normal, TTL Serial devices tend to run a little slower but 921600 baud is normally acheivable. On BMP the baudrate is set via the gdb session with the 'monitor traceswo xxxx' command. For a TTL Serial device its set by the Orbuculum command line. Segger devices can normally work faster, but no experimentation has yet been done to find their max limits, which are probably it’s dependent on the specific JLink you are using. JLink-Pro and JTrace devices appear to work up to 50MHz. YMMV. When using parallel trace you are limited by the capabilities of the FPGA configuration and the speed you can get data off the chip. The current maximum speed supported for the target is around 150MHz but you will swamp the chip very quickly if you start streaming data at that speed. The offboard link is curently limited to about 22Mbps serial. This issue will be resolved when dedicated FPGA target hardware is available (it’s on its way).