LOGI Guide - Your First Project using Xilinx ISE
This guide will take you through the steps necessary to create your own FPGA HDL projects that can be used to create your own custom FPGA configuration files. This guide is intended to be used for the LOGI Pi and the LOGI Bone, as the steps are identical. There will be minor differences when creating the UCF fies and moving the bitstreams to the FPGA to be run between the LOGI Pi and LOGI Bone boards.
Xilinx ISE is a free IDE tool suite used to create and synthesize your HDL projects to be used on the LOGI Boards. We will walk you through creating your first blink led project to input some custom HDL and synthesize the code to the bitfile that will be loaded from the FPGA.
You can access the source code for thsi project in the logi-projects repository.
Setup Your Development Environment
Development for the Spartan 6 target is done in Xilinx’s ISE development environment (ISE loosely means Integrated Software Environment). As of this writing, Xilinx is on ISE version 14.5. Go here to start downloading it. If you have a slow or unreliable, intermittent connection you might want to download the file in parts. If you have a “rippen” broadband connection, shoot the moon and go for the full DVD, single file download.
When the file is finally done downloading you will need to extract the contents to your hard drive, as your download comes in a .tar archive format. If you’ve never used .tar archives there is a pleasant little open source program you should have a look at: 7Zip. It’s an archiving software tool that you can use to extract the files. Once you’ve extracted the contents of the .tar file you will see “xsetup.exe” under the extracted files’ root folder. Run this installer program and follow the on screen instructions. A “typical” installation will suffice.
When the installation completes, open the Xilinx ISE. The ISE download comes with the “full” version of the software. However, your computer will not have licenses to enable the various features Xilinx offers. Therefore, you need to get your own license file before you continuing.
Go to the Xilinx website and create a user account. Yes, needing a user account might seem like overkill if you’re a new user, but what you will find is your user account gives you access to many useful design resources. With a Xilinx user account you can watch training videos, use the forum, get updates and add-on software and get license files – it’s totally worth it.
Xilinx offers many different licensing tiers. We will be using the free “WebPack” license. This enables enough software features to get us started. The WebPack allows your software to compile and you can use most of the basic Xilinx development tools.
In ISE, navigate to the “Help” toolbar on the top of the screen and choose “Manage License.” Under the “Acquire License” tab, select the “Get Free ISE WebPack License” radio button and click Next.
Figure – Xilinx License Configuration Manager
The software will gather some unique information about your machine and then give you the option to “Connect Now.” Click it:
Figure – Unique Computer Info Tied to WebPack License
At this point the software will open your web browser and bring you to the Xilinx site. It will ask you to login with your user account. Do it and follow the on screen instructions. Once you complete the on screen steps Xilinx will email you a license file with the file extension .lic. Save this .lic attachment somewhere safe. The ISE installation directory would suffice. The email also contains instructions on how to install the license.
Essentially all you need to do is open the Xilinx License Configuration Manager again, click the Manage Xilinx Licenses tab, and click Copy License. This will open a dialog that lets you find and select the .lic license file you downloaded from your email. Select it and click Ok. Under the Manage Xilinx Licenses tab the table should now be populated with details about what features of the software is enabled by your WebPack license. Congratulations, your software is setup and ready to go!
Create Your First Project
In this tutorial we will be using the LOGI Pi hardware to create a working VHDL Blink LED design, though the steps are identical when using the LOGI Bone. We will keep the physical goals simple in order to demonstrate the basics. In the following example, the LOGI-Pi’s will simply blink some LEDs. Thrilling, absolutely yes, but it’s an invaluable exercise none the less. Let’s begin with creating our “Project” file in the ISE Project Navigator.
In the Xilinx ISE, like many other engineering programs, users create “Projects” to save all aspects of their design. FPGA designs often consist of many files of many different file types. The Project encapsulates everything and serves as a means to easily manage all the FPGA’s design files. (Project files contain references to many support files like the source code files and configuration files. They have a .xise file type.).
To create a project for this tutorial, open the Xilinx ISE Project Navigator. Under the File menu, choose New Project… you should see the New Project Wizard open. Choose some file paths and a name for your project (it is recommended each of your projects be put in its own folder to contain all the design files in one place):
Figure – The New Project Wizard
After clicking next you will find the project’s settings page. You can use the settings shown below for the LOGI Boards. These settings can be changed at any time later on. This wizard page is designed to let you choose important software environment settings from lists of possibilities.
For example, it is on this dialog where you specify what chip you’re designing for, the speed grade, and physical package. You also set which software toolchain and HDL language you prefer. We’ll touch on what the common tools are and why they are used shortly.
Figure – Project Settings
The last page is a summary of your chosen settings displayed in plain text. Click Finish and you will be brought into the ISE Project Navigator development environment. You are now ready to add content to your design.
Add Some LOGIc to Your Project
Take some time to look around the software. The Project Navigator has a clean looking layout and there can be an enormous density of information displayed at once. Windows users will be familiar with the standard set of menu items located across the top of the screen; File, Edit, View, Project, Source, Process, Tools, Window, Layout and Help all contain items that fit their respective categories – as is tradition. The rearrangeable buttons across the top are concise and self-explanatory as well.
In the default workspace view, the top left pane shows the Project’s “Hierarchy.” This tree view shows the relationship between various HDL modules in the design. You can use this pane to add or remove HDL files from the project. Let’s start by adding your design’s top level HDL file.
Figure – An Empty Design in the Hierarchy View
FPGA designs are often designed in a tree structure of “modules.” Modules are blocks of logic that encapsulate some discrete, unique part of a design. The blue link describes encapsulation in the context of object-oriented programming but really the term is effective in a broader sense; HDL modules are can be thought of as “layers” that encapsulate the logic of some abstract but compartmentalized piece of circuitry.
To add a top level HDL file, right click the target chip in the Hierarchy view (denoted by the model, xc6slx9…) and choose New Source. This will bring up a view that allows you to add a design file to your project. There are many different types of files you can choose here but for this instruction we will have you load a new “VHDL Module.” Give it a name and click Next.
Figure – New Source Wizard
By clicking next you are presented with a GUI that lets you define the module’s input and outputs. It’s convenient to think of VHDL HDL modules as chips on a circuit board. Typically a chip has a number of pins that are either inputs or outputs. This GUI lets the user specify names for the module’s IO, then, when the VHDL file is generated and added to the project it will contain definitions for these IOs. Setup your VHDL module like the picture below. Note that you don’t need to specify these IO locations as being buses or what their most or least significant bit is – all of these IO locations are just one bit (or wire, depending on how you view the world).
Figure– A Top-Level VHDL Module’s IO Definition
In the Hierarchy view you will see a new VHDL source file called “logi_blink.vhd”. “.vhd” is the file extension for VHDL files. Double click it and its contents will be shown in the text editor on the pane to the right. Here is what you should see:
You will notice that the VHDL syntax is highlighted. Things marked in green are comments, blue are VHDL language keywords and the pink at the top used to denote the module’s language type keywords.
At this point you have your top-level VHDL module defined and all you need to do is add logic to it. The module has one input clk signal and two output bits. One could even think of these as wires coming in and going out of our module. We will use the “OSC_FPGA” input bit to define a system clock signal. This signal will be used to turn over the logic on a specific time base.
The “LED(0)” and “LED(1)” represent the wires going out to LED0 and LED1 on the PCB.
What we’re going to do with these signals is ground breaking. The goal is to simply blink the LEDs at a defined timebase and LED0 will be illuminated and LED1 will toggle from on to off based on this time base.
Add a few lines of code to your design as shown below:
Figure – VHDL Code for Example Design
So What Does This Simple Program Do?
The goal of this document is to get the user on their feet, not to teach VHDL. If you are really interested in learning VHDL see the section at the end called Where To Go From Here. That said, here is a quick description of what’s going on.
For specific details on how this project works and see the LED Blink LOGI project Documentation page on the wiki.
For details on how the surrounding hardware is connected to the FPGA consult the LOGI-Pi schematic or the LOGI-Bone Schematics. Within github you select the board version schematic you want to access then select "raw" on the tab to download the schematic pdf file.
Constraining the Design
In the previous section we described a simple module that toggles the LED based on an incrementing counter driven by the 50 Mhz Oscillator. The VHDL that describes the circuit is simple. It was entirely defined in one top-level module with one input and two outputs. What we didn’t describe is how this simple design links the module’s inputs and outputs to physical IO points on the FPGA.
This is where the “Implementation Constraints File” comes in. These files have a .ucf file extension and describe the design’s “user constraints.” Design constraints are a set of rules that the compilation process needs to take into account when building the design’s binary output file. This “.bit” file is output by the compilation process and is the file that gets downloaded and run on the FPGA.
Some examples of types of things that can be constrained in an FPGA design are:
Mapping and Routing constraints (or directives)
Physical pin assignment
User constraint files can vary dramatically in complexity and detail. The topic is very vast and discussing it is outside the scope of this document.
Given there is a huge amount of information to know surrounding how to constrain designs, fortunately for us, our design only needs to constrain a handful of items to work properly (this design is so simple we’re also not going to worry about enforcing any timing constraints). All that we need to do is to define what hardware pins our top-level VHDL module’s inputs and outputs link up to. We also give some details about the design’s clock input OSC_FPGA.
Using the New Source Wizard to create User Constraint file (UCF)
Start by adding a constraints file to the project. Right click anywhere in the project Hierarchy view and choose New Source. This time, select Implementation Constraints File, give it a name and choose Next:
Figure– Add a new constraints file to the design
A Summary window will appear. Click Finish. Now in your project Hierarchy view you will see a new “.ucf” file. Double click it. The Text Editor view on the right window pane will show your file is totally empty. Add the following code to it then we will discuss what each piece means:
Figure – Implementation constraints file for the LOGI Pi - Use the LOGI Bone code
As is tradition, the green denotes comments and the language syntax are highlighted appropriately. Thank goodness for modern IDE’s… and remember that end each statement with a semicolon! The 12th line defines a “net” called OSC_FPGA and its TNM_NET parameter gets the name clk50_grp. TNM_NET is a keyword used for defining a design’s clock signals. Again, there are many keywords that can be used in an infinite number of ways in these constraints files. Don’t worry about the details of this line until you take the time to actually study more advanced FPGA principles such as Timing Closure or consult a recent copy of the official Xilinx Constraints Guide.
After the OSC_FGPA net declaration is a new TIMESPEC definition. This constraint essentially calls out how fast our OSC_FPGA clock signal is. A 20 nanosecond clock period means the clock is running at 50MHz. You’re free to research exactly what this keyword means but for our purposes, feel free to regard this line as magic.
Lines 22 through 24 define some new nets and use the LOC keyword to assign them to the FPGA’s physical pins. This is how we link our top-level VHDL module’s inputs and outputs to physical pins on the IC. The names of these nets must be identical to the names of your module’s input and output ports! The pin number can be found by referencing the electrical schematic.
Figure– LOGI Pi Schematic - Newer board versions and the LOGI Bone pins will vary
Here you can see all the connections to the Banks of our FPGA. You can see wires connecting the LEDs and the OSC pins.
For example our design uses LED0 and LED1. These LEDs are connected to pin 105 and 104 for LOGI Pi R1 and pin 140 and 74 for the LOGI Bone. BE SURE TO CHECK YOUR BOARD VERSION PIN CONSTRAINTS IF NOT USING THE LOGI PI R1. In our constraints file we can see that we’ve called out the net LED0 to land on “P105” for the LOGI Pi using the LOC keyword. We use the same syntax to provide the pin locations for LED1 and OSC_FPGA. You can use the LOGI board schematic to find these pins and other pins that you want to use in your project.
LOGI Master UCF files
You can also find master UCF files that have all the of the board pins already specified. The LOGI master UCF files can be located in the LOGI hardware repository.
Build Your Project
We’re almost done! Phew! All that’s left is to compile the design and then we’re ready to run. If you’ve followed the directions above carefully this step should be simple!
The final step is for the Xilinx software toolchain to take all of your design files and compile them into one single “bit-stream” file, or “binary” file as its often called. With a file type of .bit, this is the file that gets downloaded to the FPGA and run. Remember, at power up, an FPGA doesn’t have a program loaded onto it. The vast arrays of programmable logic blocks in an FPGA need to receive a configuration before the chip does anything useful. Once configured, the FPGA starts executing your program.
There are a handful of software build steps that need to be complete for the toolchain to output a bit-stream file. Novels have been written about each topic but here’s a rapid summary:
Synthesize – This step is where the Xilinx XST tool converts HDL logic into a gate-level netlist. This low level netlist is represented in terms of the UNISIM component library. If your HDL code has syntax errors this step will not complete. Fortunately, the Output window pane at the bottom of the ISE will tell you where the error is.
Implementation – This step converts the gate-level netlist into a placed and routed design that fits on the chip selected. This is composed of three discrete parts.
Translate – The NGDBUILD software tool is used to translate the netlist from using the UNISIM library to the SIMPRIM library.
Map – the MAP software tool is used to take the SIMPRIM primitives and decide how the chip’s physical resources (flip-flops, BRAMs, Multipliers, LUTs etc.) will be used.
Place and route – the PAR software program runs a lot of computation to layout where all the chips resources will be used and how the design components get placed, routed and interconnected.
Generate Programming File – The final step takes the output from the previous steps and puts them together into a single binary that can be used to program the device.
The ISE Project Navigator has an entire window pane dedicated to this process. This is because when designs get very large these discrete steps can take hours! An engineer would not like to have to re-run every step of the compilation process if it’s not necessary.
The following view can be used to explicitly run individual steps of the build process and see the status of what’s currently running or even what’s failed (note in order to see the following view you must have the LOGI-PiStarter_TopLevel.v file selected in the Hierarchy view:
Figure – The Process View
Simply click the little green play button in the top left corner to compile the whole design. On a modern computer this should take less than 1 minute to run for this project. If the process completes without any errors or warnings you will get green check boxes next to the major steps in the compilation process. There are often warnings that are given that give feedback to the designer about possible conflicts in the design. You should always read any warnings received before using the synthesized .bit file. In our case of synthesizing the project there are some errors reported in regard to not using all of the “counter_output” bits of the vector. We are safe to ignore the warnings in this case.
Figure– A Successful Build
Also you will note the Console view pane on the bottom of the ISE will show output like the following:
Figure– Console Output at the End of a Successful Build
Chances are you’re going to make a mistake at some point along the way. If not in this tutorial, someday, you will make a mistake and get a compiler error, sorry. In this case one of your build steps will have a red X next to it. The X isn’t entirely helpful to a beginner. It does tell you which build step failed and to the trained developer this can greatly narrow the scope of what’s gone wrong. More often though you will immediately query the error log to find out what’s going on.
For example, if you try to recompile your design without the semicolon at the end of the “counter_output” signals declaration. If you try to re-synthesize your project you get the following error. Note it does not explicitly state that there is a semicolon missing, but you can infer that the error came just before the “begin” statement.
Figure – Syntax Error Found During Synthesis
If you get errors, don’t fret. This is normal. It happens all the time. Read the error message carefully and try to understand what the compiler isn’t happy about. Non-developers tend to forget this, but error messages are designed to point you to the problem so you can resolve it! Imagine a world without error messages!
You will find that when you’re new to a programming language, working through compiler errors teaches you about what’s allowed and what’s not allowed slowly, but effectively. However, in general, it’s advisable to save yourself some headache, buy or find a beginners book online on the language and power through it before taking on any serious projects.
Run Your Project
If you’ve gotten this far it means you’ve created your very own FPGA design in the Xilinx ISE. You’ve added a VHDL module to the design, constrained it, compiled it and now you’re ready to run it!
But before you do you need to generate the programming “binary” file that gets downloaded to the target. Simply double click the build step called “Generate Programming File” in the Process view (it’s directly under Place & Route).
When this finishes successfully, open Windows Explorer and navigate to the folder where you’ve saved your project files. In this folder you will see a .bit file with the same name as your top-level module, “logi_blink.bit” in this tutorial’s case.
This bit file can be used to configure the FPGA as described in the next section Moving your synthesized bitfiles to your Raspberry Pi
Moving your synthesized bitfiles to your LOGI Board
Note that the below steps show how to transfer your bitfile to the Raspberry Pi. The steps for the BeagleBone are the same. You can see the LOGI Bone User manual or Quick Start Guide for exact steps.
After synthesizing your own HDL projects for the LOGI-Pi the user will need to move the bitfiles to the Raspberry Pi to be loaded onto the FPGA. The most direct method of transferring the bitfile is to use an SCP client connected from you host PC to the Raspberry Pi. Alternatively you could can use git to access your bitfiles from a remote repository.
You will need to know your Raspberry Pi’s assigned IP address as detailed in the previous section. You can then use SSH Secure File Transter client which was installed along with the SSH Secure Shell Client. If you have not already instaleed SSH Secure Shell Clent you can download and install from the following or similar download links.
1) Run the Secure Shell Transfer Client
2) Click the Quick Connect Button
3) Enter the IP address of your network connected Raspberry Pi
4) Enter the username and password for your logi-image,
Username and Pass for Raspberry Pi Raspbian Image: User: pi Pass: raspberry
Username and Pass for BeagleBone using DEBIAN: User: debian Pass: temppwd
Username and Pass for BeagleBone using UBUNTU: User: ubuntu Pass: temppwd
Use the default Port number 22. Then press the “Connect” button.
SCP LOGIN for the Raspberry Pi
5) Browse to the bitfile locations on your PC (Local Director browser pane) and your Raspberry Pi (Remote Directory browse pane).
SCP Connection for the Raspberry Pi
6) You can now use click on the “new terminal window” button to bring up a command line terminal to browse to the location and file and use the logi_loader to load the file LOGI-Pi as needed.
Transferred bitfile for the Rapsberry Pi
7) Use the logi_loader to load the FPGA with the .bit file
You should get the output from the logi_loader giving you statistics on loading the bitstream and now see the LEDs blinking on your LOGI Board!
Note if you have problems connecting to your Raspberry Pi or loading the fpga using the logi_loader see the previous sections for more details on how to do this.
Where to Go From Here
There are many places you can go from here. You’ve successfully programmed an FPGA and now the sky is the limit. Have a look over the following sections to see what else is possible with the LOGi-Pi platform.
Visit Hamster's Wiki to access his FREE FPGA course and Projects
Hamster has an excellent open source and free course that you can access on his wiki. Hamster has some of the best material I have come accross and most importantly gives full explanations and background of his projects.
Read Pong P. Chu’s Book
There’s a great intro book by Pong P. Chu that you should read if you want to develop a sound understanding of the Verilog or VHDL languages. We currently have examples ported from this book that allows users to step thorugh the book material and learn by examples. If you are looking for a more in depth and formal walk through of how to begin using HDL this is a great choice.
LOGi Repsository with logi-apps, projects and drivers
Head over to our logi repository where can find a number of ways to kickstart your FPGA experience.
We provide a number of ways that you can begin working on your own with your LOGi-Pi. The easiest way to get started is to run the "logi-apps". The apps alow you to simply clone the apps repository onto you LOGi-Pi and run the applications. This is intended to allow users any easy way to run any of our applications without having to work in HDL, build and compile the projects.
The logi-projects are open source projects that contain all of the source for you learn from and to customize your own projects. This is where you find the complete projects source for the applications run in logi-apps.
Once you are ready for you can get started creating your own projects by using any of our drivers. We provide easy to use drivers that will allow you to get a head start on your own projects.
LOGi Projects and Users projects documenation
We will be documenting all of our projects using the wiki. You can find detailed guides and documentation related to the projects you find in our repository. We also allow users to submit your projects and create some base documentation to showcase your projects.
Want to get involved in a project?
In the logi/user projects wiki there will be a section "get involved' that will have a listing of potential items that anybody can take on to contribute and get involved in the project.
Integrate a PMOD and Arduino Modules and Shields
The PMOD headers on the side of the LOGi allow for easy connectivity to off-the-shelf electronics modules. You can easily add things like GPS, Audio Amplifiers, OLED displays, Wifi, Networking, RS232, DACs, ADCs Accelerometers, Motor Drivers etc. to your design!
Open Cores hosts great open source HDL cores that you can use in your own projects.
This quick start guide was heavily based upon a Quick Start guide for the LOGi-Mark written by Andy Gikling. Andy is a great asset to this project and we thank him for all of his great work. Be sure to drop by and see his ongoing beer toting robot project, BBot, that he has created using the LOGi boards.