| MATLAB Link for Code Composer Studio Development Tools | |
Write data to memory on the target processor
Syntax
write(objname) write(objname,index) write(objname,stindex,member1,value1,...,membern,valuen,memindex) write(...,timeout)
Link 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 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. 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.
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. 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.
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 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).
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 timeout 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 timeout 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--232 for the C6xxx processor family and 216 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.
Embedded Object Syntaxes
write works with all of the objects you create with createobj. To transfer data from MATLAB to Code Composer Studio, 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 MATLAB 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.
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.
write(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, write returns all the data stored at the memory location. When you enter a scalar for index, write returns a column vector of length size containing the data from the memory space. When index is a vector, write 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], write 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, write cannot determine which elements to return.
write(objname,stindex,member1,value1,...,membern,valuen,memindex)
reads the members of the structure that objname accesses. When you omit all of the input arguments except objname, write returns the entire structure. membern, valuen, memindex, and stindex (an optional input argument) specify which structure member to read:
membern--specifies the name of the member of the structure to write
valuen--specifies the value to write to membern
memberindex--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 read--numeric values return numeric objects, string values return string objects, and so on.
write(...,timeout)
During write operations, the timeout property of objname determines the time allowed to complete the write. Including a value for the timeout input argument in the write 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 write run to completion. Note that using the timeout input option does not change the timeout property value for objname.
When you need to write one member of a structure or to do individual write operations, consider using getmember.
Notes About 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.
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.
Notes About Writing Strings to Memory
Writing strings to memory has some idiosyncracies. Recall the following points when you use write with string data.
write accepts and writes only characters with ASCII values from 0 to 127 when the charconversion property value is ASCII.
write.
write appends a null character as the last element written to memory, except when
write does not fill the extra space with zeros--no zero padding.
Notes About 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 samples of write in use.
Link Object Examples
Create a link to a target processor and write data to the target. In this example, CCS IDE recognizes one board having one processor.
cc = ccsdsp; cc.visible(1); write(cc,'50',1:250); mem = read(cc,0,50,'double') % 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,[10 10],'double') 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 Notes About 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.
To write multiple element to different indices in the 1-by-10 array, use multiple write calls.
writes value 6 to the fifth index in the array. Now to write another value to a different index, use
which writes value 9 to the seventh element of the array. Trying to use one call like
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
which writes 11 characters to memory plus the additional null character at the end of the string.
| H |
e |
l |
l |
o |
W |
o |
r |
l |
d |
\0 |
M |
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."
After writing to memory, the stored string looks like:
| C |
i |
a |
o |
\0 |
W |
o |
r |
l |
d |
\0 |
M |
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. Alll 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."
| | visible | writemsg | |