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 line 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).