.. _fast_printf: Using XSCOPE for fast "printf debugging" ======================================== The previous example in :doc:`switch-setup` was very slow due to the time taken to print each line of text to the terminal. This is made particularly noticable if the value of :samp:`ITERATIONS` is increased. This default behaviour can be slow for a number of reasons: * A JTAG interface is being used to control the transfer. * There is no buffering for the transferred data. * The data is transferred via the debug kernel. All running logical cores on a tile are halted whilst the transfer on a given logical core completes. It is clear to see that the default behaviour can play havoc if the application being debugged has any real-time constraints. To mitigate this problem, the XSCOPE interface is provided. .. figure:: images/debug-setup.png :width: 531 XTAG debug setup showing JTAG and xlink connections The XSCOPE interface makes use of a physical high bandwidth XLINK connection to the XTAG debugger. Buffering is provided on the XTAG debugger itself. Through this mechanism there is no need to halt all the logical cores whilst another conducts a transfer. The net result is that XSCOPE can be used as a high performance debug interface with minimal impact on the real-time performance of the application under examination. Use of XSCOPE is thus recommended in almost all cases. Configuring and using XSCOPE ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ This example presumes that we are using XSCOPE to accelerate debug of the previous example: :doc:`switch-setup`. XSCOPE is configured by creating an XML :ref:`config_xscope_format` with the suffix: :file:`.xscope`. Here we create the most basic configuration file: .. literalinclude:: examples/fast-printf/basic.xscope :caption: basic.xscope :language: XML XCC recognises files with this suffix. The file is provided to XCC as an argument during building (specifically during the link step if compiling and linking as separate build steps): .. code-block:: bash xcc -target=XCORE-200-EXPLORER basic.xscope mapfile.xc main.c Now run the application using :option:`xrun --xscope` (not :option:`--io ` as previously used): .. code-block:: bash xrun --xscope a.xe The printed output is now produced seemingly instantaneously. Try increasing the value for :samp:`ITERATIONS`. .. important:: Use of XSCOPE on one or more logical cores of a tile results in a single channel end being allocated for use by XSCOPE. .. tip:: Try changing :samp:`ioMode` from :samp:`basic` to :samp:`timed`. This causes the output timestamp to be displayed with the printed data in the console. Note that this also reduces the amount of data that can be buffered at any time. .. warning:: An alternative approach for configuring XSCOPE used the :samp:`xscope_user_init()` function. This approach has since been deprecated. Using XSCOPE "probes" ^^^^^^^^^^^^^^^^^^^^^ As well as using XSCOPE to accelerate literal "printf debugging" as above, XSCOPE "probes" can be used to send named streams of data to the host for debugging purposes. These might be streams of ADC samples, say. The underlying mechanism used for XSCOPE probes is the same as that used by the calls to :samp:`printf()` above. Probes however are even more efficient, as they avoid overheads both in CPU time and data transfer. Probes are added into the XSCOPE config as follows: .. literalinclude:: examples/fast-printf/probes.xscope :caption: probes.xscope :language: XML :emphasize-lines: 2-4 With XSCOPE probes now configured, they can be exploited by adding the highlighted modifications into :file:`main.c`: .. literalinclude:: examples/fast-printf/main.c :caption: main.c :emphasize-lines: 3,12,18,31-32 Build similarly to before: .. code-block:: bash xcc -target=XCORE-200-EXPLORER probes.xscope mapfile.xc main.c This time, when running, add :option:`--xscope-file ` to specify a file to write the probe output into: .. code-block:: bash $ xrun --xscope --xscope-file xscope.vcd a.xe A standard VCD file :file:`xscope.vcd` is produced in the current directory, which can be opened with any 3rd-party VCD viewer. One option is `GTKWave `_. To use :command:`gtkwave` to view the VCD file: .. code-block:: bash $ gtkwave xscope.vcd After 'dragging' the signals into the viewing area, the display might look like this: .. figure:: images/gtkwave.png Installation and use of GTKWave or other VCD viewers is outside the scope of this document. .. note:: XScope tracing as described in this example can be performed :ref:`using XSIM `. Summary ^^^^^^^ You can now use the XScope facility to perform "printf debugging". In fact, this method (using :option:`xrun --xscope`) should always be the preferred approach, instead of the default approach (using :option:`xrun --io`) shown in previous tutorials.