profile (MATLAB Link for Code Composer Studio Development Tools)

MATLAB Link for Code Composer Studio Development Tools

Return code profiling information from executing code with or without DSP/BIOS

Syntax

ps=profile(cc,'option',timeout)
ps=profile(cc,'option')
ps=profile(cc)

Description

ps=profile(cc,'option',timeout) returns generated code profile measurements from the statistics timing objects (STS) that you defined in CCS IDE. Structure ps contains the information in either raw form or filtered and formatted into fields. STS objects are a service provided by the DSP/BIOS real-time kernel that can help you profile and track the way your code runs. For details about STS objects and DSP/BIOS, refer to your Texas Instruments documentation that came with CCS IDE.

To let you to define how to return the information from your STS objects, profile supports three formatting options for the contents of structure ps.

option String
Description

'raw'
Returns an unformatted list of the STS timing objects information. All time-based objects get returned and formatted.

'report'
Returns the same data as the 'raw' option, formatted into an HTML report. Works only on projects that include DSP/BIOS. If you own Embedded Target for TI C6000 DSP, profile(cc,'report') provides more information about code you generate from Simulink models, using data from the STS objects that are part of DSP/BIOS instrumentation. Refer to Profiling Code in your Embedded Target for TI C6000 DSP documentation for more information.

'tic'
Returns a formatted list of the STS timing objects information. Filters out some of the information returned with the 'raw' option. To be returned by this option, the object must be time-based. User-defined objects are not returned. Use raw to see user-defined objects.

option String	Description
'`raw`'	Returns an unformatted list of the STS timing objects information. All time-based objects get returned and formatted.
'`report`'	Returns the same data as the '`raw`' option, formatted into an HTML report. Works only on projects that include DSP/BIOS. If you own Embedded Target for TI C6000 DSP, `profile(cc,'report')` provides more information about code you generate from Simulink models, using data from the STS objects that are part of DSP/BIOS instrumentation. Refer to Profiling Code in your Embedded Target for TI C6000 DSP documentation for more information.
'`tic`'	Returns a formatted list of the STS timing objects information. Filters out some of the information returned with the '`raw`' option. To be returned by this option, the object must be time-based. User-defined objects are not returned. Use `raw` to see user-defined objects.

When you choose 'raw', variable ps contains an undocumented list of the information provided by CCS IDE. The 'tic' option provides the same information in ps, as a collection of fields.

Fields in ps
Description

ps.cpuload
Execution time in percent of total time spent out of the idle task.

ps.sts
Vector of defined STS objects in the project.

ps.sts(n).name
User-defined name for an STS object sts(n). Value for n ranges from 1 to the number of defined STS objects.

ps.sts(n).units
Either `Hi Time' or `Low Time.' Describes the timer applied by this STS object, whether high- or low- resolution time based.

ps,sts(n).max
Maximum measured profile period for sts(n), in seconds.

ps.sts(n).avg
Average measured profile period for sts(n), in seconds.

ps.sts(n).count
Number of STS measurements taken while executing the program.

Fields in ps	Description
`ps.cpuload`	Execution time in percent of total time spent out of the idle task.
`ps.sts`	Vector of defined STS objects in the project.
`ps.sts(n).name`	User-defined name for an STS object `sts(n)`. Value for `n` ranges from 1 to the number of defined STS objects.
`ps.sts(n).units`	Either ``Hi Time`' or ``Low Time`.' Describes the timer applied by this STS object, whether high- or low- resolution time based.
`ps,sts(n).max`	Maximum measured profile period for `sts(n)`, in seconds.
`ps.sts(n).avg`	Average measured profile period for `sts(n)`, in seconds.
`ps.sts(n).count`	Number of STS measurements taken while executing the program.

Note For the information gathered during the reporting periods to be accurate, your CLK and STS must be configured correctly for your target. Use the DSP/BIOS configuration file to add and configure CLK and STS objects for your project.

With projects that you generate that use DSP/BIOS, the report option creates a report that contains all of the information provided by the other options, plus additional data that comes from DSP/BIOS instrumentation in the project. You enable the DSP/BIOS report capability with the Profile performance at atomic subsystem boundaries option on the TI C6000 Code Generation option on the Real-Time Workshop pane of the Simulink Paramters dialog.

ps=profile(cc,'option') defaults to the timeout period specified in the link cc.

ps=profile(cc) returns the profile information in ps as a formatted structure of fields.

Example

Since you use profile to view information about your application running on your target, this example presents both forms of the data returned in ps. Open and build one of the DSP/BIOS-enabled projects from the TI DSP/BIOS Tutorial Module, such as volume.pjt located in the folder ti\tutorial\target\volume2. When you specify the project to open, enter the full pathname to the project file.

cc=ccsdsp;
open(cc,'..\tutorial\sim62xx\volume2\volume.pjt');
build(cc,'all')

In CCS IDE, open the file volume.cdb that contains the DSP/BIOS configuration. For details about STS and CLK objects, refer to your TI documentation.

Review the settings for the existing CLK and STS objects already in place in the project. When you use profile, the information returned comes from these objects. Make any changes you require and save the DSP/BIOS configuration file. Now rebuild your project, either in CCS IDE or from MATLAB, then load the file volume.out generated by the build process. If you get a timeout error, add the timeout option to the build command, specifying a long timeout period, such as 60 seconds. Often, when you receive the timeout error the build has been completed successfully.

build(cc,'all')
load(cc,'..\tutorial\sim62xx\volume2\debug\volume.out')

With the project built and loaded, run your program.

run(cc) % Assumes that volume2 is the active project.

Running profile returns structure ps containing STS and CLK information that DSP/BIOS gathered while your program ran.

ps=profile(cc)

ps = 

    cpuload: 0
        obj: [3x1 struct]

ps.obj(1)

ans = 

     name: 'KNL_swi'
    units: 'Hi Time'
      max: 1.1759e-005
      avg: 2.7597e-006
    count: 29

for k=1:length(ps.obj),disp(k),disp(ps.obj(k)),end;
     1

     name: 'KNL_swi'
    units: 'Hi Time'
      max: 1.1759e-005
      avg: 2.7597e-006
    count: 29

     2

     name: 'processing_SWI'
    units: 'Hi Time'
      max: 1.1489e-005
      avg: 1.1474e-005
    count: 2

     3

     name: 'TSK_idle'
    units: 'Hi Time'
      max: -16.1465
      avg: 0
    count: 0

Omitting the format option caused profile to return the data fully formatted and slightly filtered. Adding the 'raw' option to profile returns the same information without filtering out any of the returned data.

ps=profile(cc,'raw')

ps = 

      cpuload: 0
        error: 0
    avgperiod: 1000
         rate: 1000
          obj: [4x1 struct]

for k=1:length(ps.obj),disp(k),disp(ps.obj(k)),end;
     1

        name: 'KNL_swi'
       units: 'Hi Time'
         max: 1564
       total: 10644
         avg: 367.0345
    pdfactor: 0.0075
       count: 29

     2

        name: 'processing_SWI'
       units: 'Hi Time'
         max: 1528
       total: 3052
         avg: 1526
    pdfactor: 0.0075
       count: 2

     3

        name: 'TSK_idle'
       units: 'Hi Time'
         max: -2.1475e+009
       total: 0
         avg: 0
    pdfactor: 0.0075
       count: 0

     4

        name: 'IDL_busyObj'
       units: 'User Def'
         max: -2.1475e+009
       total: 0
         avg: 0
    pdfactor: 0
       count: 0

Your results can differ from this example depending on your computer and target. In the raw data in this example, one extra timing object appears -- IDL_busyObj. As defined in the .cdb file, this is not a time based object (Units is 'User Def') and is not returned by specifying 'tic' as the format option in profile.

See Also
ccsdsp

open read