An analysis of the previous software installation manual: what became wrong, what needs amending, and what is missing
Statements that were true when the previous edition came out but today would lead the reader into a mistake. In the new manual they are either corrected or marked "used to be true" — the illustrations are kept, so that a reader running an older version of the software still recognises their own windows.
| In the previous edition | How it is now | Section of the new manual |
|---|---|---|
| "Intel Quartus Prime Lite", "Intel Altera", "FPGAs from Intel Altera" — in headings and throughout the text. | The division is called Altera again: Intel sold its controlling stake in 2024. New Quartus Lite releases install into altera_lite and Quartus Pro into altera_pro (the older ones went into intelFPGA_lite and intelFPGA_pro). The scripts look for all eight spellings. | 4.1.1, 4.1.1.4 |
"Add the following environment variables to ~/.bashrc": QSYS_ROOTDIR, QUARTUS_ROOTDIR and a PATH addition — presented as a mandatory step. | The step is no longer mandatory: the scripts find Quartus themselves, through QUARTUS_ROOTDIR, then PATH, then the vendor directories under $HOME, /opt and /tools. The variables are only needed for an installation in an unusual place, or to force one of several versions. | 4.1.1.4, 4.2.1.4, 12 |
In that same example, QUARTUS_ROOTDIR points at intelFPGA_lite/21.1 while PATH points at intelFPGA_lite/20.1. | This is a typo in the previous edition itself: the version numbers in adjacent lines disagree, and a non-existent directory lands on PATH. Since the variables are no longer needed, the example has been dropped. | 4.2.1.1 |
| "Installing Icarus Verilog 12" — in the headings of sections 1.6 and 2.4 of the previous edition. | Version 13 is needed, 14 is better: some examples use SystemVerilog constructs that versions 11 and 12 do not understand. The scripts check the version and warn about it. | 4.1.5, 4.2.5 |
The whole of section 3 — installing OpenLane through Docker: git clone The-OpenROAD-Project/OpenLane, make, make test, make mount. | In basics-graphics-music, OpenLane has been replaced by LibreLane, its continuation. It installs through Nix, Docker is not involved, and it runs as ./07_synthesize_for_asic.bash from the example's directory rather than make from OpenLane's. The section is rewritten completely. | 4.1.11, 4.2.11 |
| "OpenLane can only be installed on Linux, so if you have Windows, install a second OS or a virtual machine." | Under Windows WSL 2 is enough — neither a second partition nor a virtual machine is needed. Nix and LibreLane work inside WSL, and that is the normal route. | 4.1.11 |
The homework repository: git clone https://gitflic.ru/project/yuri-panchul/systemverilog-homework.git. | The address is obsolete. For the School's classes use github.com/chipdesignschool/systemverilog-homework. | 1.3, 9 |
The examples repository: git clone https://github.com/yuri-panchul/basics-graphics-music.git. | The yuri-panchul copy is the working one; experimental changes land there. The copy meant for the School's classes is github.com/chipdesignschool/basics-graphics-music, and the one for the international seminars is verilog-meetup. | 1.2 |
A mention of the valid-ready-etc repository on gitflic (in the section about updating the repositories on the SSD). | That repository is obsolete; its material went into basics-graphics-music, in the 4_microarchitecture part. | 6.3 |
Example paths of the form labs/01_and_or_not_xor_de_morgan. | The examples are now grouped by part of the course: labs/1_basics/1_01_and_or_not_xor_de_morgan, labs/2_graphics/… and so on. | 6.4, 8.1 |
| FAQ: "List of supported boards … as of September 2024" — 39 boards. | 54 boards are supported now (the 112 directories are the same boards in different configurations). The list in this edition is read straight from the repository's boards/README.csv, so it cannot drift away from the code. | 3 |
| "To install Vivado or Gowin IDE you can use the information available on the internet" — that is, there are no instructions. | Those sections now exist: installing Vivado and Gowin EDA on every operating system, the programmer drivers, the udev rules, and an explanation of how the scripts locate each of these toolchains. | 4.1.2, 4.1.3, 4.2.2, 4.2.3 |
| "Everything is distributed free of charge … copies are hosted on Yandex Disk" — with cloud links as the main way to download. | Links to cloud copies are short-lived and go stale quickly inside the text of a manual. This edition names the official sources, and mentions the School's own distributions as a fallback, without specific links. | 4.1.1, 11 |
RARS: "you will need at least Java …", followed by installing OpenJDK by hand, JAVA_HOME, and %JAVA_HOME\bin on PATH. | In %JAVA_HOME\bin the closing percent sign is missing — the correct spelling is %JAVA_HOME%\bin. Under Linux, Java installs with the single command sudo apt install default-jre and needs no variables at all. | 4.1.9, 4.2.9 |
Here the old text is not wrong but incomplete: it is true for one case and silent about the rest, or gives an instruction without the reasoning, leaving the reader unable to tell when they may depart from it.
| In the previous edition | How it is now | Section of the new manual |
|---|---|---|
| Quartus is named as "21.1 Lite", as though it were the only version. | 21.1 Lite remains the recommended one, but it needs qualifications: Cyclone II boards need Quartus II 13.0sp1, Cyclone III boards need 13.1 (21.1 no longer supports those families), and the DE23-Lite needs Quartus Pro with a free licence. Recent releases (24.1, 25.1) are also fine for current boards. | 3.1, 4.1.1 |
| "Leave the installation path at its default." | Good advice, but it is worth explaining why it matters and when you may depart from it: the path must contain no spaces and no non-Latin characters, and an installation in an unusual directory means setting QUARTUS_ROOTDIR. | 4.1.1, 4.2.1.1 |
| The USB Blaster driver: USB Blaster and USB Blaster II are described. | USB Blaster III is needed as well — it is used on the DE23-Lite. Under Linux that is one extra udev rule line with idProduct 6022; without it the board cannot be programmed. | 4.1.1.2, 4.2.1.2 |
| The udev rule is given as one block, with no explanation. | It helps to explain how udev behaves: every *.rules file is read, in filename order, and the := operator forbids any later change to a value. So your own file and the one shipped with Quartus do not conflict, but the one that comes first alphabetically wins. | 4.2.1.2 |
| VS Code: one extension is recommended, SystemVerilog - Language Support. | Surfer is worth adding — an extension that shows waveforms inside the editor, without switching to a separate program. | 4.1.6, 4.1.7 |
| GTKWave is presented as the only waveform viewer. | There is an alternative now, Surfer; it is selected with WAVE_VIEWER=surfer and is more convenient on macOS, since it installs as an ordinary executable. On Apple Silicon the scripts in fact expect Surfer. | 4.1.7, 4.3 |
| Vivado: "the installer image is over 80 GB", with version 2022.2 recommended. | The size depends on the device families selected — picking only the ones you need makes the download substantially smaller. The scripts work with any version from 2018 onwards and, from 2024.2, understand the new directory layout (<parent>/<vendor>/<version>/Vivado instead of the former <parent>/<vendor>/Vivado/<version>). | 4.1.2 |
| Bootable SSD: "start pressing one of the keys to enter the BIOS". | The key opens the boot menu, not the BIOS — these are different things, and on some machines the keys differ. It is also worth explaining why the script erases the backup GPT table. | 6.1, 6.2 |
The verification virtual machine: "the user password" with no username given; the SSD image uses verilog for both login and password, while the verification VM uses the password 1234. | Two different images with two different sets of credentials are easy to mix up, so in this edition the credentials are stated next to each image separately. | 5, 6.2, 7 |
| Steps 1.1–1.3 (Windows) and 2.1–2.3 (Linux) "can be skipped" if the board is not an Altera one. | True, but it is better put the other way round: install the toolchain that matches your board, and the table in section 3 says exactly which that is. With no board you need no toolchain at all. | 3, 12 |
| "The manual may be updated, check the news on the site and in the Telegram channel" — with a link to the channel. | Worth adding that the repository itself carries a docs/ directory with separate files on Quartus, Gowin EDA, Yosys, Vivado, WSL and QEMU — it is updated together with the code and so is always fresher than any manual. | 11 |
Topics absent from the previous edition altogether. Some arrived with new tools; others existed before but were never written down.
| In the previous edition | How it is now | Section of the new manual |
|---|---|---|
| macOS support. | The previous edition covers only Windows and Linux. Under macOS there is neither Quartus nor Vivado, so Altera and Xilinx boards need a virtual machine; Gowin EDA, OSS CAD Suite, Icarus, Surfer and LibreLane, on the other hand, all work. There are peculiarities of its own: Gowin EDA only on Apple Silicon, an application bundle instead of a directory (Contents/Resources/Gowin_EDA), the com.apple.quarantine attribute, and a waveform viewer that depends on the processor. | 4.3 |
| OSS CAD Suite. | A single archive with Yosys, nextpnr, Icarus Verilog, GTKWave and the programming tools. It covers Lattice and Gowin boards without a proprietary toolchain and supplies a recent Icarus where the distribution only has an old one. Unpacking it into ~/oss-cad-suite is all that is required. | 4.1.4, 4.2.4 |
| Surfer — the program and the VS Code extension. | An alternative to GTKWave for viewing waveforms. | 4.1.7 |
| XPACK RISC-V GCC. | The C and assembly compiler for programs that run on processor cores inside the FPGA — including the aps core from MIET. Without it, the parts of the course about programming your own processor cannot be done. | 4.1.10, 4.2.10 |
| Terminal programs: minicom, picocom, putty. | Needed in order to upload a program into the board over UART and talk to the processor. Under Linux the user also has to be added to the dialout group. | 4.2.10, 8.2 |
Choosing a RISC-V core: aps (MIET), yrv, picorv32. | Switched with 13_choose_another_riscv_core_for_software.bash. | 8.1, 8.2 |
| A board table that states the toolchain and the acceptable versions. | In the previous edition the board list in the FAQ gave only the name and the FPGA family. The new table covers 54 boards with the FPGA and board manufacturer, the family, the required toolchain with its version range, whether TM1638 is used, and how graphics are wired. | 3 |
| An explanation of how the scripts find the toolchains. | The most common reason people write to the chat is "the script does not find Quartus" or "it finds the wrong version". This edition describes the search order for Quartus, Vivado and Gowin EDA, together with the rule for choosing a version by the board's chip and the cache in ~/.cache/basics-graphics-music. | 4.1.1.4, 4.1.2, 4.1.3 |
| The list of an example's scripts and the order to use them in. | The previous edition ended with checking the installation and did not explain what to do next. All 14 scripts are now described, from 01_clean to 14_run_terminal_program. | 8.2 |
| What the course consists of: the basics, graphics, music, microarchitecture and cpu parts. | A map of what is in which part and what it produces on the board — so that it is clear what all this software is being installed for. | 8.1 |
| A separate section on systemverilog-homework. | Previously the repository was mentioned in a single line, with an obsolete address. Yet it needs only Icarus Verilog and Git — no board and no vendor toolchain — which makes it a convenient place to start before a board arrives. | 1.3, 9 |
| Tiny Tapeout — having an example manufactured as a real chip. | The template takes the lab_top module out of the example, the same one that was debugged on the board; manufacturing is at the IHP foundry. The local check is ./07_synthesize_for_asic.bash. | 10 |
| Icarus from OSS CAD Suite, and building from source. | Two more ways to get Icarus 13 or 14 when the distribution's repositories only carry version 11 or 12. | 4.1.5, 4.2.5 |
| An installation FAQ. | The previous FAQ consisted of a single item, the board list. The new one answers the questions people actually ask: which toolchain to install, whether it works without a board, whether PATH is needed, why no Quartus version fits, why the scripts will not run from cmd.exe, and what to do about the macOS quarantine. | 12 |
| Selecting the board with one script. | ./check_setup_and_choose_fpga_board.bash checks the installed software and remembers the board choice for the whole repository — a step the previous edition never described, even though the examples cannot be built without it. | 6.4, 8.2 |
Three inaccuracies in the brief itself and in the list of recommendations. They are listed separately so that the corrections do not look arbitrary: the manual carries the corrected forms.
| Where | What was meant |
|---|---|
| The brief for this edition, item 2: "13.0sp1 for Cyclone II boards and 13.1 for Cyclone II boards". | The second one clearly meant Cyclone III: 13.0sp1 is the last version with Cyclone II and 13.1 the last with Cyclone III. The manual says so. |
| The brief, item 3: "new boards supported such as DE3-Lite". | The board is called DE23-Lite (Terasic, Agilex 3). No board named DE3-Lite exists; there is an old DE3 on Stratix III and a DE10-Lite on MAX 10. |
| The brief, outline of the "What is new" section: "Mention the update for DE23-Lite, Sound Blaster III". | What was meant is USB Blaster III — a programmer (idProduct 6022), not a sound card. Item 6 of the recommendations list says the same. |
The discrepancies were found by comparing three sources:
Инструкция_по_установке_ПО.pdf (68 pages) — line by line;main branch of the basics-graphics-music repository — the
scripts/steps/00_setup_*.source_bash scripts and the
boards/ and docs/ directories. Where the manual and
the code disagree, the code is right: it is what runs;The board table in section 3 of the manual is not retyped by hand; it is
generated from the repository's own boards/README.csv. It
therefore cannot drift away from the code the way the old FAQ's list did: to
update it, take that file again.
The toolchain search order was checked not only by reading the scripts but
by running them: determining the Quartus version from the board's chip was done
with the Tcl queries get_part_list and
get_family_list against every installed version, confirmed by real
synthesis runs. Hence the rule: a build is possible if the part is in the
device list or its family is in the family list — neither
query alone is sufficient.
The sections that could not be verified on live hardware are marked "not verified" in the manual. Those are macOS, and the dates and cost of the Tiny Tapeout shuttles.