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 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.
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.
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
.
Two essential variables are:
MATLAB_PATH
- the path to the directory where MATLAB was installedXILINX_PATH
- the path to the directory where Xilinx Vivado is installedCOMPOSER_PATH
- the path to the directory where the Xilinx Model Compose is installed
Optional variables:
PLATFORM
- Used by the Xilinx tools to select suitable runtime binaries for your system. If not specified, it will be defaulted tolin64
, 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 arevivado
orise
. The default isvivado
, 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.
Here is a sample startsg.local
file:
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 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 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 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:
$ ./startsg # Uses startsg.local if one exists in the current directory
$ ./mlib_devel/startsg # Uses startsg.local if one exists in ./mlib_devel/
$ ./startsg startsg.local.use_vivado_2016 # Uses the startsg.local.use_vivado_16 configuration file
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.
To configure such a symlink you should run
# Go to the directory you store your models in.
# You should place a startsg.local file here.
cd /directory/where/my/models/are
# Create the symbolic link
ln -s /directory/where/mlib_devel/is/startsg startsg
# Run startsg from your model directory
./startsg my.startsg.local
This model of operating works particularly well when using git submodules to store a copy of mlib_devel
alongside your models. Using submodules in this way ensures that whoever downloads your models can also easily obtain the version of mlib_devel
they were originally compiled against.
In this case, your directory structure will look something like:
my_spectrometer/
├── my_spectrometer.slx
├── startsg.local
├── startsg (symlink -> ./mlib_devel/startsg)
└── mlib_devel (submodule)
├── startsg
├── casper_library
├── ...
├── ...
└── ...