aximanager

Read and write memory locations on FPGA board from MATLAB

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^®.

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

vendor — FPGA brand name

'Intel' | 'AMD'

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

Interface — Type of interface used for communication with FPGA board

'JTAG' (default) | 'PCIe' | 'PLEthernet' | 'PSEthernet' | 'USBEthernet'

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.

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

'auto' (default) | character vector | string scalar

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

DeviceAddress — IP address of Ethernet port or USB Ethernet gadget on FPGA board

character vector | string scalar

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

Port — UDP port number of target FPGA board

'50101' (default) | integer

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

JTAGCableType — Type of JTAG cable used for communication with FPGA board (AMD only)

'auto' (default) | 'FTDI'

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

TckFrequency — JTAG clock frequency (AMD only)

15 (default) | positive integer

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

JTAGChainPosition — Position of FPGA in JTAG chain (AMD only)

0 (default) | nonnegative integer

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

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

0 (default) | nonnegative integer

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

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

0 (default) | nonnegative integer

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 — Username to log into target Linux^® operating system

'root' (default) | character vector | string scalar

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 — Password associated with specified username

'root' (default) | character vector | string scalar

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

readmemory	Read data out of AXI4 memory-mapped subordinates
release	Release JTAG or Ethernet cable resource
writememory	Write data to AXI4 memory-mapped subordinates

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

Select from Multiple JTAG Cables for Intel Boards

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

Select from Multiple JTAG Cables for AMD Boards

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

R2024a: aximaster has been removed

The aximaster object has been removed. Instead, use the aximanager object. In the software and documentation, the terms "manager" and "subordinate" replace "master" and "slave," respectively.

If you use the aximaster object, the object now gives this error message:

aximaster has been removed in 2024a. Use aximanager instead.

R2024a: UDP has been removed

The "UDP" setting of the Interface property been removed. Instead, use the "PLEthernet" or "PSEthernet" values.

If you use the "UDP" value, the object now returns this error message:

UDP interface type has been removed in R2024a. Use PL Ethernet or PS Ethernet instead.

R2024a: PL Ethernet or PS Ethernet replaces Ethernet interface

The "Ethernet" setting of the Interface property is now "PLEthernet" or "PSEthernet" depending on your hardware board.

Using the "Ethernet" value is not recommended. This value will be removed in a future release. If you use the "Ethernet" value, the object now returns this warning message:

Ethernet is replaced by PL Ethernet and PS Ethernet, which are introduced in R2024a. Ethernet will be removed in a future release. Use PL Ethernet or PS Ethernet instead.

R2023b: Support for USB Ethernet

The aximanager object supports the USB Ethernet interface for a Xilinx^® Zynq board. To use this interface, set the Interface property to "USBEthernet".

R2023b: New properties for aximanager object

You can now use the Username and Password properties to log in to the target Linux operating system. These properties apply only when you configure a user account for the custom SD card image files on the target Linux operating system.

Note

The aximanager object supports the Username and Password properties only for SoC boards over an Ethernet or USB Ethernet interface.

For example, you can create an AXI manager object for the Ethernet interface with the Username and Password properties.

aximanager("Xilinx",Interface="Ethernet", ...
Username="John",Password="P@ssw0rd123");

You can still use an AXI manager hardware design that contains an aximanager object that you created in a previous release. The object uses the default value for these properties, which is "root".

R2023b: UDP renamed to Ethernet

The "UDP" setting of the Interface property is now "Ethernet".

Using the "UDP" value is not recommended. This value will be removed in a future release. If you use the "UDP" value, the object now returns this warning message:

UDP interface type has been renamed to Ethernet in R2023b. UDP will be removed in a future release. Use Ethernet instead.

R2023b: DeviceType will be removed

The DeviceType property, which you used to specify the type of target device, will be removed in a future release. If you use this property, the aximanager object now returns this warning message:

Using the DeviceType property is not recommended. This property will be removed in a future release.

R2022a: aximaster renamed to aximanager

The aximaster object has been renamed to the aximanager object. In the software and documentation, the terms "manager" and "subordinate" replace "master" and "slave," respectively.

To create an AXI manager object, use the aximanager object. Using the aximaster object is not recommended and will be removed in a future release. If you use the aximaster object, the object now gives this warning message.

aximaster has been renamed to aximanager in R2022a. aximaster will be removed in a future release. Use aximanager instead.