| MATLAB Link for Code Composer Studio Development Tools | |
Reference for the Properties of the Objects
This section presents details of the properties that apply to the objects in MATLAB Link for Code Composer Studio. The reference information contained can help you learn about using the links and objects.
Property Reference Format and Contents
Ordered alphabetically by property name, most references include:
Some reference pages may not include all the features listed; in particular some pages may not provide examples or the range of valid property values or referrals.
Description
Reports the starting address of the symbol the object references--either a memory address or a register name. In some cases the address is in [Offset Page] format when the processor supports memory pages and the address is a location in memory.
Characteristics
Either a numeric (for memory locations) or alphanumeric (for register locations), this is a writable value.
If you change the offset and page values for the property, the object points to a different location in memory. Changing the address property does not affect the location of the symbol.
Range
Covers the entire range of addresses available on the target.
Description
Contains a string that defines the version of the CCS application program interface (API) being used by the link object.
Characteristics
A string value. The first entry in the square brackets is the major version number and the second entry is the minor revision number. You cannot set this value--it is read-only.
Range
Any ASCII characters that make up the name and version number of the API.
Examples
Create a link object and use get to review the object properties. For this object, the API version returns 1.2 and apiversion is [1 2]. The API version in not necessarily the same as the version of CCS.
cc=ccsdsp CCSDSP Object: API version : 1.2 Processor type : TMS320C6711 Processor name : CPU_1 Running? : No Board number : 0 Processor number : 0 Default timeout : 10.00 secs RTDX channels : 0 get(cc) rtdx: [1x1 rtdx] apiversion: [1 2] ccsappexe: 'D:\Applications\ti\cc\bin\' boardnum: 0 procnum: 0 timeout: 10 page: 0
Description
Specifies the manner in which the object interprets data stored linearly in memory, whether as rows or columns of an array.
Characteristics
arrayorder is a string with one of two possible values--row-major (C style intrepretation) or column-major (normal MATLAB style).
Range
Allowed strings are row-major and column-major.
Examples
When you have nine values in memory, such as 1,2,...,9, the arrayorder property value determines how to build an array from the values.
You can increase the number of array dimensions without limit.
Description
Specifies the location of the binary point in a value. To interpret the actual value of a value in memory, you need both the data type and binary point to convert correctly from the binary or hexadecimal representation to decimal. A fixed-point data type is characterized by the word size in bits, the binary point, and whether it is signed or unsigned. The position of the binary point is the means by which fixed-point values are scaled and interpreted. Since the object uses double-precision representation, the word size and binary point form the basis for simulating fixed-point values.
Characteristics
An positive or negative integer.
Range
binarypt ranges from 0 to the word size. You can use negative binary point locations and binary point locations larger than the word size, to the limit of double-precision representation.
Referrals
Description
Reports the number of bits per address location (addressable unit) on the target. Memory locations and registers may have different values on a target. And different processors can use different values as well.
Characteristics
Range
Depends on the target processor. Usually 8, 16, or 32 bits.
Referrals
See also numberofstorageunits and storageunitspervalue.
Description
Specifies the target board or simulator with which the link object communicates.
Characteristics
An integer. This is a read-only value determined when you create link objects and select your target.
Range
Integer values ranging from 0 for the first board up to the number of boards that CCS recognizes configured on your machine. Note that both simulators and hardware count as boards.
Description
Reports the full directory path to the CCS executable.
Characteristics
A string that shows the path to your CCS installation. You cannot change this string except by moving you CCS storage location.
Examples
If your CCS installation is in a folder called Applications on your D: drive, you might see a string like
for the ccsappexe property value.
Description
Specifies whether to interpret the bit pattern in memory as little-endian or big-endian format. Big-endian format assumes the least significant bit (LSB) is last in a word that spans more than one addressable unit in memory; little-endian assumes the LSB is first in a word that spans multiple addressable units.
Characteristics
Property values are strings, either little or big. You can change the state within the object, which changes the way MATLAB interprets the bits stored in memory on your target.
Range
You have two options for endianness--little or big.
Examples
When you have a variable in memory, such as ddat from the link object tutorial, creating a numeric object from ddat shows you the endianness for ddat.
ddat = createobj(cc,'ddat') NUMERIC Object Symbol Name : ddat Address : [ 40072 0] Wordsize : 64 bits Address Units per value : 8 AU Representation : float Binary point position : 0 Size : [ 4 ] Total address units : 32 AU Array ordering : row-major Endianness : little
get(ddat) address: [40072 0] bitsperstorageunit: 8 numberofstorageunits: 32 link: [1x1 ccsdsp] timeout: 10 name: 'ddat' wordsize: 64 storageunitspervalue: 8 size: 4 endianness: 'little' arrayorder: 'row-major' prepad: 0 postpad: 0 represent: 'float' binarypt: 0
Description
Indicates that the refernced pointer points to itself. When you dereference the pointer repeatedly, you may eventually find the pointer points to void. You should only see this in structures that have pointer that refer to the structure.
Characteristics
Double data type. isrecursive default is zero.
Description
Contains the names of the fields in an enumerated object or memory location.
Characteristics
ASCII characters of any type. Contains as many strings as there are enumerated entries, entered as a cell array of strings.
Examples
Using the cfield object created in the link tutorial (run ccstutorial at the MATLAB prompt), you see the following when you display the object.
cfield 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
The labels are MATLAB, Simulink, SignalToolbox, MatlabLink, and EmbeddedTargetC6x. In this case, label is {1x5 cell}.
Referrals
Description
Specifies the link object that you used when you created the embedded object.
Characteristics
A 1 by 1 array containing the name of the link object associated with the symbol table that holds the symbol.
Examples
In the tutorial, you created a numeric object named uicvar, using cast with the numeric object cvar. To create cvar, you used link object cc to determine the symbol table and project or target. When you view the properties of uicvar, you see the property link listing the link object as ccsdsp.
get(uicvar) address: [40060 0] bitsperstorageunit: 8 numberofstorageunits: 4 link: [1x1 ccsdsp] timeout: 10 name: 'idat' wordsize: 16 storageunitspervalue: 2 size: 2 endianness: 'little' arrayorder: 'row-major' prepad: 0 postpad: 0 represent: 'unsigned' binarypt: 0
Delving more deeply into the property link reveals the properties of the link object.
uicvar.link CCSDSP Object: API version : 1.2 Processor type : TMS320C6711 Processor name : CPU_1 Running? : No Board number : 0 Processor number : 0 Default timeout : 10.00 secs RTDX channels : 0
Referrals
See also createobj
Description
This identifies a MATLAB structure that holds the entry for each C member in the structure accessed by the object.
Characteristics
Examples
If you have a stucture in DSP memory declared like the following structure
the member property of an object the access myStruct, might look like
get(cvar) name: 'myStruct' member: [1x1 ccs.containerobj] membname: {'iy' 'iz'} memboffset: [0 24] address: [40032 0] storageunitspervalue: 28 size: 1 numberofstorageunits: 28 arrayorder: 'row-major'
where member returns as a 1-by-1 MATLAB array with a handle to the object that contains it named ccs.containerobj.
Description
Contains the names of the fields in a structure or union accessed by a structure object.
Characteristics
membname is one or more strings providing the names of the structure fields, formatted as a cell array.
Range
Strings in membname contain any valid ASCII characters that might be found in a C structure field.
Examples
In CCS, if you had the following structure in your project code:
you could create a structure object, var, that access the structure. Using get with var, you can review the names of the fields in the structure by looking at the membname property for var.
Description
While this is not directly useful to you, the values in the vector specify how far, in memory in addressable units, each field in a structure is from the starting address for the structure.
Characteristics
Any numeric or alphanumeric value that represents a valid address or register location on the target. The vector contains one element for each field in the structure, representing the offset to that field in memory.
Range
A vector containing M element, where M is the number of fields in the structure. The second element in the vector is the offset to the second field in the structure, the third element in the vector is the offset to the third field, and so on until the final element is the offset to the final field. The first element in the memoffset vector is always 0, since this represents the offset to the first element in the structure, which is where the structure begins. Also any valid register address, such as A0 or PC.
Examples
When you are working with structure objects, the property memoffset tells you how far one structure field is from another in memory.
cvar = createobj(cc,'myStruct') STRUCTURE Object: Symbol Name : myStruct Address : [ 40032 0] Address Units per value : 28 AU Size : [ 1 ] Total Address Units : 28 AU Array ordering : row-major Members : 'iy', 'iz' read(cvar) ans = iy: [2x3 double] iz: 'MatlabLink' get(cvar) name: 'myStruct' member: [1x1 ccs.containerobj] membname: {'iy' 'iz'} memboffset: [0 24] address: [40032 0] storageunitspervalue: 28 size: 1 numberofstorageunits: 28 arrayorder: 'row-major'
From the property memoffset, you see that member iz of myStruct is 24 addresses from member iy, and from the start of the structure.
Description
Provides the name of the symbol or embedded object (mostly they are the same thing) to which the object refers.
Characteristics
ASCII characters that compose valid C variable names.
Range
Any valid C variable name that occurs in your project.
Description
Reports the number of addressable units necessary to represent the symbol to which the object refers.
Characteristics
Reported in addressable units. Property bitsperstorageunit tells you how many bits are in each addressable unit. Combined with property numberofstorageunits, you can determine the storage used by the symbol.
Range
Any number of addressable unit up to the limit of memory on the target.
Description
Reports the number of RTDX communications channels configured for the RTDX link. Includes both read and write channels and does not depend on whether the channels are enabled.
Examples
As you did if you followed the RTDX tutorial, create a link object, then open two RRTDX channels for the link.
cc=ccsdsp('boardnum',boardNum,'procnum',procNum) CCSDSP Object: API version : 1.2 Processor type : TMS320C6711 Processor name : CPU_1 Running? : No Board number : 0 Processor number : 0 Default timeout : 10.00 secs RTDX channels : 0 cc.rtdx.configure(1024,4); cc.rtdx.open('ichan','w'); cc.rtdx.open('ochan','r'); cc.rtdx.enable; get(cc,'rtdx') RTDX Object: Default timeout : 15.00 secs Open channels : 2 Ch Name Mode -- ---- ---- 1 ichan write 2 ochan read
Where the listing for the RTDX object shows two open channels, this is the numChannels property value.
Description
Specifies which memory page contains the symbol address. For processors that do not use pages in memory, such as the C6701, the page value is always 0. When you get the properties of an object, the address comes back in the format [address page].
Characteristics
An integer that specifies the memory page for an address in memory.
Range
From 0 to the maximum number of memory pages supported by the processor.
Examples
Given a symbol in memory named ddat, when you create an object to access ddat, you can get the properties for the object and see the the address format.
ddat=createobj(cc,'ddat') NUMERIC Object Symbol Name : ddat Address : [ 40072 0] Wordsize : 64 bits Address Units per value : 8 AU Representation : float Binary point position : 0 Size : [ 4 ] Total address units : 32 AU Array ordering : row-major Endianness : little
Notice that the page property value is 0. Since this example targets a C6711 digital signal processor, the page property value is always zero--the C6711 processor does not support memory pages.
Description
Reports the number of bits of padding required at the end of the memory buffer to fill the buffer. Determining the final numeric value stored in memory ignores the added bits.
Characteristics
Double-precision value that specifies the number of added bits.
Description
Reports the number of bits of padding required at the beginning of the memory buffer to fill the buffer. Determining the final numeric value stored in memory ignores the added bits.
Characteristics
Double-precision value that specifies the number of added bits.
Description
The number assigned by CCS to the processor on the board or simulator. When the board contains more than one processor, CCS assigns a number to each processor, numbering from 0 for the first processor on the first board. For example, when you have two recognized boards, and the second has two processors, the first processor on the first board is procnum=0, and the first and second processors on the second board are procnum=1 and procnum=2. This is also a property used when you create a new link to CCS IDE.
Range
From 0 for one processor to N-1, where N is the number of processors that CCS recognizes as installed and configured on your machine.
Description
Contains the name of the register as defined in the C source code. Note that this is not the same as a CPU register on the target.
Characteristics
regname is a MATLAB array with no initial value nor a default value.
Range
Any valid register declared in your C source code.
Description
Contains a string that specifies the data type for the accesses symbol. Memory locations consist of bits and bytes. Property represent reports to MATLAB how to interpret the data stored in memory.
Characteristics
A string that defines the data type for the variable--one of:
float--IEEE floating point representation, either 32- or 64 bits
fract--fractional fixed-point data
signed--two's complement signed integers
ufract--unsigned fractional fixed-point data
unsigned--unsigned two's complement integer data
Range
While MATLAB recognizes many different data types, C and the TI processors are somewhat different. The tables provided here show the valid data types (from property datatype) and the strings that appear for them as the represent property value.
Various TI processors restrict the sizes of the datatypes used by objects in MATLAB Link for Code Composer Studio. Shown in the next table, the processor families restrict the valid word sizes for the listed data types.
Using the properties of the objects, you change the word size by changing the value of the storageunitspervalue property of the object. Note that you cannot change the bitsperstorageunit property value which depends on the processor and whether the object represents a memory location or a register.
Referrals
Description
Specifies whether the link object has RTDX channels included in the link. When the link has open RTDX channels, this property contains a structure of cell arrays that detail the information about the channels--the number of channels and the names of the channels.
Characteristics
Empty or an array of cell arrays containing strings and values.
Examples
When you create a link, the default state is not to have RTDX channels and the property rtdx is empty, as you see here.
cc=ccsdsp('boardnum',boardNum,'procnum',procNum) CCSDSP Object: API version : 1.2 Processor type : TMS320C6711 Processor name : CPU_1 Running? : No Board number : 0 Processor number : 0 Default timeout : 10.00 secs RTDX channels : 0
Now, configure and open two RTDX channels to the target.
After creating the channels, displaying the link shows that the rtdx property is no longer empty. It contains the names and number of channels available, and the channel mode, either read or write.
get(cc) rtdx: [1x1 rtdx] apiversion: [1 2] ccsappexe: 'D:\Applications\ti\cc\bin\' boardnum: 0 procnum: 0 timeout: 10 page: 0 get(cc,'rtdx') RTDX Object: Default timeout : 15.00 secs Open channels : 2 Ch Name Mode -- ---- ---- 1 ichan write 2 ochan read
Referrals
Description
Provides the names of open RTDX channels for the link.
Characteristics
Alphanumeric strings using ASCII characters that define the channel names.
Range
From 0 to the number of defined and open channels in your project.
Description
Defines the number of dimensions for the numeric array that is accessed by the numeric object. The size property provides the same information that function size provides in MATLAB.
Characteristics
size is a vector having as many elements as the number of dimensions in the symbol represented by the object. Each element in the vector reports the number of entries in that dimension.
Range
size can be a scalar greater than or equal to one, or a vector of integers, each one greater than or equal to one.
Examples
When you have a variable declaration in your code like
the size property tells you about x if you create an object that accesses x.
so x represents a 3-by-2 array having six elements.
Description
Describes how many storage units (addressable units) make up the accessed symbol.
Characteristics
Given in addressable units (AU), storageunitspervalue is an integer.
Range
storageunitspervalue is an integer equal to or greater than one, up to the limit of your target processor. This can have a value less than one in the case of packing of the bits in the symbol.
Examples
From the link tutorial, object cfield returns the following properties when you create an object to provide access to the myStruct member iz.
cfield = getmember(cvar,'iz') % Extract object from structure 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
get(cfield) address: [40056 0] bitsperstorageunit: 8 numberofstorageunits: 4 link: [1x1 ccsdsp] timeout: 10 name: 'iz' wordsize: 32 storageunitspervalue: 4 size: 1 endianness: 'little' arrayorder: 'row-major' prepad: 0 postpad: 0 represent: 'signed' binarypt: 0 label: {1x5 cell} value: [0 1 2 3 4]
Requiring 4 addressable units (storage units) with 8 bits per storage unit (property bitsperstorageunit = 8) and a size of 1, cfield requires 32 bits of storage space in memory.
Description
Specifies how long MATLAB Link for Code Composer Studio waits for an operation to complete, or at least to return a status of complete. In some cases, operations continue after the timeout expires, since the time period depends on the status of the operation, not the actual completion.
Characteristics
Range
A value greater than zero. 10 seconds is the default value.
Examples
In this example, the time out period is 10 seconds for the new object.
cc=ccsdsp('boardnum',boardNum,'procnum',procNum) CCSDSP Object: API version : 1.2 Processor type : TMS320C6711 Processor name : CPU_1 Running? : No Board number : 0 Processor number : 0 Default timeout : 10.00 secs RTDX channels : 0
Description
Describes the data type of the referent for the pointer the pointer object accesses. typestring returns the data type for the referent as well as an asterisk to indicate that the symbol is a pointer.
Examples
For a pointer object that points to a floating point symbol, the property value for typestring is float *. For a pointer to an integer, the value is int *.
Description
Reports the values associated with labels in an enumerated object.
Characteristics
Numbers, one or more, configured as a vector depending on the number of entries.
Examples
Using the enumerated data type variable myEnum from the link tutorial, create an object that accesses the labels and values for the enumerated data variable iz.
cvar = createobj(cc,'myStruct') STRUCTURE Object: Symbol Name : myStruct Address : [ 40032 0] Address Units per value : 28 AU Size : [ 1 ] Total Address Units : 28 AU Array ordering : row-major Members : 'iy', 'iz' cfield = getmember(cvar,'iz') 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
The values for iz are 0, 1, 2, 3, and 4. In the value property, the values show up as [0 1 2 3 4], a vector whose elements are the values.
Description
Specifies the word size for the target processor, and the referenced symbol.
Characteristics
Depends on the processor architecture. Because this is fixed on the processor, it is read-only, set when you create an embedded object.
Range
For most processors, the word size can be from 8 to 64 bits, usually 8, 16, or 32.
| | Properties of Structure Objects | Link Functions Reference | |