Merge pull request #224 from lnis-uofu/gg_docs
[Docs] Added documentation for docker based run and shell shortcuts documentation
This commit is contained in:
tangxifan
GitHub
commit
184788880c
|
|
@ -49,28 +49,31 @@ In particular, OpenFPGA requires specific versions for the following dependencie
|
|||
|
||||
.. _install_dependencies_build: https://github.com/lnis-uofu/OpenFPGA/blob/master/.github/workflows/install_dependencies_build.sh
|
||||
|
||||
Docker
|
||||
~~~~~~
|
||||
If some of these dependencies are not installed on your machine, you can choose to use a Docker (the Docker tool needs to be installed).
|
||||
For the ease of the customer first experience, a Dockerfile is provided in the OpenFPGA folder. A container ready to use can be created with the following command
|
||||
|
||||
.. code-block:: shell
|
||||
Running with the docker image
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
docker run lnis/open_fpga:release
|
||||
Users can skip the traditional installation process by using Dockerized version
|
||||
of the OpenFPGA tool. OpenFPGA project maintains the docker image/Github package of
|
||||
the latest stable version of OpenFPGA in the following repository
|
||||
`openfpga-master <https://github.com/orgs/lnis-uofu/packages/container/package/openfpga-master>`_.
|
||||
This image contains precompiled OpenFPGA binaries with all prerequisites installed.
|
||||
|
||||
.. note:: This command is for quick testing. If you want to conserve your work, you should certainly use other options, such as ``-v``.
|
||||
.. code-block:: bash
|
||||
|
||||
Otherwise, a container where you can build OpenFPGA yourself can be created with the following commands
|
||||
# To get the docker image from the repository, docker pull ghcr.io/lnis-uofu/openfpga-master:latest
|
||||
|
||||
.. code-block:: shell
|
||||
# To invoke openfpga_shell
|
||||
docker run -it ghcr.io/lnis-uofu/openfpga-master:latest openfpga/openfpga -i
|
||||
|
||||
docker build . -t open_fpga
|
||||
docker run -it --rm -v $PWD:/localfile/OpenFPGA -w="/localfile/OpenFPGA" open_fpga bash
|
||||
# To run the task that already exists in the repository.
|
||||
docker run -it ghcr.io/lnis-uofu/openfpga-master:latest bash -c "source openfpga.sh && run-task compilation_verification"
|
||||
|
||||
For more information about dock, see dock_download_link_
|
||||
# To run a task from a local machine
|
||||
mkdir <<task_name>>/config
|
||||
vi <<task_name>>/config/task.config # Create your task configuration
|
||||
TASK_NAME=<<task_name>> docker run -it -v ${PWD}/${TASK_NAME}:/opt/openfpga/openfpga_flow/tasks/${TASK_NAME} ghcr.io/lnis-uofu/openfpga-master:latest bash -c "source openfpga.sh && run-task ${TASK_NAME}"
|
||||
|
||||
.. _dock_download_link: https://www.docker.com/products/docker-desktop
|
||||
|
||||
To build the tool, go in the OpenFPGA folder and follow the compilation steps
|
||||
|
||||
.. note:: Using docker, you cannot use ``make -j``, errors will happen
|
||||
.. note::
|
||||
While running local task using docker, make sure all the additional files
|
||||
are maintained in the task_directory and reference using variable ${TASK_DIR}
|
||||
|
|
@ -1,11 +1,13 @@
|
|||
.. _tutorials:
|
||||
Tutorials
|
||||
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
compile
|
||||
|
||||
shell_shortcuts
|
||||
|
||||
tools
|
||||
|
||||
design_flow/index
|
||||
|
|
|
|||
|
|
@ -0,0 +1,42 @@
|
|||
OpenFPGA shortcuts
|
||||
------------------
|
||||
|
||||
OpenFPGA provides bash/zsh shell-based shortcuts to perform all essential functions and navigating through the directories. Go to the OpenFPGA directory and source ``openfpga.sh``
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
cd ${OPENFPGA_PATH} && source openfpga.sh
|
||||
|
||||
.. note::
|
||||
The OpenFPGA shortcuts are designed to work with only bash based shells. e.g. bash/zsh/fish etc.
|
||||
|
||||
Shortcut Commands
|
||||
^^^^^^^^^^^^^^^^^
|
||||
|
||||
Once the ``openfpga.sh`` script is sourced, you can run any of the following commands directly in the terminal.
|
||||
|
||||
.. option:: list-tasks
|
||||
|
||||
This command lists all the OpenFPGA tasks from the current task directory.
|
||||
default task directory is considered as ``${OPENFPGA_PATH}/openfpga_flow/tasks``
|
||||
|
||||
.. option:: run-task <task_name> **kwarags
|
||||
|
||||
This command runs the specified task listed from the ``list-task`` command or from the existing directory. The command name is relative to the ``TASK_DIRECTORY``. User can provide any additional arguments which are listed `here <_openfpga_task_args>`_ to this command.
|
||||
|
||||
.. option:: run-modelsim
|
||||
|
||||
This command runs the verification using ModelSim.
|
||||
The test benches are generated during the OpenFPGA run.
|
||||
**Note**: user need to have ``VSIM`` install and configured
|
||||
|
||||
|
||||
.. option:: run-regression-local
|
||||
|
||||
This script runs the regression test locally using the current version of OpenFPGA.
|
||||
**NOTE** Important before making a pull request to the master
|
||||
|
||||
.. option:: unset-openfpga
|
||||
|
||||
Unregisters all the shortcuts and commands from the current shell session
|
||||
|
||||
32
openfpga.sh
32
openfpga.sh
|
|
@ -5,9 +5,15 @@
|
|||
#author : Ganesh Gore <ganesh.gore@utah.edu>
|
||||
#==============================================================================
|
||||
|
||||
export OPENFPGA_PATH="$(pwd)"
|
||||
export OPENFPGA_SCRIPT_PATH="$(pwd)/openfpga_flow/scripts"
|
||||
export OPENFPGA_TASK_PATH="$(pwd)/openfpga_flow/tasks"
|
||||
if [ -z $OPENFPGA_PATH ]; then
|
||||
echo "OPENFPGA_PATH variable not found"
|
||||
export OPENFPGA_PATH=$(pwd);
|
||||
echo "Setting OPENFPGA_PATH=${OPENFPGA_PATH}"
|
||||
else
|
||||
echo "OPENFPGA_PATH=${OPENFPGA_PATH}"
|
||||
fi
|
||||
export OPENFPGA_SCRIPT_PATH="${OPENFPGA_PATH}/openfpga_flow/scripts"
|
||||
export OPENFPGA_TASK_PATH="${OPENFPGA_PATH}/openfpga_flow/tasks"
|
||||
if [ -z $PYTHON_EXEC ]; then export PYTHON_EXEC="python3"; fi
|
||||
|
||||
# This function checks the path and
|
||||
|
|
@ -44,7 +50,7 @@ run-flow () {
|
|||
# lists all the configure task in task directory
|
||||
list-tasks () {
|
||||
check_execution_path "$(pwd)"
|
||||
ls -tdalh ${OPENFPGA_TASK_PATH}/* | awk '{printf("%-4s | %s %-3s | ", $5, $6, $7) ;system("basename " $9)}'
|
||||
tree -P 'task.conf' --prune | sed "/.* task.conf/d" | sed "/.* config/d" | sed '$d'
|
||||
}
|
||||
|
||||
# Switch directory to root of OpenFPGA
|
||||
|
|
@ -58,15 +64,6 @@ run-regression-local () {
|
|||
bash .github/workflows/*reg_test.sh
|
||||
}
|
||||
|
||||
# Run regression test locally
|
||||
run-regression-local-docker () {
|
||||
cd ${OPENFPGA_PATH}
|
||||
docker run \
|
||||
-v $(pwd)/openfpga_flow:/opt/openfpga/ \
|
||||
-v $(pwd)/.github:/opt/openfpga/ \
|
||||
ghcr.io/lnis-uofu/openfpga-master:latest "bash .github/workflows/*reg_test.sh"
|
||||
}
|
||||
|
||||
# Changes directory to task directory [goto_task <task_name> <run_num[default 0]>]
|
||||
goto-task () {
|
||||
if [ -z $1 ]; then
|
||||
|
|
@ -105,7 +102,14 @@ unset-openfpga (){
|
|||
if [[ $(ps -p $$ -oargs=) == *"zsh"* ]]; then
|
||||
autoload -U +X bashcompinit; bashcompinit;
|
||||
fi
|
||||
TaskList=$(ls -tdalh ${OPENFPGA_TASK_PATH}/* | awk '{system("basename " $9)}' | awk '{printf("%s ",$1)}')
|
||||
|
||||
command -v shopt && shopt -s globstar
|
||||
# TaskList=$(ls -tdalh ${OPENFPGA_TASK_PATH}/* | awk '{system("basename " $9)}' | awk '{printf("%s ",$1)}')
|
||||
TaskList=$(ls -tdalh ${OPENFPGA_TASK_PATH}/**/task.conf |
|
||||
awk '{print $9}' | sed -e "s/\/config\/task.conf//" |
|
||||
sed -e "s/${OPENFPGA_PATH//\//\\/}\/openfpga_flow\/tasks\///" |
|
||||
awk '{printf("%s ",$1)}')
|
||||
|
||||
complete -W "${TaskList}" goto-task
|
||||
complete -W "${TaskList}" run-task
|
||||
complete -W "${TaskList}" run-shell-task
|
||||
|
|
|
|||
Loading…
Reference in New Issue