Xilinx Demo Documentation 13.1
- 1 Known Problems
- 2 Test Setup for Xilinx 13.1 & 13.2 SDK
- 2.1 Setting up the SDK: Placement of the Treck TCP/IP Library
- 2.2 Setting up the SDK: Creating a Workspace
- 2.3 Setting up the SDK: Project Creation and Source Code
- 2.4 Setting up the SDK: Compiler Optimizations
- 3 Programming the FPGA with the Hardware Description File (.bit)
- 4 Programming the FPGA with the Application File (.elf)
- 5 Running the Application
- 6 Results
- 7 Conclusion
- 8 References
- 9 Revision History
- 10 Notice of Disclaimer
There is currently one known problem with the AXI DMA engine code that is distributed with both the Xilinx 13.1 and 13.2 tools. The 13.1 tools come with axidma v3.00a while the 13.2 tools come with axidma v4.00a.
The fix for axidma v3.00a is the following modification to xaxidma_bdring.c:
/* The last BD should also have the completed status bit cleared */ BdSts &= ~XAXIDMA_BD_STS_COMPLETE_MASK; XAxiDma_BdWrite(CurBdPtr, XAXIDMA_BD_STS_OFFSET, BdSts); /* Flush the last BD so DMA core could see the updates */ XAXIDMA_CACHE_FLUSH(CurBdPtr); + mbar(1); /* This set has completed pre-processing, adjust ring pointers and * counters */ XAXIDMA_RING_SEEKAHEAD(RingPtr, RingPtr->PreHead, NumBd); RingPtr->PreCnt -= NumBd; RingPtr->HwTail = CurBdPtr; RingPtr->HwCnt += NumBd;
The fix for axidma v4.00a is the following two modifications to xaxidma_bdring.c:
/***************************** Include Files *********************************/ #include "xaxidma_bdring.h" + #include "mb_interface.h" /************************** Constant Definitions *****************************/ ... /* The last BD should also have the completed status bit cleared */ BdSts &= ~XAXIDMA_BD_STS_COMPLETE_MASK; XAxiDma_BdWrite(CurBdPtr, XAXIDMA_BD_STS_OFFSET, BdSts); /* Flush the last BD so DMA core could see the updates */ XAXIDMA_CACHE_FLUSH(CurBdPtr); + mbar(1); /* This set has completed pre-processing, adjust ring pointers and * counters */ XAXIDMA_RING_SEEKAHEAD(RingPtr, RingPtr->PreHead, NumBd); RingPtr->PreCnt -= NumBd; RingPtr->HwTail = CurBdPtr; RingPtr->HwCnt += NumBd;
Test Setup for Xilinx 13.1 & 13.2 SDK
There are a couple of ways to get the Treck demo up and running. The first way is to set up an SDK workspace and use the SDK to program the board. This method will allow the user to examine and modify the demo source code, set up compiler optimizations and run the debugger. The method for Setting up the SDK is detailed in the following section.
The second way to run the Treck demo is to download one of the pre-built executables to the board. Using the pre-built executable will allow the user to run the demo application immediately without any setup, only a couple of commands in a bash shell. The obvious disadvantage to this method is that the user won't be set up to modify the application or easily browse the application source. To use the prebuilt executable, follow the directions in the From a Bash Shell section of Programming the FPGA with the Hardware Description File and the Programming the FPGA with the Application File instructions. The board must be programmed with the hardware description file first and then the application file in order to run the demo.
The necessary files for the demo are contained within the demo kit:
Extract the contents of the archive to a folder in the file system.
|Note:||If Windows is being used, the contents of this archive should be extracted to a folder whose path does not contain any spaces. Because the Xilinx tools use Unix emulation, using spaces in file names can cause problems.|
Setting up the SDK: Placement of the Treck TCP/IP Library
Using the Pre-built Treck Library
The Treck TCP/IP software is built as a library and linked with the standalone application at compile time. The EDK tool searches though specific directories to find libraries to build as part of the LibGen process. For the SDK to find the Treck software and include it in the Software Platform settings dialogue, both directories contained in the /treck_demo_virtex6/sw_services and/or /treck_demo_spartan6/sw_services folder(s) must be placed in the proper directory for software libraries,
$XILINX_EDK is the location in which the EDK has been installed and <library_name> is the name of the library (often just "lib"), e.g., C:\Xilinx\13.1\EDK\sw\lib\sw_services for a Windows system or /opt/Xilinx/13.1/sw/lib/sw_services for a Linux system. The directory structure must be correct for the SDK to find the Treck library and allow it to be used in software projects. See the the section on the library generator, LibGen, in the [Embedded Systems Tools Reference Manual (UG111)] for additional details on the directories used.
|Note:||For Linux systems it is important to ensure that the permissions are correct when copying the Treck libraries into sw_services. Check to ensure the user that will be running the SDK has read/write/execute permissions for both of the Treck library folders after they are placed in sw_services. If not, see the Troubleshooting section in this guide for a method to grant the proper permissions to the user.|
After the Treck libraries have been copied to the EDK sw_services directory, if any Xilinx software packages are running, restart them. Unless the Treck TCP/IP stack has been purchased, skip the following section, Building the Treck Library from Source, and go on to Setting up the SDK: Creating a Workspace.
Building the Treck Library from Source
If the Treck TCP/IP stack has been purchased it is possible to avoid the one hour time limit of the demo and compile the Treck library from source. Follow the instructions below.
1. Get the demo up and running using the pre-built library. Technically this step is not necessary, but it will make things easier and it will isolate any problems encountered as being issues with building the Treck library, not setting up an SDK project. The directions will assume that the pre-built libraries have been placed in $XILINX_EDK/sw/<library_name>/sw_services as done in Using the Pre-built Treck Library.
2. Begin by removing or renaming the pre-compiled Treck library, libtreck.a in the /mb directory. For example, for compiling the library to run on the MB under Xilkernel this library should be located in $XILINX_EDK/sw/lib/sw_services/treck_xmk_mb_plb_v2_00_c/src/mb If the .tcl script sees a compiled library it will skip compiling a new library from source.
3. The library will be compiled using source code located in the $XILINX_EDK/sw/lib/sw_services/treck_library_name/src/ directory e.g., treck_xmk_mb_plb_v2_00_c/src/. You should copy the /source, /include and /snmpd (if applicable) directories from your Treck shipment into this directory.
4. It is recommended you retain the compile options from the pre-compiled library. To do this you must overwrite the trsystem.h file included in your shipment with the version used to compile the time-limited library. Using the same example as above, this file can be found in $XILINX_EDK/sw/treck_xmk_mb_plb_v2_00_c/src/mb/include/trsystem.h. To remove the time-limit from the library you can modify this file and remove the following macro definition: TM_DEMO_TIME_LIMIT.
|Note:|| It may be necessary to remove macros for other features in the demo if those features have not been purchased from Treck.
Only leave these defined if you have purchased HTTP:
Only leave this defined if you have purchased SNMP:
#define TM_SNMP_VERSION 2
5. Similarly, you will need to replace the trkernel.c file included in your Treck shipment with one appropriate for your environment. The trkernel.c file originally shipped with your Treck source code is a stub file intended to be replaced or modified by the user. Example kernel integration files can be found in the /source/kernel directory of your Treck shipment. The kernel integration file used to build the time-limited library can be found in $XILINX_EDK/sw/treck_xmk_mb_plb_v2_00_c/src/mb/source. Replace the /source/trkernel.c file in your Treck shipment with the trkernel.c file that comes with the time limited libraries.
6.Finally, clean and rebuilt the Software Platform project. This can be done from the SDK by selecting Project->Clean... This process should take noticeably longer while compiling the Treck stack. If there are problems, the output of the Treck build is put into a file called logs (with no extension). You may view this file to see any compilation errors that may occur.
Setting up the SDK: Creating a Workspace
After the Treck libraries have been placed in the proper location, the SDK can properly import the application code for the demo.
1. Start the SDK. Click browse and select a folder that can serve as the location for a workspace. Any folder will work, but the path for the workspace you choose must not contain any spaces.
Figure 1: Workspace Selection Dialog
2. Click File->New->Xilinx Hardware Platform Specification
Figure 2: New Hardware Project (blank)
3. Click the Browse button and select the system.xml file from the /treck_demo_virtex6/MicroBlaze_Processor_SubSystem/SDK/SDK_Export/hw directory.
Figure 3: New Hardware Project (populated)
Setting up the SDK: Project Creation and Source Code
There are two methods for setting up the projects in the SDK. The first is to import the SDK projects from an archive file included with the demo. This method is the fastest and will require the least amount of interaction with the SDK settings. The second method is to create the projects from scratch. This method will work if there were any problems with the first method or if a more detailed understanding of working with the SDK is desired.
Method 1: Importing Included Projects
1. After the hardware specification file has been loaded and the common_src folder has been placed in the workspace directory, the SDK projects included with the demo can be imported. Go to File->Import... In the first window of the import wizard, choose General->Existing Projects into Workspace and click Next.
Figure 4: Import Wizard
2. On the next screen select Select archive file: and browse to import_these_projects.zip inside of /treck_demo_virtex6/ or /treck_demo_spartan6/. Make sure all of the projects are selected and click Finish.
Figure 5: Import Wizard - Project Selection
3. Allow some time for the SDK to import the projects. After the import wizard is done, it will return to the default perspective in the SDK. There will be compile errors in the two managed make C applications indicated by red "x's" on the project folder icons, those errors will be fixed in the next few steps.
4. The next step is to create a linked folder. This is done through the advanced settings of the regular new folder dialog in the SDK. Right click on treck_xilkernel_demo_0 in the C/C++ Projects view. Go to New->Folder.
5. Click the Advanced >> button to expand the advanced options
6. Click Browse... navigate to the folder containing the current workspace and select the common_src folder that should have been placed in the root of the workspace directory in step 3 of Setting up the SDK: Creating a Workspace.
7. In the folder name: text box, type common_src. Click Finish.
|Note:||For the include paths in the project properties to work correctly, the common_src directory must be in the root of the workspace directory and the linked folder must be called "common_src".|
Figure 6: Creating a Linked Folder
8. Repeat steps 4 - 7 to set up a linked folder in the standalone project. The only difference is to right click on treck_standalone_demo_0 instead of treck_xilkernel_demo_0 in step 4.
9. Wait for the project to recompile. The demo should be ready to send to the board. See Programming the FPGA with the Hardware Description File and Programming the FPGA with the Application File to get the demo running on the FPGA.
Method 2: Creating the Projects from Scratch
If importing the projects included in the archive that came with the demo doesn't work, or a more hands-on approach to setting up the SDK is desired, this method can be used to get the Treck demo up and running on the SDK. Again, this assumes that the Treck libraries (sw_services) have been placed in the proper location, and that a Xilinx Hardware Platform Specification has been loaded.
1. Click File->New->Xilinx Board Support Package.
Figure 7: New Board Support Package Project
2. Choose either xilkernel or standalone and click Finish. You can also change the Project name field, but for the purposes of this example we will assume that the project name is xilkernel_bsp_0 or standalone_bsp_0.
3. When the Board Support Package Settings dialog window appears, you should see the treck_standalone_mb and treck_xmk_mb libraries listed under the Supported Libraries. If you do not see these, then you have either not properly copied the sw_services directory, not set the appropriate permissions on the sw_services directory, or you have not refreshed the available repositories after doing so. To refresh the available repositories, you will need to click the Cancel button to exit the BSP settings dialog, then choose Xilinx Tools->Repositories from the SDK menu, and then click the Rescan Repositories button. After this has finished, you should right-click xilkernel_bsp_0 and choose Board Support Package Settings. This will return you to the BSP settings dialog and allow you to continue. If you still do not see the libraries listed, you may need to restart your computer. If that does not fix the issue, then you either have failed to copy the sw_services directory successfully or have failed to set the appropriate permissions on the library directories.
Figure 8: Board Support Package Settings Overview
4. You will need to choose a Treck library to include in your project. This will include the Treck library in the software platform, allowing Treck function calls in the application. You should only choose one of these. Please choose treck_xmk_mb for the Xilkernel BSP and treck_standalone_mb for the Standalone BSP.
5. After checking the box, select either Overview->xilkernel or Overview->standalone in the left-hand navigation pane of the Board Support Package Settings dialog window.
6. For standalone, you will simply need to modify the stdin and stdout configuration parameters. For xilkernel, you should ensure that the parameters match the ones listed in the following table:
|systmr_freq||100,000,000 (no commas)|
7. After the Board Support Package Settings match the ones in the table above, click OK and wait for the SDK to clean and build the project.
8. After the project has finished rebuilding the newly created Board Support Package, click File->New->Xilinx C Project.
9. In the Select Project Template box, choose Empty Application and click Next. You can also change the Project name field, but for the purposes of this example we will assume that the project name is treck_xilkernel_demo_0 or treck_standalone_demo_0.
Figure 9: New Xilinx C Project
10. Choose Target an existing Board Support Package and select the BSP appropriate for your project. If you are creating a Xilkernel project, use the xilkernel_bsp_0 BSP. If you are create a Standalone project, use the standalone_bsp_0 BSP. Click Finish.
Figure 10: New Xilinx C Project BSP Selection
11. Right click the newly created project in the Project Explorer. Click C/C++ Build Settings.
12. At the top of the Properties dialog, change the Configuration to [ All configurations ].
13. Treck must be added as a library for this project. Under MicroBlaze gcc linker, click Libraries and add treck as seen in the screenshot below.
Figure 11: Set the Library in the MicroBlaze Linker
14. While in the same properties dialog, under MicroBlaze gcc compiler, click Directories. You will need to add two new include paths. In the Add directory path dialog, click Workspace. Here you need to navigate to the following workspace directories, adding each separately:
- For the Xilkernel demo:
- For the Standalone demo:
15. If the project does not contain a src directory, you need to create one. Right-click the treck_xilkernel_demo_0 or treck_standalone_demo_0 in the Project Explorer and click New->Folder. In the Folder name box type src and click Finish.
16. Open /treck_demo_virtex6/TreckDemoSrc/common_src using the operating system's file browser.
17. Select all of the source files in that folder and copy them into the source folder that was just created in the SDK. The files can be dragged directly to the src folder in the SDK window. If the source files are placed into the src folder using the operating systems file browser instead of dragging them directly into the SDK, a refresh will be required for the new files to be recognized (right click the project and select Refresh).
18. Open /treck_demo_virtex6/TreckDemoSrc/xilkernel (if creating the Xilkernel demo) or /treck_demo_virtex6/TreckDemoSrc/standalone (if creating the Standalone demo) using the operating system's file browser.
19. Select all of the src files in that folder and drag them into the source folder that was just created in the SDK. The files can be dragged directly to the src folder in the SDK window. If the source files are placed into the src folder using the operating systems file browser instead of dragging them directly into the SDK, a refresh will be required for the new files to be recognized (right click the project and select Refresh).
20. Wait for the SDK to rebuild the project. If it does not rebuild, you can safely continue.
21. Before the project can be run, a linker script must be generated. Right-click the treck_xilkernel_demo_0 or the treck_standalone_demo_0 and click Generate Linker Script.
22. In the Linker Script Generator window, select DDR3_SDRAM_MPMC_BASEADDR for all three of the drop-down boxes on the right-hand side. Also on the right-hand side, change the Heap Size and Stack Size to 0x4000.
Figure 12: Generate the Linker Script
23. Click Generate and wait for the SDK to rebuild the project. If you are prompted to overwrite the existing linker script, choose Yes. If generating the linker script fails or causes errors in the project the first time, repeat the procedure and try again double checking the settings.
Both applications should now be ready to be run. See Programming the FPGA with the Hardware Description File and Programming the FPGA with the Application File to get the demo running on the FPGA.
Setting up the SDK: Compiler Optimizations
Adjusting the compiler optimizations is not necessary to get the demo running, but it is the only way to get the best performance out of the demo application and the Treck TCP/IP stack. In most cases there will be a noticeable increase in transfer rate for both TCP and UDP performance tests. Also, understanding these SDK features can help to troubleshoot any problems with getting the demo to run on the board properly and introduce new features of the tool set.
The SDK automatically sets up three different build configurations for the project when the Xilinx C Project is created (see step 8 of Method 2: Creating the Projects from Scratch). By default the SDK will be configured to build the demo applications using the Debug configuration. This means that the compiler will not attempt to optimize the code at all. This allows for better communication with the debugger, but comes at the cost of speed. The Release mode configures the compiler to optimize the code for speed, but doesn't include debug symbols, making communication with the debugger impossible. The SDK makes switching between the two build configurations very easy after the initial setup.
To change the build configuration for a Xilinx C Project Application, simply right-click the application in the Project Explorer and select Build Configurations->Set Active->[ Debug/Release ].
To modify a build configuration: 1. Right click the application in the Project Explorer view and select C/C++ Build Settings.
2. Change the Configuration to be either Debug, Release, or [ All configurations ].
3. It is recommended that you change the active configuration to be the configuration you wish to modify before modifying it.
Programming the FPGA with the Hardware Description File (.bit)
Before the application can be run on the board, it must be programmed with the hardware design. There are several ways to program the FPGA with the bitstream file using the Xilinx tool-set. It can be done from the SDK or iMPACT via a bash shell.
From the SDK (.bit)
To program the board from the SDK you will need to have a workspace that contains the correct hardware platform.
1. Open the Xilinx 13.1 SDK and choose a workspace directory. If the workspace already contains the correct hardware platform specification please skip to step 5.
2. Click File->New->Xilinx Hardware Platform Specification
Figure 13: New Hardware Project (blank)
3. Click the Browse button and select the system.xml file from the /treck_demo_virtex6/MicroBlaze_Processor_SubSystem/SDK/SDK_Export/hw directory.
Figure 14: New Hardware Project (populated)
4. Click the Finish button.
5. Now click Xilinx Tools->Program FPGA. The .bit file and .bmm file locations should be auto-populated, but if not they are in /treck_demo_virtex6/MicroBlaze_Processor_SubSystem/SDK/SDK_Export/hw/, the same place system.xml is located.
Figure 15: Program the FPGA from the SDK
6. Click Program to program the FPGA with the .bit file.
From a Bash Shell (.bit)
A bash shell can be opened either through the SDK (Xilinx Tools->Launch Bash Shell), the Windows start menu (Start->Xilinx ISE Design Suite 13.1->EDK->Tools->Xilinx Bash Shell) or by simply opening a terminal window in Linux.
1. Change directories to the /treck_demo_virtex6/ready_for_download directory.
2. Use iMPACT to download the bitstream by using the following: impact -batch download.cmd
Programming the FPGA with the Application File (.elf)
Once the FPGA has been programmed with the bitstream, the application can be sent to the board and and run. Again, this can be done by using the SDK or a bash shell.
|Note:||Before running the application, read the section on Optimizing the PC Network Connection and the Running the Application section of this document for information on setting up the computer to properly communicate over the serial port and Ethernet.|
From the SDK (.elf)
After the SDK has been properly set up as detailed in the Test Setup section of this document, running the program is very straightforward.
1. Expand the Binaries section of the project to be run (either treck_xilkernel_demo_0 or treck_standalone_demo_0).
2. Determine the binary you wish to run, right-click it, and click Run As->Launch on Hardware. You may be presented with a dialog box warning you that the target processor is currently in use by a previous launch. It is safe to terminate the previous launch.
In the Console window, you may see the message:
- Process STDIO not connected to console.
- If you'd like to see UART output in this console, please modify STDIO settings in the Run/Debug configuration.
If you would like to connect the STDIO to the console, perform the following steps:
1. Right-click the project in the Project Explorer (either treck_xilkernel_demo_0 or treck_standalone_demo_0) and click Properties.
2. Select the launch configuration that you wish to modify and click the Edit button, or create a new launch configuration.
3. Under the STDIO Connection tab, check the box next to Connect STDIO to Console and then chose the correct COM port. Set the BAUD Rate to 115200. Click OK. Then click OK to return to the SDK. Follow the steps to run the binary again. This time you should see the STDIO in the console. If you do not see the STDIO in the console, you may need to reload the .bit file or restart your computer.
From a Bash Shell (.elf)
A bash shell can be opened either through the SDK (Xilinx Tools->Launch Bash Shell), the Windows start menu (Start->Xilinx ISE Design Suite 13.1->EDK->Tools->Xilin Bash Shell) or by simply opening a terminal window in Linux.
1. Change directories to /treck_demo_virtex6/ready_for_download.
|Note:||If an .elf file other than the pre-built one is to be downloaded, change to the directory of that .elf file.|
2. Start xmd with xmd.
3. Enter connect mb mdm.
4. To download the .elf file, type dow treck_xilkernel_demo_0.elf or dow treck_standalone_demo_0.elf (or the name of the .elf file to be downloaded).
5. Once the download has completed, run the program with run.
6. The program can be stopped with stop or reset with rst.
Running the Application
Now you can return to Running the Application.
The test results can be found here.
The demo provided demonstrates the versatility and speed of the Treck TCP/IP stack running in many applications utilizing protocols including TCP, UDP, HTTP, FTP, Telnet and SNMP across different software platforms and architectures. The example code not only provides a method for obtaining performance numbers, but serves as an excellent starting point for using the Treck TCP/IP stack in combination with Xilinx hardware and tool-sets. Combined with the Xilinx Tri-Mode Ethernet MAC (TEMAC), the Treck stack is able to achieve exceptional performance in embedded applications.
|05/31/11||1.0||Initial release to wiki.treck.com, demo kit only includes ML605 hardware design for PLB bus.|
|05/31/11||2.0||Added SP605 hardware design for PLB bus.|
Notice of Disclaimer
ALL MATERIALS, INFORMATION, DEMO SOFTWARE, AND SERVICES SET FORTH IN THIS DEMO PACKAGE ARE PROVIDED "AS IS" WITH NO WARRANTY OF ANY KIND. TRECK DISCLAIMS ALL WARRANTIES OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, IMPLIED WARRANTIES OF MERCHANTABILITY, AND FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT. TRECK DOES NOT WARRANT THAT THE CONTENT OF THIS DEMO PACKAGE, OR ANY DEMO SOFTWARE ASSOCIATED THEREWITH, IS ACCURATE, RELIABLE, CORRECT, FREE OF ERRORS OR DEFECTS. YOUR USE OF THIS DEMO PACKAGE IS SOLELY AT YOUR RISK. TRECK AND ITS PARTNERS SHALL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, PUNITIVE, INCIDENTAL, SPECIAL OR CONSEQUENTIAL DAMAGES THAT RESULT FROM THE USE OF THIS DEMO PACKAGE OR DEMONSTRATION SOFTWARE AVAILABLE VIA USE OF THIS DEMO. THIS LIMITATION APPLIES WHETHER THE ALLEGED LIABILITY IS BASED ON CONTRACT, TORT, NEGLIGENCE, STRICT LIABILITY OR ANY OTHER BASIS, EVEN IF TRECK HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.