MATLAB Link for Code Composer Studio Development Tools

read

Retrieve data from memory on the target processor or in CCS

Syntax

• mem = read(cc,address,'datatype',count,timeout)
  mem = read(cc,address,'datatype',count)
  mem = read(cc,address,'datatype')
  data = read(objname)
  data = read(objname,index)
  data = read(objname,member,memberindex,structindex)
  data = read(...,timeout)
  

Description

Link Object Syntaxes

mem = read(cc,address,count,datatype,timeout) returns data from the processor referred to by cc. The address, count, and datatype input arguments define the memory block to be read. The data block to be read begins at the memory location defined by address. count determines the number of values to be read, starting at address. datatype defines the format of the raw data stored in the referenced memory block.

read uses the datatype parameter to determine the number of bytes to read per stored value. timeout is an optional input argument you use to specify when to terminate long read processes and data transfers. For details about each input parameter, read the following descriptions.

address -- read uses address to define the beginning of the memory block to read. You provide values for address as either decimal or hexadecimal representations of a memory location in the target processor. The full address at a memory location consists of two parts: the offset and the memory page, entered as a vector [location, page], a string, or a decimal value. In cases where the processor has only one memory page, as is true for many digital signal processors, the page portion of the memory address is 0. By default, ccsdsp sets the page to 0 at creation if you omit the page property as an input argument to set the page parameter.

For processors that have one memory page, setting the page value to 0 lets you specify all memory locations in the processor using just the memory location without the page value.

Table 3-6: Examples of Address Property Values

Property Value	Address Type	Interpretation
'1F'	String	Offset is 31 decimal on the page referred to by cc(page)
10	Decimal	Offset is 10 decimal on the page referred to by cc(page)
[18,1]	Vector	Offset is 18 decimal on memory page 1 (cc(page) = 1)

To specify the address in hexadecimal format, enter the address property value as a string. read interprets the string as the hexadecimal representation of the desired memory location. To convert the hex value to a decimal value, the function uses hex2dec. Note that when you use the string option to enter the address as a hex value, you cannot specify the memory page. For string input, the memory page defaults to the page specified by cc(page).

count -- a numeric scalar or vector that defines the number of datatype values to read. Entering a scalar for count causes read to return mem as a column vector which has count elements. count can be a vector to define multidimensional data blocks. The elements of count define the dimensions of the data matrix returned in mem. The following table shows examples of input arguments to count and how read responds.

Input	Response
n	Read n values into a column vector. Return the vector in mem.
[m,n]	Read (m*n) values from memory into an m-by-n matrix in column major order. Return the matrix in mem.
[m,n,p,...]	Read (m*n*p*...) values from the processor memory in column major order. Return the data in an m-by-n-by-p-by... multidimensional matrix and return the matrix in mem.

datatype -- a string that represents a MATLAB data type. The total memory block size is derived from the value of count and the specified datatype. datatype determines how many bytes to check for each memory value. read supports the following data types:

datatype String	Description
'double'	Double-precision floating point values
'int8'	Signed 8-bit integers
'int16'	Signed 16-bit integers
'int32'	Signed 32-bit integers
'single'	Single-precision floating point data
'uint8'	Unsigned 8-bit integers
'uint16'	Unsigned 16-bit integers
'uint32'	Unsigned 32-bit integers

To limit the time that read spends transferring data from the target processor, the optional argument timeout tells the data transfer process to stop after timeout seconds. timeout out is defined as the number of seconds allowed to complete the read operation. You might find this useful for limiting prolonged data transfer operations. If you omit the timeout option in the syntax, read defaults to the global timeout defined in cc.

mem = read(cc,address,'datatype',count) reads data from memory on the processor referred to by cc and defined by the address, and datatype input arguments. The data block being read begins at the memory location defined by address. count determines the number of values to be read. When you omit the timeout option, timeout defaults to the value specified by the timeout property in cc.

mem = read(cc,address,'datatype') reads the memory location defined by the address input argument from the processor memory referred to by cc. The data block being read begins at the memory location defined by address. When you omit the count option, count defaults to 1. This syntax reads one memory location of datatype.

Note    read does not coerce data type alignment in your processor memory. You can write and read data of any type (datatype) to and from any memory location (address). Certain combinations of address and datatype are difficult for some processors to use. To ensure seamless read operation, use the address function to extract address values that are compatible with the alignment required by your target processor.

Like the isreadable, iswritable, and write functions, read checks for valid address values. Illegal address values are any address space larger than the available space for the processor--2³² for the C6xxx processor family and 2¹⁶ for the C5xxx series. When read identifies an illegal address, it returns an error message stating that the address values are out of range.

Embedded Object Syntaxes

read works with all of the objects you create with createobj. To transfer data from Code Composer Studio to MATLAB, use the read function--read--depending on the data to access. Note that read and its variants are the only way to get data from CCS to MATLAB as objects.

data = read(objname) reads all the data in memory at the location accessed by object objname, and converts the data into a numeric representation. Properties of objname, such as wordsize, storageunitspervalue, size, represent, and binarypt--determine how read performs the numeric conversion. data is a numeric array whose dimensions are defined by the size property of objname. Object property size is the dimensions vector. Each element in the dimensions vector contains the size of the data array in that dimension. When size is a scalar, data is a column vector of the length specified by size.

For example, when size is [2 3], data is a 2-by-3 array.

Properties of the Object

objname, the object that accesses the data, has the following properties, if the object is a numeric object. The properties differ for different types of objects, such as structure objects or register objects.

Property	Options	Description
size	Greater than 1	Specifies the dimensions of the output numeric array.
arrayorder	col-major or row-major	Defines how to map sequential memory locations into arrays. 'col-major' is the default, and the MATLAB standard. C uses 'row-major' ordering most often.
represent	float, signed, unsigned, fract	Determines the numeric representation used in the output data. float--IEEE floating point representation, either 32- or 64 bits signed--two's complement signed integers unsigned--unsigned binary integer fract--fractional fixed-point data
wordsize	Greater than 1	(Read-only) Calculated from other object properties such as storageunitspervalue
binarypt	0 to wordsize	Determines the position of the binary point in a word to specify its interpretation

data = read(objname,index) reads the specified element in the memory location accessed by objname. index is a scalar or a vector that identifies the particular data element to return. When you enter [] for index, read returns all the data stored at the memory location. When you enter a scalar for index, read returns a column vector of length size containing the data from the memory space. When index is a vector, read returns the element in the array specified by the entries in the vector. For example, if you are reading data from a 3-by-3-by-3 array, setting index to be [2 2 2] returns the element data(2,2,2). To return more than one element, use MATLAB standard range notation for the vector elements in index. As an example, when index is [1:6], read returns the first six elements of data. You must remember that the number of elements in the vector in index must be either one (a scalar) or the same as the number of dimensions in data and specified by the property size. When data is a four dimensional array, your vector in index must have four elements, one for each array dimension. Otherwise, read cannot determine which elements to return.

data = read(objname,member,memberindex,structindex) reads the members of the structure that objname accesses. When you omit all of the input arguments except objname, read returns the entire structure. member, memberindex, and structindex (an optional input argument) specify which structure member to read:

• member--specifies the name of the member of the structure to read.
• memberindex--provides the index of the data element to read.
• structindex--identifies the structure to read when objname accesses a structure containing structures or a vector.

Note that the class of the object data from the read operation depends on the class of the member being read--numeric values return numeric objects, string values return string objects, and so on.

data = read(...,timeout) During read operations, the timeout property of objname determines the time allowed to complete the read. Including a value for the timeout input argument in the read syntax lets you override the timeout property setting for objname with the value you enter for argument timeout. For reading large data arrays, being able to explicitly set the timeout value as an input option may be necessary to let read run to completion. Note that using the timeout input option does not change the timeout property value for objname.

When you need to read one member of a structure or to do individual read operations, consider using getmember.

Examples

In its most straightforward form, read reads data that you wrote to the target processor.

• cc = ccsdsp;
  indata = 1:25;
  write(cc,0,indata,30);
  outdata=read(cc,0,25,'double',10)
  
  outdata =
  
    Columns 1 through 13 
  
       1     2     3     4     5     6     7     8     9    10    11    12    13
  
    Columns 14 through 25 
  
      14    15    16    17    18    19    20    21    22    23    24    25
  

outdata now contains the values in indata, returned from the target processor.

As a further demonstration of read, try the following functions after you create a link cc and load an appropriate program to your target. To perform the first example, 'var' must exist in the symbol table loaded in CCS.

• Read one 16-bit integer at the location of target symbol 'var'.

• mlvar = read(cc,address(cc,'var'),'int16')
  

• Read 100 32-bit integers from address f000 (hexadecimal) and plot the data.

• mlplt = read(cc,'f000','int32',100)
  plot(double(mlplt))
  

• Increment the integer value stored at address 10 (decimal) of the target processor.

• cc = ccsdsp;
  ainc = 10
  mlinc = read(cc,ainc,'int32')
  mlinc = int32(double(mlinc)+1)
  cc.write(ainc,mlinc)
  

Reading String Variables

Using read to return a string creates a string object. Within the string object, the property charconversion controls the read operation. When you set charconversion to ASCII, read recognizes only the ASCII characters from 0 to 127. ASCII is the only accepted type for the charconversion property value.

While reading strings from memory, read continues until it encounters a null character, then it stops.

For example, if memory contains the string "Hello World" in the following format in memory (each block represents one memory location)

H

e

l

l

o

W

o

r

l

d

\0

M

read does not return the M because it stops at the null character \0.

To return a string from memory as a numeric object in MATLAB, use readnumeric.

Reading Enumerated Variables

If you read an enumerated date type from memory, the returned entry is a string object.

Reading Structures

See Also
getmember, isreadable, symbol, write

profile

readmat