Main Content

socAXIMaster

Read and write memory locations on hardware board from MATLAB

Description

The socAXIMaster object communicates with the MATLAB® AXI master 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 socAXIMaster 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

example

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

axiMasterObj = socAXIMaster(hw) creates an object that connects to an AXI master IP on the specified hardware board.

axiMasterObj = socAXIMaster(___,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

expand all

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

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

Properties

expand all

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

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.

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.

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.

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.

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

readmemoryRead data from AXI4 memory-mapped slaves
releaseRelease JTAG cable resource
writememoryWrite data to AXI4 memory-mapped slaves

Examples

collapse all

For an example of how to configure and use the AXI master 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 master connection by creating a socHardwareBoard and passing it to the socAXIMaster object. The socAXIMaster 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);
AXIMasterObj = socAXIMaster(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(AXIMasterObj,memRegions.AXI4MasterMemRegion1,inputImage);
writememory(AXIMasterObj,memRegions.AXI4MasterMemRegion2,uint32(zeros(1,x*y)));

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

Create a MATLAB AXI master 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 = socAXIMaster('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)

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 = socAXIMaster('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 master IP is running. To see the JTAG cable identifiers, attempt to create an socAXIMaster object, which, in this case, errors and returns a list of the current JTAG cable names.

h = socAXIMaster('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 master to learn how to set
the cable name.

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

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

Introduced in R2019a