Note: This HTML section is rendered based on the Markdown file in cFCreate.
4.2. cFCreate¶
Framework for creating and updating cloudFPGA projects
4.2.1. Requirements¶
The cFCreate script has some python dependencies, hence we recommend the usage of virtualenvs.
This python Virtual environment is only required for the execution of cFCreate, not for the build of the FPGA bistreams in a cFp!
However, python3 is required to build cFp bitstreams.
4.2.1.1. Setup your Virtualenv¶
(we recommend the use of python3.8)
If you received this repository as Zip-folder, extract it into <your-path>/cFCreate. Otherwise clone this repositroy into <your-path/cFCreate.
$ cd <your-path>/cFCreate/
$ which python3.8
/usr/bin/python3.8
$ virtualenv -p /usr/bin/python3.8 cfenv
$ source cfenv/bin/activate
$ pip install -r requirements.txt
You may have to install pip and virtualenv first:
$ sudo su
$ /usr/bin/python3.8-m ensurepip
$ pip3 install virtualenv
$ exit
And maybe also python-devel. For Centos or Redhat:
$ sudo yum install python3-devel.x86_64
For Ubuntu:
$ apt install python3.8-dev
Important: The absolute path to this virutalenv and the virtualenv itself will be used by other components of
the cloudFPGA framework!
If cFCreate is moved to a different location, all projects must be updated (using cFCreate update).
4.2.2. Usage¶
$ ./cFCreate -h
cloudFPGA Project Management Framework
cFCreate creates or updates cloudFPGA projects (cFp) based on the cloudFPGA Development Kit (cFDK).
Usage:
cFCreate new (--cfdk-version=<cfdkv> | --cfdk-zip=<path-to-zip>) [--git-url=<git-url>] [--git-init] <path-to-project-folder>
cFCreate update <path-to-project-folder>
cFCreate adorn (--cfa-repo=<cfagit> | --cfa-zip=<path-to-zip>) <folder-name-for-addon> <path-to-project-folder>
cFCreate -h|--help
cFCreate -v|--version
Commands:
new Creates a new cFp based on the given cFDK
update Update the environment setting of an existing cFp
adorn Installs a cloudFPGA addon (cFa) to an existing cFp
Options:
-h --help Show this screen.
-v --version Show version.
--cfdk-version=<cfdkv> Specifies that the cFDK can be accessed via Github and which cFDK-version should be used.
'latest' will use the latest available version.
--git-url=<git-url> Uses the given URL to clone cFDK instead the default.
--cfdk-zip=<path-to-zip> If the cFDK can't be reached via Github, a zip can be used.
--git-init Creates the new cFp as git-repo; Adds the cFDK as git submodule, if not using a cfdk-zip
--cfa-repo=<cfagit> Link to the cFa git repository
--cfa-zip=<path-to-zip> Path to a cFa zip folder
Copyright IBM Research, licensed under the Apache License 2.0.
Contact: {ngl,fab,wei}@zurich.ibm.com
There are three typical use-cases:
General notice: The terms ‘git url’ or ‘git repo’ always refer to a link that can be used to clone the repository!
E.g. git@git.example.com:group/repo.git or https://git.example.com/group/repo.git.
If ‘a zip folder’ is mentioned, a zip-file provided by the cloudFPGA team is meant, so that it has the right structure etc.
4.2.2.1. 1. Create new cloudFPGA project (cFp)¶
To create a new cFp, use the cFCreate command:
The script will ask for the type of SRA or cF module –> see cFDK documentation.
The project-folder should not exist (yet) or must be empty.
New cFp with a cFDK-zip .. code-block:: bash
./cFCreate new –cfdk-zip=./<path>/cFDK-v0.1.zip <path-to-project-folder>
New cFp using cFDK from Github
./cFCreate new --cfdk-version=v0.1 <path-to-project-folder>
If the default Github URL is not accessible, an alternative can be specified with -git-url.
The new project is initalized as git repository, if the option ``–git-init`` is used. In case of using cFDK from Github, this is initialized as git-submodule. To init the project as git repository can also be done manually, see the section Git integration below.
The use of ``–git-init`` is recommended!
4.2.2.2. 2. Update an existing cFp¶
- If it is necessary to regenerate the environment of the cFp (e.g. switch of SRA type or cFDK version,
or after a fresh clone of an existing cFp), run:
in the existing cFp path:
$ git submodule init
$ git submodule update
before you then run:
./cFCreate update <path-to-project-folder>
You have to answer a few questions to regenerate the environment.
For example the path to the Xilinx environment which is in case of our ZYC2 VM
/tools/Xilinx/Vivado/2017.4/
4.2.2.3. 3. Add a cloudFPGA addon (cFa) to an existing cFp¶
Further features may be available outside the default cFDK. There are again two ways to install them to an existing cFp:
Using an existing git repository: .. code-block:: bash
./cFCreate adorn –cfa-repo=<cfagit> <folder-name-for-addon> <path-to-project-folder>
Using a cFa-zip .. code-block:: bash
./cFCreate adorn –cfa-zip=<path-to-zip> <folder-name-for-addon> <path-to-project-folder>
The <folder-name-for-addon> will be the name of the folder that will be created in <path-to-project-folder> for the new cFa.
If the cFp is a git-repository, all changes will be commited by cFCreate (maybe check the output for error messages).
It is not necessary to run cFCreate update afterwards on any machine.
4.2.3. Structure of a cFp¶
$ tree <cFp_repo>
cFDK/ (submodule)
TOP/
└──tcl/ (don't touch, is copied from cFDK)
└──xdc/ (add debug nets here)
└──hdl/
└──top.vhdl
└── a.s.o. (if custom hdl files for TOP)
ROLE/
└── role1 (or not, depends on PR, etc.)
└── a.s.o.
dcps/ (contains the dcps and bitfiles)
xpr/ (vivado project)
ip/ (contains the IP cores (generated during build))
Makefile
env/
└── setenv.sh (sets the envrionments)
<possible_addons/>
4.2.4. Build a cFp¶
See the documentation of cFDK. In short:
$ source env/setenv.sh # DON'T FORGETT!
$ make monolithic
# or
$ make pr
If synthesis fails without an error retry the make monolithic or open the project with Vivado and start synthesis there.
Resulting bitfiles are in ./dcps/.
4.2.5. Git integration¶
If not done with the ``–git-init`` option during the creation of a new cFp, the following steps are necessary to use the cFp as git repository and/or use the cFDK as git-submodule:
4.2.5.1. Push new cFp to a git repository¶
Basically, follow this steps. In short:
$ cd <cFp_repo>
$ git init
$ git add .
$ git commit -m "First commit"
$ git remote add origin <remote-repository-URL>
$ git push origin master
(This could also be done by ``cFCreate`` with the ``–git-init`` option.)
4.2.5.2. cFDK as git submodule¶
If not done automatically with the ``–git-init`` option: It is recommended, to declare the cFDK folder as git submodule to the cFp git repository. Therefore, execute the following:
$ cd <cFp_repo>
$ git submodule add --name cFDK file://./cFDK/
Before commit, you must manually update the path to the remote location, if desired.
Hence, overwrite the file <cFp_repo>/.gitmodules with the following content:
[submodule "cFDK"]
path = cFDK
url = git@github.ibm.com:cloudFPGA/cFDK.git
also, update .git/config accordingly, from:
[submodule "cFDK"]
url = file://./cFDK/
to
[submodule "cFDK"]
url = git@github.ibm.com:cloudFPGA/cFDK.git
Or use the alternative git-url as mentioned above.
Afterwards, run:
$ git submodule init
$ git submodule update
$ git commit
$ git push
Further information about git submodules can be found here.
4.2.6. sra tools as bash alias¶
If you want to use the ./sra command withou the ./, you can add the following lines to your ~/.bashrc:
srafunc(){
cur_pwd=$(pwd)
srat=$cur_pwd/sra
if [ -f "$srat" ]; then
$srat
else
echo "Error: No cloudFPGA sra tools present in this folder."
fi
}
alias sra=srafunc
Afterwards, activate it by reloading the bashrc (source ~/.bashrc).
4.2.7. Mantle support¶
Mantles/Middlewares can be configured like any other cFa. Please refer to the documentation of the particular Mantle.
4.2.8. Known Limitations/Bugs¶
Only one Middleware per SRA is supported. Hence, the current flexibility is:
Shell:Middleware:Role = 1:1:2