!!! warning This content is meant for developers or advanced users and is not meant for general consumption.
-This page discusses the HDL targeting support from the perspective of the HDL source repo and HDL-Coder itself. It is not necessary for users to understand these details but for those managing the toolbox or developers extending support to new platforms this information is valuable.
-This page assumes a basic understanding of MathWork's HDL Workflow Advisor (HWA) and its different steps for creating IP, creating a HDL project, and generating a bitstream.
-When the toolbox is built it will clone a specific branch of the ADI HDL repo and apply certain changes to support the IP-Core Generation HDL-Coder workflow. However, with the current flow there are minimal changes required which makes moving between release simpler. This is currently done by simply replacing certain TCL scripts within the HDL repo.
-Creation of the toolbox, cloning of the HDL source, and applying the necessary update is driven through a Makefile in the CI/scripts folder. The toolbox is built in source form with the build as follows:
- -After the above command completes the HDL source will be in place with necessary changes. -The changes primarily required of the HDL source are interceptions of the build functions (procs) to skip synthesis when building a project. This is done by inserting environmental variable checks into the adi_project_xilinx.tcl script. At build time these environmental variables are set and will prevent synthesis. This way an HDL project can be built, then handed off to HDL-Coder for IP insertion and eventual synthesis.
-HDL-Coder is limited to only interact with Vivado or Quartus. Therefore, it cannot leverage the makefiles as traditionally used to build HDL projects in the HDL repo. HDL-Coder and the authored scripts in the toolbox use the TCL flow normally recommended for just Windows users. This is used on all platforms (Windows and Linux) to support HDL code-generation and integration with ADI toolboxes.
-The orchestration of Vivado and calling of specific TCL scripts is managed through MathWork's HWA. HWA generates HDL (Verilog is currently the only supported language) for specific Simulink blocks, calls a number of TCL scripts maintained by ADI to build a project and make room for IP, then inserts that IP and calls synthesis. This will be discussed from HWA and the generated scripts it creates. This is detailed from the scripting perspective first in the figure below:
-At a high-level there are six main steps, two of which are optional. From the far left stage "Generate Verilog From Simulink IP" occurs in Stage 3 "HDL Code Generation" within HWA as outlined in red below. This will create Verilog within the defined project folder and then be copied into the full HDL project later on.
-
-
Within the largest central block of the flowchart labeled vivado_create_prj.tcl are all the core steps related the HWA Step 4.1, where the reference HDL project folder is built and necessary cores and nets removed to make room for IP from Simulink generated in HWA Step 3. This stage is highlighed in the figure below. The purple boxes are optional stages that are used in certain customized examples when additional work is required to prepare a reference design. The Frequency Hopping example leverages these stages. Once the project is prepared the IP is inserted and bitstream generated, which occurs through HWA Step 4.3.
-
-
Based on the flow in Figure 1, there are a three main states the HDL reference design enters from a high level. These states will be discussed more from the Vivado project perspective, specifically the data path of an FMComms2 project. Other HDL projects will be similar.
-The first state is just the initial creation of the standard unmodified block design. Looking at Figure 4, the three IPs show the dataflow from the interface core (axi_ad9361), through the ADC FIFO, and finally into the pack core. In orange are the data buses and valid signal highlighted. These are important since the generated IP needs to be inserted where these nets are connected. Therefore, in the second state of the design these nets are removed to make room from the new IP.
-
-
Once the IP is inserted into the project by HDL-Coder it is connected to the FIFO and pack cores where the nets in Figure 4 were highlighted. The new inserted and connected IP can be see in Figure 5.
-
-
The connecting of the IPs and insertion are entirely managed by HDL-Coder and through the add_io_ports function and supporting JSON port definition file.
-The following scripts outlined in the figure above have certain purposes:
-{% include 'header.tmpl' %}
-Examples for streaming data and targeting FPGAs are listed within the Toolbox documentation itself. To view run the following with MATLAB:
- -They can also be viewed on GitHub:
- -Certain examples have full articles that discuss different applications
- - - - - - - -{% include 'header.tmpl' %}
- - - -
-
-ADI maintains a set of tools to model, interface, and target with ADI transceiver devices within MATLAB and Simulink. These are combined into single Toolbox which contains a set of Board Support Packages (BSP). The list of supported boards is provided below.
-The following have device-specific implementations in MATLAB and Simulink. If a device has an IIO driver, MATLAB support is possible, but a device-specific MATLAB or Simulink interface may not exist yet.
-| Evaluation Card | -FPGA Board | -Streaming Support | -Targeting | -Variants and Minimum Supported Release | -
|---|---|---|---|---|
| Pluto | -- | Yes | -Yes | -ADI (2018b) MathWorks (2017a) | -
| FMComms2/3/4 | -Zedboard | -Yes | -Yes | -ADI (2018b) MathWorks (2014b) | -
| - | ZC702 | -Yes | -Yes | -ADI (2018b) MathWorks (2014b) | -
| - | ZC706 | -Yes | -Yes | -ADI (2018b) MathWorks (2014b) | -
| - | ZCU102 | -Yes | -Yes | -ADI (2018b) MathWorks (2014b) | -
| ARRADIO | -Arrow SoCKit | -Yes | -No | -ADI (2018b) | -
| ADRV9361-Z7035 | -- | Yes | -Yes | -ADI (2018b) MathWorks (2015b) | -
| ADRV9364-Z7020 | -- | Yes | -Yes | -ADI (2018b) | -
| ADRV9371/5 | -ZC706 | -Yes | -Yes | -ADI (2018b) | -
| - | ZCU102 | -Yes | -Yes | -ADI (2018b) | -
| - | ZYNQ3 | -Yes | -No | -ADI (2018b) | -
| ADRV9002 | -ZCU102 | -Yes | -Yes | -ADI (2020a) | -
| ADRV9009/8 | -ZC706 | -Yes | -No | -ADI (2018b) | -
| - | ZCU102 | -Yes | -Yes | -ADI (2018b) | -
| ADRV9009-ZU11EG | -- | Yes | -No | -ADI (2020a) | -
{% include 'header.tmpl' %}
-The toolbox has different dependencies based on the features required. These are broken down into the base dependencies for data stream and control, and HDL code generation.
-The base dependencies for the toolbox requires libiio and the libiio MATLAB bindings. There are three options for this install with different required MathWorks Toolboxes:
-To leverage HDL-Coder and the reference designs with the toolbox requires the following components:
-The Transceiver Toolbox itself can be installed either from:
- -MATLAB Versions
-Before installing Transceiver Toolbox check the Release Page to check for the lasted supported of MATLAB. The latest version is the one which is available in Add-on Explorer, since Add-On Explorer does not currently support hosting multiple versions. If ypu have an older release of MATLAB, download the MLTBX installer from matching release on the Release Page.
-To install the toolbox from within MATLAB using the Add-On Explorer, first launch the Explorer from MATLAB's Home tab:
-
Search for the toolbox:
- -
Select Transceiver Toolbox from results:
- -
Select add:
- -
{% include 'header.tmpl' %}
-Remote data streaming to and from hardware is made available through system object interfaces, which are unique for each component or platform. The hardware interfacing system objects provide a since class to both configure a given platform and move data back and forth from the device.
-Command and control of hardware from MATLAB is accomplished by leveraging the IIO drivers built into the target platform's kernel and libiio which provides remote backends to control drivers across different backends. Backends can be Ethernet, serial, or USB based. Below is a diagram of the different components in the stack for an FMComms based systems, but will be nearly identical for all transceiver based systems.
-
Since libiio is cross-platform it can be used from Windows, Linux, or macOS based systems. It is also a lower level library independent of MATLAB, so when moving toward production or untethered systems similar APIs that are used in MATLAB can be used in C,C++,Python, or other languages.
-Connecting to hardware is done by setting the uri property of the system object interface. The uri for libiio always has the convention "< backend >:< address >", where backend can be ip,usb, or serial. address will be specific to the backend. This is documented in the libiio API.
-Below is a basic example of setting up an AD9361 receiver using an Ethernet/IP backend where the address of the target system is 192.168.2.1: -
-With the code above, the hardware is not contacted until the operator or step method is called on line 3. Therefore, any properties that are set or defined before line 3 are not applied or updated on the hardware until after line 3. However, after line 3 has completed the object will become locked and certain configuration changes cannot be applied after this point. These will primarily sample rates and buffer sizes. -The state of the object follows the flow of the diagram below triggered by line line 3 above.
-To provide a complete example we can do more advanced configuration like so to demonstrate property changes: -
To receive or capture data from a given device first you must instantiate that device's interface class. For example on a AD9361 based system, this would be as follows:
- -Once instantiated you can configure the number of samples to be captured by setting the property SamplesPerFrame.
- -SamplesPerFrame is the number of samples per channel which will be captured. If your device produces complex data (I and Q) this is the number of complex samples. There will be a limit to the maximum samples which can be collected. By default this is set to 2^20, but it may be possible to make it larger depending on hardware. Once the operator methods are used for a give instantiation, the object will become locked and the SamplesPerFrame property cannot be changed. This is known as a non-tunable property.
-To actually collect the samples or perform the capture, the operator of the system object should be used or the step method as so:
- -Both method calls are equivalent, and the produced matrix data will be of size [SamplesPerFrame x length(EnabledChannels)]. EnabledChannels determines the channels which data will be collected from. EnabledChannels is a [1xN] vector with indexes starting at 1 of the desired channels. If the device transmits or receive complex data, these indexes are for complex channel pairs. For example, the AD9361 has 2 receivers (4 ADC) and setting EnabledChannels as so will capture data from all 4 converters:
- -You cannot enable individual converters on complex data based devices, and the EnabledChannels property is always sorted so the channel mappings cannot be changed within the produced data.
-Transmitting data is very similar to receiving it, a transmitter class needs to be instantiated to send data first. For a ADRV9009 based device this would be as follows:
- -Unlike the receivers, transmit objects automatically create their internal buffers based on the data passed to them during their operator or step methods. These methods can be called as follows with some data:
-tx_data = complex(2^15.*randn(1024,1),2^15.*randn(1024,1));
-tx(tx_data); % Operator method
-tx.step(tx_data); % Step method
-However, once the step or operator method is called the object becomes locked and future passed data vectors must be the same length. As with the receive classes, the size of the passed data must be [SomeFixedSize x EnabledChannels]. EnabledChannels has the same definition as the receive side, except applied to DACs.
-Unlike the receiver, transmit objects have the ability to utilize cyclic buffers which will continuously transmit a provided vector without gaps forever. To utilize cyclic buffers set the EnableCyclicBuffers property then pass the operator data as follows:
-tx = adi.ADRV9009.Tx;
-tx.EnableCyclicBuffers = true;
-tx_data = complex(2^15.*randn(1024,1),2^15.*randn(1024,1));
-tx(tx_data); % Data will repeat forever
-One a vector is passed to the object with EnableCyclicBuffers set to true, the object will not accept future buffers unless first release or cleared.
-By default the system objects will utilize DMA as the source of data for the DACs, which will use data past from the operator. This can be set manually through the DataSource properties as follows:
- -Instead of providing data for transmission, it is possible to utilize DDSs inside the FPGA to send tones to individual DACs. For specific boards there are two DDS per DAC, which can be used to create complex (one-sided) tones. These DDSs can be used by first setting the DataSource property:
- -Then the scale, frequency, and phase of each DDS can be controlled through three attributes as follows:
-rx.DDSFrequencies = [1e3,1e3,1e3,1e3;1e4,1e4,1e4,1e4]; % Must be range [0 FS/2]
-rx.DDSScales = [1,1,1,1;0,0,0,0]; % Must be range [0,1]
-rx.DDSPhases = [0,90e3,0,90e3,0,0;0,0,0,0]; % Each in millidegrees [0,90000]
-Each of the above properties must be of size [2x(NumberOfPartDACs)], where each row is the first DDS of a given DAC (column) and the second row is the second DDS of a given DAC (column).
-{% include 'header.tmpl' %}
-Transceiver Toolbox supports the IP Core generation flow from MathWorks which allows for automated integration of DSP into HDL reference designs from Analog Devices. This workflow will take Simulink subsystems, run HDL-Coder to generate source Verilog, and then integrate that into a larger reference design. The figure below is a simplified block diagram of a SoC (Fabric+ARM) device, where specialized IP are inserted into the receive and transmit datapaths. This is supported on specific FPGA families and transceiver based reference designs. This support is based on the Zynq HDL-Coder and support
-