wiki:OFDMReferenceDesign/SDK

Version 18 (modified by murphpo, 12 years ago) (diff)

--

These are preliminary instructions for re-creating a working SDK workspace for the OFDM 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 OFDM ref design .zip

Setup
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 the reference design .zip file from the 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/
 |- SDK_Export/
SDK_Workspace/  <- recommended SDK workspace folder
bit/            <- pre-compiled .bit and .bin files
data/           <- design constraints 
etc/            <- build configuration
pcores/         <- custom PHY peripherals
system.mhs
system.xmp

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.

The project archive does not include the intermediate hardware implementation files (the synthesis/, hdl/ and implementation/ folders). These will be re-generated if you initiate the 'Generate Bitstream' process. However, this is not necessary if you only want to iterate on software. For this, refer to the SDK project instructions below.

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 creating your workspace in the SDK/SDK_Workspace subdirectory of the XPS project. This directory already contains the project files for the ref design.

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>/SDK_Workspace
    • If not, choose File->Switch Workspace, then choose <xps_proj>/SDK_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_Workspace (this path is probably already selected by default)
    • Make sure five projects are checked (CSMAMAC, NOMAC, WARPNET_Example, OFDM_RefDesign_FPGAv2_bsp, OFDM_REfDesign_FPGAv2_v17.0_hw_platform)
    • Make sure "Copy projects into workspace" is unchecked
    • 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 CSMAC project and choose Generate Linker Script
    • Assign:
      • Code Sections to iocm (Virtex-4) or ilmb (Virtex-6)
      • Data sections to docm (Virtex-4) or xps_bram_if_cntlr_0 (Virtex-6)
      • Heap/Stack to xps_bram_if_cntlr_1
    • In both the Basic and Advanced tabs confirm nothing is assigned to xps_bram_if_cntlr_2 (this memory maps to the PHY packet buffers)
    • Change Heap/Stack sizes to 4096 (4K)
    • Click Generate; click Yes to overwrite existing linker script
  • Repeat the linker script generation for NoMAC and WARPNET_Example

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

  • Connect the JTAG cable
  • Xilinx Tools->Program FPGA
    • Choose your desired software project (the .elf corresponding to the MAC you want to run)
    • Click Program
  • Wait ~20 seconds; FPGA Board should now be configured (green DONE LED on, hex displays lit)

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
   ../../old_project_name_hw_platform/system.xml
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.


Creating the OFDM SDK Projects

The process for creating the SDK projects discussed above is involved. We wrote it up here: SDK_Project_Creation. These notes are mostly for our future reference in creating new ref designs, but they will be useful if you want to create a custom project with a similar structure (i.e. a workspace with multiple software projects all referencing a common src folder).