Embedded IDE Link™ CC

list - Information listings from CCS

Syntax

list(ff,varname)
infolist = list(cc,'type')
infolist = list(cc,'type',typename)

Description

list(ff,varname) lists the local variables associated with the function accessed by function object ff. Compare to list(cc,'variable','varname') which works the same way to return variables from ticcs object cc.

Note   list does not recognize or return information about variables that you declare in your code but that are not used or initialized.

Some restrictions apply when you use list with function objects. list generates an error in the following circumstances:

• When varname is not a valid input argument for the function accessed by ff

  For example, if your function declaration is

  int foo(int a)
  

  but you request information about input argument b, which is not defined

  list(ff,'b')
  

  MATLAB^® software returns an error.

• When varname is the same as a variable assigned by MATLAB software. Usually this happens when you use declare to pass a function declaration to MATLAB software and the declaration string does not match the declaration for ff as determined when you created ff.

  In an example that demonstrates this problem, the function declaration has a name for the first input, a. In the declare call, the declaration string does not provide a name for the first input, just a data type, int. When you issue the declare call, MATLAB software names the first input ML_Input1. If you try to use list to get information about the input named ML_Input, list returns an error. Here is the code, starting with the function declaration in your code:

  int foo(int a)  % Function declaration in your source code
  declare(ff,'decl','int foo(int)')
  % MATLAB generates a warning that it has assigned the name 
  % ML_Input to the first input argument
  list(ff,'ML_Input') % list returns an error for this call
  

• When varname does not match the input name in the function declaration provided in your source code, as compared to the declaration string you used in a declare operation.

  Assume your source code includes a function declaration for foo:

  int foo(int a);
  

  Now pass a declaration for foo to MATLAB software:

  declare(ff,'decl','int foo(int b)')
  

  MATLAB software issues a warning that the input names do not match. When you use list on the input argument b,

  list(ff,'b')
  

  list returns an error.

• When varname is an input to a library function. list always fails in this case. It does not matter whether you use declare to provide the declaration string for the library function.

Note   When you call list for a variable in a function object  list(ff,varname)the address field may contain an incorrect address if the program counter is not within the scope of the function that includes varname when you call list.

infolist = list(cc,type) reads information about your CCS session and returns it in infolist. Different types of information and return formats apply depending on the input arguments you supply to the list function call. The type argument specifies which information listing to return. To determine the information that list returns, use one of the following as the type parameter string:

• project — Tell list to return information about the current project in CCS.

• variable — Tell list to return information about one or more embedded variables.

• globalvar — Tell list to return information about one or more global embedded variables.

• function — Tell list to return details about one or more functions in your project.

• type — Tell list to return information about one or more defined data types, including struct, enum, and union. ANSI^® C data type typedefs are excluded from the list of data types.

Note, the list function returns dynamic CCS information that can be altered by the user. Returned listings represent snapshots of the current CCS configuration only. Be aware that earlier copies of infolist might contain stale information.

Also, list may report incorrect information when you make changes to variables from MATLAB software. To report variable information, list uses the CCS API, which only knows about variables in CCS. Your changes from MATLAB software, such as changing the data type of a variable, do not appear through the API and list. For example, the following operations return incorrect or old data information from list.

Suppose your original prototype is

unsigned short tgtFunction7(signed short signedShortArray1[]);

After creating the function object fcnObj, perform a declare operation with this string to change the declaration:

unsigned short tgtFunction7(unsigned short signedShortArray1[]);

Now try using list to return information about signedShortArray1.

list(fcnObj,'signedShortArray1')

 address: [3442 1]
location: [1x66 char]
    size: 1
    type: 'short *'
 bitsize: 16
 reftype: 'short'
  referent: [1x1 struct]
member_pts_to_same_struct: 0
      name: 'signedShortArray1'

The type field reports the original data type short.

You get this is because list uses the CCS API to query information about any particular variable. As far as the API is concerned, the first input variable is a short*. Changing the declaration does not change anything.

infolist = list(cc,'project') returns a vector of structures containing project information in the format shown here when you specify option type as project.

infolist = list(cc,'variable') returns a structure of structures that contains information on all local variables within scope. The list also includes information on all global variables. Note, however, that if a local variable has the same symbol name as a global variable, list returns the information about the local variable.

infolist = list(cc,'variable',varname) returns information about the specified variable varname.

infolist = list(cc,'variable',varnamelist) returns information about variables in a list specified by varnamelist. The information returned in each structure follows the format below when you specify option type as variable:

list uses the variable name as the field name to refer to the structure information for the variable.

infolist = list(cc,'globalvar') returns a structure that contains information on all global variables.

infolist = list(cc,'globalvar',varname) returns a structure that contains information on the specified global variable.

infolist = list(cc,'globalvar',varnamelist) returns a structure that contains information on global variables in the list. The returned information follows the same format as the syntax infolist = list(cc,'variable',...).

infolist = list(cc,'function') returns a structure that contains information on all functions in the embedded program.

infolist = list(cc,'function',functionname) returns a structure that contains information on the specified function functionname.

infolist = list(cc,'function',functionnamelist) returns a structure that contains information on the specified functions in functionnamelist. The returned information follows the format below when you specify option type as function:

To refer to the function structure information, list uses the function name as the field name.

infolist = list(cc,'type') returns a structure that contains information on all defined data types in the embedded program. This method includes struct, enum and union data types and excludes typedefs. The name of a defined type is its ANSI C struct tag, enum tag or union tag. If the ANSI C tag is not defined, it is referred to by the CCS compiler as '$faken' where n is an assigned number.

infolist = list(cc,'type',typename) returns a structure that contains information on the specified defined data type.

infolist = list(cc,'type',typenamelist) returns a structure that contains information on the specified defined data types in the list. The returned information follows the format below when you specify option type as type:

For the field name, list uses the type name to refer to the type structure information.

The following list provides important information about variable and field names:

• When a variable name, type name, or function name is not a valid MATLAB software structure field name, list replaces or modifies the name so it becomes valid.

• In field names that contain the invalid dollar character $, list replaces the $ with DOLLAR.

• Changing the MATLAB software field name does not change the name of the embedded symbol or type.

Examples

This first example shows list used with a variable, providing information about the variable varname. Notice that the invalid field name _with_underscore gets changed to Q_with_underscore. To make the invalid name valid, list inserts the character Q before the name.

varname1 = '_with_underscore'; % invalid fieldname
list(cc,'variable',varname1);
ans =

    Q_with_underscore : [varinfo]
ans. Q_with_underscore 
ans=

       name: '_with_underscore'
   isglobal: 0
   location: [1x62 char]
       size: 1
     uclass: 'numeric'
       type: 'int' 
    bitsize: 16 

To demonstrate using list with a defined C type, variable typename1 includes the type argument. Because valid field names cannot contain the $ character, list changes the $ to DOLLAR.

typename1 = '$fake3'; % name of defined C type with no tag 
list(cc,'type',typename1);            
ans =

       DOLLARfake0 : [typeinfo]    

ans.DOLLARfake0=
                 
        type: 'struct $fake0'       
        size: 1     
      uclass: 'structure'     
      sizeof: 1    
     members: [1x1 struct]

When you request information about a project in CCS, you see a listing like the following that includes structures containing details about your project.

projectinfo=list(cc,'project')

projectinfo = 

          name: 'D:\Work\c6711dskafxr_c6000_rtw\c6711dskafxr.pjt'
          type: 'project'
    targettype: 'TMS320C67XX'
      srcfiles: [69x1 struct]
      buildcfg: [3x1 struct]

See Also

info

iswritable

load