| | 1 | {{{ |
| | 2 | #!div class=important style="border: 1pt solid;" |
| | 3 | 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 [//forums/viewtopic.php?id=1379 the forums] to discuss. |
| | 4 | }}} |
| | 5 | |
| | 6 | === Using the OFDM ref design .zip === |
| | 7 | '''Setup'''[[BR]] |
| | 8 | Before using a WARP reference design XPS or SDK project you must install the Xilinx tools and configure repository settings: |
| | 9 | |
| | 10 | * Install Xilinx ISE 13.4 System Edition (includes ISE, EDK, System Generator) |
| | 11 | * Checkout a copy of the WARP edk_user_repository to a local directory |
| | 12 | * 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. |
| | 13 | |
| | 14 | === Project Files === |
| | 15 | Download the reference design .zip file from the [wiki:../Changelog Download page]. |
| | 16 | |
| | 17 | 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: |
| | 18 | {{{ |
| | 19 | SDK/ |
| | 20 | |- SDK_Export/ |
| | 21 | |- SDK_Workspace/ |
| | 22 | data/ |
| | 23 | etc/ |
| | 24 | pcores/ |
| | 25 | platgen.opt |
| | 26 | system.make |
| | 27 | system.mhs |
| | 28 | system.xmp |
| | 29 | system_incl.make |
| | 30 | }}} |
| | 31 | |
| | 32 | === Using the XPS project === |
| | 33 | 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. |
| | 34 | |
| | 35 | 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. |
| | 36 | |
| | 37 | === Using the SDK project === |
| | 38 | The SDK is based on the idea of workspaces and projects. A workspace contains projects. A normal SDK project contains at least three projects: |
| | 39 | * The hardware specification (auto-generated by XPS) |
| | 40 | * The board support package (auto-geneated by SDK, derived from the hardware spec) |
| | 41 | * Software projects (user code in an SDK-generated template) |
| | 42 | |
| | 43 | 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. |
| | 44 | |
| | 45 | 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. |
| | 46 | |
| | 47 | 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. |
| | 48 | |
| | 49 | 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. |
| | 50 | |
| | 51 | '''Creating the workspace''' |
| | 52 | * Launch the Xilinx SDK |
| | 53 | * If prompted to select a workspace, choose {{{<xps_proj>/SDK/SDK_Workspace}}} |
| | 54 | * If not, choose File->Switch Workspace, then choose {{{<xps_proj>/SDK/SDK_Workspace}}} |
| | 55 | * Choose Xilinx Tools->Repositories |
| | 56 | * Verify the WARP edk_user_repository is listed in the Global Repositories section |
| | 57 | * 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. |
| | 58 | * Click OK |
| | 59 | * Choose File->Import, expand General, choose Existing Projects into Workspace, click Next |
| | 60 | * For 'Select root directory:', click Browse and navigate to {{{<xps_proj>/SDK/SDK_Workspace}}} (this path is probably already selected by default) |
| | 61 | * Make sure four projects are checked (CSMAMAC, NoMAC, OFDM_RefDesign_FPGAv2_bsp, OFDM_REfDesign_FPGAv2_v17.0_hw_platform) |
| | 62 | * Make sure "Copy projects into workspace" is unchecked |
| | 63 | * Click Finish |
| | 64 | * SDK will begin building the software projects. If everything works, this process will finish with a log message {{{'elfcheck passed'}}}. |
| | 65 | * Choose File->Import again, expand Run/Debug, chose Launch Configurations, click Next |
| | 66 | * Click Browse and navigate to {{{<xps_proj>/SDK/SDK_Workspace/launch-configs}}} |
| | 67 | * Check launch-configs |
| | 68 | * Check CSMAMAC.launch and NoMAC.launch |
| | 69 | * Click Finish |
| | 70 | * In the Project Explorer tab right-click the CSMAC project and choose Generate Linker Script |
| | 71 | * Assign Code Sections to iocm, Data sections to docm, Heap/Stack to xps_bram_if_cntlr_1 |
| | 72 | * 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) |
| | 73 | * Change Heap/Stack sizes to 4096 (4K) |
| | 74 | * Click Generate; click Yes to overwrite existing linker script |
| | 75 | * Repeat the linker script generation for NoMAC |
| | 76 | |
| | 77 | |
| | 78 | '''Running the design''' ''Brief instructions, to be elaborated soon''[[BR]] |
| | 79 | Program the FPGA: |
| | 80 | * Connect the JTAG cable |
| | 81 | * Xilinx Tools->Program FPGA |
| | 82 | * Choose bootloop |
| | 83 | * Click Program |
| | 84 | * Wait ~20 seconds; FPGA Board should now be configured (green DONE LED on, red Radio Board PLL unlocked LEDs on) |
| | 85 | |
| | 86 | |
| | 87 | Download the software program: |
| | 88 | * Click on the NoMAC project in Project Explorer |
| | 89 | * Choose Run->Run |
| | 90 | * Software should now be running (FPGA Board hex displays on, Radio Board Rx LEDs on, PLL unlocked LEDs off) |
| | 91 | * Connect serial cable (57600bps) to monitor STDOUT |
| | 92 | |
| | 93 | '''Iterating on software''' ''Brief instructions, to be elaborated soon''[[BR]] |
| | 94 | FPGA only needs to be configured once; software iterations only require re-running the code[[BR]] |
| | 95 | * Make desired changes to source code |
| | 96 | * Verify compilation succeeds (watch for {{{'elfcheck passed'}}}) |
| | 97 | * Click on the desired project, Run->Run; if prompted "Target processor is currently in use", click Yes. |
| | 98 | |
| | 99 | '''Debugging software''' ''Brief instructions, to be elaborated soon''[[BR]] |
| | 100 | * Same preparation as running software |
| | 101 | * Choose Run->Debug (instead of Run->Run) to enter debug mode |
| | 102 | |
| | 103 | ---- |
| | 104 | |
| | 105 | == SDK Hints == |
| | 106 | Some helpful things we've figured out: |
| | 107 | |
| | 108 | * Do not power cycle the FPGA Board or disconnect the JTAG/USB cable while SDK is running. Always quit SDK first. |
| | 109 | * 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. |
| | 110 | |
| | 111 | * 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). |
| | 112 | |
| | 113 | * 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. |
| | 114 | |
| | 115 | * 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). |
| | 116 | |
| | 117 | * Console tabs: |
| | 118 | * You can choose what log is shown in console tabs (little drop down arrow in Display Selected Console button\). |
| | 119 | * You can "pin" a console (Pin Console button), which prevents anything from switching the log source. |
| | 120 | * 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. |
| | 121 | |
| | 122 | * Changing the SDK log level to Trace is helpful for debugging odd SDK behavior (Window->Preferences->Xilinx SDK->Log Information Level) |
| | 123 | |
| | 124 | * 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 |
| | 125 | |
| | 126 | {{{ |
| | 127 | ERROR:EDK:756 - Cannot read XML file |
| | 128 | ../../old_project_name_hw_platform/system.xml |
| | 129 | Error: Creating Hardware Debug Object from ../../old_project_name_hw_platform/system.xml |
| | 130 | }}} |
| | 131 | |
| | 132 | 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. |
