< JavaScript example that functions as a command-line loader which can load/run an executable .out file on TI targets. Any C I/O standard output can be sent to the console and scripting logs. It can also perform basic benchmarking of the application. The lack of GUI dependency and ease of use make it an attractive automation tool, useful for quick sanity tests and batch regressions. **loadti** works with any TI target supported by the CCS debugger.
Some basic supported functionality includes:
- C I/O standard output can be sent to the console and scripting logs
- Generate detailed executions logs
- Perform basic application benchmarking (using profile clock)
- Pass arguments to **main()**
- Loading/saving data from host to target memory (and vice versa)
- Resetting the target
<iframe width="854" height="480" src="https://www.youtube.com/embed/sYo1z2oW2Fw" frameborder="0" allowfullscreen></iframe>
Refer to the loadti <tt>readme.txt</tt> and console help for a full list of supported features.
loadti is delivered with the default installation of DSS. The loadti documentation (<tt>readme.txt</tt>) is found in the root loadti directory (See the next section for the directory location).
## Environment Setup
To enable the ability to run loadti from any location, it is recommended to add the below directory to your system PATH:
```bat
set PATH=%PATH%;"<INSTALL PATH>\ccsv[x]\scripting\examples\loadti";
```
The above can be typed in manually after opening a command window, or stored in a batch file to run when opening a command window, or simply added permanently to the system PATH in Windows.
Once the location of loadti is added to the system PATH, it can be called from anywhere.
## Using loadti
Usage:
```text
loadti [OPTION]... [OUT_FILE] [ARGUMENT]...
```
Example: The below command will use loadti to configure the debug server for the target specified in the [target configuration file](./users_guide/ccs_debug-main.html#target-configuration-files) (mytarget.ccxml), load an application (myapp.out), pass two arguments to main (arg1, arg2), run the application to completion, and generate a DSS log file (mylog.xml):
```text
loadti -c C:\myproject\mytarget.ccxml -x C:\myproject\mylog.xml C:\myproject\myapp.out arg1 arg2
```
To get a list of all the supported options with loadti, simply bring up the command line help:
```text
loadti -h
```
### loadti Help Output
```text
Usage: loadti [OPTION]... [OUT_FILE1[+OUT_FILE2]...] [ARGUMENT]...
Load OUT_FILE executable(s) to TI target and run, passing ARGUMENT(s) to main.
Mandatory arguments to long options are mandatory for short options too.
Options:
-a, --async-run
-b, --init-bss-section[=VALUE]
-c, --cfg-file=CONFIG_FILE
-cpu, --cpu-name=CPU_NAME
-h, --help
-l, --load
-mlr, --mem-load-raw="PAGE,ADDR,FILE,TYPE_SIZE,BYTE_SWAP"
-mld, --mem-load-dat="PAGE,ADDR,FILE,LEN"
-msr, --mem-save-raw="PAGE,ADDR,FILE,LEN,TYPE_SIZE,BYTE_SWAP"
-msd, --mem-save-dat="PAGE,ADDR,FILE,LEN,IO_FORMAT,APPEND"
-n, --no-profile
-q, --quiet
-r, --reset
-s, --stdout-file=FILE
-t, --timeout=VALUE
-v, --verbose
-x, --xml-log=FILE
-@, --options-file=FILE
```
## Known Limitations
- loadti can only connect to one CPU at a time. For multi-core environments, use the <tt>-cpu</tt> option to specify the CPU/core to connect to (check the name of the CPU/core in the [target configuration file](./users_guide/ccs_debug-main.html#target-configuration-files)). If a CPU/core name is not specified, the default behavior is to use the first CPU/core detected in the JTAG scan chain
- Unless the asynchronous run (<tt>-a</tt>) option used, loadti will wait until program execution is completed (hits the program exit breakpoint) or, if the run timeout option is specified (<tt>-t</tt>), if the run timeout occurs. If none of these events occur, loadti will not return from execution. Note that is some cases, loadti may not halt even if an exit point is reached (see the section below for using loadti with MSP430 devices)
- When running loadti with the asynchronous (<tt>-a</tt>) option, profiling information (cycle counts) will not be collected
- loadti relies on the existance of a dedicated HW profile clock to provide cycle counts. Not all devices support a dedicated profile clock (such as Cortex-M). In those cases, loadti will not be able to provide cycle counts
### Using loadti with MSP430
Unless the asynchronous run (<tt>-a</tt>) option used, loadti will wait until program execution is completed (hits the program exit breakpoint) or, if the run timeout option is specified (<tt>-t</tt>), if the run timeout occurs. However there are instances where a breakpoint is not set on the program exit point, often on devices where the program is running from persistent memory like on an MSP430. This is to conserve the limited number of hardware breakpoints available for debug. In these cases, when using loadti, the user may notice that loadti never seems to finish executing when a synchronous run is done without a timeout specified. This is because when the exit point of the application is reached, execution does not halt. To avoid this from occurring, either:
- Use the <tt>-a</tt> option to do an asynchronous run, keeping in mind that loadti may "finish" before program execution is done. Note that an asynchronous run will not output any profiling (cycle count) information
- Use the <tt>-t</tt> option to set the run timeout
- Change the default debugger settings to set a breakpoint at the program exit point
- Modify loadti to add a breakpoint at the program exit point (can set a breakpoint at the exit point label)
## Customizing loadti
loadti is a DSS JavaScript example. loadti can be used right out of the box *as-is* or it can be customized to add more options and functionality. All the files needed to extend loadti functionality is provided within the loadti example folder. The main loadti scripts are straight JavaScript. With a cursory knowledge of Javascript and DSS, customizing loadti will not be difficult. When modifying the loadti scripts, the main files of interest is:
- **getArgs.js**: This script has the list of command line options. Add to this script to add additional command-line options.
- **main.js**: This script has the main functionality of loadti. Add to this script to add additional functionality to loadti. This includes adding the functionality for the additional command-line options specified in getArgs.js
Please see the [Debug Server Scripting](./users_guide/sdto_dss_handbook.html) documentation for more information on DSS and where to find the full DSS API documentation.
### Debugging Your Changes to loadti
Because loadti is a DSS JavaScript, [the Rhino Debugger delivered with DSS can be used to debug loadti](./users_guide/sdto_dss_handbook.html#debugging-your-javascript).
<!-- End of markdown source -->
<div id="footer"></div>
]]>