{"id":70,"date":"2021-12-28T22:23:26","date_gmt":"2021-12-28T22:23:26","guid":{"rendered":"http:\/\/orbcode.org\/?page_id=70"},"modified":"2023-10-09T15:10:48","modified_gmt":"2023-10-09T15:10:48","slug":"orbuculum","status":"publish","type":"page","link":"https:\/\/orbcode.org\/orbuculum\/","title":{"rendered":"Orbuculum"},"content":{"rendered":"\n<p class=\"wp-block-paragraph\">An Orbuculum is a Crystal Ball, used for seeing things that would be otherwise invisible. In the context of Orbcode it&#8217;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 &amp; 4 bit parallel trace too. If you want to find out more about SWO, start reading <a href=\"http:\/\/orbcode.org\/orbuculum\/single-wire-output\/\">here<\/a>. 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&#8217;s available <a href=\"https:\/\/www.embeddedrelated.com\/webinar\/22\/Instrumenting_Embedded_Applications.php\">here<\/a>. Alternatively, if you want a good example of using the suite to improve the performance of your embedded application, checkout this <a href=\"https:\/\/www.hbo-kennisbank.nl\/resolve\/utrechthogeschool\/eyJ1IjogImh0dHBzOi8vc3VyZnNoYXJla2l0Lm5sL29iamVjdHN0b3JlLzU0NWE0ZjhhLTk0YmQtNGVlMi05M2MwLWIzMWYyYmUzODY5YyIsICJpIjogbnVsbCwgImgiOiAiNzdlYWU5ZTllNGU3YzdkZjZjODIzOWRlNTA5MDdlYjRhMDgyNThlNzA0ZjE3ZTMzNzk1YTE0NjcxMzk1MzI5MCJ9\">graduation report<\/a> from Ian Baak.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">The Orbuculum tools are available from <a href=\"https:\/\/github.com\/orbcode\/orbuculum\/\">GitHub<\/a>.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">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 &#8216;top&#8217; tool for your desktop computer through to full multichannel debug feeds and post-mortem crash analysis.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">The current set is;<\/p>\n\n\n\n<ul class=\"has-normal-font-size wp-block-list\">\n<li><strong>orbuculum:<\/strong> 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&#8217;re using and then you can just leave it running and it&#8217;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.<\/li>\n<\/ul>\n\n\n\n<ul class=\"has-normal-font-size wp-block-list\">\n<li><strong>orbfifo:<\/strong> The fifo pump: Turns a trace feed into a set of fifos (or permanent files).<\/li>\n<\/ul>\n\n\n\n<ul class=\"has-normal-font-size wp-block-list\">\n<li><strong>orbcat:<\/strong> A simple cat utility for ITM channel data.<\/li>\n<\/ul>\n\n\n\n<ul class=\"has-normal-font-size wp-block-list\">\n<li><strong>orbdump: <\/strong>A utility for dumping raw SWO data to a file for post-processing.<\/li>\n<\/ul>\n\n\n\n<ul class=\"has-normal-font-size wp-block-list\">\n<li><strong>orbtop:<\/strong> A top utility to see what&#8217;s actually going on with your target. It can also provide dot and gnuplot source data for perty graphics.<\/li>\n<\/ul>\n\n\n\n<ul class=\"has-normal-font-size wp-block-list\">\n<li><strong>orbstat: <\/strong>An analysis\/statistics utility which can produce KCacheGrind input files. KCacheGrind is a very powerful code performance analysis too<\/li>\n<\/ul>\n\n\n\n<ul class=\"has-normal-font-size wp-block-list\">\n<li><strong>orbtrace: <\/strong>The fpga configuration bitstream maker to support parallel trace operation.<\/li>\n<\/ul>\n\n\n\n<p class=\"wp-block-paragraph\"><\/p>\n\n\n\n<p class=\"wp-block-paragraph\">At the present time Orbuculum supports ten different devices for collecting trace from the target;<\/p>\n\n\n\n<ul class=\"has-normal-font-size wp-block-list\">\n<li>the Black Magic Debug Probe (BMP)<\/li>\n\n\n\n<li>the SEGGER JLink<\/li>\n\n\n\n<li>generic USB TTL Serial Interfaces<\/li>\n\n\n\n<li>FTDI High speed serial interfaces<\/li>\n\n\n\n<li>OpenOCD (Add a line like <strong><em>tpiu config internal :3443 uart off 32000000<\/em><\/strong> to your openocd config to use it.)<\/li>\n\n\n\n<li>PyOCD (Add options like <strong><em>enable_swv: True, swv_system_clock: 32000000 <\/em><\/strong>to your pyocd.yml to use it.)<\/li>\n\n\n\n<li>The ice40-HX8K Breakout Board for parallel trace<\/li>\n\n\n\n<li>The ECPIX-5 ECP5 Breakout Board for parallel trace<\/li>\n\n\n\n<li>Anything capable of saving the raw SWO data to a file<\/li>\n\n\n\n<li>Anything capable of offering SWO on a TCP port<\/li>\n<\/ul>\n\n\n\n<h2 class=\"wp-block-heading\">Reading List<\/h2>\n\n\n\n<p class=\"wp-block-paragraph\">If you want to learn more about orbuculum and how it&#8217;s used, you could do much worse than read through the articles in the <a href=\"http:\/\/orbcode.org\/blog\/\">Data Feed<\/a> about SWO and how it can be used, here&#8217;s a suggested reading order for the first few articles to get you going;<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li><a href=\"http:\/\/orbcode.org\/orbuculum\/single-wire-output\/\">Single Wire Output<\/a> : What it is and how it works.<\/li>\n\n\n\n<li><a href=\"http:\/\/orbcode.org\/orbuculum\/swo-getting-started-with-tooling\/\">Using tooling<\/a> : How to plug into SWO to get useful output.<\/li>\n\n\n\n<li><a href=\"http:\/\/orbcode.org\/orbuculum\/swo-the-hardware-channels\/\">The Hardware Channels<\/a> : What information you can get from the chip with no software intervention.<\/li>\n\n\n\n<li><a href=\"http:\/\/orbcode.org\/orbuculum\/swo-starting-with-apps\/\">Example Apps<\/a> : Using SWO with external post-processing.<\/li>\n\n\n\n<li><a href=\"http:\/\/orbcode.org\/orbuculum\/swo-code-instrumentation\/\">Code Instrumentation<\/a> : Example of using the SWO output for learning more about execution paths.<\/li>\n\n\n\n<li><a href=\"http:\/\/orbcode.org\/orbuculum\/swo-more-instrumentation\/\">Using KCacheGrind<\/a> : More tools for code understanding.<\/li>\n\n\n\n<li><a href=\"http:\/\/orbcode.org\/orbuculum\/swo-even-more-instrumentation\/\">gprof2dot<\/a> : An openly available path visualiser.<\/li>\n<\/ul>\n\n\n\n<p class=\"wp-block-paragraph\">If you&#8217;ve not yet selected your capture device, you should also checkout <a href=\"http:\/\/orbcode.org\/orbtrace-mini\/\">ORBTrace Mini<\/a>.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\"><\/p>\n","protected":false},"excerpt":{"rendered":"<p>An Orbuculum is a Crystal Ball, used for seeing things that would be otherwise invisible. In the context of Orbcode it&#8217;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 <a href=\"https:\/\/orbcode.org\/orbuculum\/\" class=\"read-more below\">READ MORE<\/a><\/p>\n","protected":false},"author":1,"featured_media":0,"parent":0,"menu_order":0,"comment_status":"closed","ping_status":"closed","template":"template-full-width.php","meta":{"footnotes":""},"class_list":["post-70","page","type-page","status-publish","hentry"],"_links":{"self":[{"href":"https:\/\/orbcode.org\/wp-json\/wp\/v2\/pages\/70","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/orbcode.org\/wp-json\/wp\/v2\/pages"}],"about":[{"href":"https:\/\/orbcode.org\/wp-json\/wp\/v2\/types\/page"}],"author":[{"embeddable":true,"href":"https:\/\/orbcode.org\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/orbcode.org\/wp-json\/wp\/v2\/comments?post=70"}],"version-history":[{"count":8,"href":"https:\/\/orbcode.org\/wp-json\/wp\/v2\/pages\/70\/revisions"}],"predecessor-version":[{"id":385,"href":"https:\/\/orbcode.org\/wp-json\/wp\/v2\/pages\/70\/revisions\/385"}],"wp:attachment":[{"href":"https:\/\/orbcode.org\/wp-json\/wp\/v2\/media?parent=70"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}