Parallella FPGA Tutorial 0: (part1) Creating a new project/repo

This tutorial covers the generation of a new parallella project, and is required reading for any of the following projects – if you create your projects using a naive planAhead Save Project As, I believe you’re in for a world of hurt.

This my currently advised method for creating a new project which is not simply a throwaway. If you intend to throw it away, you could simply edit one of the provided projects in parallella-hw, and then do a git checkout on the files with local modifications to remove them.

I am going to suggest you create your own repo alongside the parallella-hw repo. I am not convinced it makes sense to fork the parallella-hw repo just to create your own project. But then I am not much of a git (I prefer mercurial), so maybe forking is more common practice than I would think.

Selecting a base project

Use the Parallella provided project which matches your hardware (z7010 or z7020, HDMI or headless, 16-core or 64-core Epiphany) – i.e. the one you use day to day so that you can load any of your projects using run-time reconfiguration without disrupting whatever else you may be doing.

Moreover, if you use a customised FPGA already, for example to support a daughterboard, then base the project on this one – that way you retain use of all existing interfaces – but with an extra IP core available.

The reason we do the first step in planAhead rather than simply doing a cp from a shell is that using the tool helps by automatically fixing up paths, as well as renaming subfolders and references – if you want to do a cp, you’ll have a fair amount of editing of the project xml files on your hands.

From the folder in which you cloned the git repo at https://github.com/parallella/parallella-hw
parallella-hw$ . /opt/Xilinx/14.7/ISE_DS/settings64.sh
parallella-hw$ planAhead fpga/projects/parallella_7020_headless/parallella_7020_headless.ppr

Cleaning the project

You can skip this step if you have never built the planAhead project, and this is a fresh checkout of parallella-hw.

The only reliable way I know of removing all the cruft is using git clean. The Xilinx tools do not know how to clean up after themselves, so we use git to take care of this for us.

For example:

parallella-hw$ git clean -d -n fpga/projects/parallella_7020_headless/

This shows you what would have been removed. If you want to proceed, replace -n with -f. Do not do this unless you are sure you have no changes to loose.

The (still to come) section with the .gitignore should save you ever accidentally commiting cruftiness to your projects in the first place. Being able to use git to clean a repo before you copy it is great.

Saving a copy of the project

Here you will need to make a choice. Do you intend to fork the whole parallella-hw repo just so you can add a few auxilliary projects (and then have to keep merging upstream into your project)? Or, you can do as I shall, and add your own repo alongside parallella-hw to store your projects. This is intuitive to me, since there is nothing in the parallella-hw repo we wish to change – we just want to copy and reference the globals/constraints. Any time you need to break from what is done in the globals/constraints and such link, it is probably time to copy this into your project and reference the new version there.

You could even make parallella-hw repo a subrepo if your repo if you wanted – but I will not cover that here.

[img] Select File >> Save Project As from the menu.

Choose the location for your project. In my case, I used the folder parallella-fpga-tutorials, which was at the same level as parallella-hw, and is the github repository I have shared at https://github.com/yanidubin/parallella-fpga-tutorials. The name of the project is Tutorial000_BaseProject, since this is the base for further projects.

Now would be a good time to do the first commit to your repo, before you start hacking the resources. After the planAhead copy, you will have a couple more files than you strictly need – but nothing worth fussing over.

Not quite so easy…

Unfortunately due to the way the parallella-hw project is laid out, there is a manual step now required so as not to cause conflicts between multiple projects using shared XPS resources. The issue is that when planAhead copies a project, it dereferences everything inside source (puts a fresh copy in your project src folder), while simply referencing everything else (refers to the original file in the original location). The reason this is a problem is that the parallella-hw layout puts the XPS files outside the project. So we will be copying the XPS files into the project directory, and updating the project to refer to the local copy.

We’ll also fix up version.v while we’re at it, since the parallella-hw projects state this is a local per-project file, but the flag in the xml resources has it marked as a global include (I believe this is why it does not get copied to the new project automatically – a less likely possibility being because it does not reside in the sources subfolder).

Note that you only need do this once – once your project has the XPS files locally, you can copy it as often as you like, and it will handle the XPS files correctly (taking a local copy). I have started a discussion thread on the official forums to see if this is something we can improve on. It is possible there is a very good reason the project is laid out this way.

The manual part

Add a system subdirectory to your new project folder, and copy the XPS files and version.v into it. Note that the edk subfolder to copy from should match up with the name of the project you used as the base.

$ mkdir -p parallella-fpga-tutorials/Tutorial000_BaseProject/Tutorial000_BaseProject.srcs/sources_1/system/data

$ cp parallella-hw/fpga/edk/parallella_7020_headless/system.{mhs,xmp} parallella-fpga-tutorials/Tutorial000_BaseProject/Tutorial000_BaseProject.srcs/sources_1/system/
$ cp parallella-hw/fpga/edk/parallella_7020_headless/data/ps7_system_prj.xml parallella-fpga-tutorials/Tutorial000_BaseProject/Tutorial000_BaseProject.srcs/sources_1/system/data/
$ cp parallella-hw/fpga/projects/parallella_7020_headless/version.v parallella-fpga-tutorials/Tutorial000_BaseProject//Tutorial000_BaseProject.srcs/sources_1/
Edit the project file manually (with whatever editor you are comforable with).

$ vim parallella-fpga-tutorials/Tutorial000_BaseProject/Tutorial000_BaseProject.data/sources_1/fileset.xml

Find the entries which look like

<File Path="$PPRDIR/../../parallella-hw/fpga/edk/parallella_7020_headless/system.xmp">

and

<File Path="$PPRDIR/../../parallella-hw/fpga/projects/parallella_7020_headless/version.v">

and change them to look like

<File Path="$PSRCDIR/sources_1/system/system.xmp">

and

<File Path="$PSRCDIR/sources_1/version.v">

respectively. Also delete the linke below version.v which sets IsGlobalInclude to Val=”1″, since having this is presumably why it didn’t get copied in the first place. Just delete the whole line – if you set it to 0, planAhead is just going to delete it anyway next time it saves the file.

The end result

You have now broken out the required files to start editing your own project. You have your own version.v should you wish to version your project, your own XPS files so that you can modify the system without impacting other projects, and you also get your own system_stub.v (automatically).

You should commit to your repo before you proceed to the next tutorial which will actually use the new project you have created.

For further project/tutorials, I recommend just doing a planAhead Save As from the base project, since that workflow is now open to you. Remember about using git to clean a repo before copying it, and commit it before you start building – this keeps those build artifacts out of your repo, and the .gitignore will help.

Still to come: .gitignore

The parallella-hw project lacks one of these, which I find very inconvenient. I have quite an involved .hgignore I use in my own repo, which works well for me, so I thought I would share this in .gitignore format in case anyone would benefit from this. It basically allows you to see only the useful/relevant changes when you do a diff/status, as well as help you know which files are worth checking in, and which are just generated/intermediary cruft (almost everything, as it happens).

Advertisements

6 thoughts on “Parallella FPGA Tutorial 0: (part1) Creating a new project/repo

  1. I.E.S

    hello, I have got a question as I am a newbie to parallella. I am a student and I am not able to start doing all mentioned above as I have a lot of confusions regarding that; do I have to do this all on the linux system directly on parallella? because it seems like you are using xilinx tools on parallella. Or could I also do this on a separate PC, edit my project on xilinx tools on that PC and then copy all the files afterwards. I would be grateful if you could clarify and explain a little bit so that I could start with the hardware.

    Like

    Reply
    1. Yani Dubin Post author

      Hi I.E.S,

      Sorry if this was a bit unclear – I aimed it at people familiar with the Xilinx tools already, but perhaps could have explained the development environment a little. The tools are x86 based, and cannot run on the Parallella as is (there are VMs like bochs, but the size of the tools, and already long compilation makes this something I’m not even interested in investigating at present).

      So what you are suggesting is the correct/only approach. There are both Linux and Windross versions of ISE WebPack, and you can use either – my tutorials are based on the Linux flavour, as this is all I use.

      The output of the tools is a binary representation of the FPGA bitstream, which you then load on. This is currently covered at the end of Tutorial 1 – I plan to write it up a little better and put it in its own post.

      For now, I recommend you start by getting the tools, and building the project in parallella-hw, and checking you can load it onto your board. Then, my tutorials are all based on making modifications to this project, so there is a good continuation.

      Hope that helps 🙂
      Yani.

      Like

      Reply
      1. I.E.S

        Thanks Yani for explanation.
        I would try progressing in this regard and would like to ask you more questions if I don’t understand something. 😀

        Like

  2. Len Reinhart

    Great work. I have read all four posts on the Parallella and this is helping me understand the environment. As they say .. You don’t know what you don’t know. Finding out what I don’t know and need to know is a start.

    Like

    Reply
  3. André Christensen

    Hi Yani

    Thanks for this great tutorial. I have one problem, when I get to running the synthesize I get an error saying this:

    [Edk 24-166] (generate_target): Failed to execute XPS script. Please check for any errors reported by the XPS application in the console: [/home/andre/Zynq/parallella-fpga-tutorials/Tutorial000_BaseProject/Tutorial000_BaseProject.srcs/sources_1/system/__xps/pa/_system_synth.tcl]

    Could it be a licens problem? and if it is how can I get my hands on a XPS licens (I’m a student 🙂

    Thanks.

    André

    Like

    Reply

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s