Merge pull request #49 from ska-sa/fft_async_restore

FFT async restore

casper_library/fft_stage_n_init.m

@@ -52,7 +52,7 @@ function fft_stage_n_init(blk, varargin)
 clog('entering fft_stage_n_init', {log_group, 'trace'});
 
 % Don't use BRAMs with fanout control
-USE_DUMB_BRAMS = 1;
+USE_DUMB_BRAMS = 0;
 
 % Set default vararg values.
 % reg_retiming is not an actual parameter of this block, but it is included
@@ -177,6 +177,11 @@ function fft_stage_n_init(blk, varargin)
 
 % registers to control fanout for signals into delay buffers
 
+%if we don't like fanout at all, then force a minimum of 1 latency, otherwise allow it to go down
+%to 0 to minimise resource use.
+min_latency = 0;
+if max_fanout <= 1, min_latency = 1; end
+
 if USE_DUMB_BRAMS == 0 && strcmp(delays_bram, 'on'),
   % if we have a 'large' delay buffer in bram, add appropriate delay
   % based on an approximation of the number of BRAMs required from bit width and buffer depth
@@ -195,12 +200,13 @@ function fft_stage_n_init(blk, varargin)
   % number of BRAMs to handle input width
   n_brams = ceil((n_inputs * input_bit_width * 2)/word_size);
 
-  fan_latency = max(1, ceil(log2(n_brams)));
+  %we work out how much latency is required to control fanout 
+  fan_latency = max(min_latency, ceil(log2(n_brams)/max(1, log2(max_fanout)))-1);
   clog(['Using input latency of ', num2str(fan_latency), ' for ', num2str(n_brams),' bram/s in biplex core stage ', num2str(FFTStage)], log_group);
   bram_latency_comp = bram_latency;
 else,
   %otherwise we control fanout based on the number of input streams
-  fan_latency = max(0, ceil(log2(n_inputs/max_fanout)));
+  fan_latency = max(min_latency, ceil(log2(n_inputs)/max(1, log2(max_fanout)))-1);
   clog(['Using input latency of ', num2str(fan_latency), ' for ', num2str(n_inputs),' streams in biplex core stage ', num2str(FFTStage)], log_group);
   bram_latency_comp = 0;
 end

docs/index.rst

@@ -65,7 +65,7 @@ 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  |
+|  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      |
 +----------------+---------------------+--------------------+--------------------+---------------------------------+-------------------+
@@ -103,10 +103,10 @@ With the exception of ROACH1/2, all CASPER hardware mentioned above has been ful
 
 Ubuntu 18.04:
 
-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:
+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>`__.
+- 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). 
 
 Ubuntu 20.04:
@@ -123,7 +123,7 @@ Setup Links
 """""""""""
 
 1. :doc:`Installing the Toolflow <src/Installing-the-Toolflow>`
-2. :doc:`Installing Matlab <src/How-to-install-Matlab>`
+2. :doc:`Installing MATLAB <src/How-to-install-Matlab>`
 3. :doc:`Installing Xilinx Vivado <src/How-to-install-Xilinx-Vivado>`
 4. :doc:`Installing casperfpga <src/How-to-install-casperfpga>`
 5. :doc:`Configuring the Toolflow <src/Configuring-the-Toolflow>`

docs/src/Configuring-the-Toolflow.md

@@ -1,26 +1,26 @@
 # Configuring the Toolflow
 
 If you have successully installed the toolflow and its dependencies, it is now time to configure the flow to suit your specific environment.
-The toolflow needs to know where dependencies like Matlab and Xilinx tools have been installed. Other site-dependent parameters may also need to be defined.
+The toolflow needs to know where dependencies like MATLAB and Xilinx tools have been installed. Other site-dependent parameters may also need to be defined.
 
 ## The `startsg` script
 
 A startup script -- `startsg` -- is provided as part of the toolflow repository. This script can be used in two ways:
 
-- 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.
+- 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 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.
+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.
 
 ### Specifying local details
 
 The `startsg` script is generic. You should not need to modify it.
-The script does not require that the Matlab and Xilinx tools be installed in specific locations, but it does require that you provide it with a few details about your local installation.  This is done by creating a `startsg.local` file that defines a few key variables needed by `startsg`.
+The script does not require that the MATLAB and Xilinx tools be installed in specific locations, but it does require that you provide it with a few details about your local installation.  This is done by creating a `startsg.local` file that defines a few key variables needed by `startsg`.
 Two essential variables are:
 
-- `MATLAB_PATH` - the path to the directory where Matlab was installed
+- `MATLAB_PATH` - the path to the directory where MATLAB was installed
 - `XILINX_PATH` - the path to the directory where Xilinx Vivado is installed
 - `COMPOSER_PATH` - the path to the directory where the Xilinx Model Compose is installed
 
@@ -32,18 +32,18 @@ Optional variables:
 - `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.
+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.
 
 Here is a sample `startsg.local` file:
 
 ```bash
     export XILINX_PATH=/opt/Xilinx/Vivado/2021.1
     export COMPOSER_PATH=/opt/Xilinx/Model_Composer/2021.1
-    export MATLAB_PATH=/usr/local/Matlab/R2021a
+    export MATLAB_PATH=/usr/local/MATLAB/R2021a
     export PLATFORM=lin64
     export JASPER_BACKEND=vivado
 
-    # over-ride the Matlab libexpat version with the OS's one.
+    # 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"
@@ -58,7 +58,7 @@ If you really want to commit your local configuration file, you can do this, but
 ### 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 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.
+This can be useful if you want to store configurations for multiple versions of MATLAB / Xilinx tools.
 
 For example:
 ```bash
@@ -71,9 +71,9 @@ For example:
 
 ### Symlink for convenience
 
-Running `startsg` from the `mlib_devel` directory (where it lives) will start Matlab with `mlib_devel` as the current directory.
-Hopefully you store your models somewhere outside `mlib_devel` (which should contain only the CASPER _libraries_), in which case after running `startsg` you will need to navigate within Matlab to the directory where your model files live.
-To avoid this minor annoyance, you can create a symbolic link to `startsg` in your application directory (i.e.  where your model file lives).  When running `startsg` via this symlink, Matlab will start up with your application directory as the current directory and also run the optional `casper_startup.m` file if one exists.
+Running `startsg` from the `mlib_devel` directory (where it lives) will start MATLAB with `mlib_devel` as the current directory.
+Hopefully you store your models somewhere outside `mlib_devel` (which should contain only the CASPER _libraries_), in which case after running `startsg` you will need to navigate within MATLAB to the directory where your model files live.
+To avoid this minor annoyance, you can create a symbolic link to `startsg` in your application directory (i.e.  where your model file lives).  When running `startsg` via this symlink, MATLAB will start up with your application directory as the current directory and also run the optional `casper_startup.m` file if one exists.
 
 To configure such a symlink you should run