Embedded IDE Link™ CC

read - Data from memory on 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,structindex)
data = read(objname,structindex,member)
data = read(objname,member)
data = read(objname,structindex,member,memberindex)
data = read(objname)
data = read(objname,index)
data = read(objname,member,memberindex,structindex)
data = read(...,timeout)

Description

ticcs Object Syntaxes

mem = read(cc,address,'datatype',count,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 read begins at the memory location defined by address. count determines the number of values to read, starting at address. datatype defines the format of the raw data stored in the referenced memory block.

To check values in memory on a running target, such as values that change during processing, insert one or more breakpoints in the project code and perform the read operation while the target code is paused at one of the breakpoints. After you read the data, release the breakpoint.

Note   Do not attempt to read data from the target while it is running.

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. When the processor has only one memory page, as is true for many digital signal processors, the value of the page portion of the memory address is 0. By default, ticcs sets the page to 0 at creation if you omit the page property as an input argument.

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

Examples of Address Property Values

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.

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:

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 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 time-out defined in cc.

Working With Negative Values

Writing a negative value causes the data written to be saturated because char is unsigned on the processor. Hence, a 0 (a NULL) is written instead. A warning results as well, as this example shows.

cc = ticcs;
ff = createobj(cc,'g_char'); % Where g_char is in the code.
write(ff,-100);
Warning: Underflow: Saturation was required to fit the data into 
an addressable unit.

When you try to read the data you wrote, the character being read is 0 (NULL) — so there seems to be nothing returned by the read function.

You can demonstrate this by the following code, after writing a negative value as shown in the previous example.

readnumeric(x)
ans =
0
read(x) % Reads the NULL character
ans =   % Apparently nothing is returned.

double(read(x)) % Read the numeric equivalent of NULL.
ans =   % Again, appears not to return a value.

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 a value of 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.

Reading Structures

Reading data from structures in memory represents a special subset of general read. In each syntax, objname accesses a structure in memory on the target or in CCS.

data = read(objname,structindex) reads the structure element referred to by structindex.

data = read(objname,structindex,member) returns the value of the specified member of the structure as identified by structindex.

data = read(objname,member) returns the value of member from the structure accessed by objname, for all indexes — the entire structure variable.

data = read(objname,structindex,member,memberindex) returns the index for member in the accessed structure.

Embedded Object Syntaxes

read works with all of the objects you create with createobj. To transfer data from CCS to MATLAB software, use the read function — 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.

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 software 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 perform individual read operations, consider using getmember.

Examples

read reads data that you wrote to the target processor.

cc = ticcs;
indata = 1:25;
write(cc,0,indata,30);
outdata=read(cc,0,'double',25,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 = ticcs;
  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)

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 software, use readnumeric.

Reading Enumerated Variables

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

Reading Structures

The following examples show various structure read syntaxes at work. Start with a structure definition.

struct tag {     
  float re;      
  float im;      
} st[2] = {1,2,3,4};

Use read to return the information stored in the structure st.

st = createobj(cc,'st')
   
answer = read(st)
ans =
   [1x2 struct]

answer{1}

   re: 1
   im: 2
answer{2}

   re: 3
   im: 4
answer = read(st,2)

answer = 
         re: 3
        im: 4
answer = read(st,2,'re')

answer =
        3
answer = read(st,'re')
answer = 
        1 3

See Also

getmember, isreadable, symbol, write

profile

readbin