diff --git a/docs/FPGA/Lucid V1/debugging.md b/docs/FPGA/Lucid V1/debugging.md index 0d49c25..88a79b3 100644 --- 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 index 4214f61..23b6455 100644 --- 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 index 60f701c..ea9b8bc 100644 --- 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 index dbacfb8..bbff4bf 100644 --- 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 index 3818db3..ca595e3 100644 --- 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 index 60c7ad4..64897a7 100644 --- 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 index 72df395..6e17a6d 100644 --- 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 index d88eb8a..a56452f 100644 --- 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 signed in to your SUTD account -* 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/`: > +### 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: + + +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 - -### 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 - + +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 migrate `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). - +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: -Then find the binary and load it to your Alchitry Au FPGA: - +Find the synthesized binary and load it to your Alchitry Au FPGA: -### 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: - -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 new file mode 100644 index 0000000..6c82198 Binary files /dev/null and b/docs/FPGA/Lucid V2/images/fpga_applesilicon/2024-10-16-11-23-16.png differ diff --git a/docs/FPGA/Lucid V2/index.md b/docs/FPGA/Lucid V2/index.md index 5d7bba5..0cd99d5 100644 --- 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 new file mode 100644 index 0000000..897fb5f Binary files /dev/null and b/docs/FPGA/images/installation/2024-10-16-09-54-29.png differ 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 new file mode 100644 index 0000000..f572454 Binary files /dev/null and b/docs/FPGA/images/installation/2024-10-16-09-59-32.png differ 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 new file mode 100644 index 0000000..259d05c Binary files /dev/null and b/docs/FPGA/images/installation/2024-10-16-09-59-57.png differ 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 new file mode 100644 index 0000000..5740d8c Binary files /dev/null and b/docs/FPGA/images/installation/2024-10-16-10-00-26.png differ 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 new file mode 100644 index 0000000..a60db51 Binary files /dev/null and b/docs/FPGA/images/installation/2024-10-16-10-01-04.png differ 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 new file mode 100644 index 0000000..dcdc762 Binary files /dev/null and b/docs/FPGA/images/installation/2024-10-16-10-01-24.png differ 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 new file mode 100644 index 0000000..d9a9603 Binary files /dev/null and b/docs/FPGA/images/installation/2024-10-16-10-01-53.png differ 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 new file mode 100644 index 0000000..880cdf6 Binary files /dev/null and b/docs/FPGA/images/installation/2024-10-16-10-02-14.png differ 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 new file mode 100644 index 0000000..3f7fcf7 Binary files /dev/null and b/docs/FPGA/images/installation/2024-10-16-10-02-29.png differ 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 new file mode 100644 index 0000000..031cecb Binary files /dev/null and b/docs/FPGA/images/installation/2024-10-16-10-03-04.png differ 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 new file mode 100644 index 0000000..d6a1146 Binary files /dev/null and b/docs/FPGA/images/installation/2024-10-16-10-12-21.png differ 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 new file mode 100644 index 0000000..3e7a578 Binary files /dev/null and b/docs/FPGA/images/installation/2024-10-16-11-04-09.png differ 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 new file mode 100644 index 0000000..3b0f99c Binary files /dev/null and b/docs/FPGA/images/installation/2024-10-16-11-04-47.png differ 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 new file mode 100644 index 0000000..9b7314c Binary files /dev/null and b/docs/FPGA/images/installation/2024-10-16-11-05-51.png differ 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 new file mode 100644 index 0000000..2a021ea Binary files /dev/null and b/docs/FPGA/images/installation/2024-10-16-11-06-23.png differ 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 new file mode 100644 index 0000000..efc0570 Binary files /dev/null and b/docs/FPGA/images/installation/2024-10-16-11-09-33.png differ 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 new file mode 100644 index 0000000..5cd9ff0 Binary files /dev/null and b/docs/FPGA/images/installation/2024-10-16-11-10-22.png differ 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 new file mode 100644 index 0000000..69e1f8b Binary files /dev/null and b/docs/FPGA/images/installation/2024-10-16-11-12-16.png differ 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 new file mode 100644 index 0000000..a5a41f8 Binary files /dev/null and b/docs/FPGA/images/installation/2024-10-16-11-15-07.png differ 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 new file mode 100644 index 0000000..ef734ce Binary files /dev/null and b/docs/FPGA/images/installation/2024-10-16-11-15-46.png differ 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 new file mode 100644 index 0000000..561b1fe Binary files /dev/null and b/docs/FPGA/images/installation/2024-10-16-11-17-20.png differ 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 new file mode 100644 index 0000000..a4b5647 Binary files /dev/null and b/docs/FPGA/images/installation/2024-10-16-11-18-24.png differ diff --git a/docs/FPGA/index.md b/docs/FPGA/index.md index 6b9f953..51bb9ed 100644 --- 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 new file mode 100644 index 0000000..a4c0a7f --- /dev/null +++ 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. + + + +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. + + + +The bitstream file can be found under `[PROJECT_DIR]/build/alchitry_au.bin`: + + +This bitstream is then **loaded** onto the FPGA, which is connected to the computer via USB for deployment. + + + + +## 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) + + + +**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: + + + +Then select Vivado: + + + +Choose Vivado ML Standard (this is the **free** version): + + + +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 + + + +Next, tick all the license agreements: + + + +Then create installation an directory. Here we create a new folder called Xilinx under ~/Documents: + + + + + +After that click **install**: + + + +{:.important} +It might take approximately 2-3 hours for installation to complete. + + + +Finally, ensure that Vivado is installed properly (you can open the app afterwards): + + + +## 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: + + + +### 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`. + + + +### Build the project +After vivado location is set, you can **test build** the project: + + + +If vivado location is set properly, you should see the message `Starting Vivado...`: + + + +{:.important} +Synthesis takes quite some time (3-10 minutes). This is normal. + +When synthesis is done, you should see the message `Finished building project`: + + + +{:.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). + + + +### Using Alchitry Loader + + + +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. +