# FAQ: Using CrossCore Embedded Studio's CCES Runner Utility

Document created by amcl on Aug 5, 2016Last modified by amcl on Nov 24, 2017
Version 10Show Document

## Overview

This document explains how to load and run programs from the command line using CCES Runner. CCES Runner is a command line utility that can be used to help automate tests. For example, ADI's CrossCore Embedded Studio (CCES) Compiler team runs a suite of automated tests that builds their compiler test programs and then uses CCES runner to run those programs on a target to verify the test results.

# Getting Started

## Installing CCES Runner from within CrossCore Embedded Studio (CCES)

### Installation

1. From the Help menu, click "Install New Software…".
2. In the "Work with:" textbox, enter the URL http://www.analog.com/static/ccesupdatesite and hit "Enter".
3. In the generated list below expand "CrossCore Embedded Studio Command Line Utilities" and choose "CCES Runner".
4. Click the "Next" button and then the "Next" button again.
5. Select "I accept the terms of the license agreement" and click "Finish".
6. Click "Yes" for the restart.

Figure 1: Installing CCES Runner

### Updating

1. To update to the latest version of CCES Runner, under the "Help" menu, click "Check for Updates". If any updates are available they will be installed automatically.

Figure 2: Updating CCES Runner

Or by visiting the "Help" menu, choosing About CrossCore Embedded Studio, Installation Details, click on the feature that you would like to update, and choose "Update...". If any updates are available they will be installed automatically.

### Uninstalling

1. Under the "Help" menu, click "About CrossCore Embedded Studio". Click the "Installation Details" button in this window.
2. Under the "Installed Software", select CCES Runner and then the "Uninstall…" button at the bottom.
3. Follow any subsequent prompts and click "Yes" to restart the IDE at the end.

Figure 3: Uninstalling CCES Runner

## Running CCES Runner

Once CCES Runner has been installed, the Runner executable file, CCES_runner.exe, will be located under the CrossCore Embedded Studio (CCES) directory. CCES Runner can be run from any directory but if run outside the CCES home directory, the command option --cceshome must be used to specify the location of CCES.

To run CCES Runner:

1. Open up Command Prompt and navigate to the location of CCES_runner.exe.
2. Type "CCES_runner.exe" followed by the command line options and arguments.

Example:

To display the help text containing all valid options and their arguments:

Figure 4: Example --help command

To run a program, at least these four options must be specified: processor, target, platform, and core. To find the values of these options, the --list option (optional combine with --processor) can be used to list all the possible target and platform values to pass as arguments. Or you can also create a launch configuration in CCES IDE and copy the session configurations into the corresponding command.

Figure 5: Launch configuration in CCES IDE

The following is a brief explanation of the purpose of each command:

Command

Description

Example

processorThe session’s processor. This command must be followed by a string specifying the processor.--processor "ADSP-SC589"
targetThe session’s target. This command must be followed by a string specifying the target.--target "Emulation Debug Target"
platformThe session’s platform. This command must be followed by a string specifying the platform.--platform "ADSP-SC589 via ICE-2000"
coreThe core as well as its prerequisites (programs that initialize memory and/or set up the system) and program to load and run. The core ID, prerequisites, and program must be separated by a comma. The prerequisite options and program must be separated by a vertical bar, “|”.

## List Command

Use the –list option to view all available targets and platforms. Specify the optional processor string to view all available targets and platforms for a specific processor. The results can then be passed to the --target and --platform commands.

Example:

To list all available combination of targets and platforms for ADSP-BF707:

Figure 6: Example --list command

$CCES_runner.exe --list --processor ADSP-BF707Target: ChipFactory SimulatorPlatform: ADSP-BF707 Functional-SimTarget: Blackfin CS EmulatorPlatform: ADSP-BF707 via ICE-2000Target: Blackfin CS EmulatorPlatform: ADSP-BF707 via ICE-1000 ## Example command lines to run ADSP-SC589 program(s) ADSP-SC589 using ICE-2000 $ CCES_runner.exe \  --target "Emulation Debug Target" \  --platform "ADSP-SC589 via ICE-2000" \  --processor ADSP-SC589 \  --core "0,C:\Users\workspace\cces\2.7.0\test_Core0\Debug\test_Core0" \  --core "1,C:\Users\workspace\cces\2.7.0\test_Core1\Debug\test_Core1.dxe" \  --core "2,C:\Users\workspace\cces\2.7.0\test_Core2\Debug\test_Core2.dxe"

Note that the core Ids when using the Functional Simulator are 0 and 1.

$CCES_runner.exe \ --target "ChipFactory Simulator" \ --platform "ADSP-SC589 Functional-Sim" \ --processor ADSP-SC589 \ --core "0,C:\Users\workspace\cces\2.7.0\test_Core1\Debug\test_Core1.dxe" \ --core "1,C:\Users\workspace\cces\2.7.0\test_Core2\Debug\test_Core2.dxe" ADSP-SC589 using Cycle-Accurate Simulator Note that the core Id when using the Cycle-Accurate Simulator is 0. $ CCES_runner.exe \  --target "ChipFactory Simulator" \  --platform "ADSP-SC589 Cycle-Accurate-Sim" \  --processor ADSP-SC589 \  --core "0,C:\Users\workspace\cces\2.7.0\test_Core1\Debug\test_Core1.dxe"

As mentioned in the description of the core command, load prerequisites can be specified to be loaded prior to loading the user program. A load prerequisite consists of a DXE file and possible options for that session. Below is a table containing available load prerequisite options:

### Options

Option

Description

SIMThe prerequisite is valid only when connected to a simulator session
EMUThe prerequisite is valid only when connected to an emulator session
KITThe prerequisite is valid only when connected to an EZ-KIT Lite session
ANYThe prerequisite is valid when connected to any type of session
CLEAR_SYMBOLSThe currently loaded symbols will be cleared before the next program is loaded
SYMBOLS_ONLYOnly the prerequisite program's symbols will be loaded.  No code/data will be loaded.
NO_RESET_BEFORE_LOADThe core will not be reset before the prerequisite program is loaded.  If this option is not specified, the core will be reset before the load.
RUN_AFTER_LOADA temporary breakpoint will be set at the prerequisite program's ___lib_prog_term label and the program will be run to that breakpoint.

To specify a prerequisite program, a path that points to the DXE file relative to the CCES installation directory is necessary.
For example, Blackfin\Examples\drivers\flash\BF506F\bf506f_flash.dxe.

### Simplification

If prerequisite options are not explicitly specified when using the core command, CCES Runner will see if default preloads are available and load them automatically.

Example:

When running an ADSP-SC589 Core 0 project:

--core "0,C:\workspace\ADSP-SC589_Core0\Debug\ADSP-SC589_Core0"

This command would also load the prerequisite program to set up clocks and DMC settings, so that the debugger is able to load the user’s application to external memory, as

--core "0,EMU|KIT|CLEAR_SYMBOLS|RUN_AFTER_LOAD|SHARC\ldr\ezkitSC589_preload_core0_v01,        C:\workspace\ADSP-SC589_Core0\Debug\ADSP-SC589_Core0"

## Reading From and Writing Data To Files and Memory

The --datafile option can be used to initialize memory from data stored in a file on the host as well as save data from memory back to a host file. The argument to --datafile is a comma separated string with 7 options as follows:

--datafile "<core>,<direction>,<filename>,<format>,<symbol>,<length>,<stride>"

### Options

ArgumentDescription
coreThe zero based core id to read data from or write data to
direction

One of two values:

in - to specify that data should be loaded from a file and written to target memory after the application is loaded but before it is executed

out - to specify that data should be read from target memory and written to a file upon termination of the application

filenameThe path and filename of the file on the host to read from or write to
format

binary or binary:le - Specifies a binary file in little-endian format

binary:be - Specifies a binary file in big-endian format

<other> - Specifies a text file format from those listed via the --list-memformats option

symbolA global symbol in your application for the specified core to which data will be read from or written to
lengthThe number of values to read from or write to the file
strideThe stride value to use when reading from or writing to memory. A stride of 1 will use every value while 2 will use every other value and so on.

### Example 1 - Writing a File to Memory

This example reads 4096 values of data from a text file called input.dat which contains floating point formatted numbers on each line and writes it to core 0 memory starting at the address specified by stream_input before the application is run.

--datafile "0,in,input.dat,Floating Point 32 bit,stream_input,4096,1"

### Example 2 - Writing Memory to a File

This example reads 1024 memory locations on core 0 starting at stream_output and writes it to a binary file called output.dat on the host. The file is written when the applications main() routine terminates.

--datafile "0,out,output.dat,binary,stream_output,1024,1"

### Listing Valid Memory Formats

Since different processor types have different file formats that they understand the list can vary from part to part. To see the list of valid --datafile <format> options you can use the --list-memformats option in conjunction with a chosen target, platform and processor. This option takes a single parameter called <core> which specifies the zero based core in the processor for which to list formats.

\$ cces_runner.exe \  --target "Sharc Emulators/EZ-KIT Lites" \  --platform "ADSP-21489 via ICE-2000" \  --processor "ADSP-21489" \  --list-memformats 0  32 Bit Hexadecimal  Binary  Floating Point 32 bit  Floating Point 40 bit  Hexadecimal  Octal  Signed Fractional  Signed Integer  Unsigned Fractional  Unsigned Integer

## Setting Breakpoints

The --breakpoint option can be used to set a breakpoint at the specified. One breakpoint option can be used per core but multiple breakpoints can be set in one breakpoint option.

Example:

To set a breakpoint at main() and adi_intComponents() for a core 0 program:

--breakpoint "0,main,adi_initComponents"

## Profile-Guided Optimization (PGO)

The --pgo command can be used to collect PGO output data in a specified file. Simulator only.

Example:

--pgo "C:\CCESWorkspace\ADSP-BF533\Debug\ADSP-BF533.pgo"

Note:

CrossCore® Embedded Studio 2.7.0 > SHARC® Development Tools Documentation > C/C++ Compiler Manual for SHARC® Processors > Optimal Performance from C/C++ Source Code > Analyzing Your Application

## Debug Session Preferences

The --preferences command can be used to set preferences for your CCES Runner debug session. The --preferences command takes a white space delineated list of preferences with optional values.

Example:

To increase the JTAG frequency to 46Mhz when loading and running program(s) using an ICE-2000, add the following command to your CCES Runner command line: --preferences "jtagfrequency=46"