Orbuculum

An Orbuculum is a Crystal Ball, used for seeing things that would be otherwise invisible. In the context of Orbcode it’s a set of tools for decoding and presenting output flows from the trace pins of a CORTEX-M CPU. Originally it only supported the Single Wire Output (SWO) pin but in combination with ORBTrace mini or other trace capture interface such as JTrace it also decodes 1, 2 & 4 bit parallel trace too. If you want to find out more about SWO, start reading here. You might also take a look at the presentation given at this years Embedded Online Conference (free registration required) which gives you a decent overview of the suite in use, that’s available here. Alternatively, if you want a good example of using the suite to improve the performance of your embedded application, checkout this graduation report from Ian Baak.

The Orbuculum tools are available from GitHub.

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; anything from an equivalent of the ‘top’ tool for your desktop computer through to full multichannel debug feeds and post-mortem crash analysis.

The current set is;

  • orbuculum: The main program which interfaces to the trace probe and then issues a network interface to which an arbitrary number of clients can connect, by default on TCP/3443. This is used by a base interface to the target by other programs in the suite. Generally you configure this for the TRACE tool you’re using and then you can just leave it running and it’ll grab data from the target and make it available to clients whenever it can. Note that some debug probes (e.g. openocd and pyocd) can now create an orbuculum-compatible interface on TCP/3443, and then you can connect the rest of the suite to that directly, without using the orbuculum mux itself.
  • orbfifo: The fifo pump: Turns a trace feed into a set of fifos (or permanent files).
  • orbcat: A simple cat utility for ITM channel data.
  • orbdump: A utility for dumping raw SWO data to a file for post-processing.
  • orbtop: A top utility to see what’s actually going on with your target. It can also provide dot and gnuplot source data for perty graphics.
  • orbstat: An analysis/statistics utility which can produce KCacheGrind input files. KCacheGrind is a very powerful code performance analysis too
  • orbtrace: The fpga configuration bitstream maker to support parallel trace operation.

At the present time Orbuculum supports ten different devices for collecting trace from the target;

  • the Black Magic Debug Probe (BMP)
  • the SEGGER JLink
  • generic USB TTL Serial Interfaces
  • FTDI High speed serial interfaces
  • OpenOCD (Add a line like tpiu config internal :3443 uart off 32000000 to your openocd config to use it.)
  • PyOCD (Add options like enable_swv: True, swv_system_clock: 32000000 to your pyocd.yml to use it.)
  • The ice40-HX8K Breakout Board for parallel trace
  • The ECPIX-5 ECP5 Breakout Board for parallel trace
  • Anything capable of saving the raw SWO data to a file
  • Anything capable of offering SWO on a TCP port

Reading List

If you want to learn more about orbuculum and how it’s used, you could do much worse than read through the articles in the Data Feed about SWO and how it can be used, here’s a suggested reading order for the first few articles to get you going;

If you’ve not yet selected your capture device, you should also checkout ORBTrace Mini.