readmemory

Read data out of AXI4 memory-mapped subordinates

Syntax

data = readmemory(mem,addr,size)

data = readmemory(mem,addr,size,Name,Value)

Description

data = readmemory(mem,addr,size) reads size locations of data, starting from the address specified in addr and then incrementing the address for each word. The function typecasts the data to the uint32 or uint64 data type (depending on the data size of the AXI manager IP). The address, addr, must refer to an AXI subordinate memory location controlled by the AXI manager IP on your FPGA board. The aximanager object, mem, manages the connection between MATLAB^® and the AXI manager IP.

data = readmemory(mem,addr,size,Name,Value) specifies options using one or more name-value arguments.

Examples

Access Memory on Intel FPGA Board from MATLAB

This example shows how to read and write the memory locations on an Intel® FPGA board from MATLAB®.

Before you can use this example, you must have a design running on an FPGA board connected to the MATLAB host machine. The FPGA design must include an AXI manager IP that is customized for your FPGA vendor. The support package installation includes this IP. To include the IP in your project, see the Access FPGA External Memory Using AXI Manager example.

Create an AXI manager object. The object connects MATLAB with the FPGA board and confirms that the IP is present.

mem = aximanager('Intel')

mem =

   aximanager with properties:

            Vendor: 'Intel'
     JTAGCableName: 'auto'

Write 10 addresses and then read data from a single location. By default, these functions auto-increment the address for each word of data.

writememory(mem,140,[10:19]);
rd_d = readmemory(mem,140,1)

rd_d =

   uint32

    10

Read data from 10 locations.

rd_d = readmemory(mem,140,10)

rd_d =

   1x10 uint32 row vector

    10   11   12   13   14   15   16   17   18   19

Read data 10 times from the same address by specifying that the AXI manager read all data from the same address (disabling auto-incrementation).

rd_d = readmemory(mem,140,10,'BurstType','Fixed')

rd_d =

   1x10 uint32 row vector

    10   10   10   10   10   10   10   10   10   10

Write data 10 times to the same address. In this case, the final value stored in address 140 is 29.

writememory(mem,140,[20:29],'BurstType','Fixed');
rd_d = readmemory(mem,140,10)

rd_d =

   1x10 uint32 row vector

    29   11   12   13   14   15   16   17   18   19

Specify the address as a hexadecimal value. Specify for the function to cast the read data to a data type other than uint32.

writememory(mem,0x1c,[0:4:64]);
rd_d = readmemory(mem,0x1c,16,'OutputDataType',numerictype(0,6,4))

rd_d =

   Columns 1 through 10
          0    0.2500    0.5000    0.7500    1.0000    1.2500 ...
                         1.5000    1.7500    2.0000    2.2500
   Columns 11 through 16
     2.5000    2.7500    3.0000    3.2500    3.5000    3.7500

           DataTypeMode: Fixed-point: binary point scaling
             Signedness: Unsigned
             WordLength: 6
         FractionLength: 4

When you no longer need to access the board, release the JTAG connection.

release(mem);

Access Memory on AMD FPGA Board from MATLAB

This example shows how to read and write the memory locations on an AMD® FPGA board from MATLAB®.

Before you can use this example, you must have a design running on an FPGA board connected to the MATLAB host machine. The FPGA design must include an AXI manager IP that is customized for your FPGA vendor. The support package installation includes this IP. To include the IP in your project, see the Access FPGA Memory Using JTAG-Based AXI Manager example.

Create an AXI manager object. The object connects MATLAB with the FPGA board and confirms that the IP is present.

mem = aximanager('AMD')

mem =

   aximanager with properties:

            Vendor: 'AMD'
     JTAGCableName: 'auto'

Write 10 addresses and then read data from a single location. By default, these functions auto-increment the address for each word of data.

writememory(mem,140,[10:19]);
rd_d = readmemory(mem,140,1)

rd_d =

   uint32

    10

Read data from 10 locations.

rd_d = readmemory(mem,140,10)

rd_d =

   1x10 uint32 row vector

    10   11   12   13   14   15   16   17   18   19

Read data 10 times from the same address by specifying that the AXI manager read all data from the same address (disabling auto-incrementation).

rd_d = readmemory(mem,140,10,'BurstType','Fixed')

rd_d =

   1x10 uint32 row vector

    10   10   10   10   10   10   10   10   10   10

Write data 10 times to the same address. In this case, the final value stored in address 140 is 29.

writememory(mem,140,[20:29],'BurstType','Fixed');
rd_d = readmemory(mem,140,10)

rd_d =

   1x10 uint32 row vector

    29   11   12   13   14   15   16   17   18   19

Specify the address as a hexadecimal value. Specify for the function to cast the read data to a data type other than uint32.

writememory(mem,0x1c,[0:4:64]);
rd_d = readmemory(mem,0x1c,16,'OutputDataType',numerictype(0,6,4))

rd_d =

   Columns 1 through 10
          0    0.2500    0.5000    0.7500    1.0000    1.2500 ...
                         1.5000    1.7500    2.0000    2.2500
   Columns 11 through 16
     2.5000    2.7500    3.0000    3.2500    3.5000    3.7500

           DataTypeMode: Fixed-point: binary point scaling
             Signedness: Unsigned
             WordLength: 6
         FractionLength: 4

When you no longer need to access the board, release the JTAG connection.

release(mem);

Input Arguments

mem — Connection to AXI manager IP on FPGA board

aximanager object

Connection to the AXI manager IP on your FPGA board, specified as an aximanager object.

addr — Starting address for read operation

nonnegative integer multiple of 4 | nonnegative hexadecimal value multiple of 4

Starting address for the read operation, specified as a nonnegative integer multiple of 4 or hexadecimal value multiple of 4. The function supports the address width of 32, 40, and 64 bits. The function casts the address to the uint32 or uint64 data type, depending on the AXI manager IP address width. The address must refer to an AXI subordinate memory location controlled by the AXI manager IP on your FPGA board.

Memory-Mapping Guidelines

• If the AXI manager IP data width is 32 bits, the memory is 4 bytes aligned, and addresses have 4-byte increments (0x0, 0x4, 0x8). In this case, 0x1 is an illegal address and emits an error.

• If the AXI manager IP data width is 64 bits, the memory is 8 bytes aligned, and addresses have 8-byte increments (0x0, 0x8, 0x10). In this case, 0x1 and 0x4 are illegal and emit errors.

• If the AXI manager IP data width is 32 bits and you set the 'BurstType' argument to 'Increment', the address has 4-byte increments.

• If the AXI manager IP data width is 64 bits and you set the 'BurstType' argument to 'Increment', the address has 8-byte increments.

• If the AXI manager IP data width is 32 bits and you set the OutputDataType argument to 'half', the function reads the lower 2 bytes and ignores the higher 2 bytes.

• If the AXI manager IP data width is 64 bits and you set the OutputDataType argument to 'half', the function reads the lower 2 bytes and ignores the higher 6 bytes.

• Do not use a 64-bit AXI manager for accessing 32-bit registers.

Example: 0xa4, specifies a starting address of 0xa4.

Data Types: uint32 | uint64

size — Number of memory locations to read

nonnegative integer

Number of memory locations to read, specified as a nonnegative integer. By default, the function reads data from a contiguous address block, incrementing the address for each operation. To disable address incrementation and read repeatedly from the same location, set the 'BurstType' argument to 'Fixed'.

When you specify a large operation size, such as reading a block of DDR memory, the function automatically breaks the operation into multiple bursts, using the maximum supported burst size of 256 words.

Example: 5 specifies five contiguous memory locations.

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: 'BurstType','Fixed' directs the AXI manager to read all data from the same address.

BurstType — AXI4 burst type

'Increment' (default) | 'Fixed'

AXI4 burst type, specified as one of these options:

• 'Increment' — The AXI manager reads a vector of data from contiguous memory locations, starting with the specified address.

• 'Fixed' — The AXI manager reads all data from the same address.

Note

The 'Fixed' burst type is not supported for the PCI Express^® interface. Use the 'Increment' burst type instead.

OutputDataType — Data type assigned to read data

'uint32' (default) | 'uint8' | 'int8' | 'uint16' | 'int16' | 'half' | 'int32' | 'single' | 'uint64' | 'int64' | 'double' | numerictype object

Data type assigned to the read data, specified as one of these options:

• 'int8'

• 'uint8'

• 'uint16'

• 'int16'

• 'half'

• 'uint32'

• 'int32'

• 'single'

• 'uint64'

• 'int64'

• 'double'

• numerictype object

The function typecasts the data read out of the FPGA to the specified data type. double is supported for 64-bit UDP connections only.

Output Arguments

data — Read data

scalar | vector

Read data, returned as a scalar or vector depending on the value you specify for the size. The function typecasts the data to the data type specified by the input.

Version History

Introduced in R2017a

R2023a: Support for half data type

The function reads half data from the memory locations on the FPGA board. The address for the read operation must refer to an AXI subordinate memory location controlled by the AXI manager IP on your FPGA board.

• If the AXI manager IP data width is 32 bits, the memory is 4 bytes aligned, and addresses have 4-byte increments (0x0, 0x4, 0x8). In this case, the function reads the lower 2 bytes and ignores the higher 2 bytes.

• If the AXI manager IP data width is 64 bits, the memory is 8 bytes aligned, and addresses have 8-byte increments (0x0, 0x8, 0x10). In this case, the function reads the lower 2 bytes and ignores the higher 6 bytes.