.. _xrun_manual: XRUN ==== .. program:: xrun Synopsis -------- | :command:`xrun [INQUIRY OPTIONS]` | :command:`xrun [RUN OPTIONS] xe-file` | :command:`xrun [RUN OPTIONS] --args xe-file arg1 arg2 .. argn` Description ----------- The xrun tool has two key roles: * To list the connected USB xtag devices * To load and run :ref:`XMOS Executable (XE)` files on target hardware via a selected USB xtag debugger. xrun is actually a wrapper around the xgdb tool, and is provided to simplify common usage patterns of xgdb. Therefore everything that can be done with xrun can also be done with xgdb (but not the other way round). Options ------- .. option:: --args ... Provides an alternative way of supplying the XE file which also allows command line arguments to be passed to a program. Inquiry options ^^^^^^^^^^^^^^^ The following options may be used without supplying an XE file. The most commonly used is :option:`-l`. .. option:: --list-devices, -l Prints an enumerated list of all JTAG adapters connected to the host and the devices on each JTAG chain. This example shows that there are two xtag devices present: .. code-block:: bash $ xrun -l Available XMOS Devices ---------------------- ID Name Adapter ID Devices -- ---- ---------- ------- 0 XMOS XTAG-3 V0JhnXmh O[0] 1 XMOS XTAG-3 wfF.G58J P[0] The adapters are ordered by their Adapter IDs. .. option:: --list-board-info, -lb Displays information about the connected target board. .. todo:: Find out what this option is for! .. option:: --help Prints a description of the supported command line options. .. option:: --version Displays the version number and copyrights. Run options ^^^^^^^^^^^ If only one xtag device is present, it will is specified implicitly. If more than one device is present, the device must be specified using :option:`--id` or :option:`--adapter-id`. .. option:: --id Specifies the adapter connected to the target hardware. .. option:: --adapter-id Specifies the serial number of the adapter connected to the target hardware. .. option:: --verbose Prints information about the program loaded onto the target devices. .. option:: --jtag-speed Sets the divider for the JTAG clock to ````. If unspecified, the default value is 0. The maximum value is 70. For XMOS-based debug adapters, the JTAG clock speed is set to 25/(*n* +1)MHz. .. option:: --noreset Does not reset the XMOS devices on the JTAG scan chain before loading the program. This is not default. The following options are used to enable debugging capabilities. .. option:: --io Causes xrun to remain attached to the JTAG adapter after loading the program, enabling system calls with the host. xrun terminates when the program calls ``exit``. By default, XRUN disconnects from the JTAG adapter once the program is loaded. .. warning:: The :option:`--xscope` option should be used in preference to the :option:`--io` option. System calls delivered via JTAG are slow and cause all threads on a tile to be paused. Any real-time guarantees in a developer's application will likely be broken. The :option:`--io` option is only used for quick examples or for platforms where the XSCOPE XLINK interface to the XTAG debugger has not been wired. .. option:: --attach Attaches to a JTAG adapter (of a running program), enabling system calls with the host. XRUN terminates when the program performs a call to ``exit``. An XE file must be specified with this option. .. option:: --dump-state Prints the core, register and stack contents of all xCORE Tiles in JTAG scan chain. The following options are used to enable xSCOPE capabilities. .. option:: --xscope Enables an xSCOPE server with the target. .. option:: --xscope-realtime Enables an xSCOPE server with the target using a socket connection. .. option:: --xscope-file Specifies the filename for xSCOPE data collection. .. option:: --xscope-port Specifies the IP address and port for realtime data capture. .. option:: --xscope-limit Specifies the record limit for xSCOPE data collection. .. option:: --xscope-io-only .. todo:: Find difference between this and --xscope option Similar to :option:`--xscope` Examples -------- .. code-block:: bash $ xrun a.xe Asynchronously launch :file:`a.xe` on the single connected target, and return control to the prompt immediately without waiting for the target to exit. .. code-block:: bash $ xrun -l List the available USB xtag devices. .. code-block:: bash $ xrun --adapter-id V0JhnXmh --args a.xe giraffe elephant Asynchronously launch :file:`a.xe` on xtag with Adapter ID of 'V0JhnXmh' with command line arguments.