feat: add installation guide for FPGA

natalieagus · Oct 16, 2024 · b447787 · b447787
1 parent 302fa27
commit b447787
Show file tree

Hide file tree

Showing 34 changed files with 206 additions and 36 deletions.
diff --git a/docs/FPGA/Lucid V1/debugging.md b/docs/FPGA/Lucid V1/debugging.md
@@ -4,7 +4,7 @@ permalink: /fpga/lucid-v1/debugging
 title: Debugging for the Frantic
 description: Getting familiar with Alchitry Lab's debug feature
 parent: Lucid V1 
-grand_parent: FPGA
+grand_parent: 1D&2D Project (FPGA)
 nav_order:  6
 ---
 

diff --git a/docs/FPGA/Lucid V1/fpga_1.md b/docs/FPGA/Lucid V1/fpga_1.md
@@ -4,7 +4,7 @@ permalink: /fpga/fpga_1
 title: FPGA Tutorial for Babies
 description: Getting Started with FPGA Part 1 - Combinational Logic
 parent: Lucid V1 
-grand_parent: FPGA
+grand_parent: 1D&2D Project (FPGA)
 nav_order:  1
 ---
 

diff --git a/docs/FPGA/Lucid V1/fpga_2.md b/docs/FPGA/Lucid V1/fpga_2.md
@@ -4,7 +4,7 @@ permalink: /fpga/fpga_2
 title: FPGA Tutorial for Toddlers
 description: Getting Started with FPGA Part 2 - Sequential Logic and FSM
 parent: Lucid V1 
-grand_parent: FPGA
+grand_parent: 1D&2D Project (FPGA)
 nav_order:  2
 ---
 

diff --git a/docs/FPGA/Lucid V1/fpga_3.md b/docs/FPGA/Lucid V1/fpga_3.md
@@ -4,7 +4,7 @@ permalink: /fpga/fpga_3
 title: FPGA Tutorial for Children
 description: Getting Started with FPGA Part 3 - Reset and I/O
 parent: Lucid V1 
-grand_parent: FPGA
+grand_parent: 1D&2D Project (FPGA)
 nav_order:  3
 ---
 

diff --git a/docs/FPGA/Lucid V1/fpga_4.md b/docs/FPGA/Lucid V1/fpga_4.md
@@ -4,7 +4,7 @@ permalink: /fpga/fpga_4
 title: Building the Beta with FPGA
 description: Getting Good with FPGA - Building Beta CPU
 parent: Lucid V1 
-grand_parent: FPGA
+grand_parent: 1D&2D Project (FPGA)
 nav_exclude: true
 nav_order:  4
 ---

diff --git a/docs/FPGA/Lucid V1/index.md b/docs/FPGA/Lucid V1/index.md
@@ -3,8 +3,8 @@ layout: default
 title: Lucid V1 
 permalink: /fpga/lucid-v1/intro
 has_children: true
-parent: FPGA
-nav_order: 1
+parent: 1D&2D Project (FPGA)
+nav_order: 2
 ---
 
 ## Lucid V1 

diff --git a/docs/FPGA/Lucid V1/programmable_machine.md b/docs/FPGA/Lucid V1/programmable_machine.md
@@ -4,7 +4,7 @@ permalink: /fpga/programmable_machine
 title: Designing a Programmable Datapath 
 description: This document shows an example on how you can create a programmable data path for a simple game idea that might be useful for your 1D project. 
 parent: Lucid V1 
-grand_parent: FPGA
+grand_parent: 1D&2D Project (FPGA)
 nav_order:  5
 ---
 * TOC

diff --git a/docs/FPGA/Lucid V2/fpga_applesilicon.md b/docs/FPGA/Lucid V2/fpga_applesilicon.md
@@ -4,7 +4,7 @@ permalink: /fpga/fpga_applesilicon
 title: Running Vivado on Apple Silicon mac 
 description: This document gives a brief overview of how you can run Vivado on Apple Silicon mac with UTM 
 parent: Lucid V2 
-grand_parent: FPGA
+grand_parent: 1D&2D Project (FPGA)
 nav_order:  10
 ---
 * TOC
@@ -34,7 +34,7 @@ brew install --cask utm
 ### Download Image and Unzip
 After that, download the image from here (TBC)
 * You need to be <span className="orange-bold">signed in to your SUTD account</span> 
-* This image comes with Debian 12, Rosetta, Vivado 2023.2, Alchitry Labs 1.2.7 and Alchitry Labs 2 pre-installed
+* This image comes with Debian 12, Rosetta, Vivado 2023.2, Alchitry Labs 1.2.7 (legacy) and Alchitry Labs 2 pre-installed (current)
 
 Then **unzip** the downloaded file, either using Finder or CLI: 
 ```
@@ -52,6 +52,13 @@ Once done, open UTM and import the image.
 > Check that there are **TWO** drives: sized approx 64 GB and 80 GB respectively in your `.utm` file. Right click on your `.utm` file and click **Show package contents**. You should see the following under `Data/`: 
 > <img src="{{ site.baseurl }}/docs/FPGA/images/fpga_applesilicon/2024-03-18-17-47-02.png"  class="center_full no-invert"/>
 
+### Share Directories with Host Machine 
+
+You can **share directories** with your mac (host machine) by setting the desired shared directory in your host machine here. In this example we use `Documents/alchitry-utm` in our host machine as shared directory: 
+<img src="{{ site.baseurl }}/docs/FPGA/images/fpga_applesilicon/shared-dir.png"  class="center_full no-invert"/>
+
+Then in Debian (your VM), you can access this directory via the path `/media/share/DIRECTORY_NAME`, in this case it will be `/media/share/alchitry-utm`.
+
 ### Login as `debian`
 
 {:.important}
@@ -61,46 +68,45 @@ Ensure that your desktop looks like this. If it doesn't it means that what you h
 
 <img src="{{ site.baseurl }}/docs/FPGA/images/fpga_applesilicon/2024-03-25-17-35-03.png"  class="center_full no-invert"/>
 
-
-### Launching Alchitry Labs v1.2.7
-You can start alchitry labs by opening terminal from the bottom menu of the desktop (press windows / command image if the dock isn't visible) and type `alchitry` command. Key in `debian` as password when prompted.
+### Launching Alchitry Labs 2
+You can start alchitry labs by opening terminal from the bottom menu of the desktop (press windows / command image if the dock isn't visible) and type `a2` command. Key in `debian` as password when prompted.
 
 ```
-debian@debian:~$ alchitry
+debian@debian:~$ a2
 [sudo] password for debian: [debian]
 ```
 
-Then, use alchitry labs as usual:
-cd 
-<img src="{{ site.baseurl }}/docs/FPGA/images/fpga_applesilicon/2024-03-25-17-38-22.png"  class="center_full no-invert"/>
+<img src="{{ site.baseurl }}//docs/FPGA/Lucid%20V2/images/fpga_applesilicon/2024-10-16-11-23-16.png"  class="center_seventy no-invert"/>
 
+It will prompt you to create/open new project (first time) or open your last opened project (subsequently).
 
-### Launching Alchitry Labs 2
-If you choose to use Alchitry Labs 2 and Lucid V2, you can launch the IDE using the `a2` command. 
+## Loading .bin from your mac to Alchitry Au FPGA
 
-```
-debian@debian:~$ a2
-[sudo] password for debian: [debian]
-```
+After **building** your code, you will need to load the binary to your FPGA. There's no USB passthrough with the VM (it's not the usual QEMU), so you will need to <span class="orange-bold">migrate</span> `PROJECT_PATH/build/alchitry_au.bin` to your host machine and flash it to your FPGA using [Alchitry Loader part of the Alchitry Labs IDE for Apple Silicon](https://alchitry.com/Alchitry-Labs-V2/download.html).
 
-<img src="{{ site.baseurl }}//docs/FPGA/images/fpga_applesilicon/2024-10-07-11-21-32.png"  class="center_full no-invert"/>
+If you have set up the [shared directory](#share-directories-with-host-machine) above, simply navigate to this location.
 
-### Loading .bin 
+### Install Alchitry Labs V2 in your mac
 
-After **building** your code, you will need to load the binary to your FPGA. There's no USB passthrough with the VM (it's not the usual QEMU), so you will need to migrate `PROJECT_PATH/work/alchitry.bin` (for Alchitry Lab 1.2.7) or `PROJECT_PATH/build/alchitry_au.bin` (for Alchitry Lab V2) to your host machine and flash it to your FPGA using [Alchitry Loader part of the Alchitry Labs IDE for Apple Silicon](https://alchitry.com/Alchitry-Labs-V2/download.html).
+From this link, [install](https://alchitry.com/alchitry-labs/) the Alchitry Labs V2 IDE. Follow the installation guide properly and open the app. Here's the important steps:
+This application does not prove its origin with a developer signature. To open it:
+
+1. Click the download button.
+2. Note: Do not use the Launchpad to perform the following steps as it will not allow you to access the shortcut menu.
+3. Open the Finder and locate the application in your Downloads folder.
+4. Control-click the app icon, then choose Open from the shortcut menu.
+5. You will see a security warning stating the identity of the app author is unknown. Click Open.
+
+### Alchitry Loader
+Then switch to Alchitry Loader first: 
 
-Switch to Alchitry Loader first: 
 <img src="{{ site.baseurl }}/docs/FPGA/images/fpga_applesilicon/2024-03-18-14-34-46.png"  class="center_full no-invert"/>
 
-Then find the binary and load it to your Alchitry Au FPGA: 
-<img src="{{ site.baseurl }}//docs/FPGA/images/fpga_applesilicon/2024-10-07-11-22-40.png"  class="center_full no-invert"/>
+Find the synthesized binary and load it to your Alchitry Au FPGA: 
 
-### Share Directories with Host Machine 
+<img src="{{ site.baseurl }}//docs/FPGA/images/fpga_applesilicon/2024-10-07-11-22-40.png"  class="center_full no-invert"/>
 
-You can **share directories** with your mac (host machine) by setting the desired shared directory in your host machine here. In this example we use `Documents/alchitry-utm` in our host machine as shared directory: 
-<img src="{{ site.baseurl }}/docs/FPGA/images/fpga_applesilicon/shared-dir.png"  class="center_full no-invert"/>
 
-Then in Debian (your VM), you can access this directory via the path `/media/share/DIRECTORY_NAME`, in this case it will be `/media/share/alchitry-utm`.
 
 
 
diff --git a/docs/FPGA/Lucid V2/images/fpga_applesilicon/2024-10-16-11-23-16.png b/docs/FPGA/Lucid V2/images/fpga_applesilicon/2024-10-16-11-23-16.png
diff --git a/docs/FPGA/Lucid V2/index.md b/docs/FPGA/Lucid V2/index.md
@@ -3,8 +3,8 @@ layout: default
 title: Lucid V2 
 permalink: /fpga/lucid-v2/intro
 has_children: true
-nav_order: 2
-parent: FPGA
+parent: 1D&2D Project (FPGA)
+nav_order: 3
 ---
 
 # Lucid V2 

diff --git a/docs/FPGA/images/installation/2024-10-16-09-54-29.png b/docs/FPGA/images/installation/2024-10-16-09-54-29.png
diff --git a/docs/FPGA/images/installation/2024-10-16-09-59-32.png b/docs/FPGA/images/installation/2024-10-16-09-59-32.png
diff --git a/docs/FPGA/images/installation/2024-10-16-09-59-57.png b/docs/FPGA/images/installation/2024-10-16-09-59-57.png
diff --git a/docs/FPGA/images/installation/2024-10-16-10-00-26.png b/docs/FPGA/images/installation/2024-10-16-10-00-26.png
diff --git a/docs/FPGA/images/installation/2024-10-16-10-01-04.png b/docs/FPGA/images/installation/2024-10-16-10-01-04.png
diff --git a/docs/FPGA/images/installation/2024-10-16-10-01-24.png b/docs/FPGA/images/installation/2024-10-16-10-01-24.png
diff --git a/docs/FPGA/images/installation/2024-10-16-10-01-53.png b/docs/FPGA/images/installation/2024-10-16-10-01-53.png
diff --git a/docs/FPGA/images/installation/2024-10-16-10-02-14.png b/docs/FPGA/images/installation/2024-10-16-10-02-14.png
diff --git a/docs/FPGA/images/installation/2024-10-16-10-02-29.png b/docs/FPGA/images/installation/2024-10-16-10-02-29.png
diff --git a/docs/FPGA/images/installation/2024-10-16-10-03-04.png b/docs/FPGA/images/installation/2024-10-16-10-03-04.png
diff --git a/docs/FPGA/images/installation/2024-10-16-10-12-21.png b/docs/FPGA/images/installation/2024-10-16-10-12-21.png
diff --git a/docs/FPGA/images/installation/2024-10-16-11-04-09.png b/docs/FPGA/images/installation/2024-10-16-11-04-09.png
diff --git a/docs/FPGA/images/installation/2024-10-16-11-04-47.png b/docs/FPGA/images/installation/2024-10-16-11-04-47.png
diff --git a/docs/FPGA/images/installation/2024-10-16-11-05-51.png b/docs/FPGA/images/installation/2024-10-16-11-05-51.png
diff --git a/docs/FPGA/images/installation/2024-10-16-11-06-23.png b/docs/FPGA/images/installation/2024-10-16-11-06-23.png
diff --git a/docs/FPGA/images/installation/2024-10-16-11-09-33.png b/docs/FPGA/images/installation/2024-10-16-11-09-33.png
diff --git a/docs/FPGA/images/installation/2024-10-16-11-10-22.png b/docs/FPGA/images/installation/2024-10-16-11-10-22.png
diff --git a/docs/FPGA/images/installation/2024-10-16-11-12-16.png b/docs/FPGA/images/installation/2024-10-16-11-12-16.png
diff --git a/docs/FPGA/images/installation/2024-10-16-11-15-07.png b/docs/FPGA/images/installation/2024-10-16-11-15-07.png
diff --git a/docs/FPGA/images/installation/2024-10-16-11-15-46.png b/docs/FPGA/images/installation/2024-10-16-11-15-46.png
diff --git a/docs/FPGA/images/installation/2024-10-16-11-17-20.png b/docs/FPGA/images/installation/2024-10-16-11-17-20.png
diff --git a/docs/FPGA/images/installation/2024-10-16-11-18-24.png b/docs/FPGA/images/installation/2024-10-16-11-18-24.png
diff --git a/docs/FPGA/index.md b/docs/FPGA/index.md
@@ -1,6 +1,6 @@
 ---
 layout: default
-title: FPGA
+title: 1D&2D Project (FPGA)
 permalink: /fpga/intro
 has_children: true
 nav_order: 22

diff --git a/docs/FPGA/installation.md b/docs/FPGA/installation.md
@@ -0,0 +1,164 @@
+---
+layout: default
+permalink: /fpga/installation
+title: Installation Guide
+parent: 1D&2D Project (FPGA)
+nav_order:  0
+---
+
+* TOC
+{:toc}
+
+
+# FPGA Tools Installation Guide
+{: .no_toc}
+
+Software to install: 
+1. **Vivado ML Edition - 2023.2** or any later version  
+2. [Alchitry Lab IDE](https://alchitry.com/alchitry-labs) (version TBC),
+3. [**Latest** Java Development Kit](https://www.oracle.com/sg/java/technologies/downloads/)
+
+{:.important}
+**Total additional space required: ~80GB**. You may want to install these to an external drive. 
+
+## Preface 
+The Alchitry IDE is used to **write** hardware designs in the Lucid programming language, offering a higher-level abstraction for FPGA development. 
+
+<img src="{{ site.baseurl }}//docs/FPGA/images/installation/2024-10-16-11-04-09.png"  class="center_seventy no-invert"/>
+
+Once the code is ready, you can press **build 🔨** button and the IDE translates Lucid to Verilog and utilizes Vivado (configured with its binary location) to synthesize and generate the bitstream file. 
+
+<img src="{{ site.baseurl }}//docs/FPGA/images/installation/2024-10-16-11-04-47.png"  class="center_thirty no-invert"/>
+
+The bitstream file can be found under `[PROJECT_DIR]/build/alchitry_au.bin`:
+<img src="{{ site.baseurl }}//docs/FPGA/images/installation/2024-10-16-11-05-51.png"  class="center_seventy no-invert"/>
+
+This bitstream is then **loaded** onto the FPGA, which is connected to the computer via USB for deployment.
+
+<img src="{{ site.baseurl }}//docs/FPGA/images/installation/2024-10-16-11-06-23.png"  class="center_seventy no-invert"/>
+
+
+## Vivado Installation (Windows x86 or Linux x86)  
+
+Vivado is used to **synthesize** high-level hardware description code (in Verilog or Lucid translated to Verilog) into a netlist of logical gates. This netlist is then further **processed** through implementation steps, such as place-and-route, to produce a bitstream or **binary file** for programming the FPGA.
+
+{:.note-title}
+> 🍎 Apple Silicon Mac 
+> 
+> You cannot natively install Vivado on Apple Silicon macs. Xilinx Vivado doesn’t officially support ARM as of late 2024. Current workaround utilises UTM + Debian 12 + Rosetta, read this guide here [TBC]. 
+
+
+We recommend you to instal Vivado ML Edition - 2023.2. You are free to try older version (see [archive](https://www.xilinx.com/support/download/index.html/content/xilinx/en/downloadNav/vivado-design-tools/archive.html)) Vivado Design Suite - HLx Editions - 2020.2 or the latest version: Vivado ML Edition - 2024.1. 
+> *Please choose one and just install one version*. 
+
+This guide assumes you select Vivado ML Edition - 2023.2. 
+
+### Vivado ML Edition - 2023.2 
+[Create an AMD account](https://www.amd.com/en/registration/create-account.html?custtarg=aHR0cHM6Ly9hY2NvdW50LmFtZC5jb20vZW4vcHJvZmlsZS5odG1s) first. 
+
+Then, download [Vivado ML Edition - 2023.2 self-extracting web installer](https://www.xilinx.com/support/download/index.html/content/xilinx/en/downloadNav/vivado-design-tools/2023-2.html) (Windows / Linux)
+
+<img src="{{ site.baseurl }}//docs/FPGA/images/installation/2024-10-16-09-54-29.png"  class="center_seventy no-invert"/>
+
+**Windows users:** Extract and open the downloaded installer as per normal. 
+
+**Linux users:** Once the installer is downloaded, open Terminal and type the following to make the `.bin` executable, and run it.
+
+```sh
+cd ~/Downloads 
+chmod +x FPGA[press TAB for autocompletion]
+
+# then run 
+./FPGA[press TAB]
+```
+Sign in with the AMD account you created earlier:
+
+<img src="{{ site.baseurl }}//docs/FPGA/images/installation/2024-10-16-09-59-32.png"  class="center_seventy no-invert"/>
+
+Then select Vivado: 
+
+<img src="{{ site.baseurl }}//docs/FPGA/images/installation/2024-10-16-09-59-57.png"  class="center_seventy no-invert"/>
+
+Choose Vivado ML Standard (this is the **free** version):
+
+<img src="{{ site.baseurl }}//docs/FPGA/images/installation/2024-10-16-10-00-26.png"  class="center_seventy no-invert"/>
+
+Only tick these packages to install (we don't need everything, you can save some space):
+- Vivado Design Suite: Vivado, Vitis HLS
+- DocNav
+- Artix-7
+
+<img src="{{ site.baseurl }}//docs/FPGA/images/installation/2024-10-16-10-01-04.png"  class="center_seventy no-invert"/>
+
+Next, tick all the license agreements:
+
+<img src="{{ site.baseurl }}//docs/FPGA/images/installation/2024-10-16-10-01-24.png"  class="center_seventy no-invert"/>
+
+Then create installation an directory. Here we create a new folder called Xilinx under ~/Documents:
+
+<img src="{{ site.baseurl }}//docs/FPGA/images/installation/2024-10-16-10-01-53.png"  class="center_seventy no-invert"/>
+
+<img src="{{ site.baseurl }}//docs/FPGA/images/installation/2024-10-16-10-02-14.png"  class="center_seventy no-invert"/>
+
+After that click **install**: 
+
+<img src="{{ site.baseurl }}//docs/FPGA/images/installation/2024-10-16-10-02-29.png"  class="center_seventy no-invert"/>
+
+{:.important}
+It might take approximately 2-3 hours for installation to complete. 
+
+<img src="{{ site.baseurl }}//docs/FPGA/images/installation/2024-10-16-10-03-04.png"  class="center_seventy no-invert"/>
+
+Finally, ensure that Vivado is installed properly (you can open the app afterwards):
+
+<img src="{{ site.baseurl }}//docs/FPGA/images/installation/2024-10-16-10-12-21.png"  class="center_seventy no-invert"/>
+
+## Alchitry Lab Installation 
+
+Download Alchitry Lab 2 from [here](https://alchitry.com/alchitry-labs/). This is your IDE.
+
+Once installed, open the app and you can create a **new** project. Select the template for Alchitry Au board and choose one of the basic template project: 
+
+<img src="{{ site.baseurl }}//docs/FPGA/images/installation/2024-10-16-11-09-33.png"  class="center_seventy no-invert"/>
+
+### Set Vivado Location
+
+Set the Vivado installation location you did earlier in Alchitry Lab. It should be something like this `[VIVADO_INSTALLATION_DIRECTORY]/Vivado/[VERSION]`. In this example, we installed Vivado ML Edition 2023.2 in `/mnt/vivado`, and hence the location to select in Alchitry is `/mnt/vivado/Vivado/2023.2`. 
+
+<img src="{{ site.baseurl }}//docs/FPGA/images/installation/2024-10-16-11-10-22.png"  class="center_seventy no-invert"/>
+
+### Build the project
+After vivado location is set, you can **test build** the project:
+
+<img src="{{ site.baseurl }}//docs/FPGA/images/installation/2024-10-16-11-12-16.png"  class="center_seventy no-invert"/>
+
+If vivado location is set properly, you should see the message `Starting Vivado...`:
+
+<img src="{{ site.baseurl }}//docs/FPGA/images/installation/2024-10-16-11-15-07.png"  class="center_seventy no-invert"/>
+
+{:.important}
+Synthesis takes quite some time (3-10 minutes). This is normal. 
+
+When synthesis is done, you should see the message `Finished building project`:
+
+<img src="{{ site.baseurl }}//docs/FPGA/images/installation/2024-10-16-11-15-46.png"  class="center_seventy no-invert"/>
+
+{:.note-title}
+> Debug Log 
+>
+> If project building fails, copy the debug log and search for the word `ERROR`. 
+
+### Load to FPGA 
+
+Connect the FPGA board to your computer. It should detect the board **automatically**. 
+
+You can **load** the binary to the Alchitry Au FPGA using the solid arrow button (load flash, persistent) or the hollow arrow button (load RAM, not persistent upon reboot of FPGA). 
+
+<img src="{{ site.baseurl }}//docs/FPGA/images/installation/2024-10-16-11-17-20.png"  class="center_fifty no-invert"/>
+
+### Using Alchitry Loader 
+
+<img src="{{ site.baseurl }}//docs/FPGA/images/installation/2024-10-16-11-18-24.png"  class="center_fifty no-invert"/>
+
+You can also load the binary to your FPGA using Alchitry Loader. It works the same. Alchitry Loader is **useful** for macOS users who cannot synthesise the binary natively, and can only **load** flash/RAM after synthesizing the binary elsewhere. 
+