J-Core
Open
Processor

HOWTO Install a VHDL to bitstream compiler.

The LX9, LX25, and LX45 FPGAs are manufactured by Xilinx, which uses a proprietary bitstream format produced by Xilinx's bitstream compiler. The freely downloadable version of this compiler is Xilinx ISE Webpack (which has both GUI and command line tools).

In theory people are working on open source bitstream compilers. (This project takes an approach similar to QEMU's old dyngen before the problems with that approach inspired its replacement in QEMU. Here's another project taking a different approach.) More recently we've made significant progress towards combining NVC and yosys to build a stripped down J1 processor for a Lattice ICE40 hx8k. (There are still extensions needed to NVC, some missing glue logic between nvc and yosys, and problems with hosting/licensing of the VHDL standard IEEE libraries. Still, that's the plan.) But the largest Lattice FPGA has kilobytes of SRAM instead of megabytes of DRAM, not remotely have enough memory to run Linux. (It's down in "Arduino country".)

Unfortunately we haven't yet found an open source bitstream compiler capable of building j-core which targets an FPGA large enough to run Linux, so we've had to use the freely downloadable but closed source version for our main development until we can come up with a replacement. Here's how we installed the Xilinx VHDL toolchain we're using.

Part 1: Download and install this monstrosity.

1. Clear off at least 34 gigabytes of space. You'll get a dozen or so gigs of that back when you delete the download files and install directory afterwards, but this package is a serious space hog.

2. Download the four chunks of ISE Webpack.

   If you try to download the one big version, it has a nasty tendency to stop suddenly at the 2.1 gigabyte mark (1<<31 bytes) because Xilinx implemented a magic javascript downloader they seem very proud of, which doesn't work on large files. Rather than stop using the broken downloader, they worked around it by splitting the download into 4 chunks. (This is very Xilinx.)

   (Update: the broken downloader is such a common problem Xilinx tech support has posted instructions for bypassing it, so you might be able to download the one big file version that way. But the downloader is still there by default, because Xilinx.)

3. Extract part one in a subdirectory.

   The download is three zipfiles and a tarball. The first part (the tarball) does _not_ extract into a subdirectory, it will crap all over the current directory, so make a subdirectory and "tar xvf ../Xilinx*.tar" from there. (Yes, capital X, because xilinx.)

4. cd into the subdirectory and run "./xsetup".

   Note that the installer expects to find the other three files (the zip.xz files) in the parent directory ("..") so it already knows you're going to make a subdirectory. Xilinx just didn't package it that way.

5. Click next. Click next again.

   Do NOT click "browse" when it offers you the option, because if you pull up that dialog the next button sometimes stops working. (Xilinx!) These instructions put the files in the default place it looks for, let it find them there.

   The "checking integrity" progress bar is presumably supposed to do that.

6. Click both checkboxes, next, click checkbox, next.

7. Select ISE WebPACK, click next. Disable all the checkboxes you can, next.

   We don't need/want any of the things the checkboxes here offer: installing the license key here doesn't work so we're doing it as a separate step later, the "cable driver" option replaces (working) libusb with nonfunctional proprietary kernel modules, and the symlinks are merely unnecessary.

   It won't let you disable the WebTalk spyware, but we're mostly using the command line tools (not the GUI) so that's less of an issue.

8. Select destination directory: installing in /opt/Xilinx (its default) requires root access. You can put it /home/yourusername/xilinx if you (wisely) don't trust this thing with root access.

9. Click install.

   The installer is very, very slow. It probably isn't hung, it just stays at 0% for a long time (even on an SSD), then goes to 2%.

Part 2: Making it actually work.

The theory here is to run the xilinx gui tool and get it to launch a web browser with the magic incatation to generate a license key.

1. Enter Xilinx Context.

   The Xilinx tools are brittle and crotchety, and want special environment variables and library paths. The script that sets up all this nonsense is settings64.sh, a script you source which of course doesn't change your command prompt or anything to indicate you've done so (because xilinx).

   If you installed it in ~xilinx, you can source this script via:

   source ~/xilinx/*/ISE_DS/settings64.sh

   (No, you don't run it, you source it, the "." command if you're using a broken shell like dash. It's exporting environment variables into your host environment. Of course it doesn't change the command prompt or anything to indicate it's done so, because Xilinx.)

   Here's a wrapper script Xilinx could have used, but didn't, because Xilinx.

   #!/bin/bash -i
   
   source ~/xilinx/*/ISE_DS/settings64.sh
   export PS1="[Xilinx] $PS1"
   exec /bin/bash --noprofile --norc
   

2. Delete broken library files

   Unfortunately entering xilinx context puts a libstdc++.so.6 in the LD_PATH that's incompatible with both firefox and chromium, and in the next step it's going to try to launch a web browser to download a license key (which will fail to launch with a completely unhelpful error dialog).

   This broken libstdc++.so.6 breaks just about everything else you try to run in "Xilinx context", such as the C compiler, and isn't actually used by the command line bitstream compiler, so let's just delete it:

   rm ~/xilinx/*/ISE_DS/ISE/lib/lin64/libstdc++.so.6
   rm ~/xilinx/*/ISE_DS/common/lib/lin64/libstdc++.so.6
   

   (Yes there are multiple copies of the broken library, because Xilinx. There are actually several more, these are just the ones xilinx context adds to the host library path.)

3. Set your default browser to firefox.

The javascript on the xilinx webpage doesn't seem to work in chromium. You can set it back when you're done.

Launch firefox, click the three little equals signs in the upper right that have inexplicably replaced the pulldown menus other apps use, select preferences, and then at the top of the "general" page click Make Default. (The reverse process is similar for chromium.)

4. run "ise"

   This runs the ise gui tool, which should be in your $PATH in xilinx context, and will try to download a license key the first time it's run. Since the command line tools won't run either until this is done, let's humor it.

   When the GUI first pops up, it will pop up a "tip of the day" dialog which may wind up on top of the modal "license error" dialog, because xilinx. Since both windows are modal, you can't always dismiss the one on top first, so if you seem locked out grab the title bar of the window on top to move it out of the way, then dismiss the other one.

Click OK on the license error dialog to pop up license configuration manager window.

5. Get a license key from the website

   Select "Get Free Vivado/ISE WebPack License".

The license window may be taller than your screen, you can grab the top edge and shrink it, then grab the title bar and move it up until you reveal the next button.

Click NEXT. The new pop-up window will remind you that you it's going to tie this license key to the mac address in your network card.

Click "connect now" to launch the browser. (This will fail unless you deleted the shared libraries above.)

6. Create a new account (if you haven't already got one).

Right click on create new account. Open it in a new tab to avoid losing the form state in the original tab.

Account creation will want an email account) and a sufficiently random userid. It will then send email with a confirmation link, paste that over the URL in your tab and log in at the prompt to activate your account.

Now close the tab and go back to the original tab (with the key request context) and log in with your new account. At this point it bothered me about filling out a profile, so I clicked "save profile" to open all the new required fields it wants you to type nonsense into. (You actually have to select a country some other dropdowns, the rest just can't be blank.)

After saving the profile the website said it had emailed me (it hadn't) and forgot my license request, but the "back" button turns into a pulldown if you click and hold, so I went to the original URL for the tab and logged in a third time.

This time it asked for the same data again, now with a few more fields, blaming export regulations (possibly because I told it "japan" for the country). It hadn't asked for/required zip code and phone before because Xilinx.

Luckily on this third login it remembered what I was there to do, and gave me the product licensing page next, so I didn't have to log in a fourth time.

7. Select ISE WebPack License checkbox.

   This part is the javascript that didn't work in Chromium (the checkbox stayed grayed out), but it worked in Ubuntu's Firefox. (Maybe chromium's been updated since then.)

   Click "Generate Node-Locked license", then click NEXT on the pop-up.

   This odd "modal dialog" is just more gratuitous javascript, if the next button is off the bottom of your screen, scroll the enclosing web page down.

   Ignore the comments field, no good will come of it, just click NEXT.

   Click NEXT again on the "review license request" dialog that serves no purpose since it has the same information as the previous dialog because Xilinx. (It warns you once again you can't turn off the spyware in the GUI, implicitly endorsing the command line tools.)

Dismiss the congratulations window (tiny little X upper right) and click the stealth download icon (tiny down arrow inside a circle in the lower left corner of the "Comments" box) to download your license key file. (Or check your email, it should be attached to the message they just sent you.) In either case the file is called Xilinx.lic

8. Close firefox, set your browser preferences back to normal if necessary.

9. Feed the license file to the guid tool.

   Your "Xilinx License Configuration Manager" window (from the ise gui tool) should still be open, and should have advanced to the "Manage licenses" tab. Click the "Load License" button, navigate to ~/Downloads and select Xilinx.lic. (Or whatever location/name you saved the email attachment under if you didn't download it.)

   Click "Open". You should get a popup saying license installation was successful.

Once you've installed the license key, close the license manager window and the main ISE window. You never have to run ise again if you don't want to.