Main Content

aximaster

Read and write memory locations on FPGA board from MATLAB

Description

The aximaster object communicates with the MATLAB® AXI master IP when it is running on an FPGA board. The object forwards read and write commands to the IP to access slave memory locations on the FPGA board. Before using this object, follow the steps in Set Up MATLAB as AXI Master.

Creation

Description

mem = aximaster(vendor) returns an object, that controls an AXI4 master IP for the FPGA that is running on your board. vendor specifies the FPGA brand name. This connection enables you to access memory locations in an SoC design from MATLAB.

mem = aximaster(vendor,Name,Value) sets properties using one or more name-value pair arguments. Enclose each property name and value in quotes. For example, 'DeviceAddress','192.168.0.10' specifies the internet protocol (IP) address of the FPGA board as 192.168.0.10.

Input Arguments

expand all

FPGA brand name, specified as 'Intel' or 'Xilinx'. This value specifies the manufacturer of the FPGA board. The AXI master IP varies depending on the type of FPGA that you specify.

Properties

expand all

Type of interface used for communication with the FPGA board, specified as 'JTAG' (default), 'PCIe', or 'UDP'. This value specifies the interface type for communicating between the host and the FPGA.

Type of JTAG cable used for communication with the FPGA board (Xilinx® boards only), specified as 'auto' (default) or 'FTDI'. This value specifies the type of JTAG cable used for communication with the FPGA board. 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 aximaster object searches for a Digilent cable. If the object finds:

    • Exactly one Digilent cable, it uses that cable for communication with the FPGA board.

    • More than one Digilent cable, it returns an error. To resolve this error, specify the desired cable using JTAGCableName.

    • No Digilent cables, it searches for an FTDI cable.

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

    • Exactly one FTDI cable, it uses that cable for communication with the FPGA board.

    • More than one FTDI cable, it returns an error. To resolve this error, specify the desired cable using JTAGCableName.

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

  3. If the object finds two cables of different types, it prioritizes the Digilent cable. To use an FTDI cable, set this property to 'FTDI'.

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

  • Exactly one FTDI cable, it uses that cable for communication with the FPGA board.

  • More than one FTDI cable, it returns an error. To resolve this error, specify the desired cable using JTAGCableName.

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

For more details, see Select from Multiple JTAG Cables.

Dependencies

To enable this property, set the vendor input to 'Xilinx'.

Name of the JTAG cable used for communication with the FPGA board, specified as a character vector or string scalar representing a JTAG cable name. 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 more details, see Select from Multiple JTAG Cables.

Data Types: char | string

Internet protocol (IP) address of the Ethernet port on the FPGA board, specified as a character vector or string scalar representing an IP address.

Example: '192.168.0.10'

Dependencies

To enable this property, set the Interface to 'UDP'.

Data Types: char | string

Type of target device, specified as, 'FPGA' (default) or 'SoC'. When you are using a Xilinx Zynq or an Intel SoC as a target device, specify this property as 'SoC'.

Example: 'SoC'

User datagram protocol (UDP) port number of the target FPGA board, specified as an integer.

Example: '12345'

Dependencies

To enable this property, set the Interface property to 'UDP' and the DeviceType property to 'FPGA'.

Data Types: uint16

Specify the JTAG clock frequency (Xilinx boards only), specified as a positive integer. Units are in MHz. The JTAG frequency depends on the type of cable and the maximum clock frequency supported by the FPGA board. Check the board documentation for maximum frequency.

Dependencies

To enable this property, set the vendor input to 'Xilinx'.

Position of the FPGA in the JTAG chain (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.

Dependencies

To enable this property, set the vendor input to 'Xilinx'.

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.

Dependencies

To enable this property, set the vendor input to 'Xilinx'.

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.

Dependencies

To enable this property, set the vendor input to 'Xilinx'.

Object Functions

readmemoryRead data out of AXI4 memory-mapped slaves
release Release JTAG or Ethernet cable resource
writememory Write data to AXI4 memory-mapped slaves

Examples

Access Memory on FPGA Board from MATLAB

Before you can use this object, you must have a design running on an FPGA board connected to the MATLAB host machine. The FPGA design must include an AXI master IP that is customized for your FPGA vendor. This IP is included with the support package installation. To include the IP in your project, see Access FPGA External Memory Using MATLAB as AXI Master.

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

mem = aximaster('Xilinx')
mem = 

  aximaster with properties:

           Vendor: 'Xilinx'
    JTAGCableName: 'auto'

Write and read one or more addresses with one command. By default, the commands auto-increment the address for each word of data. For example, this code writes ten addresses and then reads from a single location.

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

  uint32

   10

Now, read 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 example, this code reads 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 ten 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 =

  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,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)

Select from Multiple JTAG Cables

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

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

If two cables of the same type are connected to your host computer, specify the JTAGCableName property identifier for the board where the JTAG master IP is running. To see the JTAG cable identifiers, attempt to create an aximaster object. The object returns a list of the current JTAG cable names.

h = aximaster('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 the Arty board, specify the matching JTAG cable name.

h = aximaster('Xilinx','JTAGCableName','#tpt_0001#ptc_0002#210319789795')
Introduced in R2017a