diff --git a/.gitignore b/.gitignore index b0c8c24f9f..5c934f921a 100644 --- a/.gitignore +++ b/.gitignore @@ -17,3 +17,6 @@ model.xml pb_type.xml *.sort.xml *~ + +/docs/_build/ +/docs/_theme/ diff --git a/cmake.md b/cmake.md deleted file mode 100644 index 1c855c43a3..0000000000 --- a/cmake.md +++ /dev/null @@ -1,87 +0,0 @@ -## CMake build system - -### Variables - -* `USE_CONDA` - Whether to rely on conda to supply external binaries (e.g. yosys, vpr). - -* `VPR_BASE_ARGS` - Base VPR arguments used during pack, place and route. - [Default arguments](common/cmake/devices.cmake#L454). - -* `VPR_EXTRA_ARGS` - Additional arguments to pass to VPR during pack, place and route. - -To set CMake variable, use the -D flag during the configuration process. Example: -``` -mkdir build -cd build -cmake -DUSE_CONDA=FALSE .. -make -``` - -### Terminology - -The CMake system in symbiflow-arch-defs uses the following hierarchy: - -* `ARCH` - Architecture is the high level grouping of a set of "similar" FPGA - types. An example would be the "Lattice iCE40 Series" (ice40) or the "Xilinx - Artix 7 Series" (artix7). - -* `DEVICE_TYPE` - A type of device. This is defined as an `ARCH` and the - arch.xml which defines the units with this device type. - -* `DEVICE` - A specific instance of a `DEVICE_TYPE`. A device definition is a - `DEVICE_TYPE`, a `PACKAGE` list, and IO map definitions for each package if - needed. Each `DEVICE` should correspond with a layout definition within the - `DEVICE_TYPE`. - -* `BOARD` - A specific `DEVICE` and `PACKAGE` instance, along with a - `PROG_TOOL`/`PROG_CMD` (e.g. commands to program a specified board). - -### Creating a new FPGA target - -If you are familiar with cmake, `ADD_FPGA_TARGET` is the rough equivalent to -the normal `ADD_EXECUTABLE` target you would use with a C project. - -`ADD_FPGA_TARGET` will create the targets needed to take a design from Verilog -to bitstream through the synthesis, place and route, bitstream and potentially -even programming. The required arguments are the `BOARD` and input files see -[`ADD_FPGA_TARGET` documentation](common/cmake/devices.cmake#L559) for further -information on other target configuration options. - -If you want to target multiple boards, `ADD_FPGA_TARGET_BOARDS` exists -that will call `ADD_FPGA_TARGET` correctly for each board you request. See -[`ADD_FPGA_TARGET_BOARDS` documentation](common/cmake/devices.cmake#L458). - -#### Note on `ADD_FILE_TARGET` and `ADD_FPGA_BOARD` - -All source files in the symbiflow-arch-defs are required to have a file target -associated with them. This is done via -[`ADD_FILE_TARGET`](common/cmake/file_targets.cmake#L193). By default -`ADD_FPGA_TARGET` and `ADD_FPGA_TARGET_BOARDS` will both implicitly invoke -`ADD_FILE_TARGET` for you. This handles the common case where input sources -are not generated files. However, if you are using generated files, then you -will need to add `ADD_FILE_TARGET` calls for all inputs to `ADD_FPGA_TARGET`. - -For non-generated verilog, `ADD_FILE_TARGET` should be invoked like: -``` -add_file_target(FILE SCANNER_TYPE verilog) -``` - -For generated verilog, `ADD_FILE_TARGET` should be invoked like: -``` -add_file_target(FILE GENERATED) -``` -Note that the input path must be current source dir relative, not absolute, -and not relative to the cmake current binary dir. Also note that CMake cannot -take depedendencies during build time, so for generated files you must supply -the dependencies for the target. See -[`APPEND_FILE_DEPENDENCY`](common/cmake/file_targets.cmake#L79) for adding -dependencies to other file targets. - -It is generally suggested that all source forms within -symbiflow-arch-defs are file targets, but it is required for verilog files -because of how verilog handles relative include paths. Verilog defines relative -paths as relative to the location of the file, not to the location of the -compiler. As a result, if you use relative includes to include both a -generated and non-generated file, unless the files are moved to a unified -source tree, verilog relative includes will not work. `ADD_FILE_TARGET` solves -this by copying non-generated files to the binary directory. diff --git a/docs/conf.py b/docs/conf.py index cbf916ca18..8674f8865d 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -24,16 +24,13 @@ master_doc = 'index' extensions = [ - 'sphinx.ext.autodoc', - 'sphinx.ext.extlinks', - 'sphinx.ext.intersphinx', - 'sphinxcontrib.images', + 'sphinx.ext.autodoc', 'sphinx.ext.extlinks', 'sphinx.ext.intersphinx', + 'sphinxcontrib.images', 'myst_parser' ] templates_path = ['_templates'] -# source_suffix = ['.rst', '.md'] -source_suffix = '.rst' +source_suffix = {'.rst': 'restructuredtext', '.md': 'markdown'} language = None diff --git a/docs/development/cmake.md b/docs/development/cmake.md new file mode 100644 index 0000000000..c189253cd1 --- /dev/null +++ b/docs/development/cmake.md @@ -0,0 +1,85 @@ +# CMake build system + +## Variables + +* `USE_CONDA` - Whether to rely on conda to supply external binaries (e.g. yosys, vpr). + +* `VPR_BASE_ARGS` - Base VPR arguments used during pack, place and route. + {ghsrc}`Default arguments `. + +* `VPR_EXTRA_ARGS` - Additional arguments to pass to VPR during pack, place and route. + +To set CMake variable, use the -D flag during the configuration process. +Example: + +```bash +mkdir build +cd build +cmake -DUSE_CONDA=FALSE .. +make +``` + +## Terminology + +The CMake system in f4pga-arch-defs uses the following hierarchy: + +* `ARCH` - Architecture is the high level grouping of a set of "similar" FPGA types. + An example would be the "Lattice iCE40 Series" (ice40) or the "Xilinx Artix 7 Series" (artix7). + +* `DEVICE_TYPE` - A type of device. + This is defined as an `ARCH` and the arch.xml which defines the units with this device type. + +* `DEVICE` - A specific instance of a `DEVICE_TYPE`. + A device definition is a `DEVICE_TYPE`, a `PACKAGE` list, and IO map definitions for each package if needed. + Each `DEVICE` should correspond with a layout definition within the `DEVICE_TYPE`. + +* `BOARD` - A specific `DEVICE` and `PACKAGE` instance, along with a `PROG_TOOL`/`PROG_CMD` (e.g. commands to program a + specified board). + +## Creating a new FPGA target + +If you are familiar with cmake, `ADD_FPGA_TARGET` is the rough equivalent to the normal `ADD_EXECUTABLE` target you +would use with a C project. + +`ADD_FPGA_TARGET` will create the targets needed to take a design from Verilog to bitstream through the synthesis, place +and route, bitstream and potentially even programming. +The required arguments are the `BOARD` and input files see {ghsrc}`ADD_FPGA_TARGET documentation ` +for further information on other target configuration options. + +If you want to target multiple boards, `ADD_FPGA_TARGET_BOARDS` exists that will call `ADD_FPGA_TARGET` correctly for +each board you request. +See {ghsrc}`ADD_FPGA_TARGET_BOARDS documentation `. + +### Note on `ADD_FILE_TARGET` and `ADD_FPGA_BOARD` + +All source files in the f4pga-arch-defs are required to have a file target associated with them. +This is done via {ghsrc}`ADD_FILE_TARGET `. +By default `ADD_FPGA_TARGET` and `ADD_FPGA_TARGET_BOARDS` will both implicitly invoke `ADD_FILE_TARGET` for you. +This handles the common case where input sources are not generated files. +However, if you are using generated files, then you will need to add `ADD_FILE_TARGET` calls for all inputs to +`ADD_FPGA_TARGET`. + +For non-generated verilog, `ADD_FILE_TARGET` should be invoked like: + +```cmake +add_file_target(FILE SCANNER_TYPE verilog) +``` + +For generated verilog, `ADD_FILE_TARGET` should be invoked like: + +```cmake +add_file_target(FILE GENERATED) +``` + +Note that the input path must be current source dir relative, not absolute, and not relative to the cmake current binary +dir. +Also note that CMake cannot take depedendencies during build time, so for generated files you must supply the +dependencies for the target. +See {ghsrc}`APPEND_FILE_DEPENDENCY ` for adding dependencies to other file targets. + +It is generally suggested that all source forms within f4pga-arch-defs are file targets, but it is required for +verilog files because of how verilog handles relative include paths. +Verilog defines relative paths as relative to the location of the file, not to the location of the compiler. +As a result, if you use relative includes to include both a generated and non-generated file, unless the files are moved +to a unified source tree, verilog relative includes will not work. +`ADD_FILE_TARGET` solves this by copying non-generated files to the binary directory. diff --git a/docs/index.rst b/docs/index.rst index a4d8836528..977961671a 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -28,8 +28,9 @@ Contents .. toctree:: :maxdepth: 2 - :caption: Development Practices + :caption: Development + development/cmake development/structure development/vtr_notes diff --git a/docs/requirements.txt b/docs/requirements.txt index 9e1f391d31..3a05527a31 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,3 +1,4 @@ +myst-parser sphinx http://github.com/SymbiFlow/sphinx_symbiflow_theme/archive/chips.zip#sphinx-symbiflow-theme sphinxcontrib-images