[mkdocs] update

.gitignore

@@ -2,6 +2,7 @@
 !*.*
 /build/
 /export/
+/docs/
 *.user
 *.o
 *.log

web/Makefile

@@ -0,0 +1,44 @@
+MAKE ?= make
+
+MKDIR := mkdocs
+DOCDIR := ../docs
+
+####################################################################
+help:
+	@echo "======================================================="
+	@echo "                   Syfala Documentation"
+	@echo "This Makefile is intended to generate the Syfala documentation"
+	@echo "======================================================="
+	@echo "Available targets are:"
+	@echo "  build    : build the web site"
+	@echo "  serve    : launch the mkdoc server"
+	@echo "Making the current version publicly available:"
+	@echo "             just commit and push the /docs folder (master branch)"
+
+
+####################################################################
+build:
+	cd $(MKDIR) && mkdocs build
+#	git checkout ../docs/CNAME
+
+serve:
+	cd $(MKDIR) && mkdocs serve
+
+all:
+	$(MAKE) build
+
+clean:
+	rm -f $(DOCDIR)
+#	git checkout ../docs/CNAME
+
+####################################################################
+install:
+	pip install mkdocs
+	pip install markdown-include
+	pip install mkdocs-bootswatch
+	pip install python-markdown-math
+
+uninstall:
+	pip uninstall -y mkdocs-material
+	pip uninstall -y pymdown-extensions
+	pip uninstall -y markdown-blockdiag

web/mkdocs/docs/index.md

@@ -0,0 +1,6 @@
+# Syfala Toolchain Documentation
+
+This is the Syfala documentation website.
+
+Please, refer to the "Manual" tab above for more information.
+

web/mkdocs/docs/manual/dependencies.md

@@ -0,0 +1,132 @@
+# Syfala Toolchain Dependencies
+
+The Syfala toolchain is a compilation toolchain of Faust programs onto AMD-Xilinx FPGA targets. This document explains how to install and run the **version 0.7.1** of the toolchain  on a Linux machine. In practice, installing the Syfala toolchain means:
+
+- Installing the required **linux-packages**, depending on your Linux distribution.
+- Installing the **Faust** compiler
+- Creating a **AMD-Xilinx account** and downloading/installing the **2022.2 version** (2020.2 is also still supported) of the AMD-Xilinx toolchain (providing softwares such as Vivado, Vitis, Vitis HLS).
+- Installing the additional **Vivado Board Files** for Digilent Boards.
+- Installing *udev* rules in order to use the JTAG connection.
+- Cloning the **Syfala repository**, and running a **simple example** to make sure everything is working properly.
+
+## Linux Targets
+
+We recommend using **Ubuntu** (>= 18.04 LTS) for installing and using the toolchain, since it is officially supported by AMD-Xilinx. While it is still possible to use other distributions, such as Archlinux, you may encounter unresolved bugs, which won't necessarily appear in our *Troubleshooting* section below. 
+
+### Ubuntu Dependencies
+
+```shell
+$ sudo apt-get update 
+$ sudo apt-get install git libncurses5 libtinfo-dev build-essential default-jre pkg-config g++-multilib gtk+2.0 locales
+```
+
+### Archlinux Dependencies
+
+```bash
+# faust (required)
+$ sudo pacman -S faust
+
+# for xilinx vivado/vitis etc.
+$ yay -S ncurses5-compat-libs libxcrypt-compat libpng12 lib32-libpng12 xorg-xlsclients gtk2
+```
+
+## Faust
+
+It is recommended to clone Faust from the official github repository: https://github.com/grame-cncm/faust
+
+```shell
+$ git clone https://github.com/grame-cncm/faust.git 
+$ cd faust
+$ make
+$ sudo make install
+```
+
+## Vivado, Vitis & Vitis HLS (2022.2 version)
+
+- Open an account on https://www.xilinx.com/registration
+- The AMD-Xilinx [download page](https://www.xilinx.com/support/download.html) contains links for downloading the **Vivado Design Suite - HLx Editions - Full Product**. It is available for both Linux and Windows. 
+  - Download the Linux installer `Xilinx_Unified_2022.2_1014_8888_Lin64.bin`
+
+- Execute `chmod a+x Xilinx_Unified_2022.2_1014_8888_Lin64.bin`
+
+- Execute `./Xilinx_Unified_2022.2_1014_8888_Lin64.bin`
+
+  - We suggest to use the "**Download Image (Install Separately)**" option. It creates a directory with a **xsetup** file to execute that you can reuse in case of failure during the installation
+
+- Execute `./xsetup`
+
+  -  Choose to install **Vitis** (it will still install **Vivado**, **Vitis**, and **Vitis HLS**). 
+  - It will need **110GB of disk space**: if you uncheck *Ultrascale*, *Ultrascale+*, *Versal ACAP* and *Alveo acceleration platform*, it will use less space and still work.
+  - **Agree** with everything and choose a directory to install (e.g. ~/Xilinx)
+  - **Install and wait** (it may take quite a while)
+
+- **Setup a shell environment variable** allowing to use the tools when necessary (add this to your `~/.bashrc`, `~/.zshrc` or whatever you're currently using, replacing `$XILINX_ROOT_DIR` by the directory you chose to install all the tools)
+
+  - ```shell
+    export XILINX_ROOT_DIR=$HOME/Xilinx
+    ```
+
+### Installing Cable Drivers on Linux
+
+-  Go to: `$XILINX_ROOT_DIR/Vivado/2022.2/data/xicom/cable_drivers/lin64/install_script/install_drivers` directory
+- Run `./install_drivers`
+- Run `sudo cp 52-xilinx-digilent-usb.rules /etc/udev/rules.d`, this allows **JTAG** connection through **USB**.
+
+### Installing Digilent Board Files
+
+- Download the board files from [github](https://github.com/Digilent/vivado-boards/archive/master.zip?_ga=2.76732885.1953828090.1655988025-1125947215.1655988024):
+- Open the folder extracted from the archive and navigate to its `new/board_files` folder. You will be copying all of this folder's subfolders
+  - For the 2020.2 version, go to `$XILINX_ROOT_DIR/Vivado/2020.2/data/boards/board_files`
+  - For the 2022.2 version, go to `$XILINX_ROOT_DIR/Vivado/2022.2/data/xhub/boards/XilinxBoardStore/boards/Xilinx`
+
+- **Copy** all of the folders found in vivado-boards `new/board_files `folder and **paste** them into this folder
+
+### Installing the 2022 patch (AMD-Xilinx toolchain v2020.2 only)
+
+Vivado and Vitis tools that use HLS in the background are also affected by this issue. HLS tools set the ip_version in the format YYMMDDHHMM and this value is accessed as a signed integer (32-bit) that causes an overflow and generates the errors below (or something similar).
+
+- Follow this link: https://support.xilinx.com/s/article/76960?language=en_US
+
+- Download the file at the bottom of th page and unzip it in `$XILINX_ROOT_DIR`
+
+- run the following commands: 
+
+- ```shell
+  $ cd $XILINX_ROOT_DIR
+  $ export LD_LIBRARY_PATH=$PWD/Vivado/2020.2/tps/lnx64/python-3.8.3/lib/
+  $ Vivado/2020.2/tps/lnx64/python-3.8.3/bin/python3 y2k22_patch/patch.py
+  ```
+
+## Cloning the Syfala Repository
+
+To clone and install the latest stable version of the Syfala toolchain, you can use the following commands:
+
+```shell
+$ git clone https://github.com/inria-emeraude/syfala 
+$ cd syfala
+$ ./syfala.tcl install
+$ syfala --help
+```
+
+In order to use the Syfala toolchain to compile your first example, please report to the main [README](https://github.com/inria-emeraude/syfala/blob/main/README.md) file located in the repository's root directory.
+
+## Troubleshooting
+
+On **Archlinux**, if you see an error like this one 
+
+```
+/lib/../lib64/crti.o: file not recognized: File format not recognized
+```
+
+you'll have to rename the `Vivado/2020.2/tps/lnx64/binutils-2.26` (Vitis will then search in the system libraries).
+
+#### Vitis/Java Issues
+
+On recent systems (or with **Archlinux**), you might have problems compiling the host-side (**ARM**) application. The problem is caused by system libraries requiring newer versions of GCC than the one provided by Vitis. Replacing GCC target in Vitis' path **by system GCC** works:
+
+```bash
+$ cd $XILINX_ROOT_DIR/Vitis/2020.2/lib/lnx64.o/Default
+$ mv libstdc++.so.6 libstdc++.so.6.old
+$ rm -rf libstdc++.so (symlink)
+$ sudo ln -s /usr/lib/libstdc++.so.6 libstdc++.so.6
+```

web/mkdocs/docs/manual/manual.md

@@ -0,0 +1,135 @@
+# Syfala Toolchain Documentation
+
+Automatic compilation of Faust audio DSP programs for AMD-Xilinx FPGAs.
+
+## Supported Board Models
+
+- [x] Digilent **Zybo Z7-10** - Zynq-7000 ARM/FPGA SoC Development Board
+- [x] Digilent **Zybo Z7-20** - Zynq-7000 ARM/FPGA SoC Development Board
+- [x] Digilent **Genesys ZU-3EG** - Zynq UltraScale+ MPSoC Development Board
+
+and more to come...
+
+## Dependencies
+
+Please follow the instructions in the file [dependencies.md](dependencies.md) in order to install the **AMD-Xilinx** **toolchain** and various other dependencies.
+
+## Installing
+
+the command `make install` will install a **symlink** in **/usr/bin**. After this you'll be able to just run:
+
+`$ syfala myfaustprogram.dsp`
+
+You'll also have to **edit** your shell **resource** **file** (~/.**bashrc** / ~/.**zshrc**) and set the following environment variable:
+
+```shell
+export XILINX_ROOT_DIR=/my/path/to/Xilinx/root/directory
+```
+
+`XILINX_ROOT_DIR` is the root directory where all of the AMD-Xilinx tools (Vivado, Vitis, Vitis_HLS) are installed.
+
+## Getting Started
+
+### Hardware Setup (Digilent **Zybo-Z7-10/20** Boards)
+
+- [ ] Jumper **JP5** should be on *JTAG*
+- [ ] **Power select** jumper should be on *USB*
+- [ ] **Switches** SW0, SW1, SW2, SW3 should be **down**
+- [ ] The **audio input** is **LINE IN** (blue), not MIC IN
+- [ ] The **audio output** is the black **HPH OUT** jack
+
+### Software
+
+#### Faust Targets
+
+Building a simple example for the **default board** (Digilent Zybo **Z7-10)**:
+
+```shell
+$ syfala examples/faust/virtualAnalog.dsp
+```
+
+This will run the **full syfala toolchain** on the virtualAnalog.dsp **Faust** file, which will then be ready to be flashed on the board. Y**ou can specify the targeted board** using the `-b (--board)` option:
+
+```shell
+$ syfala examples/faust/virtualAnalog.dsp --board Z20
+$ syfala examples/faust/virtualAnalog.dsp --board GENESYS
+```
+
+You can now **connect the board** to your computer with the proper **USB/Serial port cable** and run the `flash` command:
+
+```shell
+$ syfala flash
+```
+
+The board's **RGB LED** should then flash **green** after a few seconds, indicating that your program is running. You can now **start the Faust GUI application**, which will display a set of sliders/knobs/buttons and **update the DSP parameters in real-time through USB-UART**:
+
+```shell
+$ syfala start-gui
+```
+
+#### C++ Targets
+
+For C++ targets, the process is exactly the same (excepted for the GUI part, which is not available):
+
+```shell
+$ syfala examples/cpp/bypass.cpp --board Z20
+$ syfala flash
+```
+
+### Exporting and Re-Importing Your Builds
+
+When you're done playing with your program, you can **save and export it** as a `.zip` file with the following command:
+
+```shell
+$ syfala export my-faust-virtual-analog-build
+# the exported .zip file is tagged with date & time, e.g.:
+>> "export/2022-02-17-my-faust-virtual-analog-build.zip"
+```
+
+The resulting `.zip` file is now available in the repository's `export` directory, you can **re-import** it by typing:
+
+```shell
+$ syfala import export/2022-02-17-my-faust-virtual-analog-build.zip
+```
+
+### Making Another Build
+
+Before building another DSP program, please **make sure you have saved and exported your previous build** beforehand, otherwise **it will be overwritten** whenever you start a new build.
+
+```shell
+$ syfala examples/my-new-dsp-build.dsp
+```
+
+## Embedded Linux
+
+Please report to the [linux-getting-started.md](doc/linux-getting-started.md) document in order to get you started with the Embedded Linux for Syfala.
+
+## Going Further
+
+Please report to the [reference](reference.md) for more information on available **commands**, **options** and documentation.
+
+## The Syfala Team
+
+Here is a list of person that have contributed to the Syfala project :
+
+- Tanguy Risset
+- Yann Orlarey
+- Romain Michon
+- Stephane Letz
+- Florent de Dinechin
+- Alain Darte
+- Yohan Uguen
+- Gero Müller
+- Adeyemi Gbadamosi
+- Ousmane Touat
+- Luc Forget
+- Antonin Dudermel
+- Maxime Popoff
+- Thomas Delmas
+- Oussama Bouksim
+- Pierre Cochard
+- Joseph Bizien
+- Agathe Herrou
+- Jurek Weber
+- Aloïs Rautureau
+