Main Content

aximanager

Read and write memory locations on FPGA board from MATLAB

expand all in page

Description

The aximanager object communicates with the AXI manager IP when it is running on an FPGA board. The object forwards read and write commands to the IP to access subordinate memory locations on the FPGA board. Before using this object, follow the steps in Set Up AXI Manager.

Note

The aximaster object has been renamed to the aximanager object. For more information, see Version History.

Creation

Syntax

mem = aximanager(vendor)
mem = aximanager(vendor,Name,Value)

Description

mem = aximanager(vendor) returns an object, that controls an AXI4 manager 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®.

example

mem = aximanager(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 'AMD'. This value specifies the manufacturer of the FPGA board. The AXI manager 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', 'PCIe', 'PLEthernet', 'PSEthernet', or 'USBEthernet'. This value specifies the interface type for communicating between the host and the FPGA.

Note

AXI manager supports the PS Ethernet and USB Ethernet interfaces for only the AMD® Zynq® devices.

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 for Intel Boards or Select from Multiple JTAG Cables for AMD Boards.

Dependencies

To enable this property, set Interface to 'JTAG'.

Data Types: char | string

Internet protocol (IP) address of the Ethernet port or USB Ethernet gadget on the FPGA board, specified as a character vector or string scalar representing an IP address. The default IP address for the PL Ethernet or PS Ethernet interface is '192.168.0.2'. The default IP address for the USB Ethernet interface is '192.168.1.2'.

Example: '192.168.0.10'

Dependencies

To enable this property, set Interface to 'PLEthernet', 'PSEthernet', or 'USBEthernet'.

Data Types: char | string

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

Example: '12345'

Dependencies

To enable this property, set Interface to 'PLEthernet'.

Data Types: uint16

Type of JTAG cable used for communication with the FPGA board, specified as 'auto' 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', 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 aximanager 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 aximanager 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 for AMD Boards.

Dependencies

To enable this property, set vendor to 'AMD' and Interface to 'JTAG'.

Specify the JTAG clock frequency, 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 vendor to 'AMD' and Interface to 'JTAG'.

Position of the FPGA in the JTAG chain, 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 vendor to 'AMD' and Interface to 'JTAG'.

Sum of instruction register length for all devices before target FPGA, 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 vendor to 'AMD' and Interface to 'JTAG'.

Sum of instruction register length for all devices after target FPGA, 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 vendor to 'AMD' and Interface to 'JTAG'.

Username to log into the target Linux operating system, specified as a character vector or string scalar. This property applies only when you configure a user account for the custom SD card image files on the target Linux operating system.

Example: 'John'

Dependencies

To enable this property, set Interface to 'PSEthernet' or 'USBEthernet'.

Data Types: char | string

Password associated with the specified username, specified as a character vector or string scalar. This property applies only when you configure a user account for the custom SD card image files on the target Linux operating system.

Example: 'P@ssw0rd123'

Dependencies

To enable this property, set Interface to 'PSEthernet', or 'USBEthernet'.

Data Types: char | string

Object Functions

readmemoryRead data out of AXI4 memory-mapped subordinates
releaseRelease JTAG or Ethernet cable resource
writememoryWrite data to AXI4 memory-mapped subordinates

Examples

collapse all

This example uses:

Open Script

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

This example uses:

Open Script

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

This example uses:

Open Script

This example shows how to select the required JTAG cable from the multiple JTAG cables that are connected to your host computer.

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

h = aximanager('Intel')

Error using fpgadebug_mex
Found more than one JTAG cable:
0 (Max10): #tpt_0001#ptc_0002#210203991642
1 (Arria): #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 AXI Manager
to learn how to set the cable name.

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

h = aximanager('Intel','JTAGCableName','#tpt_0001#ptc_0002#210319789795');

This example uses:

Open Script

This example shows how to select the required JTAG cable from the multiple JTAG cables that are connected to your host computer.

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 = aximanager('AMD','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 AXI manager IP is running. To see the JTAG cable identifiers, attempt to create an aximanager object. The object returns a list of the current JTAG cable names.

h = aximanager('AMD')

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 AXI Manager
to learn how to set the cable name.

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

h = aximanager('AMD','JTAGCableName','#tpt_0001#ptc_0002#210319789795');

Version History

Introduced in R2017a

expand all

See Also

Topics