socAXIManager

Read and write memory locations on hardware board from MATLAB

Description

The socAXIManager object communicates with the MATLAB^® AXI manager IP running on a hardware board. The object uses a JTAG connection to forward read and write commands to the IP and access slave memory locations on the hardware board. Pass an socAXIManager object as an argument when you create an socIPCore object, so that the object can access memory locations within the IP core on the board.

Creation

Description

axiManagerObj = socAXIManager(vendor) creates an object that connects to an AXI manager IP for the specified vendor.This connection enables you to access memory locations in an SoC design from MATLAB.

axiManagerObj = socAXIManager(hw) creates an object that connects to an AXI manager IP on the specified hardware board.

axiManagerObj = socAXIManager(___,Name,Value) creates an object with additional properties specified by one or more Name,Value pair arguments. Enclose each property name in quotes. Specify properties in addition to the input arguments in previous syntaxes.

Input Arguments

vendor — FPGA brand name

'Intel' | 'Xilinx'

FPGA brand name, specified as 'Intel' or 'Xilinx'. The AXI manager IP varies depending on the type of FPGA you have.

hw — Hardware object

socHardwareBoard object

Hardware object, specified as a socHardwareBoard object that represents the connection to the SoC hardware board.

Properties

JTAGCableType — Type of JTAG cable used for communication with FPGA board (Xilinx^® boards only)

'auto' (default) | 'FTDI'

Type of JTAG cable used for communication with the FPGA board (Xilinx boards only), specified as 'auto' or 'FTDI'. This property is most useful when more than one cable is connected to the host computer.

When this property is set to 'auto' (default), the object autodetects the JTAG cable type. The object prioritizes searching for Digilent^® cables and uses this process to autodetect the cable type.

1. The socAXIManager object searches for a Digilent cable. If the object finds:

   • Exactly one Digilent cable –– The object uses that cable for communication with the FPGA board.

   • More than one Digilent cable –– The object returns an error. To resolve this error, specify the desired cable using the JTAGCableName property.

   • No Digilent cables –– The object searches for an FTDI cable (see step 2).

2. If no Digilent cable is found, the socAXIManager object searches for an FTDI cable. If the object finds:

   • Exactly one FTDI cable –– The object uses that cable for communication with the FPGA board.

   • More than one FTDI cable –– The object returns an error. To resolve this error, specify the desired cable using the JTAGCableName property.

   • No FTDI cables –– The object returns an error. To resolve this error, connect a Digilent or FTDI cable.

The cable search in 'auto' mode prioritizes connection using a Digilent cable. If one Digilent and one FTDI cable are connected to the host computer and this property is set to 'auto', the object selects the Digilent cable for communication with the FPGA board.

When this property is set to 'FTDI', the object searches for FTDI cables. If the object finds:

• Exactly one FTDI cable –– The object uses that cable for communication with the FPGA board.

• More than one FTDI cable –– The object returns an error. To resolve this error, specify the desired cable using the JTAGCableName property.

• No FTDI cables –– The object returns an error. To resolve this error, connect a Digilent or FTDI cable.

For an example, see Select from Multiple JTAG Cables.

JTAGCableName — Name of JTAG cable used for communication with FPGA board

'auto' (default) | character vector

Name of JTAG cable user for communication with FPGA board, specified as 'auto' or a character vector. Specify this property if more than one JTAG cable of the same type are connected to the host computer. If the host computer has more than one JTAG cable and you do not specify this property, the object returns an error. The error message contains the names of the available JTAG cables. For an example, see Select from Multiple JTAG Cables.

TckFrequency — JTAG clock frequency

15 (default) | positive integer

JTAG clock frequency, in MHz, specified as a positive integer. For Intel^® FPGAs the JTAG clock frequency must be 12 MHz or 24 MHz. For Xilinx FPGAs, the JTAG clock frequency must be 33 MHz or 66 MHz. The JTAG clock frequency depends on the type of cable and the maximum clock frequency supported by the FPGA board.

JTAGChainPosition — Position of FPGA in JTAG chain (Xilinx boards only)

1 (default) | positive integer

Position of FPGA in JTAG chain (Xilinx boards only), specified as a positive integer. Specify this property value if more than one FPGA or Zynq^® device is on the JTAG chain.

IRLengthBefore — Sum of instruction register length for all devices before target FPGA (Xilinx boards only)

0 (default) | nonnegative integer

Sum of instruction register length for all devices before target FPGA (Xilinx boards only), specified as a nonnegative integer. Specify this property value if more than one FPGA or Zynq device is on the JTAG chain.

IRLengthAfter — Sum of instruction register length for all devices after target FPGA (Xilinx boards only)

0 (default) | nonnegative integer

Sum of instruction register length for all devices after target FPGA (Xilinx boards only), specified as a nonnegative integer. Specify this property value if more than one FPGA or Zynq device is on the JTAG chain.

Object Functions

readmemory	Read data from AXI4 memory-mapped locations
release	Release JTAG cable resource
writememory	Write data to AXI4 memory-mapped locations

Examples

Initialize Memory on SoC Hardware Board from MATLAB

For an example of how to configure and use the AXI manager IP in your design, see Random Access of External Memory. Specifically, review the soc_image_rotation_axi_master.m script that initializes the memory on the device, starts the FPGA logic, and reads back the modified data. This example shows only the memory initialization step.

Load a .mat file that contains structures derived from the board configuration parameters. This file was generated by SoC Builder. These structures also describe the IP cores and memory configuration of the design on the board. Set up a JTAG AXI manager connection by creating a socHardwareBoard object and passing it to the socAXIManager object. The socAXIManager object connects with the hardware board and confirms that the IP is present.

load('soc_image_rotation_zc706_aximaster.mat');
hwObj = socHardwareBoard('Xilinx Zynq ZC706 evaluation kit','Connect',false);
AXIManagerObj = socAXIManager(hwObj);

Initialize the memory contents on the device by loading the figure data and writing it to Region1. The FPGA logic is designed to read this data, rotate it, and write it into Region2. Clear the contents of Region2.

load('soc_image_rotation_inputdata.mat');
inputFigure = smallImage;
[x, y] = size(inputFigure);
inputImage = uint32(reshape(inputFigure',1,x*y));
writememory(AXIManagerObj,memRegions.AXI4MasterMemRegion1,inputImage);
writememory(AXIManagerObj,memRegions.AXI4MasterMemRegion2,uint32(zeros(1,x*y)));

Access Memory on SoC Hardware Board from MATLAB

For this example, you must have a design running on a hardware board connected to the MATLAB host machine.

Create a MATLAB AXI manager object. The object connects with the hardware board and confirms that the IP is present. You can create the object with a vendor name or an socHardwareBoard object.

mem = socAXIManager('Xilinx');

Write and read one or more addresses with one command. By default, the functions auto-increment the address for each word of data. For instance, write ten addresses, then read the data back from a single location.

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

rd_d =

  uint32

   10

Now, read the written data from ten locations.

rd_d = readmemory(mem,140,10)

rd_d =

  1×10 uint32 row vector

   10   11   12   13   14   15   16   17   18   19

Set the BurstType property to 'Fixed' to turn off the auto-increment and access the same address multiple times. For instance, read the written data ten times from the same address.

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

rd_d =

  1×10 uint32 row vector

   10   10   10   10   10   10   10   10   10   10

Write incrementing data ten times to the same address. The final value stored in address 140 is 29.

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

rd_d =

  1×10 uint32 row vector

   29   11   12   13   14   15   16   17   18   19

Alternatively, specify the address as a hexadecimal string. To cast the read data to a data type other than uint32, use the OutputDataType property.

writememory(mem,'1c',[0:4:64])
rd_d = readmemory(mem,'1c',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 are done accessing the board, release the JTAG connection.

release(mem)

Select from Multiple JTAG Cables

When multiple JTAG cables are connected to your host computer, the object prioritizes Digilent cables over FTDI cables. To use an FTDI cable, specify the JTAG cable type property.

h = socAXIManager('Xilinx', 'JTAGCableType', 'FTDI')

If two cables of the same type are connected to your host computer, specify the JTAGCableName property for the board where the JTAG manager IP is running. To see the JTAG cable identifiers, attempt to create an socAXIManager object, which, in this case, errors and returns a list of the current JTAG cable names.

h = socAXIManager('Xilinx')

Error using fpgadebug_mex
Found more than one JTAG cable:
0 (JtagSmt1): #tpt_0001#ptc_0002#210203991642
1 (Arty): #tpt_0001#ptc_0002#210319789795
Please disconnect the extra cable, or specify the cable name as an input argument.
See documentation of FPGA Data Capture or MATLAB as AXI manager to learn how to set
the cable name.

To communicate with this Arty board, specify the matching JTAG cable name.

h = socAXIManager('Xilinx','JTAGCableName','#tpt_0001#ptc_0002#210319789795')

Version History

Introduced in R2019a