Xilinx Demo Documentation 14.5
- 1 Test Setup for Xilinx 14.5 SDK
- 1.1 Setting up the SDK: Placement of the Treck TCP/IP Library
- 1.2 Setting up the SDK: Creating a Workspace
- 1.3 Setting up the SDK: Project Creation and Source Code
- 1.4 Setting up the SDK: Compiler Optimizations
- 2 Programming the FPGA with the Hardware Description File (.bit)
- 3 Programming the FPGA with the Application File (.elf)
- 4 Running the Application
- 5 Results
- 6 Conclusion
- 7 References
- 8 Revision History
- 9 Notice of Disclaimer
Test Setup for Xilinx 14.5 SDK
There are a couple of ways to get the Treck Xilinx 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, setup 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 Xilinx 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 setup 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 filenames 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 through 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 dialog, 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\14.5\EDK\sw\lib\sw_services for a Windows system or /opt/Xilinx/14.5/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 and not with 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 $XILINX_EDK/sw/lib/sw_services/treck_(standalone/xmk)_mb_axi4_v6_30_a/src/mb directory. If the .tcl script sees a pre-compiled library at this location 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_(standalone/xmk)_mb_axi4_v6_30_a/src/ directory. You should copy the /source, /include and /snmpd (if applicable) directories and their subdirectories from your Treck shipment into this directory. There are two exceptions to this: see steps 4 and 5 below.
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_(standalone/xmk)_mb_axi4_v6_30_a/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_(standalone/xmk)_mb_axi4_v6_30_a/src/mb/source. Replace the /source/trkernel.c file in your Treck shipment with the file that comes with the time limited libraries.
6. Finally, clean and rebuild 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) located under the BSP folder, in the microblaze_0/libsrc/treck_(standalone/xmk)_mb_axi4_v6_30_a/src folder. 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->Other.
3. Expand the Xilinx section and select Hardware Platform Specification. Click Next.
Figure 2: New Hardware Project
4. 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)
5. Click Finish.
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. Wait for the SDK to rebuild the project. If the SDK does not automatically rebuild the project, simply click Project->Build All.
4. Before the project can be run, a linker script must be generated. Right-click treck_standalone_demo_0 or treck_xilkernel_demo_0 and click Generate Linker Script.
5. In the Linker Script Generator window, select ddr3_sdram_S_AXI_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 or 16384.
Figure 6: Generate the Linker Script
6. 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.
The application 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.
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->Board Support Package
If you see the "No Hardware Platforms in the Workspace" dialog (below), simply click Cancel and proceed with the steps above in the section Setting up the SDK: Creating a Workspace to load a Hardware Platform Specification.
Figure 7: No Hardware Platforms in the Workspace
Otherwise, you will see the dialog for creating a New Board Support Package. Choose either standalone or xilkernel 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 standalone_bsp_0 or xilkernel_bsp_0.
2. When the Board Support Package Settings dialog window appears, you should see the treck_standalone_mb_axi4 and treck_xmk_mb_axi4 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 standalone_bsp_0 or 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
3. 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_standalone_mb_axi4 for the Standalone BSP or treck_xmk_mb_axi4 for the Xilkernel BSP.
4. If you are using Standalone mode, simply skip the next step. If you are using Xilkernel then after checking the box next to treck_xmk_mb_axi4, select Overview->xilkernel in the left-hand navigation pane of the Board Support Package Settings dialog window.
5. Verify that the parameters in the "Configuration for OS: xilkernel" window match the ones listed in the following table. Bold values indicate non-default values:
|systmr_freq||100,000,000 (no commas)|
6. 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. If using Standalone mode, simply click OK.
7. After the project has finished rebuilding the newly created Board Support Package, click File->New->Application Project. Enter a Project name. For the purposes of this example we will assume that the project name is treck_standalone_demo_0 or treck_xilkernel_demo_0. Also, under Board Support Package ensure that Use existing is selected and that the corresponding BSP is selected (if you are creating a Standalone project, use standalone_bsp_0; if you are creating a Xilkernel project, use xilkernel_bsp_0).
Figure 9: New Project: Application Project
8. Click Next. Select Empty Application from the Available Templates section.
Figure 10: New Project: Templates
9. Click Finish to create the new project.
10. 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. Before we do this, however, we need to make sure that the target folder is in the correct location on the hard disk. Verify that the /treck_demo_virtex6_14.5_AXI/treck_demo_virtex6/TreckDemoSrc/common_src folder has been copied to the workspace. You will have to do this manually.
11. Right-click the newly created project in the Project Explorer. Go to New->Folder.
12. Click the Advanced >> button to expand the advanced options.
13. Select Link to alternate location (Linked Folder).
Figure 11: Creating a Linked Folder
14. In the text field next to the Browse button, enter WORKSPACE_LOC/common_src and click Finish. At this point, the SDK may try to build the project, but will fail. This is expected.
15. Right-click the newly created project in the Project Explorer. Click C/C++ Build Settings.
16. At the top of the Properties dialog, change the Configuration to [ All configurations ].
17. 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 12: Set the Library in the MicroBlaze Linker Libraries
18. While in the same properties dialog, under MicroBlaze gcc compiler, click Directories. You will need to add three 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 Standalone demo:
- For the Xilkernel demo:
Figure 13: Set the Library in the MicroBlaze Include Paths
19. Click OK to close the C/C++ Build Settings dialog. At this point, the SDK may try to build the project, but will fail. This is expected.
20. If the project does not contain a src directory, you need to create one. Right-click the treck_standalone_demo_0 or treck_xilkernel_demo_0 in the Project Explorer and click New->Folder. In the Folder name box type src and click Finish.
21. Open treck_demo_virtex6_14.5_AXI/treck_demo_virtex6/TreckDemoSrc/standalone (if creating the Standalone demo) or treck_demo_virtex6_14.5_AXI/treck_demo_virtex6/TreckDemoSrc/xilkernel (if creating the Xilkernel demo) using the operating system's file browser. 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. Make sure to select "Copy files" and not "Link to files" if you drag and drop them. 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).
22. Wait for the SDK to rebuild the project. If the SDK does not automatically rebuild the project, simply click Project->Build All.
23. Before the project can be run, a linker script must be generated. Right-click treck_standalone_demo_0 or treck_xilkernel_demo_0 and click Generate Linker Script.
24. In the Linker Script Generator window, select ddr3_sdram_S_AXI_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 or 16384.
Figure 14: Generate the Linker Script
25. 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.
The application 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 two different build configurations for the project when the Xilinx C Project is created. 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 14.5 SDK and choose a workspace directory. If the workspace already contains the correct hardware platform specification please skip to step 5. Otherwise, follow the instructions in Setting up the SDK: Creating a Workspace
2. 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
3. Click Program to program the FPGA with the .bit file.
From a Bash Shell (.bit) (Linux Only)
1. Open a terminal window.
2. Change directories to the /treck_demo_virtex6/ready_for_download directory.
3. 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 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 setup 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_standalone_demo_0 or treck_xilkernel_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_standalone_demo_0 or treck_xilkernel_demo_0) and click Properties.
2. Choose Run/Debug Settings on the left side of the Properties dialog.
3. Select the launch configuration that you wish to modify and click the Edit button, or create a new launch configuration.
4. 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 9600. 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) (Linux Only)
1. Open a terminal window.
2. 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.|
3. Start xmd with xmd.
4. Enter connect mb mdm.
5. To download the .elf file, enter dow treck_standalone_demo_0.elf or dow treck_xilkernel_demo_0.elf (or the name of the .elf file to be downloaded).
6. Once the download has completed, run the program with run.
7. 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/02/13||1.0||Initial release to wiki.treck.com.|
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.