Ctprof Users Guide

Introduction

Ctprof (cTools Profile) is a client/server based utility that provides multiple bus profile use cases.

Operations

The server (ctprof_srv) is a Linux user space application that must be started before the any commands are executed by the client (ctprof). The server can be started one of three ways:

• Using ctprof_sync.sh (a bash shell script) to synchronize the server state with execution of your application. Typically used to profile across an entire application. Requires no application integration with ctprof_srv state (the script takes case of that).
• Using ctprof_srv in pipe mode. Pipe mode allows application specific synchronization with ctprof_srv, but requires some minor application integration.
• Using ctprof_srv with no state synchronization with the application.

See the ctprof_srv User's Guide section for details.

ctprof User's Guide

ctprof usaage

ctprof [-options] command [operand …]

ctprof output

If --output/-o is not used to select an output file for the profile data, the profile data will be exported to stdout. All error messages are exported to stderr. All message output from options (such as --help, --version, --list, --output) are exported vis stdout.

ctprof Global Options

Global options can be used with any combination of use case commands and options.

--buffer-mode <mode>

Where mode is:

circular(default) - Profile data collection buffer is setup for circular operation. When the recording session is terminated the data will be retrieved and transported to the host for formatting.

fixed - Profile data collection buffer is setup for one-time fixed operation (fill and done). When the recording session is terminated the data will be retrieved and transported to the host for formatting.

--connect <server:x.x.x.x[:port]>

In the “server:x.x.x.x[:port]” case the etb is the default collection buffer for profile data.

Note: This option is mandatory except where --help and/or --version are used. It has no default.

--csv-semicolon

Change the character used to delimit values in the csv file from a comma to a semicolon. Use of this option is only valid with “--format csv”. If used with other format options an error will be sent to stderr and the utility exited.

--device <name>

This option allows the user to provide a required device name.

Note: This option is mandatory except where --help and/or --version are used. It has no default.

--duration -D <milliseconds>

Set the profile collection duration time (from --start-delay) for all use cases in milliseconds. This is an optional parameter whose default is infinity (0).

--fclk <value>

Set the device's functional clock rate in Mhz. The default value is 1000.

--format -f <type>

Define the format operation for sampled data, where type is:

csv(default) - Generate a csv file where strings are in quotes and values are not. The default delimiter is ‘,’.

tdf - Generate a tdf file that can be imported into CCS for data display.

gnuplot - Generate two files, a gnuplot command file (outfile.gnuplot_cmd) and a data file (outfile.gnuplot_csv) compatible with gnuplot. ctprof will automatically launch gnuplot. The gnuplot command file references the data file, so a user can manually start gnuplot with "gnuplot outfile.gnuplot_cmd".

--help –h

Display help and terminate. Default operation is to export to stdout a brief usage for each option, command and required operands.

--list <probes|masters>

Provides a list of probes or masters for the selected device. If a device is not selected an error is generated.

--log-level -l <level>

Generate a ctprof_log.txt file and save it to the current directory. If the file already exists it will be over written with the new file, thus it’s the users responsibility to rename the file to save it.

Where level is:

0 – Provides basic logging appropriate for most users. The log file will contain all input parameters (read from ctprof.rc file, the command line, and stdin if used) and then all default parameters. Any command output to stdout or stderr will also be logged.

1 – Provide level 0 plus internal function call log.

2 – Provide Level 0 and Level 1 plus internal function logging

By default --logfile is disabled.

--op-mode <mode>

This option is used to modify the operation mode.

Where mode is:

time(default) – Use --start_delay and --duration to frame data acquisition from the CP Tracers. The recording session will start after –start_delay time and stop after –duration time.

signal – Use user-defined signals (SIGUSR1 and SIGUSR2) to start and stop CP Tracer data export. Start and Stop signals can be used only once. If used more than once only the last data will be provided. SIGINT (CNTL-C) will terminate the recording session.

trigger – CP Tracer probes are set to enable EMU0/1 input triggers. CP Tracer data generation starts with an EMU0 trigger and terminates with an EMU1 trigger. The --duration and --start_delay options can also be utilize to frame the recording session (see time option).

Note: the trigger mode is limited to TCI6614/12 and C66AK2Hxx devices (when supported by ctprof).

--output -o <filename>

Define filename for formatted output. If no filename is specified then stdout is used to export formatted data. The utility will apply the appropriate filename extension (.csv,.tdf, .data.gnuplot and .cmd.gnuplot ) depending on the format. When ctprof writes the profile data to a file, it also exports a message to stdout indicating new files are ready:

New gnuplot command file available is l2.gnuplot_cmd
New gnuplot data file available is l2.gnuplot_csv

--quiet –q

Suppress all stdout messages.

--start-delay <milliseconds>

Set profile data generation start delay for all use cases in milliseconds. This is an optional parameter whose default is zero.

--version -V

Export the version to stdout.

If --connect option not used then just the version of the ctprof client is provided:

./ctprof client version 1.0
Copyright (C) 2013 Texas Instruments, Inc.
Exiting ./ctprof

If --connect used then both the ctprof client and server versions are provided (assuming the server is running):

./ctprof client version 1.0
Copyright (C) 2013 Texas Instruments, Inc.
server version 1.1
Copyright (C) 2013 Texas Instruments, Inc.
Exiting ./ctprof

ctprof Use Case Commands

Use case commands can be used in combination with filter options to provide additional resolution in the profile data. By default all filtering is disabled. Filtering options includes master, source, address range, and direction (rd/wr). See the ctprof Use Case Options section for details.

Valid bus profile use-case commands are:

bw <probe list>

Bandwidth profile of multiple slaves:

• Provides bus throughput in MB/s for the selected probes with all masters filtered (enabled).

lp <probe list>

Latency profile of multiple slaves:

• Provides profile of bus latency for the selected probes with all masters filtered (enabled).

tp <probe>

Total profile of a single slave:

• Provides total profile of a selected master compared against all other masters.
• Requires a master to be selected with --master option.
• Data provided by the use-case is:
  • Bus bandwidth utilized by selected maters in MB/s.
  • Bus bandwidth utilized by all masters in MB/s.
  • Average access size for all masters.
  • Bus utilization in millions of transactions/s for all masters.
  • Bus contention % (wait time/sample period) for all masters.
  • Average latency for all masters.

mp <probe>

Master profile of a single slave:

• Provides total profile of a selected master compared to a second masters.
• Requires two masters to be selected with --master.
• Data provided by the use-case is:
  • Bus bandwidth utilized in MB/s for the two masters selected
  • Bus utilization in millions of transactions/s for all masters.
  • Bus contention % (wait time/sample period) for all masters.
  • Average latency for all masters.

nre <probe>

New-request-event for a single slave:

• Provides logging of new request events (both read and write).
• Events can be filtered.
• Data provides Master ID, XID, R/W and 10 bits of the address.
• Gnuplot format option can not be used to display "nre" data.

Probe selection defines the slave bus to profile. Probe selection is mandatory with no default value. The probes available are device specific. Probe selections for the tci6614 and tci6612 are:

MSMC_n (where n is in the range of 0 to 3)

QM_M

DDR

SM

QM_CFG

CFG

L2_n (where n is 0 to the maximum number of DSP cores in the device)

RAC

RAC_CFG

TAC

SCR_6P_A

DDR_2

To get a list of probes for your specific device (note the server must be running on the target):

ctprof --connect server:x.x.x.x --device tci6614 --list probes

Note - Multiple event use-case with different probe types can be enabled at the same time, although this is not recommended due to the high probability of STM message overflow.

ctprof Use Case Options

Use case options are applied to a command.

--dir <select>

Bus direction (read or write) selection (optional). Where select is:

rd

wr

rw (default)

--exclude-src -e <select>

Source exclusion selection (optional). Where select is:

cpu-inst

cpu-data

edma

none (default)

This option may be utilized multiple times to exclude more than one source. By default all sources are included.

Note – source exclusion is only valid for MSMC and the DDR probes. For all other probes the source qualifier input is tied off to the edma value, thus if you exclude the edma, the probe will not export any data. An error message is sent to stderr if --exclude is applied to a probe that does not support it.

--master -m <select>

Master filter selection. Where <select> is one of the following (the following apply to TCI6614 and TCI6612):

DSPn

ARM_64

DSPn_CFG

EDMA0_TCO_RD

EDMA0_TCO_WR

EDMA0_TC1_RD

EDMA0_TC1_WR

EDMA1_TCO_RD

EDMA1_TCO_WR

EDMA1_TC1_RD

EDMA1_TC1_WR

EDMA1_TC2_RD

EDMA1_TC2_WR

EDMA1_TC3_RD

EDMA1_TC3_WR

EDMA2_TCO_RD

EDMA2_TCO_WR

EDMA2_TC1_RD

EDMA2_TC1_WR

EDMA2_TC2_RD

EDMA2_TC2_WR

EDMA2_TC3_RD

EDMA2_TC3_WR

SRIO_CPPI_n (where n is 0 or 1)

DAP

TPCCn (where n is 0 to 2)

MSMC

PCIE

SRIO_M

HYPERBRIDGE

PA_SS_n (where n is 0 to 3)

AIF_n (where n is 0 to 7)

QM_CDMA_n (where n is 0 to 3)

QM_SECOND_n (where n is 0 or 1)

TAC

BCP_DIOn (where n is 0 or 1)

BCP_CDMA

ARM_128_0

To get a list of masters for your device (note the server must be running on the target)

ctprof --connect server:x.x.x.x --device tci6614 --list masters

For the bw and la use case, all masters are selected by default. For the tp and nre use cases, a minimum of one master must be selected or an error will be generated and the utility terminated. Multiple masters may be selected for both the tp and nre use case. In the case of the mp use case two masters must be selected. If more than or less than two masters are provided an error will be generated.

--sample-rate -s <milliseconds>

Set the rate at which probe data is sampled in milliseconds. This is an optional parameter with a default value of .200. Value may be provided as a float for microseconds (so .200 is 200 microseconds).

--range-msb –R <value>

Optional MSB selection for address filtering, where value is the MSBs (>bit 32) of the address filter range (default is 0).

--start-range <address1>

--end-range <address2>

Optional address range selection for starting and ending probe address filter where address1 defines the start of the address range and address2 defines the end of address range. Since some probes support addresses greater than 32 bits, --range-msb may be used to define address values greater than 32-bits for the --start-range and --end-range options. Address filtering remains disabled until a valid range is set. If address2 is less than or equal to address1 the utility will terminate with an error.

--exclusive -e

Change the address filter mode from the default (inclusive) to exclusive.

--event-addr-bits -b <value>

Provides a 6-bit value for the nre use case that defines the LSbit of the 10 address bits that are logged.

0 - bits 9:0 are exported

1 - bits 10:1 are exported

...

37 - bits 46:37 are exported

If a value greater than 54 used the utility will exit with an error.

Warnings/Errors

ctprof: Fatal Error: : Can not open socket to server

Typically this means the server(ctprof_srv) is not running on the target.

Warning - trace buffer wrapped. Trace will show last data collected only.

The collection buffer will wrap if --sample-rate is set low enough and --duration is set high enough, leaving only the most recent data collected in the buffer at the end of the duration period. For example, using the following ctprof command with the ctprof_ex

On the target:

ctprof_sync.sh ctprof_ex

On the host:

./ctprof --connect server:x.x.x.x --device tci6614 --duration 60 --sample-rate .1 --format gnuplot bw l2_0 l2_1 l2_2 l2_3 -o l2
Warning - trace buffer wrapped. Trace will show last data collected only.

Profile Buffer Wrap Example

Profile No Buffer Wrap Example

The result in the first gnuplot graph to the left shows samples from time 0, when in reality the samples are from the end of the duration period. In this case the last ~40 milliseconds of the 60 millisecond profile duration. If --sample-rate is changed to .2, as shown in the second graph, then the buffer does not wrap and the data at 0 corresponds to the beginning of the 60 millisecond --duration period.

ctprof_srv User's Guide

ctprof_srv Usage

ctprof_srv [hlpPqv]

ctprof_srv Options

--help/-h :Export help to stdout.

--logging/-l <level>

Enable logging to ctprof_srv_log.txt.

Level 0 - User information logging

Level 1 - Debug logging

--port/-p <ip port>

Set ip port value.

--pipe/-P

Issue server recording state over a named pipe

--quiet/-q

Send stdout to /dev/null

--terminate/-t

Terminate server on disconnect from client

--version/-v

Export version to stdout.

ctprof_srv Startup Methods

script:ctprof_sync.sh app[app_options]

• ctprof_sync.sh is a bash shell script that is utilized to synchronize the server state with execution of your application.
• When you execute "ctprof_sync.sh app [app_options]" once the server is ready to accept client commands, it prints the message:

Ready for client commands

• When the client command completes processing the script terminates ctprof_srv.
• Also see ctprof_sync.sh example.

ctprof &

• Run the server in the background allowing multiple client commands to be issued.
• No synchronization with the target system is provided using this method.

ctprof -P &

• Enables pipe mode. Pipe mode allows application specific synchronization with the ctprof_srv.
• Requires some minor application integration (see ctprof_srv Pipe Mode).
• Once started, multiple ctprof client command/application execution sessions can be executed without restarting the server.
• Also see ctprof_srv with pipes example.

ctprof_srv Pipe Mode

• The ctprof_utility.c/.h is provided with the ctprof_ex source that can be integrated with your application to synchronize the server state with your application. See ctprof_srv source installation instructions for details.
• A named pipe (ctprof_fifo) is used that exports server status.
• ctprof_srv status strings are:
  • "ctprof recording\n"
  • "ctprof stopped__\n"
  • "ctprof ready____\n"

Note: ctprof_srv will export it's binary pid (whose size is sizeof(pid_t)) to the pipe when a client connect is detected by the server, prior to exporting any status messages.

ctprof_srv Pipe Operation

Your application must be running and the pipe(ctprof_fifo) open for reading before the client(ctprof) can issue a command to the server(ctprof_srv). If you get this sequence out of order and you get the following message:

ctprof_srv:Opening pipe for writing. Waiting on pipe to be open for reading.

Simply run the application that opens the pipe for reading. The client operation will be processed by the server.

If you get the following error message (or one similar to):

ctprof_srv:warning - pipe reading end closed when sending ready status.
ctprof_srv:  This can be caused by issuing a client operation before
ctprof_srv:  starting the task that opens the pipe's reading end OR
ctprof_srv:  early termination of the task that opens the pipe's reading end.
ctprof_srv:Opening pipe for writing. Waiting on pipe to be open for reading.

In this case you must kill the current client operation and then run the application that opens the pipe before you retry the client operation.