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:

  1. 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.
  2. Select File ‣ Import…. A new window will appear. In this window, select General ‣ Existing Projects into Workspace and click Next.
  3. In the Import Projects window, ensure the following options are not checked.
    1. Search for nested projects
    2. Copy projects into workspace
    3. Hide projects that already exist in the workspace
  4. Click Browse… next to Select root directory:. Navigate to mango_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.
    1. wlan_bsp_cpu_high
    2. wlan_bsp_cpu_low
    3. app_standalone_ap
    4. app_standalone_ibss
    5. app_standalone_sta
    6. app_low_dcf
    7. app_low_nomac
    8. wlan_top_wrapper_hw_platform_0
  5. 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:

  1. 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
  2. Download and extract the mango_802.11_mac_sw_<platform>_<version> archive that matches the platform of the Vivado project that exported the SDK.
  3. Copy the wlan-mac-sw and wlan-sdk from mango_802.11_mac_sw_<platform>_<version> into <proj_name>.sdk (resulting in <proj_name>.sdk/wlan-mac-sw and <proj_name>.sdk/wlan-sdk).
  4. 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.
  5. 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:
    1. One hardware project, usually named wlan_top_wrapper_hw_platform_0
    2. Two BSP projects named wlan_bsp_cpu_high and wlan_bsp_cpu_low
  6. Select File ‣ Import…. A new window will appear. In this window, select General ‣ Existing Projects into Workspace and click Next.
  7. In the Import Projects window, ensure the following options are not checked.
    1. Search for nested projects
    2. Copy projects into workspace
  8. In the Import Projects window, ensure the following options are checked.
    1. Hide projects that already exist in the workspace
  9. 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.
    1. wlan_bsp_cpu_high
    2. wlan_bsp_cpu_low
    3. app_standalone_ap
    4. app_standalone_ibss
    5. app_standalone_sta
    6. app_low_dcf
    7. app_low_nomac
    8. wlan_top_wrapper_hw_platform_0
  10. 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:

  1. Select File ‣ Import…, then select Run/Debug ‣ Launch Configurations and click Next.
  2. Click Browse… then navigate to <SDK Workspace>/wlan-sdk/launch_config and click OK.. The launch_config directory will appear in the window. Check the box next to it and click Finish.
../_images/sdk_debug_run_2017.4.png

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