Merge pull request #153 from moragb96/docs_update

Docs update

docs/index.rst

@@ -84,7 +84,19 @@ The current compatibility matrix is below:
 |SNAP2           | Ubuntu 16.04        |  2016b             |  Vivado 2016.4     |  branch: `master`               |   Python 3        |
 +----------------+---------------------+--------------------+--------------------+---------------------------------+-------------------+
 
-The recommended OS is Ubuntu as it is what the majority of the collaboration are using. This makes it easier for us to support you. If you are so inclined, you could also use Red Hat, but we definitely do not support Windows. You are welcome to try but you will be on your own. You could always run Linux in a VM although this will increase your compile times. 
+A Note on Operating Systems
+"""""""""""""""""""""""""""
+
+The recommended OS is Ubuntu as this is what the majority of the collaboration are using. This makes it easier for us to support you. If you are so inclined, you could also use Red Hat, but we definitely do not support Windows. You are welcome to try but you will be on your own. You could always run Linux in a VM although this will increase your compile times. 
+
+With the exception of ROACH1/2, all CASPER hardware mentioned above has been fully tested using the Ubuntu 16.04 LTS distribution. However, while the above combinations have not been fully tested using Ubuntu 18.04 LTS (and it is therefore not yet an officially supported OS), it is possible to get the toolflow working on this OS with a few tweaks. 
+
+Some common issues encountered in running the tools on 18.04 include missing packages and incompatibilities between the libraries used to build older versions of Matlab/Vivado and the libraries that come with Ubuntu 18.04. Some tips on fixing these issues:
+
+- If you encounter System Generator socket timeout errors when trying to open a model in Simulink, or are faced with errors about GUI function call recursion when double-clicking Xilinx blocks, installing KDE (``sudo apt install kde-full``) may solve this.
+- If you encounter an error along the lines of `"MATLABWindow application failed to launch. Unable to launch the MATLABWindow application"`, this is due to library incompatibilities between 18.04 and Matlab R2018a and can be solved using `this workaround <https://www.mathworks.com/matlabcentral/answers/397138-why-do-i-get-a-matlabwindow-application-failed-to-launch-error-when-launching-live-editor-app-des>`__.
+- For more detailed information on debugging library clashes/missing libraries, `this blog post <https://strath-sdr.github.io/tools/matlab/sysgen/vivado/linux/2021/01/28/sysgen-on-20-04.html>`__ by Craig Ramsay very kindly steps through the debugging process of getting System Generator working on Ubuntu 20.04 and contains information that is equally applicable to debugging on 18.04 (such as using the ``ldd`` command to find missing/incorrect library dependencies, and then installing/excluding the relevant libraries as needed). 
+
 
 Please refer to the setup links below for more information on setting up the toolflow.
 

docs/src/How-to-install-casperfpga.md

@@ -1,6 +1,6 @@
 # How to install casperfpga
 
-This section explains how to install `casperfpga`, a python library used to interact with CASPER hardware.
+This section explains how to install `casperfpga`, a python library used to interact with CASPER hardware. The `casperfpga` library currently works fully with Python 2.7, with efforts underway to port it to Python 3.
 
 Once you have cloned the casperfpga repository, ensure that you are on the correct branch (usually **master** unless you are a contributor) and always pull regularly to make sure you have the latest version of casperfpga.
 
@@ -43,7 +43,7 @@ $ sudo python setup.py install
 
 ### Testing that the installation worked
 
-To check that casperfpga has been installed correctly open an ipython session and import casperfpga. To avoid errors, move out of your cloned casperfpga repository directory before doing this test. `casperfpga.__version__` will output the build and githash version of your casperfpga library.
+To check that casperfpga has been installed correctly open an ipython session and import casperfpga. **To avoid errors, move out of your cloned casperfpga repository directory before doing this test.** `casperfpga.__version__` will output the build and githash version of your casperfpga library.
 
 ```shell
 $ cd ..

docs/src/Installing-the-Toolflow.md

@@ -19,7 +19,8 @@ _(Note that official support for ROACH plaforms is no longer provided, however [
 |ZCU111          | Ubuntu 16.04        |  2018a             |  Vivado 2019.1.1   |  branch: `master`               |  Python 3        |
 |SNAP2           | Ubuntu 16.04        |  2016b             |  Vivado 2016.4     |  branch: `master`               |  Python 3        |
 
-Other software combinations may work, but these are the tested configurations.
+Other software combinations may work, but these are the tested configurations. Please see the [Note on Operating Systems](https://casper-toolflow.readthedocs.io/en/latest/index.html#a-note-on-operating-systems) for information on which alternative OS versions _may_ work with the tools.
+
 The master branch is usually updated once a year. Between updates, code with newer features can be found in the `casper-astro-soak-test` branch. This branch can usually be used in place of the `master` branch for platforms which support `master`. However, be aware that `casper-astro-soak-test` is likely to be less stable. Please report any bugs you encounter via github's issue tracker.
 
 
@@ -84,6 +85,8 @@ pip3 install -r requirements.txt
 
 You may need to run the `pip3 install` command as an administrator if you are using the system-maintained python installation instead of a virtual environment.
 
+**Note: there appears to be an incompability between pip3 v21.3.1 and xml2vhdl (one of the dependencies listing in the requirements file) that results in errors when installing requirements.txt. If you encounter an issue in fetching xml2vhdl when running `pip3 install -r requirements.txt`, try install pip3 v18.1 or earlier and use that instead (this is one of those things best done in a virtual environment, so as to not mess around with the system verson of python)**  
+
 ## Configuring the toolflow
 
 You now have all the software you need to start building your designs. However, you'll still need to specify some local configuration details which will depend on how you carried out your installation. See [Configuring the Toolflow](https://casper-toolflow.readthedocs.io/en/latest/src/Configuring-the-Toolflow.html) for more details.