function resp = read(id,address,datatype,count,timeout)
%READ Retrieves a block of data values from processor memory.
% MEM = READ(id,ADDRESS,DATATYPE,COUNT,TIMEOUT) returns a block of data
% values from the memory space of the target processor referenced by the id
% object. The blocks to read begins from the processor memory location
% given by the ADDRESS parameter. The data format of the raw memory image
% is specified by the DATATYPE option. Read multiple blocks of data
% values by specifying a COUNT parameter.
% ADDRESS is a decimal or hexadecimal representation of a memory address in
% the target processor. In all cases, the full address consist of two
% parts: the offset and the memory page. Many processors have only a
% single memory page, in which case the page portion of the full address
% should always be 0. The page value can be explicitly defined using a
% numeric vector representation of the address. Alternatively, the id
% object has a default page value that is applied if the page value is not
% explicitly incorporated into the passed address parameter. In
% processors with only a single page, by setting the id object page value
% to zero it is possible to specify all addresses using the abbreviated
% (implied page) format. The address parameter can be specified in two
% ways, first as a numerical value which is a decimal representation of
% the processor address. Alternatively, a string is interpreted as a
% hexadecimal representation of the address offset. (See HEX2DEC, which is
% used for the conversion to a decimal value). When the address is defined
% by a string, the page is always derived from the id object. Thus, there
% is no method of explicitly defining the page when the address parameter
% is passed as a hexadecimal string.
% Examples of the address parameter:
% '1F' Hex, Offset is decimal 31, with the page taken from id.page.
% 10 Decimal, Offset is decimal 10, with the page taken from id.page.
% [18,1] Decimal with page, Offset is decimal 18, with page equal to 1.
% DATATYPE defines the interpretation of the raw values read from the
% processor memory. The data is read starting from ADDRESS without regard
% to type-alignment boundaries in the processor. Conversely, the byte
% ordering of the data type is automatically applied. The following MATLAB
% data types are supported:
% 'double' IEEE Double-precision floating point
% 'single' IEEE Single-precision floating point
% 'uint8' 8-bit unsigned binary integer
% 'uint16' 16-bit unsigned binary integer
% 'uint32' 32-bit unsigned binary integer
% 'int8' 8-bit signed 2's complement integer
% 'int16' 16-bit signed 2's complement integer
% 'int32' 32-bit signed 2's complement integer
% The COUNT parameter defines the dimensions of the returned data block
% (MEM). COUNT can be a scalar value which causes read to return a column
% vector which has COUNT values. Multidimensional reads are possible by
% passing a vector for COUNT. The elements of count define the dimensions
% of the returned data matrix. The memory is read in column-major order.
% COUNT defines the dimensions of the returned data array (MEM) as follows:
% n Read n values into a column vector.
% [m,n] Read m-by-n values into m by n matrix in column-major order.
% [m,n,...] Read a multidimensional matrix of values.
% The TIMEOUT parameter defines how long to wait (in seconds) for the
% read to complete. If this period is exceeded, the routine returns
% immediately with a timeout error.
% MEM = READ(id,ADDRESS,DATATYPE,COUNT) Same as above, except the timeout
% value defaults to the value specified by the id object. Use
% GET(id, 'timeout') to examine the default supplied by the object.
% MEM = READ(id,ADDRESS,DATATYPE) Same as above, except the count value
% defaults to one value of type DATATYPE.
% This routine does not coerce data type alignment. Certain combinations
% of ADDRESS and DATATYPE are difficult for the processor to use. To
% ensure seamless operation, best practice is to use the ADDRESS method to
% extract address values that are compatible with the alignment
% requirements of the processor.
% 1. Read one 16-bit integer 'var'.
% mlvar = read(id,address(id,'var'),'int16');
% 2. Read and plot 100 integers (32-bits) from address 0xF000.
% mlplt = read(id,'F000','int32',100);
% 3. Increment integer value at address 10 (decimal) of target processor.
% mlinc = read(id,10,'int32');
% mlinc = int32(double(mlinc)+1);
% See also GHSMULTI/WRITE, GHSMULTI/ADDRESS, HEX2DEC, INT32.
% Copyright 2012 The MathWorks, Inc.