Embedded IDE Link™ CC

write - Write data to memory on target processor

Syntax

write(cc,address,data,timeout)
write(cc,address,data)
write(objname)
write(objname,index)
write(objname,structindex,mem1,value1,...,memn,valuen,memindex)

Description

ticcs Object Syntaxes

write(cc,address,data,timeout) sends a block of data to memory on the processor referred to by cc. The address and data input arguments define the memory block to write—where the memory starts and what data is being written. The memory block to write to begins at the memory location defined by address. data is the data to write, and can be a scalar, a vector, a matrix, or a multidimensional array.

Data get written to memory in column-major order. timeout is an optional input argument you use to terminate long write processes and data transfers. For details about each input parameter, read the following descriptions.

To update values in memory on a running target, such as values to change during processing, insert one or more breakpoints in the project code and perform the write 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 write data to the target while it is running.

address — write uses address to define the beginning of the memory block to write to. 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 value to 0 at creation if you omit page 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. write interprets the string as the hexadecimal representation of the desired memory location. To convert the hex value to a decimal value, the write uses hex2dec. 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..

data — the scalar, vector, or array of values that are written to memory on the processor. write supports the following data types:

To limit the time that write 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 write operation. You may find this useful for limiting prolonged data transfer operations. If you omit the timeout option in the syntax, write defaults to the global time-out defined in cc.

write(cc,address,data) ends a block of data to memory on the processor referred to by cc. The address and data input arguments define the memory block to be written — where the memory starts and what data is being written. The memory block to be written to begins at the memory location defined by address. data is the data to be written, and can be a scalar, a vector, a matrix, or a multidimensional array. Data get written to memory in column-major order. Refer to the preceding syntax for details about the input arguments. In this syntax, timeout defaults to the global time-out period defined in cc.timeout. Use get to determine the default timeout value.

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

Writing 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.

Embedded Object Syntaxes

write works with all of the objects you create with createobj. To transfer data from MATLAB^® environment to CCS, use one of the write functions — write — depending on the data to write. Note that write and its variants are the only way to get data from the MATLAB environment to CCS from objects.

write(objname) writes all the data in objname to the location accessed by object objname. Properties of objname, such as wordsize, storageunitspervalue, size, represent, and binarypt — determine how write 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 are different for different types of objects, such as structure objects or register objects.

write(objname,index) writes the data in objname to the memory location accessed by objname. Input argument index (called the address offset) is a scalar or a vector that identifies the particular data element to write to at the location in memory. When you enter [] for index, write writes all the data in objname to the memory location it accesses. When you enter a scalar for index, write outputs a column vector of length size containing the referenced data to the memory space starting at index. When index is a vector, write outputs the referenced data elements to the memory locations specified by the entries in the vector.

For example, if you are writing one data element to a 3-by-3-by-3 array in memory, setting index to be [2 2 2] writes the data value to the element (2,2,2) in memory. To write more than one element at a time, use MATLAB software standard range notation for the vector elements in index. As an example, when index is [1:6], write writes six data values to the first six memory locations. Remember that the number of elements in the vector in index must be either one (a scalar) or the same as the number of memory locations available and specified by the property size of objname.

When objname represents a four dimensional array, your vector in index must have four elements, one for each array dimension. Otherwise, write cannot determine where to write the elements in memory.

write(objname,structindex,mem1,value1,...,memn,valuen,memindex) writes the members of the structure that objname accesses. When you omit all of the input arguments except objname, write writes the entire structure. memn, valuen, memindex, and stindex (an optional input argument) specify which structure member to write:

• memn — Specifies the name of the member of the structure to write

• valuen — Specifies the value to write to membern

• memindex — Provides the index of the data element to write

• structindex — Identifies the structure to write when objname accesses a structure containing structures or a vector

Note that the class of the object data from the write operation depends on the class of the member being written — numeric objects write numeric values, string objects write string values, and so on.

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

Using write with Embedded Objects

When you are writing data into memory on your target, consider a number of points that affect how write performs the write operation.

• The data you write to the target can be either numeric or hexadecimal format.

• When the data you are writing contains values that exceed the representable range for the variable date type and word size, the values written saturate to the maximum or minimum representable value for the variable representation. For example, if you try to write the value 70000 into an unsigned, 16-bit variable, the write operation stores 65535 into memory. 65535 is the maximum representable value for unsigned, 16-bit integers. Similarly, if you try to write -3 to the same variable, the stored value will be 0—you cannot represent negative numbers in the unsigned format.

• When you write more data elements to memory than fit in the specified size of the memory block, only the number of elements that fit in the memory block get written to the target. Excess elements do not get stored and are lost.

• When you write fewer data elements to memory than fit in the specified size of the memory block, all the elements get written to the memory block on the target. Memory space in the block which does not receive new elements is not affected by the write operation and remains unchanged.

• Use separate write operations to write multiple data elements to different locations within the memory block accessed by an object. For example, to write to the fifth and eighth elements of a 1-by-10 array in memory accessed by an object, use write twice — once to write to the fifth memory location and the again to write to the eighth location. You cannot combine the write operations in a single command unless the memory locations are contiguous. Refer to the next item in this list for information about writing to contiguous memory locations within a memory block.

• To write a block of data into contiguous locations in the memory block accessed by the object, supply just the starting index for the locations in the memory block.

Writing Strings to Memory

Writing strings to memory has some idiosyncrasies. Recall the following points when you use write with string data.

• Data that you write to memory can be numeric or string data.

• When your data is strings or characters, the write operation is controlled by the charconversion property value for the object. write accepts and writes only characters with ASCII values from 0 to 127 when the charconversion property value is ASCII.

• Numeric data is not restricted in any way when you use write.

• write appends a null character as the last element written to memory, except when

  • You write numeric data.

  • The object points to a single ANSI^® C character (size equals 1).

  • The amount of data you are writing exceeds the allocated space.

• When the string data you write does not fill the allotted space in memory, write does not fill the extra space with zeros — no zero padding.

Writing to Structures

When you are writing data to a particular index within the structure, consider using getmember to create an object that accesses the desired member. Then use your new object as objname in the write function call.

Refer to the section Embedded Object Examples for examples of write in use with structures.

Examples

ticcs Object Examples

Connect to a processor and write data to it. In this example, CCS IDE recognizes one board having one processor.

cc = ticcs;
cc.visible(1);
write(cc,'50',1:250);
mem = read(cc,0,'double',50) % Returns 50 values as a column 
                             % vector in mem.

It may be more convenient to return the data in an array. If you enter a vector for count, mem contains a matrix of dimensions the same as vector count.

write(cc,10,1:100);
mem=read(cc,10,'double',[10 10])

mem =

     1    11    21    31    41    51    61    71    81    91
     2    12    22    32    42    52    62    72    82    92
     3    13    23    33    43    53    63    73    83    93
     4    14    24    34    44    54    64    74    84    94
     5    15    25    35    45    55    65    75    85    95
     6    16    26    36    46    56    66    76    86    96
     7    17    27    37    47    57    67    77    87    97
     8    18    28    38    48    58    68    78    88    98
     9    19    29    39    49    59    69    79    89    99
    10    20    30    40    50    60    70    80    90   100

Embedded Object Examples

The following examples show you some of the details about using write with embedded objects. Also, you can find an example or two for each of the items in the list from the section Using write with Embedded Objects.

When you try to write more elements to the memory space than the space can hold, write ignores the extra elements, storing only the ones that fit. In this example, mm is an object that access a 1-by-10 variable in memory.

• Writing 15 elements to the 1-by-10 array

  write(mm,[1:15])
  

  results in elements 1 through 10 (or [1:10]) being written to memory. Elements 11 through 15 are ignored.

• Writing 5 element to the 1-by-10 array

  write(mm,[1:5])
  

  results in elements [1:5] being written to memory without changing the values in memory for element [6:10].

To write multiple element to different indices in the 1-by-10 array, use multiple write calls.

write(mm,5,6)

writes value 6 to the fifth index in the array. Now to write another value to a different index, use

write(mm,7,9)

which writes value 9 to the seventh element of the array. Trying to use one call like

write(mm,[5 7],[6 9])

to write 6 into index 5 and 9 into index 7 does not work.

Examples That Write Strings

Embedded object mm accesses a 1-by-12 array in memory on the target.

To write a string to target memory, use

write(mm,'Hello World')

which writes 11 characters to memory plus the additional null character at the end of the string.

Notice that the M at the end of the memory space is not affected by the write operation. Now write a new string to memory, such as "Ciao."

write(mm,'Ciao')

After writing to memory, the stored string looks like:

where the fifth element now holds the null character that resulted from writing Ciao to indices 1 through 4, plus the null character in index 5. All the characters after index 5 remain the same. Recall that if you now read the memory, the read operation stops at the first null character and does not return "World" or "M."

See Also

read, symbol

visible

writebin