2.3. Vivado SDK Workspace¶
The Xilinx Software Development Kit (SDK) is the primary IDE for writing and debugging 802.11 MAC Software.
Prerequisites¶
Please review the following requirements before using the 802.11 MAC Software.
Vivado Tools¶
Each release of the 802.11 MAC Software is built in a specific Vivado version. No support is offered for using the design with other Vivado versions.
The current 802.11 MAC Software requires Xilinx Vivado 2019.1.
Using the 802.11 MAC Software requires familiarity with the Vivado SDK. Users must be comfortable with the SDK before being productive with the 802.11 FPGA Design.
Xilinx provides extensive Vivado documentation and Vivado training
Project Path¶
The Vivado tools have specific requirements for project paths (folder and file names). There are additional path restrictions on Windows.
- Paths must contain only letters, numbers and simple (ASCII) punctuation.
- Paths must not contain spaces.
- Use short folder names on Windows (max path length is 255 characters; Vivado creates many intermediate files with long names)
MAC Software Archive¶
The Mango 802.11 MAC Software is distributed as a zip archive containing design files and source code. The archive name varies with hardware platform and design version. You must expand the archive to a path following the naming requirements above.
The guide below refers to the expanded archive as mango_802.11_mac_sw_<platform>_<version>
.
The expanded archive has the following structure:
mango_802.11_mac_sw_<platform>_<version>/
├── wlan_bsp_cpu_high
├── wlan_bsp_cpu_low
├── wlan_top_wrapper.hdf
├── wlan_top_wrapper_hw_platform_0
├── wlan-mac-sw
└── wlan-sdk
The wlan_bsp_
folders are the Board Support Package projects tied to the Vivado hardware design in wlan_top_wrapper_hw_platform_0
.
The wlan-sdk
folder contains the SDK project definitions for the MAC software applications. The wlan-mac-sw
folder contains the complete source code for the MAC applications, MAC frameworks, and platform-specific support code:
wlan-mac-sw
├── frameworks
│ ├── common
│ ├── high
│ └── low
├── high_apps
│ ├── linux_dev
│ ├── standalone_ap
│ ├── standalone_ibss
│ └── standalone_sta
├── high_periphs
│ ├── dma
│ ├── eth
│ ├── intc
│ └── timer
├── low_apps
│ ├── dcf
│ └── nomac
├── low_periphs
│ └── rf_ad936x
└── platforms
└── <high/low/common platform support code>
Creating the Vivado SDK Workspace¶
The Vivado SDK stores all source code, tools settings, and compiled applications in a single folder called a Workspace. This guide describes how to create a reference workspace containing the known-good FPGA design and software provided by Mango.
You can have multiple workspaces each with independent hardware designs, source code, and applications. We recommend creating and testing a reference workspace (with unmodified code) first, then creating your own workspaces to experiment with customizations.
The process for creating the SDK Workspace depends on whether you use the FPGA hardware design supplied by Mango, or if you use an FPGA Design you have built locally and exported from Vivado.
Workspace with Reference FPGA Design¶
To create a new SDK workspace using the reference hardware design:
- Launch the Vivado SDK. A window titled
Eclipse Launcher
will appear. Click Browse… and navigate to your SDK workspace folder (mango_802.11_<platform>_<version>
). Click OK. - Select Next. . A new window will appear. In this window, select and click
- In the Import Projects window, ensure the following options are not checked.
Search for nested projects
Copy projects into workspace
Hide projects that already exist in the workspace
- Click Browse… next to
Select root directory:
. Navigate tomango_802.11_mac_sw_<platform>_<version>
and click OK. The list will update to show 8 software projects (listed below). Ensure these 8 projects are checked. Un-check any other projects that might appear, then click Finish. wlan_bsp_cpu_high
wlan_bsp_cpu_low
app_standalone_ap
app_standalone_ibss
app_standalone_sta
app_low_dcf
app_low_nomac
wlan_top_wrapper_hw_platform_0
- Click Browse… next to
- Close the SDK Welcome tab (if shown). The SDK Project Explorer tab will list all 8 projects (one hardware, two BSPs, five applications). Refer to the next section for running the complete 802.11 design in hardware using the SDK Run/Debug tools.
Workspace with Hardware Exported from Vivado¶
To create an SDK workspace from a custom Vivado hardware project:
- Vivado creates a blank SDK workspace during the Export Hardware flow. Follow our Export Hardware to SDK guide first, then locate your workspace folder inside the Vivado project folder (
<proj_name>.sdk
). After completing the guide, the folder contents should have the following folder structure:: - <proj_name>.sdk/
- wlan_bsp_cpu_high
- wlan_bsp_cpu_low
- wlan_top_wrapper.hdf
- wlan_top_wrapper_hw_platform_0
- Vivado creates a blank SDK workspace during the Export Hardware flow. Follow our Export Hardware to SDK guide first, then locate your workspace folder inside the Vivado project folder (
- Download and extract the
mango_802.11_mac_sw_<platform>_<version>
archive that matches the platform of the Vivado project that exported the SDK. - Copy the
wlan-mac-sw
andwlan-sdk
frommango_802.11_mac_sw_<platform>_<version>
into<proj_name>.sdk
(resulting in<proj_name>.sdk/wlan-mac-sw
and<proj_name>.sdk/wlan-sdk
). - Launch the Vivado SDK. A window titled
Eclipse Launcher
will appear. Click Browse… and navigate to your SDK workspace folder (<proj_name>.sdk
). Click OK. - The SDK will open. Look for the Project Navigator tab and verify there are three projects listed. If these projects are not listed, revisit the Export Hardware to SDK guide:
- One hardware project, usually named
wlan_top_wrapper_hw_platform_0
- Two BSP projects named
wlan_bsp_cpu_high
andwlan_bsp_cpu_low
- One hardware project, usually named
- Select Next. . A new window will appear. In this window, select and click
- In the Import Projects window, ensure the following options are not checked.
Search for nested projects
Copy projects into workspace
- In the Import Projects window, ensure the following options are checked.
Hide projects that already exist in the workspace
- Click Browse… next to
Select root directory:
. Navigate to<proj_name>.sdk
and click OK. The list will update to show projects that will be imported. Click Finish. wlan_bsp_cpu_high
wlan_bsp_cpu_low
app_standalone_ap
app_standalone_ibss
app_standalone_sta
app_low_dcf
app_low_nomac
wlan_top_wrapper_hw_platform_0
- Click Browse… next to
- Close the SDK Welcome tab (if shown). The SDK Project Explorer tab will list all 8 projects (one hardware, two BSPs, five applications). Refer to the next section for running the complete 802.11 design in hardware using the SDK Run/Debug tools.
Exploring the SDK Projects¶
Each software project can be accessed in the Project Explorer tab on the left of the screen. If a source file is edited and saved, the SDK will automatically begin to compile all affected projects. If there are no compilation errors the SDK will generate the executable binary (.elf
file) for each software application.
The 802.11 MAC Software design shares code across projects. All source code is stored in the wlan-mac-sw
folder. You can edit code in any project; other projects which share a file will be re-compiled automatically.
The compiler output is displayed in the SDK Console tab. Click on a project in the Project Explorer tab to change which project’s output is displayed in the Console. The Console will report Finished building: <application name>
when the compilation is successful.
Running the Design¶
The SDK includes tools to execute and debug designs running in FPGA hardware. You must define a “Launch Configuration” for each combination of software applications in your SDK workspace.
The Mango 802.11 design archive includes a number of Launch Configurations you can use. To import these:
- Select Next. , then select and click
- Click Browse… then navigate to
<SDK Workspace>/wlan-sdk/launch_config
and click OK.. Thelaunch_config
directory will appear in the window. Check the box next to it and click Finish.
The above image shows the Debug as and Run as. By selecting the arrow next to either option, one of the imported run configurations can be chosen and used to program the hardware platform with the design.
For example, to configure your hardware and run the AP (CPU High) and DCF (CPU Low) applications, click the arrow next to the Run button and select “Configure PL and Run AP+DCF”.