MATLAB Link for Code Composer Studio Development Tools

Working with Embedded Objects

Having direct access to the memory on your target DSP, as provided by the links in MATLAB Link for Code Composer Studio, can be a powerful tool for helping you develop and troubleshoot your digital signal processing applications. But for programming in C, it is perhaps more valuable to be able to work with memory and data in ways that are consistent with the C variables embedded in your programs.

MATLAB Link for Code Composer Studio implements just this sort of access and manipulation capability by using MATLAB objects (called embedded objects in this guide) that access and represent variables and data embedded in your project. Various functions that compose the MATLAB Link for Code Composer Studio, such as createobj, convert, and write, help you create the embedded objects you use to work with your data in DSP memory and registers, and let you manipulate the data in MATLAB and in your code.

This portion of the tutorial introduces some of the functions and how to use them to access and manipulate them.

Function list generates a lot of information for you about an embedded variable in the symbol table. An even more useful function is createobj that creates a MATLAB object that represents a C variable in the symbol table in CCS. Working with the object that createobj returns, you can read the entire contents of a variable, or one or more elements of the variable when the variable is an array or structure.

From the beginning of this tutorial you have used the link object cc with all of the functions. cc represents the path to communicate with a particular processor in CCS. For the remainder of this tutorial you work with a variety of functions that use, not the link object cc, but other objects such as numeric or structure objects, that represent embedded objects in CCS. All of these new functions use the object names (handles) as the first input argument to the function ( in just the way you used cc). When you create the object cvar in step 4 that follows, cvar represents the embedded variable idat.

To begin, restart the program and use list to get some information about a variable (an embedded object) in Code Composer Studio.

Using list

1. To restart the program in CCS, enter

• restart(cc)
  

1. This resets the program counter to the beginning of your program.

2. To move the program counter (PC) to the beginning of main, which you should do before rerunning your program, enter

• goto(cc,'main')
  

1. Moving the PC to main ensures that the program initializes the embedded C variables.

3. Now, to get information about a variable in your program, use list with two input options--'variable' which defines the type of information to return, and 'idat' which identifies the symbol itself.

• idatlist = list(cc,'variable','idat')
  

1. idat is a global variable; the input keyword variable identifies it as one. Other keywords for list include project, globalvar, function, and type. Refer to list for more information about these options.

   In your MATLAB workspace and window, you see a new structure named idatlist. If you use the MATLAB Workspace browser, double-click idatlist in the browser to see idatlist.

4. Rather than using list to get information about idat, create an object that represents idat in your MATLAB workspace by entering

• cvar = createobj(cc,'idat')
  

1. which creates the new numeric object cvar.

   • NUMERIC Object
       Symbol Name             : idat
       Address                 : [ 40060 0]
       Wordsize                : 16 bits
       Address Units per value : 2 AU
       Representation          : signed
       Binary point position   : 0
       Size                    : [ 4 ]
       Total address units     : 8 AU
       Array ordering          : row-major
       Endianness              : little
     

   You use cvar, through the numeric object properties and functions, to access and manipulate the embedded variable idat, both in your MATLAB workspace and in CCS if you write your changes back to CCS from your workspace.

Using read and write

5. Try the following functions to read and write cvar. Notice the way the return values change as you change the function syntax. Notice also that write actually changes the data in memory on the target, as you see from what comes back to MATLAB after the third read.
1. read(cvar)

• This form returns all of the entries in the embedded array cvar to your MATLAB workspace.

  ans =

  • 
               1         508         647        7000
    

2. read(cvar,2)

• In contrast to the previous syntax, this one returns only the second element of cvar--508.

3. write(cvar,4,7001)

• Using write to change the value stored in the fourth element of cvar to 7001.

4. write(cvar,1,'FFFF')

• Change the first element of cvar to -1, which is the decimal equivalent of 0xFFFF. When you entered FFFF as a string (enclosed in single quotation marks), write converts the string to its decimal equivalent and stores that at the target location in memory.

5. read(cvar)

• At last, read the embedded array cvar to see if your changes to the first and fourth elements really occurred (they did).

6. read(cvar,[1 size(cvar)]

• Finally, read the first and last elements of the embedded variable cvar.

Using cast, convert, and size

1. Each time you used read, the function took the raw values of idat stored in memory on your target and converted them to equivalaent MATLAB numeric values. The way that read converts idat elements to numeric values is controlled by the properties of the object cvar which resulted from using createobj to create it. When you created cvar, the object that accesses the embedded variable idat, createobj assigned default property values to the properties of cvar that were appropriate for your target DSP architecture and for the C representation of variable idat.

   In many cases, it may help you develop your program if you change the default conversion properties. Several of the object properties, such as endianness, arrayorder, and size respond to changes made using function set. To make more complex changes, use functions like cast and convert that adjust multiple object property values simultaneously.

   In step 6 of this tutorial, you have the opportunity to use cast, convert, and size to modify cvar by changing property values. Unlike read and write, cast, convert, and size (and set mentioned earlier) do not affect the information stored on the target; they only change the properties of the object in MATLAB. Unless you write your changes back to your target, the changes you make in MATLAB stay in MATLAB.

6. To introduce changing the properties of cvar using cast, convert, and size, enter the following commands at the prompt. In this series of examples, you use read to view the changes each command makes to cvar.
1. set(cvar,'size',[2])

• As a result of this function, idat gets resized to only the first two elements in the array.

2. read(cvar)

• ans =

  1 508

  Returns only two values, not the full data set you saw in step 5a.

3. uintcvar = cast(cvar,'unsigned short')

• uintcvar is a new object, a copy of cvar (and thus idat), but with the datatype property value of unsigned short instead of double. Notice that the actual values are not different--just the interpretation. Where cvar interprets the values in idat as doubles, uintcvar interprets the values in idat as unsigned integers with 16 bits each. Now when you use the object to read idat, the returned values from idat are interpreted differently.

4. read(uintcvar)
5. convert(cvar,'unsigned short')

• In contrast to cast, convert does not make a copy of cvar; it changes the datatype property of cvar to be unsigned short.

  NUMERIC Object

  Symbol Name : idat

  Address : [ 40060 0]

  Wordsize : 16 bits

  Address Units per value : 2 AU

  Representation : unsigned

  Binary point position : 0

  Size : [ 2 ]

  Total address units : 4 AU

  Array ordering : row-major

  Endianness : little

6. read(cvar)

• ans =

  1 508

  Remember that one of the first things you did in these examples was change the size of cvar to 2. You should see that reflected in the returned values. The values returned by cvar after you change the datatype property should match the values returned by uintcvar since the objects have the same properties.

  One more thing to notice--the first value of idat is no longer -1, although you changed the value in step 5d. Recall that you changed the datatype to unsigned short for cvar, so the first element of idat that you set to -1 is now shown as the unsigned equivalent 1.

Using getmember

1. To this point you have worked with fairly simple data in memory on your target. However, with functions in MATLAB Link for Code Composer Studio, you can manipulate more complex data like strings, struactures, bitfields, eumerated data types, and pointers in a very similar way.

   In the next, somewhat extended examples, the tutorial demonstrates some common functions for manipulating structures, strings, and enumerated datatypes on your target. Pay particular attention to function getmember which extracts a single specified field from a structure on your target as an object in MATLAB.

7. cvar = createobj(cc,'myStruct')

1. Here you create a new object cvar, replacing the old cvar, that represents an embedded structure named myStruct on your target. When you loaded this tutorial program, one of the defined structures in the program was myStruct.

   • STRUCTURE Object
       Symbol Name         : myStruct
       Address             : [ 40032 0]
       Size                : [ 1 ]
       Total Address Units : 28 AU
       Members             : 'iy', 'iz'
     

8. read(cvar)

• ans = 
  
      iy: [2x3 double]
      iz: 'MatlabLink'
  

1. Now you see the contents of myStruct, its fields and values.

   Here's the definition of myStruct from ccstut.c in CCS.

   • struct TAG_myStruct {
         int iy[2][3];
         myEnum iz;
     } myStruct = { {{1,2,3},{4,-5,6}}, MatlabLink}
     

9. write(cvar,'iz','Simulink')

1. After this command, you have updated the field iz in myStruct with the actual enumerated name Simulink. If you look into ccstut.c, you see that iz is an enumerated datatype. That feature comes into play in the next steps.

10. cfield = getmember(cvar,'iz')

1. cfield, the object returned by getmember, represents the embedded variable iz in the project. Here's what cfield looks like in property form.

   • ENUM Object
       Symbol Name             : iz
       Address                 : [ 40056 0]
       Wordsize                : 32 bits
       Address Units per value : 4 AU
       Representation          : signed
       Binary point position   : 0
       Size                    : [ 1 ]
       Total address units     : 4 AU
       Array ordering          : row-major
       Endianness              : little
       Labels & values         : MATLAB=0, Simulink=1, SignalToolbox=2, 
     MatlabLink=3, EmbeddedTargetC6x=4
     

11. write(cfield,4)
12. read(cvar)

• ans = 
  
      iy: [2x3 double]
      iz: 'EmbeddedTargetC6x'
  

1. Your command write(cfield,4) replaced the string MatlabLink with the fourth value EmbeddedTargetC6x. That is an example of writing to an embedded variable by value.

13. cstring = createobj(cc,'myString')

1. createobj returns the object cstring that represents a C structure embedded in the project. When you leave off the closing semicolon (;) on the command, you see

   • STRING Object :
       Symbol Name             : myString
       Address                 : [ 40104 0]
       Total wordsize          : 8 bits
       Address Units per value : 1 AU
       Representation          : signed
       Binary point position   : 0
       Size                    : [ 29 ]
       Total address units     : 29 AU
       Array ordering          : col-major
       Endianness              : little
       Char Conversion Type    : ASCII
     

   which provides details about cstring. Using get with cstring returns the same information, plus more, in a form listing the property names and property values of cstring.

14. read(cstring)

1. In response you see the contents of cstring

   • ans =
     
     Treat me like an ASCII String 
     

15. write(cstring,7,'ME')

1. This changes the the seventh element of MyString to ME. When you reread cstring, me should be replaced by ME, so the string becomes

   • Treat ME like an ASCII String 
     

   as you see in the next example.

16. read(cstring)

• ans =
  
  Treat ME like an ASCII String 
  

17. write(cstring,1,127)

1. write changes the contents of the first element of MyString to the ASCII character 127--a nonprinting character.

18. readnumeric(cstring)

1. Using readnumeric with a string object returns the numeric equivalent of the characters in MyString, as shown here.

   • ans =
     
       Columns 1 through 12 
     
        127   114   101    97   116    32    77    69    32   108   105   107
     
       Columns 13 through 24 
     
        101    32    97   110    32    65    78    83    73    32    83   116
     
       Columns 25 through 29 
     
        114   105   110   103     0
     

Working with Links and Data

Closing the Links or Cleaning Up CCS IDE