Xilinx Demo Documentation 12.3

Jump to: navigation, search

Test Setup for Xilinx 12.3 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, [treck_demo_virtex6.zip]. Extract the contents of the archive to a folder in the file system.


Note 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 folder must be placed in the proper directory for software libraries,

$XILINX_EDK\sw\ThirdParty\sw_services\<library_name>\

$XILINX_EDK is the location in which the EDK has been installed (e.g. C:\Xilinx\12.3\ISE_DS\EDK for a Windows system) and <library_name> is the name of the library found in the zip file, e.g., treck_xmk_mb_v1_00_c. 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 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/ThirdParty/sw_services/<library_name> 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/ThirdParty/sw_services/treck_xmk_mb_v1_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/ThirdParty/sw_services/<library_name>/src/ directory e.g., treck_xmk_mb_v1_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/ThirdParty/sw_services/treck_xmk_mb_v1_00_c/src/mb/include/trsystem.h. After replacing the trsystem.h file found in the shipment with the version used in to compile the time-limited library, you can modify this file and remove the following macro definition: TM_DEMO_TIME_LIMIT.


Note 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:

#define TM_USE_HTTPD

#define TM_USE_HTTPD_CGI

Only leave this defined if you have purchased SNMP:

#define TM_SNMP_VERSION 2


5. Similarly, you will need to replace the kernel interface file (e.g. trkernel.c) 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/ThirdParty/sw_services/treck_xmk_mb_v1_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.

Note Note: The kernel integration file that is provided with the time-limited library may have a different name such as trxmkmb.c. You can identify it because it will contain definitions for functions such as tfKernelMalloc() and tfKernelFree(). If this is the case, simply delete the trkernel.c file that came with the shipment, and copy the trxmkmb.c file from the time-limited library source to the new /source/ directory.


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

Figure 1: Workspace Selection Dialog

2. Click File->New->Xilinx Hardware Platform Specification

FigX: New Hardware Project (blank)

FigX: 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 X: New Hardware Project (populated)

Figure X: 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 3: Import Wizard

Figure 3: Import Wizard

2. On the next screen select Select archive file: and browse to import_these_projects.zip inside of /treck_demo_virtex6/. Make sure all of the projects are selected and click Finish.


Figure 4: Import Wizard - Project Selection

Figure 4: 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. Wait for the project to recompile.

4. If there are compile errors, click Project->Clean, choose Clean all projects, and click OK. After the projects have finished cleaning and recompiling there should be no more errors.

5. 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 X: New Board Support Package Project

Figure X: 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 X: Board Support Package Settings Overview

Figure X: 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:

stdin RS232_Uart_1
stdout RS232_Uart_1
sysintc_spec Interrupt_Cntlr
systmr_spec true
systmr_dev Dual_Timer_Counter
systmr_freq 100,000,000 (no commas)
systmr_interval 10
config_pthread_support true
max_pthreads 10
pthread_stack_size 16384
config_pthread_mutex false
max_pthread_mutex 10
max_pthread_mutex_waitq 10
static_pthread_table
config_sched true
sched_type SCHED_PRIO
n_prio 32
max_readyq 10
config_time true
max_tmrs 10
config_sema true
max_sem 10
max_sem_waitq 10
config_named_sema false
config_msgq false
config_shm false
config_bufmalloc false
copyoutfiles false
config_debug_support false
enhanced_features true
config_kill false
config_yield true


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 X: New Xilinx C Project

Figure X: 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 X: New Xilinx C Project BSP Selection

Figure X: 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 X: Set the Library in the MicroBlaze Linker

Figure 10: 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:
xilkernel_bsp_0/microblaze_0/libsrc/treck_xmk_mb_v1_00_c/src/include
xilkernel_bsp_0/microblaze_0/libsrc/treck_xmk_mb_v1_00_c/src/snmpd
  • For the Standalone demo:
standalone_bsp_0/microblaze_0/libsrc/treck_standalone_mb_v1_00_c/src/include
standalone_bsp_0/microblaze_0/libsrc/treck_standalone_mb_v1_00_c/src/snmpd

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 X: Generate the Linker Script

Figure X: 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 12.3 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

FigX: New Hardware Project (blank)

FigX: 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 X: New Hardware Project (populated)

Figure X: 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 X: Program the FPGA from the SDK

Figure X: 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 12.3->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

Note Note: In Linux, if this command produces "bash: impact: command not found", make sure that the directory containing the impact binary is in the path variable or use the absolute path, making the command /opt/Xilinx/12.3/ISE/bin/lin/impact -batch download.cmd, assuming /opt/Xilinx is where the Xilinx tool-set was installed.


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 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 12.3->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 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.

Note Note: In Linux, if this command produces "bash: xmd: command not found", make sure that the directory containing the xmd binary is in the path variable or use the absolute path, making the command /opt/Xilinx/12.3/EDK/bin/lin/xmd, assuming /opt/Xilinx is where the Xilinx tool-set was installed.

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.


Problems with the Xilinx 12.2 SDK

Please click here for a list of known issues with the 12.2 version of the Xilinx SDK.

When using the Windows version of the Xilinx 12.2 SDK we encountered what we believe is a interrupt controller issue which would cause random lock-ups on the hardware. We were unable to find an appropriate solution to this issue, so we upgraded to the Xilinx 12.3 SDK.


Results

The test results can be found here.


Conclusion

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.

For more information about Treck or purchasing information, visit http://www.treck.com or contact sales@treck.com.


References

XAPP1041: Reference System: XPS LL Tri-Mode Ethernet MAC Embedded Systems for MicroBlaze and PowerPC Processors

XAPP1043: Measuring Treck TCP/IP Performance Using the XPS LocalLink TEMAC in an Embedded Processor System

UG111: Embedded System Tools Reference Guide EDK 12.3

UG535: ML605 Design User Guide

Virtex-6 FPGA Embedded Kit Reference Design and Documentation

OS and Libraries Document Collection (UG 643 April 19, 2010)


Revision History

Date Version Revision
8/19/09 0.9 Draft release to partners.
8/27/09 1.0 Initial release to treck.com, demo kit only includes ML507 hardware design.
1/29/10 2.0 Updated to include SP605 demo.
8/10/10 3.0 Converted to MediaWiki format. All future revision history will be maintained by the wiki.
1/14/10 4.0 Split from main documentation to separate page.


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.