Version 4 (modified by chunter, 10 years ago) (diff)


These are preliminary instructions for re-creating a working SDK workspace for both the OFDM Reference Design and WARPlab Reference Design. These are subject to change, maybe significantly, as we (and other WARP users) learn the nuances of the SDK. We're eager to hear feedback- ideas to improve these instructions, better ways to package/distribute SDK projects, etc. Please head to the forums to discuss.

Using the Reference Design Archives

Before using a WARP reference design XPS or SDK project you must install the Xilinx tools and configure repository settings:

  • Install Xilinx ISE 13.4 System Edition (includes ISE, EDK, System Generator)
  • Checkout a copy of the WARP edk_user_repository to a local directory
  • Add the WARP edk_user_repository to the global repositories in XPS (Edit->Preferences->Application) and SDK (Xilinx Tools->Repositories->Global Repositories). Close both XPS and SDK.

Project Files

Download either reference design .zip file from the OFDM Reference Design download page or the WARPLab OFDM Reference Design download page?.

The ref design archive includes both the XPS project (i.e. the hardware design) and SDK projects (i.e. the software designs). The archive folder structure is:

 |- SDK_Export/
workspace/ *this folder is intentionally empty for the user to create his or her workspace in*

Using the XPS project

The ref design XPS project is at the root of the expanded .zip file, in the directory with the system.xmp and system.mhs files. Open system.xmp in XPS to explore or modify the XPS project. It is not required to build the hardware project to iterate on software projects. The Xilinx SDK can modify software on top of those downloaded XPS project without needing to rebuild the hardware project.

Using the SDK project

The SDK is based on the idea of workspaces and projects. A workspace contains projects. A normal SDK project contains at least three projects:

  • The hardware specification (auto-generated by XPS)
  • The board support package (auto-geneated by SDK, derived from the hardware spec)
  • Software projects (user code in an SDK-generated template)

We have chosen the approach of having one SDK workspace per XPS project, so the SDK workspace always contains exactly one _hw_platform project and one _bsp project, both referenced to the parent XPS project.

A workspace always maps to a folder on your hard drive. That folder will contain workspace settings (in a .metadata directory) and subdirectories for each project in the workspace.

Unfortunately workspaces are not portable. The ref design .zip file contains all the necessary project files to populate a workspace, but you must initialize your workspace first and import these project files manually. We recommend using the blank workspace folder in the root directory of the XPS project.

In the instructions below we use <xps_proj> to represent the path where you expanded the ref design .zip. If the XPS project file is in C:\work\WARP\OFDM_RefDesign_FPGAv2_v17.0\system.xmp, then you should use C:\work\WARP\OFDM_RefDesign_FPGAv2_v17.0\ in place of <xps_proj> below.

Creating the workspace

  • Launch the Xilinx SDK
    • If prompted to select a workspace, choose <xps_proj>/workspace
    • If not, choose File->Switch Workspace, then choose <xps_proj>/workspace
  • Choose Xilinx Tools->Repositories
    • Verify the WARP edk_user_repository is listed in the Global Repositories section
    • In Local Repositories, click New, then navigate to <xps_proj>. Be sure to select the XPS project folder, not any of the folders above/below that.
    • Click OK
  • Choose File->Import, expand General, choose Existing Projects into Workspace, click Next
    • For 'Select root directory:', click Browse and navigate to <xps_proj>/SDK/SDK_PROJECTS_IMPORT
    • Make sure all projects are selected
    • Make sure "Copy projects into workspace" is checked... this will move them out of the temporary import folder into your workspace
    • Click Finish
  • SDK will begin building the software projects. If everything works, this process will finish with a log message 'elfcheck passed'.
  • In the Project Explorer tab right-click the user software project and choose Generate Linker Script
    • Assign Code Sections to iocm, Data sections to docm, Heap/Stack to xps_bram_if_cntlr_1
    • Change Heap/Stack sizes to 4096 (4K)
    • Click Generate; click Yes to overwrite existing linker script

Running the design Brief instructions, to be elaborated soon
Program the FPGA:

  • Connect the JTAG cable
  • Xilinx Tools->Program FPGA
    • Choose bootloop
    • Click Program
  • Wait ~20 seconds; FPGA Board should now be configured (green DONE LED on, red Radio Board PLL unlocked LEDs on)

Download the software program:

  • Click on the user software project in Project Explorer
  • Choose Run->Run
  • Software should now be running (FPGA Board hex displays on, Radio Board Rx LEDs on, PLL unlocked LEDs off)
  • Connect serial cable (57600bps) to monitor STDOUT

Iterating on software Brief instructions, to be elaborated soon
FPGA only needs to be configured once; software iterations only require re-running the code

  • Make desired changes to source code
  • Verify compilation succeeds (watch for 'elfcheck passed')
  • Click on the desired project, Run->Run; if prompted "Target processor is currently in use", click Yes.

Debugging software Brief instructions, to be elaborated soon

  • Same preparation as running software
  • Choose Run->Debug (instead of Run->Run) to enter debug mode

SDK Hints

Some helpful things we've figured out:

  • Do not power cycle the FPGA Board or disconnect the JTAG/USB cable while SDK is running. Always quit SDK first.
    • If an active SDK session loses the JTAG connection, the JTAG cable will get locked and will fail to function for the current or future SDK sessions. The SDK may freeze in this state. Use Task Manager to kill eclipse.exe and xmd.exe. Then run iMPACT (Programs->Xilinx Design Suite 13.4->ISE Design Tools->32/64-bit Tools->iMPACT), double-click Boundary Scan, choose Output->Cable Reset. Then re-launch SDK to reestablish the JTAG connection.
  • The XMD console view in SDK is useful for debugging issues when communicating via JTAG. Open Xilnx Tools->XMD Console. In the new XMD Console tab, type verbose in the command box (bottom of the tab).
  • Force SDK to prompt for a workspace on every launch (Window->Preferences->General->Startup and Shutdown->Workspaces; check "Prompt for workspace on startup"). We found this is the best way to avoid confusion about what workspace is active.
  • Remarkably, ChipScope Analyzer and the SDK debugger can access the same JTAG cable simultaneously. This can be very useful (i.e. capture PHY state signals via ChipScope to verify what software sees via register reads).
  • Console tabs:
    • You can choose what log is shown in console tabs (little drop down arrow in Display Selected Console button\).
    • You can "pin" a console (Pin Console button), which prevents anything from switching the log source.
    • You can add a console tab, to view multiple logs simultaneously, each pinned to a different source. Having one tab pinned to SDK Log and one to C-Build is useful.
  • Changing the SDK log level to Trace is helpful for debugging odd SDK behavior (Window->Preferences->Xilinx SDK->Log Information Level)
  • If you import a software project from an old workspace into a new workspace, some stale metadata comes with it. You may see an error in the console that says
ERROR:EDK:756 - Cannot read XML file
Error: Creating Hardware Debug Object from ../../old_project_name_hw_platform/system.xml

Here, 'old_project_name' will be the name of the hardware project that you imported from-- not necessarily the name of the hardware project in your current workspace. This name is populated in the properties for your software project under C/C++ Build->Settings->Tool Settings Tab->Xilinx ELF Check->Options->Hardware Specifications. You can manually update that string, or you can simply right click on your software project and 'Change Referenced BSP' then simply hit 'OK'. That's enough for the SDK to reach into the BSP and update that field with the proper string.