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

Loading and Running Programs

Loading Programs

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:lo

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-BF707

Target: ChipFactory Simulator
Platform: ADSP-BF707 Functional-Sim

Target: Blackfin CS Emulator
Platform: ADSP-BF707 via ICE-2000

Target: Blackfin CS Emulator
Platform: 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"

ADSP-SC589 using Functional Simulator

$ CCES_runner.exe \ 
--target "ChipFactory Simulator" \ 
--platform "ADSP-SC589 Functional-Sim" \ 
--processor ADSP-SC589 \ 
--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"

ADSP-SC589 using Cycle-Accurate Simulator

Please note core id starts from zero.

$ 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"

Load Prerequisites

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

Preload Program

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 8 options as follows:

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

Options

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"

--datafile "0,in,input.dat,Floating Point 32 bit,0x001c0c4f,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"

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

Example 3 - Writing Memory to a File When a Specified Breakpoint is Hit

This example reads 1024 memory locations on core 1 starting at stream_output and writes it to a binary file called output.dat on the host. The file is written when the program runs and hits the specified breakpoint symbol 'BP'.

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

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

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 address 0x001c0c4f, main() and adi_intComponents() for a core 0 program:

--breakpoint "0,0x001c0c4f,main,adi_initComponents"

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

target=ADSP-BF5xx Blackfin Family Simulators  
platform=ADSP-BF5xx Single Processor Simulator
processor=ADSP-BF504 
core=0,C:\tmp\bf.dxe
breakpoint=0,main,f1,0xffa00112
datafile=0,out,address-final.dat,Hexadecimal,0xff800598,1,1
datafile=0,out,name-final.dat,Hexadecimal,ga,1,1
datafile=0,out,name-initial.dat,Hexadecimal,ga,1,1,main
datafile=0,out,name-middle.dat,Hexadecimal,ga,1,1,0xffa00112
verbose=2

And specify -@ options.txt on the CCES Runner command line:

$ CCES_Runner.exe -@ options.txt