Merge pull request #112 from moragb96/mo_docs_update

Morag docs update
casper-astro · Oct 30, 2019 · f801975 · f801975
2 parents 8751be1 + 69abd04
commit f801975
Show file tree

Hide file tree

Showing 7 changed files with 137 additions and 62 deletions.
diff --git a/docs/conf.py b/docs/conf.py
@@ -58,7 +58,8 @@ def setup(app):
     'sphinx.ext.imgmath',
     'sphinx.ext.ifconfig',
     'sphinx.ext.viewcode',
-    'sphinx.ext.githubpages'
+    'sphinx.ext.githubpages',
+    'sphinx_markdown_tables',
 ]
 
 # Add any paths that contain templates here, relative to this directory.

diff --git a/docs/index.rst b/docs/index.rst
@@ -58,25 +58,42 @@ This script will resynchronize every CASPER block in your design with its latest
 Setup
 ------
 
-The software stack you will require to use the toolflow will depend what hardware you are targetting. Older hardware (ROACH2 and earlier) use the older Xilinx software (ISE) which forces the use of different tools.
-
-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.
-
-+-------------+--------------------+----------------+---------------+----------------------------------------------------------------------------+
-| Platform    | OS                 | Matlab Version | Xilinx Tools  | mlib_devel                                                                 |
-+=============+====================+================+===============+============================================================================+
-| ROACH1 or 2 | Ubuntu 12.04/14.04 | R2013b         | ISE 14.7      | `ROACH branch <https://github.com/casper-astro/mlib_devel/tree/roach2>`__  |
-+-------------+--------------------+----------------+---------------+----------------------------------------------------------------------------+
-| SNAP        | Ubuntu 14.04/16.04 | R2016b         | Vivado 2016.4 | `Master branch <https://github.com/casper-astro/mlib_devel>`__             |
-+-------------+--------------------+----------------+---------------+----------------------------------------------------------------------------+
-| SKARAB      | Ubuntu 14.04/16.04 | R2016b         | Vivado 2016.2 | `Master branch <https://github.com/casper-astro/mlib_devel>`__             |
-+-------------+--------------------+----------------+---------------+----------------------------------------------------------------------------+
-| VCU118      | Ubuntu 14.04/16.04 | R2017b         | Vivado 2018.2 | `vcu118 branch <https://github.com/casper-astro/mlib_devel/tree/vcu118>`__ |
-+-------------+--------------------+----------------+---------------+----------------------------------------------------------------------------+
+The software stack you will require to use the toolflow will depend what hardware you are targeting. Older hardware (ROACH2 and earlier) use the older Xilinx software (ISE) which forces the use of different tools.
+
+The current compatibility matrix is below:
+
+(Note that official support for ROACH plaforms is no longer provided, however `this version <https://github.com/casper-astro/mlib_devel/tree/d77999047d2f0dc53e1c1e6e516e6ef3cdd45632/docs>`__ of `mlib_devel` contains all ROACH related documentation and ROACH tutorials can be found `here <https://casper-tutorials.readthedocs.io/en/latest/tutorials/roach/tut_intro.html>`__)
+
++----------------+---------------------+--------------------+--------------------+---------------------------------+-------------------+
+|  Hardware      |   Operating System  |    Matlab Version  |    Xilinx Version  |    mlib_devel branch / commit   |   Python Version  |
++================+=====================+====================+====================+=================================+===================+
+|ROACH1/2        | Ubuntu 14.04        |  2013b             |  ISE 14.7          |  branch: `roach`                |   Python 2.7      |
++----------------+---------------------+--------------------+--------------------+---------------------------------+-------------------+
+|SKARAB          | Ubuntu 16.04        |  2018a             |  Vivado 2019.1.1   |  branch: `master`               |   Python 3        |
++----------------+---------------------+--------------------+--------------------+---------------------------------+-------------------+
+|SNAP            | Ubuntu 16.04        |  2018a             |  Vivado 2019.1.1   |  branch: `master`               |   Python 3        |
++----------------+---------------------+--------------------+--------------------+---------------------------------+-------------------+
+|Red Pitaya      | Ubuntu 16.04        |  2018a             |  Vivado 2019.1.1   |  branch: `master`               |   Python 3        |
++----------------+---------------------+--------------------+--------------------+---------------------------------+-------------------+
+|VCU118          | Ubuntu 16.04        |  2018a             |  Vivado 2019.1.1   |  branch: `master`               |   Python 3        |
++----------------+---------------------+--------------------+--------------------+---------------------------------+-------------------+
+|VCU128          | Ubuntu 16.04        |  2018a             |  Vivado 2019.1.1   |  branch: `master`               |   Python 3        |
++----------------+---------------------+--------------------+--------------------+---------------------------------+-------------------+
+|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        |
++----------------+---------------------+--------------------+--------------------+---------------------------------+-------------------+
+
+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. 
+
+Please refer to the setup links below for more information on setting up the toolflow.
+
+Setup Links
+"""""""""""
 
 1. :doc:`Installing the Toolflow <src/Installing-the-Toolflow>`
 2. :doc:`Installing Matlab <src/How-to-install-Matlab>`
-3. :doc:`Installing Xilinx Vivado <src/How-to-install-Xilinx-Vivado>` or :doc:`Installing Xilinx ISE (ROACH only) <src/How-to-install-Xilinx-ISE>`
+3. :doc:`Installing Xilinx Vivado <src/How-to-install-Xilinx-Vivado>`
 4. :doc:`Configuring the Toolflow <src/Configuring-the-Toolflow>`
 5. :doc:`Running the Toolflow <src/Running-the-Toolflow>`
 
@@ -88,7 +105,6 @@ The recommended OS is Ubuntu as it is what the majority of the collaboration are
     src/Installing-the-Toolflow
     src/How-to-install-Matlab
     src/How-to-install-Xilinx-Vivado
-    src/How-to-install-Xilinx-ISE
     src/Configuring-the-Toolflow
     src/Running-the-Toolflow
 
@@ -118,3 +134,4 @@ Get Involved
 If you are a CASPER collaborator, or you’re just interested in what we’re up to, feel free to join our mailing list by sending a blank email `here. <casper+subscribe@lists.berkeley.edu>`_
 
 If would like to get involved in the development of the tools, please join our dev mailing list by sending a blank email `here. <casper-dev+subscribe@lists.berkeley.edu>`_.
+
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1,6 +1,7 @@
 markdown
 sphinx
 sphinx_rtd_theme
+sphinx_markdown_tables
 recommonmark
 PyYAML
 numpy
diff --git a/docs/src/Configuring-the-Toolflow.md b/docs/src/Configuring-the-Toolflow.md
@@ -10,7 +10,7 @@ A startup script -- `startsg` -- is provided as part of the toolflow repository.
 - If _executed_ (i.e. `/path/to/mlib_devel/startsg`): start MATLAB with the correctly defined library paths. 
 - If _sourced_ (i.e. `source /path/to/mlib_devel/startsg`): configure software paths without starting MATLAB.
 
-The former method is what you shoud do if you want to start a Simulink design, or open an existing one.
+The former method is what you should do if you want to start a Simulink design, or open an existing one.
 
 The latter method is useful if you want to run parts of the toolflow outside of MATLAB (eg. `exec_flow.py`) or run Xilinx tools (eg. `vivado`) directly from the command line.
 
@@ -27,7 +27,8 @@ Optional variables:
 
 - `PLATFORM` - Used by the Xilinx tools to select suitable runtime binaries for your system.  If not specified, it will be defaulted to `lin64`, indicating a 64-bit Linux operating system. This is the only configuration the collaboration tests.
 - `XILINXD_LICENCE_FILE` - The path to your Xilinx software license if it exists in a non-standard location.
-- `JASPER_BACKEND` - the type of Xilinx tools you want to use to implement your design. Supported options are `vivado` or `ise`. The default is `vivado`, which is correct for all CASPER-supporterd platforms except ROACH1/ROACH2.
+- `JASPER_BACKEND` - the type of Xilinx tools you want to use to implement your design. Supported options are `vivado` or `ise`. The default is `vivado`, which is correct for all CASPER-supported platforms. _(Note: `ise` is the Xilinx tool used for ROACH1/ROACH2 designs, however official support for ROACH platforms is no longer provided)._
+- `CASPER_PYTHON_VENV_ON_START` - The path to your Python virtual environment (if one is being used). This will activate the virtual environment on load.
 
 Other variables:
 Depending on your operating system, and MATLAB / Xilinx quirks, you may need to specify other generic OS variables. For example, with MATLAB 2018a and Ubuntu 16.04, it is necessary to over-ride the default MATLAB libexpat library to a newer version. To do this you can set the `LD_PRELOAD` variable.
@@ -39,18 +40,22 @@ Here is a sample `startsg.local` file:
     export MATLAB_PATH=/usr/local/MATLAB/R2018a
     export PLATFORM=lin64
     export JASPER_BACKEND=vivado
+
     # over-ride the MATLAB libexpat version with the OS's one.
     # Using LD_PRELOAD=${LD_PRELOAD}:"..." rather than just LD_PRELOAD="..."
     # ensures that we preserve any other settings already configured
     export LD_PRELOAD=${LD_PRELOAD}:"/usr/lib/x86_64-linux-gnu/libexpat.so"
+
+    # Activate a custom python environment on load
+    export CASPER_PYTHON_VENV_ON_START=/home/user/work/casper_venv
 ```
 
-Since this configuration refers to your specific installation environment, in general it shouldn't be commited to the `mlib_devel` repository. In fact, the repository is configured to ignore changes to any files wite names beginning `startsg.`.
+Since this configuration refers to your specific installation environment, in general it shouldn't be commited to the `mlib_devel` repository. In fact, the repository is configured to ignore changes to any files with names beginning `startsg.`.
 If you really want to commit your local configuration file, you can do this, but it's helpful to call it something other than `startsg.local`, (eg. `startsg.local.example` or `startsg.local.my-server-name`) so as not to conflict with other users, all of whom will have similar files with different contents.
 
 ### Using `startsg`
 By default, executing (or sourcing) the `startsg` script will use variables defined in the configuration file `startsg.local` residing in the same directory as `startsg`.
-However, you can uswe a specific configuration by specifying one as an argument to `startsg`.
+However, you can use a specific configuration by specifying one as an argument to `startsg`.
 This can be useful if you want to store configurations for multiple versions of MATLAB / Xilinx tools.
 
 For example:

diff --git a/docs/src/How-to-install-Xilinx-Vivado.md b/docs/src/How-to-install-Xilinx-Vivado.md
@@ -38,6 +38,8 @@ is highly recommended, as the documentation is part of the Ultrafast design meth
 
 ## Optional: Install USB Drivers for JTAG
 
+*Note: this will only be used by toolflow/yellow block developers and is not required for standard use of the toolflow*
+
 The most reliable way to install the JTAG cable drivers is to use the drivers provided with ISE.
 
 A folder containing all the files required has been uploaded in the same folder as this document: [linux_jtag_cable_drivers.tar.gz](https://drive.google.com/file/d/0Byu0Sq2IEDuJdVFMMkNLN2pxYnc/view?usp=sharing). This also includes a useful installation script that prepares the files and places them in the correct directories.
@@ -84,6 +86,8 @@ is highly recommended, as the documentation is part of the Ultrafast design meth
 
 ## Optional: Install USB Drivers for JTAG
 
+*Note: this will only be used by toolflow/yellow block developers and is not required for standard use of the toolflow*
+
 A folder containing all the files required has been uploaded in the same folder as this document: [linux_jtag_cable_drivers.tar.gz](https://drive.google.com/file/d/0Byu0Sq2IEDuJdVFMMkNLN2pxYnc/view?usp=sharing). This also includes a useful installation script that prepares the files and places them in the correct directories.
 
 Instructions: