diff --git a/README.md b/README.md index 3720fd80..0884105d 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,8 @@ SoCMake Documentation | - Examples + Examples | + API documentation diff --git a/SoCMakeConfig.cmake b/SoCMakeConfig.cmake index c6e63395..f84e09b8 100644 --- a/SoCMakeConfig.cmake +++ b/SoCMakeConfig.cmake @@ -52,9 +52,6 @@ include("${CMAKE_CURRENT_LIST_DIR}/cmake/sim/xilinx/vivado_sim.cmake") # ----- FC4SC ------- include("${CMAKE_CURRENT_LIST_DIR}/cmake/sim/fc4sc/fc4sc_merge_coverage.cmake") -# ----- VeriSC -------- -include("${CMAKE_CURRENT_LIST_DIR}/cmake/sim/verisc/verisc_install.cmake") - # ----- Cocotb -------- include("${CMAKE_CURRENT_LIST_DIR}/cmake/sim/cocotb/cocotb.cmake") include("${CMAKE_CURRENT_LIST_DIR}/cmake/sim/cocotb/add_cocotb_tests.cmake") @@ -101,18 +98,13 @@ set(IBEX_TOOLCHAIN "${CMAKE_CURRENT_LIST_DIR}/cmake/firmware/toolchains/riscv_to include("${CMAKE_CURRENT_LIST_DIR}/cmake/lint/verible.cmake") include("${CMAKE_CURRENT_LIST_DIR}/cmake/lint/vhdl_linter.cmake") -# ==================================== -# ====== Riscv ======================= -# ==================================== - -include("${CMAKE_CURRENT_LIST_DIR}/cmake/riscv/sail/sail_install.cmake") - # ==================================== # ====== Build scripts =============== # ==================================== include("${CMAKE_CURRENT_LIST_DIR}/cmake/build_scripts/systemc/systemc_build.cmake") include("${CMAKE_CURRENT_LIST_DIR}/cmake/build_scripts/uvm-systemc/uvm-systemc_build.cmake") include("${CMAKE_CURRENT_LIST_DIR}/cmake/build_scripts/verilator/verilator_build.cmake") +include("${CMAKE_CURRENT_LIST_DIR}/cmake/build_scripts/riscv/sail/sail_install.cmake") # ==================================== # ====== IPXact ====================== diff --git a/cmake/riscv/sail/install_sail.sh b/cmake/build_scripts/riscv/sail/install_sail.sh similarity index 100% rename from cmake/riscv/sail/install_sail.sh rename to cmake/build_scripts/riscv/sail/install_sail.sh diff --git a/cmake/riscv/sail/requirements.txt b/cmake/build_scripts/riscv/sail/requirements.txt similarity index 100% rename from cmake/riscv/sail/requirements.txt rename to cmake/build_scripts/riscv/sail/requirements.txt diff --git a/cmake/riscv/sail/sail_install.cmake b/cmake/build_scripts/riscv/sail/sail_install.cmake similarity index 89% rename from cmake/riscv/sail/sail_install.cmake rename to cmake/build_scripts/riscv/sail/sail_install.cmake index 7f0cae84..3d37142f 100644 --- a/cmake/riscv/sail/sail_install.cmake +++ b/cmake/build_scripts/riscv/sail/sail_install.cmake @@ -1,7 +1,15 @@ +#[[[ @module sail +#]] + include_guard(GLOBAL) set(SAIL_INSTALL_LIST_DIR ${CMAKE_CURRENT_LIST_DIR} CACHE INTERNAL "") +#[[[ +# This macro install the RISC-V SAIL C-emulator. No arguments are needed. +# +# pip will be needed to install the requirements for SAIL installation, then a bash script will be ran. +#]] # SAIL C-emulator installation macro macro(sail_install) cmake_parse_arguments(ARG "" "" "" ${ARGN}) diff --git a/cmake/build_scripts/systemc/systemc_build.cmake b/cmake/build_scripts/systemc/systemc_build.cmake index e92de95f..ec658e78 100644 --- a/cmake/build_scripts/systemc/systemc_build.cmake +++ b/cmake/build_scripts/systemc/systemc_build.cmake @@ -1,4 +1,18 @@ +#[[[ @module build_scripts +#]] +#[[[ +# Build and install the SystemC library. +# It might not build a new SystemC library, if one is found using find_package() cmake function. +# +# **Keyword Arguments** +# +# :keyword VERSION: Version of the SystemC library that need to be built. +# :type VERSION: string +# :keyword EXACT_VERSION: If EXACT_VERSION is set, the SystemC library given version is build if not found. +# :type EXACT_VERSION: bool +# :keyword INSTALL_DIR: Path to the location where the library will be installed. The default is ${PROJECT_BINARY_DIR}/systemc or ${FETCHCONTENT_BASE_DIR}/systemc if FETCHCONTENT_BASE_DIR is set. +#]] function(systemc_build) cmake_parse_arguments(ARG "EXACT_VERSION" "VERSION;INSTALL_DIR" "" ${ARGN}) if(ARG_UNPARSED_ARGUMENTS) diff --git a/cmake/build_scripts/uvm-systemc/uvm-systemc_build.cmake b/cmake/build_scripts/uvm-systemc/uvm-systemc_build.cmake index 5a01ea0b..2f7badbe 100644 --- a/cmake/build_scripts/uvm-systemc/uvm-systemc_build.cmake +++ b/cmake/build_scripts/uvm-systemc/uvm-systemc_build.cmake @@ -1,4 +1,18 @@ +#[[[ @module build_scripts +#]] +#[[[ +# Build and install the UVM-SystemC library. +# It might not build a new SystemC library, if one is found using find_package() cmake function. +# +# **Keyword Arguments** +# +# :keyword VERSION: Version of the UVM-SystemC library that need to be built. +# :type VERSION: string +# :keyword EXACT_VERSION: If EXACT_VERSION is set, the UVM-SystemC library given version is build if not found. +# :type EXACT_VERSION: bool +# :keyword INSTALL_DIR: Path to the location where the library will be installed. The default is ${PROJECT_BINARY_DIR}/uvm-systemc or ${FETCHCONTENT_BASE_DIR}/uvm-systemc if FETCHCONTENT_BASE_DIR is set. +#]] function(uvm_systemc_build) cmake_parse_arguments(ARG "EXACT_VERSION" "VERSION;INSTALL_DIR" "" ${ARGN}) if(ARG_UNPARSED_ARGUMENTS) diff --git a/cmake/build_scripts/verilator/verilator_build.cmake b/cmake/build_scripts/verilator/verilator_build.cmake index b03c5bbb..cdd47990 100644 --- a/cmake/build_scripts/verilator/verilator_build.cmake +++ b/cmake/build_scripts/verilator/verilator_build.cmake @@ -1,4 +1,18 @@ +#[[[ @module build_scripts +#]] +#[[[ +# Build and install the Verilator binary. +# It might not build a new Verilator binary, if one is found using find_package() cmake function. +# +# **Keyword Arguments** +# +# :keyword VERSION: Version of the Verilator binary that need to be built. +# :type VERSION: string +# :keyword EXACT_VERSION: If EXACT_VERSION is set, the Verilator given version is build if not found. +# :type EXACT_VERSION: bool +# :keyword INSTALL_DIR: Path to the location where the binary will be installed. The default is ${PROJECT_BINARY_DIR}/verilator/v${VERSION} or ${FETCHCONTENT_BASE_DIR}/verilator/v${VERSION} if FETCHCONTENT_BASE_DIR is set. +#]] function(verilator_build) cmake_parse_arguments(ARG "EXACT_VERSION" "VERSION;INSTALL_DIR" "" ${ARGN}) if(ARG_UNPARSED_ARGUMENTS) diff --git a/cmake/fpga/vivado/vivado.cmake b/cmake/fpga/vivado/vivado.cmake index ebd7f5a3..6d815f16 100644 --- a/cmake/fpga/vivado/vivado.cmake +++ b/cmake/fpga/vivado/vivado.cmake @@ -1,3 +1,24 @@ +#[[[ @module fpga +#]] + +#[[[ +# Generate a vivado FPGA project and create a target to generate the bitstream. +# +# The python script, edalize_vivado, using edalize library is used to correctly run vivado with the given informations. +# The different arguments are parsed and formatted to be properly given to vivado. +# +# :param IP_LIB: The target IP library. +# :type IP_LIB: string +# +# **Keyword Arguments** +# +# :keyword TOP: Top-level module name used for elaboration. The default is the IP_LIB ``IP_NAME`` property. +# :type TOP: string +# :keyword VERILOG_DEFINES: Additional SV/Verilog compilation flags to be passed to vivado project +# :type VERILOG_DEFINES: +# :keyword OUTDIR: output directory in which the files will be generated. The default is ${BINARY_DIR}/vivado. +# :type OUTDIR: string path +#]] function(vivado IP_LIB) cmake_parse_arguments(ARG "" "TOP" "VERILOG_DEFINES" ${ARGN}) if(ARG_UNPARSED_ARGUMENTS) diff --git a/cmake/fusesoc/add_ip_from_fusesoc.cmake b/cmake/fusesoc/add_ip_from_fusesoc.cmake index d2d308d6..bddb1766 100644 --- a/cmake/fusesoc/add_ip_from_fusesoc.cmake +++ b/cmake/fusesoc/add_ip_from_fusesoc.cmake @@ -1,3 +1,16 @@ +#[[[ @module fusesoc +#]] + +#[[[ +# This function imports an IP fusesoc core file and convert it to an SoCMake HWIP. +# +# This function will convert FuseSoC .core (YAML) files to SoCMake CMakeLists.txt. +# The IP will be added to the IP_LIB, by formatting the information coming from the .core file, to add and link the IP with it different file sets. +# Unfortunately, this function does not resolve dependencies between different .core file, so the IPs that need to be linked with. +# +# :param CORE_FILE: Path to the fusesoc core file +# :type CORE_FILE: string +#]] function(add_ip_from_fusesoc CORE_FILE) cmake_parse_arguments(ARG "" "" "" ${ARGN}) if(ARG_UNPARSED_ARGUMENTS) diff --git a/cmake/hwip.cmake b/cmake/hwip.cmake index 8a928f16..82ed6ccb 100644 --- a/cmake/hwip.cmake +++ b/cmake/hwip.cmake @@ -1,4 +1,5 @@ - +#[[[ @module hwip +#]] include("${CMAKE_CURRENT_LIST_DIR}/utils/socmake_graph.cmake") include("${CMAKE_CURRENT_LIST_DIR}/utils/alias_dereference.cmake") include("${CMAKE_CURRENT_LIST_DIR}//utils/file_paths.cmake") @@ -16,25 +17,25 @@ include("${CMAKE_CURRENT_LIST_DIR}//utils/file_paths.cmake") # # This function can be used in FULL and SHORT form: # Full form: -# ``` -# add_ip(ip -# VENDOR vendor -# LIBRARY lib -# VERSION 1.2.3 -# DESCRIPTION "This is a sample IP" -# ) -# ``` +# :: +# add_ip(ip +# VENDOR vendor +# LIBRARY lib +# VERSION 1.2.3 +# DESCRIPTION "This is a sample IP" +# ) +# # In full form it is possible to ommit VENDOR, LIBRARY and VERSION, DESCRIPTION, although it is not recommended. # # Ommiting them all would have following signature: -# ``` -# add_ip(ip2) -# ``` +# :: +# add_ip(ip2) +# # # Short form: -# ``` -# add_ip(vendor2::lib2::ip2::1.2.2) -# ``` +# :: +# add_ip(vendor2::lib2::ip2::1.2.2) +# # In short form only the full VLNV format is accepted # # :param IP_NAME: The name of the IP. @@ -514,7 +515,9 @@ function(get_ip_include_directories OUTVAR IP_LIB LANGUAGE) set(${OUTVAR} ${INCDIRS} PARENT_SCOPE) endfunction() - +# This fonctions is used by the next function, to compare available version of IPs with the versions wanted. +# +# The allowed comparisons are ==, >=, >, <=, <, != function(__compare_version RESULT COMPARE_LHS RELATION COMPARE_RHS) unset(NEGATION) @@ -540,6 +543,10 @@ function(__compare_version RESULT COMPARE_LHS RELATION COMPARE_RHS) endif() endfunction() +# This function is used by ``ip_link``, it checks the conditions for version. +# +# It will check if condition needs to be checked. If it does, +# It will strip the `IP_LIB` value to extract the VLN value and will return it. function(__ip_link_check_version OUT_IP_WO_VERSION IP_LIB) string(REPLACE " " "" ip_lib_str "${IP_LIB}") string(REGEX MATCH "(!=|>=|<=|==|<|>)" version_ranges "${ip_lib_str}") @@ -586,14 +593,16 @@ endfunction() # as a list after the parameters and the keyword. # # It is also allowed to pass version conditions to be checked as following: -# ``` -# ip_link(v::l::ip1::1.1.1 -# "v::l::ip2 >= 1.0.4, <=2.0.0") -# ``` +# +# :: +# +# ip_link(v::l::ip1::1.1.1 +# "v::l::ip2 >= 1.0.4, <=2.0.0") +# # If all the comparisons are not satisfied, FATAL_ERROR is issued. # Allowed comparisons are ==, >=, >, <=, < # -# :param IP_LIB: The target IP library name. +# :param IP_LIB: The target IP library. # :type IP_LIB: string # # **Keyword Arguments** @@ -650,7 +659,7 @@ endfunction() # # :param OUTVAR: Variable containing the requested property. # :type OUTVAR: string -# :param IP_LIB: The target IP library name. +# :param IP_LIB: The target IP library. # :type IP_LIB: string # :param PROPERTY: Property to retrieve from IP_LIB. # :type PROPERTY: string @@ -698,7 +707,7 @@ endfunction() # ip_compile_definitions(foo VERILOG "" FOO) # "" ignored # ip_compile_definitions(foo VERILOG -D FOO) # -D becomes "", then ignored. # -# :param IP_LIB: The target IP library name. +# :param IP_LIB: The target IP library. # :type IP_LIB: string # :param LANGUAGE: Language to which the definition should apply. # :type LANGUAGE: string @@ -747,7 +756,7 @@ endfunction() # # :param OUTVAR: Variable containing the requested property. # :type OUTVAR: string -# :param IP_LIB: The target IP library name. +# :param IP_LIB: The target IP library. # :type IP_LIB: string # :param LANGUAGE: Language to which the definition apply. # :type LANGUAGE: string @@ -850,6 +859,14 @@ function(socmake_add_languages) set_property(GLOBAL APPEND PROPERTY SOCMAKE_ADDITIONAL_LANGUAGES ${ARGN}) endfunction() +#[[[ +# This function return a list of the supported language by your SoCMake environnement. +# +# This means, the langauges initially supported by SoCMake and the one that have been added using ``socmake_add_languages()``. +# +# :param OUTVAR: Variable in which to store the supported languages +# :type OUTVAR: list[string] +#]] function(get_socmake_languages OUTVAR) get_property(additional_languages GLOBAL PROPERTY SOCMAKE_ADDITIONAL_LANGUAGES) @@ -907,7 +924,7 @@ endfunction() # This will then search for a file called "Vendor__Library__NameConfig.cmake" or "vendor__library__name-config.cmake" # It is recommended to place the directory of this file in "CMAKE_PREFIX_PATH" variable, to facilitate finding it # -# :param IP_LIB: the name of the IP library to search for. +# :param IP_LIB: the target IP library. # :type IP_LIB: string #]] macro(find_ip IP_LIB) @@ -923,7 +940,7 @@ endmacro() # In case it is not already defined it calls ip_find( REQUIRED) # Finally it calls ip_link() to link it. # -# :param IP_LIB: the name of the IP library to search for. +# :param IP_LIB: the target IP library. # :type IP_LIB: string #]] function(ip_find_and_link IP_LIB) @@ -935,7 +952,14 @@ function(ip_find_and_link IP_LIB) endforeach() endfunction() -# Optimization to disable graph flattening too often in EDA tool functions +#[[[ +# This function is an optimization to disable graph flattening too often in EDA tool functions. +# +# The flattening is done using ``flatten_graph``, an SoCMake function and a variable is set to disallow further flattening, made by EDA tool. +# +# :param IP_LIB: the target IP library. +# :type IP_LIB: string +#]] function(flatten_graph_and_disallow_flattening IP_LIB) get_ip_links(ips ${IP_LIB}) list(POP_BACK ips ips) # get_ip_links already flattens top ip @@ -945,10 +969,23 @@ function(flatten_graph_and_disallow_flattening IP_LIB) socmake_allow_topological_sort(OFF) endfunction() +#[[[ +# This function can be used to allow or disallow flattening by setting ``STATE`` to ON or OFF. +# +# :param STATE: ON to allow it, OFF to disallow it. +# :type STATE: bool +#]] function(socmake_allow_topological_sort STATE) set_property(GLOBAL PROPERTY SOCMAKE_ALLOW_TOPOLOGICAL_SORT ${STATE}) endfunction() +#[[[ +# This function return the value of ``SOCMAKE_ALLOW_TOPOLOGICAL_SORT``, the variable used to allow or disallow flattening. +# By default, it's set to ON. +# +# :param OUTVAR: Variable that will store the value of ``SOCMAKE_ALLOW_TOPOLOGICAL_SORT``. +# :type OUTVAR: bool +#]] function(socmake_get_topological_sort_state OUTVAR) get_property(state GLOBAL PROPERTY SOCMAKE_ALLOW_TOPOLOGICAL_SORT) if(NOT DEFINED state) @@ -957,6 +994,12 @@ function(socmake_get_topological_sort_state OUTVAR) set(${OUTVAR} ${state} PARENT_SCOPE) endfunction() +#[[[ +# As the name of this function say, it will look at ``SOCMAKE_ALLOW_TOPOLOGICAL_SORT`` value and proceed to flattening if allowed. +# +# :param IP_LIB: the target IP library. +# :type IP_LIB: string +#]] function(flatten_graph_if_allowed IP_LIB) socmake_get_topological_sort_state(state) if(state) diff --git a/cmake/ipxact/importer/ipxact_ip_importer.cmake b/cmake/ipxact/importer/ipxact_ip_importer.cmake index 101dee0e..d5049cf6 100644 --- a/cmake/ipxact/importer/ipxact_ip_importer.cmake +++ b/cmake/ipxact/importer/ipxact_ip_importer.cmake @@ -1,3 +1,25 @@ +#[[[ @module ipxact +#]] + +#[[[ +# This function import an IP-XACT .xml file and convert it to an SoCMake HWIP. +# +# ``xmlstarlet`` or ``xsltproc`` will be used, depending on the one found on your system, +# to extract the data coming from the .xml file. +# +# It will find the differents IPs, find the corresponding file and do the corresponding linking, +# everything will be stored in a Config.cmake file. +# +# :param COMP_XML: Path to the ipxact .xml file. +# :type COMP_XML: string +# +# **Keyword Arguments** +# +# :keyword GENERATE_ONLY: If set, no Config.cmake file is generated, but the HWIP is still created and can be referenced in a parent scope (similar to a call to add_ip(), the IP variable is set to the parent scope). +# :type GENERATE_ONLY: bool +# :keyword IPXACT_SOURCE_DIR: path to be set has ${ip_vendor}__${ip_library}__${ip_name}__${ip_version}_IPXACT_SOURCE_DIR, if this argument is used. +# :type IPXACT_SOURCE_DIR: string +#]] function(add_ip_from_ipxact COMP_XML) cmake_parse_arguments(ARG "GENERATE_ONLY" "IPXACT_SOURCE_DIR" "" ${ARGN}) if(ARG_UNPARSED_ARGUMENTS) diff --git a/cmake/lint/verible.cmake b/cmake/lint/verible.cmake index 68f38035..6f39785a 100644 --- a/cmake/lint/verible.cmake +++ b/cmake/lint/verible.cmake @@ -4,21 +4,14 @@ #[[[ # Verible lint tool interface # -# Verible-lint is a SystemVerilog linter... +# This function will create a target for linting the SystemVerilog files, more information about the tool can be found `here `_. # -# Verible can be found `here `_ -# -# Function expects that **IP_LIB** *INTERFACE_LIBRARY* has **SOURCES** property set with a list of System Verilog files to be used as inputs. -# To set the SOURCES property use `target_sources() `_ CMake function: -# -# .. code-block:: cmake -# -# target_sources( INTERFACE ...) +# It expects that **IP_LIB** *INTERFACE_LIBRARY* has **SOURCES** property set with a list of System Verilog files to be used as inputs. # # Function will create targets for linting or formatting depending on passed option # -# :param IP_LIB: RTL interface library, it needs to have SOURCES property set with a list of System Verilog files. -# :type IP_LIB: INTERFACE_LIBRARY +# :param IP_LIB: The target IP library. +# :type IP_LIB: string # # **Keyword Arguments** # diff --git a/cmake/lint/vhdl_linter.cmake b/cmake/lint/vhdl_linter.cmake index fefd453e..83c6b636 100644 --- a/cmake/lint/vhdl_linter.cmake +++ b/cmake/lint/vhdl_linter.cmake @@ -1,5 +1,21 @@ +#[[[ @module vhdl +#]] include_guard(GLOBAL) +#[[[ +# vhdl-linter tool interface. +# +# This function will create a target for linting the VHDL files, more information about the tool can be found `here `_. +# It does support ``vhdl-linter.yml`` configuration file, if you have your own. +# +# It expects that **IP_LIB** has **SOURCES** property set with a list of VHDL files to be used as inputs. +# +# During the linting, errors, warning or informations will be displayed in the terminal. +# No changes will be done to the files and no new files with corrected errors or warning will be produced. +# +# :param IP_LIB: The target IP library. +# :type IP_LIB: string +#]] function(vhdl_linter IP_LIB) cmake_parse_arguments(ARG "" "" "" ${ARGN}) if(ARG_UNPARSED_ARGUMENTS) diff --git a/cmake/peakrdl/peakrdl_docusaurus.cmake b/cmake/peakrdl/peakrdl_docusaurus.cmake index ecc501f7..2a3a8870 100644 --- a/cmake/peakrdl/peakrdl_docusaurus.cmake +++ b/cmake/peakrdl/peakrdl_docusaurus.cmake @@ -1,3 +1,25 @@ +#[[[ @module peakrdl_docusaurus +#]] + +#[[[ +# Create a target for invoking PeakRDL-docusaurus on IP_LIB. +# +# PeakRDL-docusaurus generates files for documentation with Docusaurus. PeakRDL-docusaurus is an internal CERN tool. +# +# Refer to the internal documentation for more information. +# +# :param IP_LIB: The target IP library, it needs to have SYSTEMRDL_SOURCES property set with a list of SystemRDL files. +# :type IP_LIB: string +# +# **Keyword Arguments** +# +# :keyword OUTDIR: output directory in which the files will be generated, if ommited ${BINARY_DIR}/docusaurus will be used. +# :type OUTDIR: string path +# :keyword SIDEBAR_TEMPLATE: sidebar template to give to peakrdl for generating the Docusaurus documentation. +# :type SIDEBAR_TEMPLATE: string +# :keyword LOGO: Logo to give to peakrdl for generating the Docusaurus documentation. +# :type LOGO: string +#]] function(peakrdl_docusaurus IP_LIB) cmake_parse_arguments(ARG "" "OUTDIR;SIDEBAR_TEMPLATE;LOGO" "" ${ARGN}) if(ARG_UNPARSED_ARGUMENTS) diff --git a/cmake/peakrdl/peakrdl_halcpp.cmake b/cmake/peakrdl/peakrdl_halcpp.cmake index a5fbe074..3bf6005d 100644 --- a/cmake/peakrdl/peakrdl_halcpp.cmake +++ b/cmake/peakrdl/peakrdl_halcpp.cmake @@ -1,3 +1,6 @@ +#[[[ @module peakrdl_halcpp +#]] + #[[[ # Create a target for invoking PeakRDL-halcpp on IP_LIB. # @@ -30,8 +33,8 @@ # FILES "firmware/hal/_ext.h" # ) # -# :param IP_LIB: RTL interface library, it needs to have SYSTEMRDL_SOURCES property set with a list of SystemRDL files. -# :type IP_LIB: INTERFACE_LIBRARY +# :param IP_LIB: The target IP library, it needs to have SYSTEMRDL_SOURCES property set with a list of SystemRDL files. +# :type IP_LIB: string # # **Keyword Arguments** # @@ -128,10 +131,8 @@ function(peakrdl_halcpp IP_LIB) endfunction() -#[[[ # Find headers that have _ext.h extension and compare with libraries. If there is a library that # matches the file name add it to list. -#]] function(__ext_header_provided LIB libs) get_ip_property(HEADERS ${LIB} HEADER_SET) get_ip_property(FLAT_GRAPH ${LIB} FLAT_GRAPH) diff --git a/cmake/peakrdl/peakrdl_html.cmake b/cmake/peakrdl/peakrdl_html.cmake index 80013258..6f65621f 100644 --- a/cmake/peakrdl/peakrdl_html.cmake +++ b/cmake/peakrdl/peakrdl_html.cmake @@ -16,8 +16,8 @@ # ip_sources(ip SYSTEMRDL ${PROJECT_SOURCE_DIR}/file.rdl) # # -# :param IP_LIB: IP for which to create html target. -# :type IP_LIB: IP library +# :param IP_LIB: The target IP library. +# :type IP_LIB: string # # **Keyword Arguments** # diff --git a/cmake/peakrdl/peakrdl_ipblocksvg.cmake b/cmake/peakrdl/peakrdl_ipblocksvg.cmake index a6b3af29..e65334c6 100644 --- a/cmake/peakrdl/peakrdl_ipblocksvg.cmake +++ b/cmake/peakrdl/peakrdl_ipblocksvg.cmake @@ -1,3 +1,6 @@ +#[[[ @module peakrdl_ipblocksvg +#]] + #[[[ # Create a target for invoking PeakRDL-ipblocksvg on IP_LIB. # @@ -22,9 +25,8 @@ # This function will append .png files to the **GRAPHIC_FILES** of the **IP_LIB**. # # -# :param IP_LIB: RTL interface library, it needs to have SYSTEMRDL_SOURCES property set with a list -# of SystemRDL files. -# :type IP_LIB: INTERFACE_LIBRARY +# :param IP_LIB: The target IP library, it needs to have SYSTEMRDL_SOURCES property set with a list of SystemRDL files. +# :type IP_LIB: string # # **Keyword Arguments** # diff --git a/cmake/peakrdl/peakrdl_print.cmake b/cmake/peakrdl/peakrdl_print.cmake index 543421ab..1b549838 100644 --- a/cmake/peakrdl/peakrdl_print.cmake +++ b/cmake/peakrdl/peakrdl_print.cmake @@ -1,3 +1,6 @@ +#[[[ @module peakrdl_print +#]] + #[[[ # Creates a target _peakrdl_print that prints address map in terminal. # diff --git a/cmake/peakrdl/peakrdl_regblock.cmake b/cmake/peakrdl/peakrdl_regblock.cmake index 8e574d27..dc741711 100644 --- a/cmake/peakrdl/peakrdl_regblock.cmake +++ b/cmake/peakrdl/peakrdl_regblock.cmake @@ -1,3 +1,6 @@ +#[[[ @module peakrdl_regblock +#]] + #[[[ # Create a target for invoking PeakRDL-regblock on IP_LIB. # @@ -15,8 +18,8 @@ # This function will append 2 generated files from PeakRDL-regblock to the **SYSTEMVERILOG_SOURCES** property of the # **${IP_LIB}**. # -# :param IP_LIB: IP for which to create regblock target. -# :type IP_LIB: IP library +# :param IP_LIB: The target IP library. +# :type IP_LIB: string # # **Keyword Arguments** # diff --git a/cmake/peakrdl/peakrdl_socgen.cmake b/cmake/peakrdl/peakrdl_socgen.cmake index d480a3ff..64e17f64 100644 --- a/cmake/peakrdl/peakrdl_socgen.cmake +++ b/cmake/peakrdl/peakrdl_socgen.cmake @@ -1,3 +1,6 @@ +#[[[ @module peakrdl_socgen +#]] + #[[[ # Create a target for invoking PeakRDL-socgen on IP_LIB. # @@ -32,8 +35,8 @@ # # PeakRDL-socgen also generates a graphviz .dot file as a visualization of the generated architecture. # -# :param IP_LIB: RTL interface library, it needs to have SYSTEMRDL_SOURCES property set with a list of SystemRDL files. -# :type IP_LIB: INTERFACE_LIBRARY +# :param IP_LIB: The target IP library, it needs to have SYSTEMRDL_SOURCES property set with a list of SystemRDL files. +# :type IP_LIB: string # # **Keyword Arguments** # diff --git a/cmake/peakrdl/peakrdl_topgen.cmake b/cmake/peakrdl/peakrdl_topgen.cmake index b1eda998..aa700a5d 100644 --- a/cmake/peakrdl/peakrdl_topgen.cmake +++ b/cmake/peakrdl/peakrdl_topgen.cmake @@ -1,3 +1,33 @@ +#[[[ @module peakrdl_topgen +#]] + +#[[[ +# Create a target for invoking PeakRDL-topgen on IP_LIB. +# +# PeakRDL-topgen compile and wrap SystenRDL into a SystemVerilog top file. PeakRDL-topgen is an internal CERN tool. +# +# Refer to the internal documentation for more information. +# +# :param IP_LIB: The target IP library, it needs to have SYSTEMRDL_SOURCES property set with a list of SystemRDL files. +# :type IP_LIB: string +# +# **Keyword Arguments** +# +# :keyword TMR: if set, it will apply triple modular redundancy on the design. +# :type TMR: bool +# :keyword OUTDIR: output directory in which the files will be generated, if ommited ${BINARY_DIR}/halcpp will be used. +# :type OUTDIR: string path +# :keyword RENAME: change the name of the IP. +# :type RENAME: string +# :keyword INTF: Interface to be used for on-chip communicatio, by default, it use apb3. +# :type INTF: string +# :keyword RESET: Change reset behaviour, the default reset is active-high and synchronous. +# :type RESET: string +# :keyword PARAMETERS: Parameters for the top level generation +# :type PARAMETERS: string +# :keyword OUT_LIST: Set the generated sources to the output variable +# :type OUT_LIST: list[string] +#]] function(peakrdl_topgen IP_LIB) # Parse keyword arguments cmake_parse_arguments(ARG "TMR" "OUTDIR;RENAME;INTF;RESET;OUT_LIST" "PARAMETERS" ${ARGN}) diff --git a/cmake/sim/cadence/xcelium.cmake b/cmake/sim/cadence/xcelium.cmake index 35bbdb86..225166e9 100644 --- a/cmake/sim/cadence/xcelium.cmake +++ b/cmake/sim/cadence/xcelium.cmake @@ -1,13 +1,15 @@ #[[[ @module xcelium #]] +include_guard(GLOBAL) + #[[[ # Create a target for invoking Xcelium (compilation, elaboration, and simulation) on IP_LIB. # # It will create a target **run__xcelium** that will compile, elaborate, and simulate the IP_LIB design. # -# :param IP_LIB: RTL interface library, it needs to have SOURCES property set with a list of System Verilog files. -# :type IP_LIB: INTERFACE_LIBRARY +# :param IP_LIB: The target IP library, it needs to have SOURCES property set with a list of SystemVerilog or VHDL files. +# :type IP_LIB: string # # **Keyword Arguments** # @@ -29,7 +31,7 @@ # :type COMPILE_ARGS: string # :keyword XRUN_COMPILE_ARGS: Extra arguments to be passed to the xrun -compile command # :type XRUN_COMPILE_ARGS: string -# :keyword SV_COMPILE_ARGS: Extra arguments to be passed to the System Verilog / Verilog compilation step. +# :keyword SV_COMPILE_ARGS: Extra arguments to be passed to the SystemVerilog / Verilog compilation step. # :type SV_COMPILE_ARGS: string # :keyword VHDL_COMPILE_ARGS: Extra arguments to be passed to the VHDL compilation step. # :type VHDL_COMPILE_ARGS: string @@ -37,12 +39,9 @@ # :type ELABORATE_ARGS: string # :keyword RUN_ARGS: Extra arguments to be passed to the simulation step. # :type RUN_ARGS: string -# :keyword FILE_SETS: Specify list of File sets to retrieve the sources from +# :keyword FILE_SETS: Specify list of File sets to retrieve the sources from # :type FILE_SETS: list[string] #]] - -include_guard(GLOBAL) - function(xcelium IP_LIB) cmake_parse_arguments(ARG "NO_RUN_TARGET;GUI;32BIT" "OUTDIR;RUN_TARGET_NAME;TOP_MODULE;LIBRARY" "COMPILE_ARGS;XRUN_COMPILE_ARGS;SV_COMPILE_ARGS;VHDL_COMPILE_ARGS;ELABORATE_ARGS;RUN_ARGS;FILE_SETS;" ${ARGN}) if(ARG_UNPARSED_ARGUMENTS) @@ -228,6 +227,31 @@ function(xcelium IP_LIB) socmake_allow_topological_sort(ON) endfunction() +# This function is called by ``xcelium``, it shouldn't be used directly in a cmake file. +# +# It will create an intermediary target to compile VDHL and SystemVerilog/Verilog file, using ``xrun -compile``. +# +# :param IP_LIB: The target IP library, it needs to have SOURCES property set with a list of SystemVerilog or VDHL files. +# :type IP_LIB: string +# +# **Keyword Arguments** +# +# :keyword OUTDIR: Output directory for the Xcelium compilation and simulation. +# :type OUTDIR: string +# :keyword LIBRARY: replace the default library name (worklib) to be used for elaboration and simulation. +# :type LIBRARY: string +# :keyword TOP_MODULE: Top module name to be used for elaboration and simulation. +# :type TOP_MODULE: string +# :keyword COMPILE_ARGS: Extra arguments to be passed to the compilation step (C, C++). +# :type COMPILE_ARGS: string +# :keyword XRUN_COMPILE_ARGS: Extra arguments to be passed to the xrun -compile command +# :type XRUN_COMPILE_ARGS: string +# :keyword SV_COMPILE_ARGS: Extra arguments to be passed to the SystemVerilog / Verilog compilation step. +# :type SV_COMPILE_ARGS: string +# :keyword VHDL_COMPILE_ARGS: Extra arguments to be passed to the VHDL compilation step. +# :type VHDL_COMPILE_ARGS: string +# :keyword FILE_SETS: Specify list of File sets to retrieve the sources from +# :type FILE_SETS: list[string] function(__xcelium_compile_lib IP_LIB) cmake_parse_arguments(ARG "" "OUTDIR;LIBRARY;TOP_MODULE" "COMPILE_ARGS;XRUN_COMPILE_ARGS;SV_COMPILE_ARGS;VHDL_COMPILE_ARGS;FILE_SETS" ${ARGN}) # Check for any unrecognized arguments @@ -447,6 +471,19 @@ function(__xcelium_compile_lib IP_LIB) endfunction() +# This function is called by ``xcelium``, it shouldn't be used directly in a cmake file. +# +# It will set values for the HDL and DPI library arguments that will be used for compilation, elaboration and simulation. +# +# :param IP_LIB: The target IP library. +# :type IP_LIB: string +# +# **Keyword Arguments** +# +# :keyword OUTDIR: Output directory for the Xcelium compilation and simulation. +# :type OUTDIR: string +# :keyword LIBRARY: replace the default library name (worklib) to be used for elaboration and simulation. +# :type LIBRARY: string function(__get_xcelium_search_lib_args IP_LIB) cmake_parse_arguments(ARG "" "OUTDIR;LIBRARY" "" ${ARGN}) if(ARG_UNPARSED_ARGUMENTS) @@ -472,7 +509,7 @@ function(__get_xcelium_search_lib_args IP_LIB) __xcelium_default_library(__comp_lib_name ${lib}) set(lib_outdir ${ARG_OUTDIR}/xcelium.d/${__comp_lib_name}) - # Append current library outdhdl_libs_argsir to list of search directories + # Append current library outdir to list of search directories if(NOT ${lib_outdir} IN_LIST hdl_libs_args) list(APPEND hdl_libs_args -reflib ${lib_outdir}) endif() @@ -483,6 +520,10 @@ function(__get_xcelium_search_lib_args IP_LIB) set(DPI_LIBS_ARGS ${dpi_libs_args} PARENT_SCOPE) endfunction() +# This function allows to find the path to xcelium home directory and to store it in a given variable. +# +# :param OUTVAR: Name of the variable in which xcelium_home will be stored +# :type OUTVAR: string function(__find_xcelium_home OUTVAR) find_program(exec_path xrun REQUIRED) get_filename_component(bin_path "${exec_path}" DIRECTORY) @@ -491,6 +532,31 @@ function(__find_xcelium_home OUTVAR) set(${OUTVAR} ${xcelium_home} PARENT_SCOPE) endfunction() +#[[[ +# This function create a target to generate a SystemC wrapper for the IP library, with Xcelium xmshell, if SystemVerilog or Verilog files are in the IP library. +# +# :param IP_LIB: The target IP library, it needs to have SOURCES property set with a list of SystemVerilog or Verilog files. +# :type IP_LIB: string +# +# **Keyword Arguments** +# +# :keyword 32BIT: Use 32 bit compilation and simulation. +# :type 32BIT: bool +# :keyword QUIET: Disable output for informative messages +# :type QUIET: bool +# :keyword OUTDIR: Output directory for the Xcelium compilation and simulation. +# :type OUTDIR: string +# :keyword LIBRARY: replace the default library name (worklib) to be used for elaboration and simulation. +# :type LIBRARY: string +# :keyword TOP_MODULE: Top module name to be used for elaboration and simulation. +# :type TOP_MODULE: string +# :keyword SV_COMPILE_ARGS: Extra arguments to be passed to the SystemVerilog / Verilog compilation step. +# :type SV_COMPILE_ARGS: string +# :keyword VHDL_COMPILE_ARGS: Extra arguments to be passed to the VHDL compilation step. +# :type VHDL_COMPILE_ARGS: string +# :keyword FILE_SETS: Specify list of File sets to retrieve the sources from +# :type FILE_SETS: list[string] +#]] function(xcelium_gen_sc_wrapper IP_LIB) cmake_parse_arguments(ARG "32BIT;QUIET" "OUTDIR;LIBRARY;TOP_MODULE" "SV_COMPILE_ARGS;VHDL_COMPILE_ARGS;FILE_SETS" ${ARGN}) # Check for any unrecognized arguments @@ -590,6 +656,23 @@ function(xcelium_gen_sc_wrapper IP_LIB) endfunction() +#[[[ +# This function create a target to generate a Verilog wrapper file from a SystemC library with Xcelium xmshell. +# +# :param SC_LIB: Name of an existing CMake target representing the SystemC library. +# :type SC_LIB: target +# +# **Keyword Arguments** +# +# :keyword 32BIT: Use 32-bit Xcelium tools instead of the default 64-bit mode. +# :type 32BIT: bool +# :keyword OUTDIR: Output directory for the Xcelium compilation and simulation. +# :type OUTDIR: string +# :keyword LIBRARY: Replace the default library name (worklib) to be used for elaboration and simulation. +# :type LIBRARY: string +# :keyword TOP_MODULE: Top module name to be used for elaboration and simulation. +# :type TOP_MODULE: string +#]] function(xcelium_gen_hdl_wrapper SC_LIB) cmake_parse_arguments(ARG "32BIT" "OUTDIR;LIBRARY;TOP_MODULE" "" ${ARGN}) # Check for any unrecognized arguments @@ -658,7 +741,20 @@ function(xcelium_gen_hdl_wrapper SC_LIB) endfunction() - +#[[[ +# This macro is used to configure the C and CXX compiler to the one used by the tool. +# +# It can also be used to add some libraries, such as SystemC and DPI-C in this case, for example if you want to use dpi, you should use this macro like this : +# +# .. code-block:: cmake +# +# xcelium_configure_cxx(LIBRARIES DPI-C) +# +# **Keyword Arguments** +# +# :keyword LIBRARIES: Libraries that needs to be added. +# :type LIBRARIES: list[string] +#]] macro(xcelium_configure_cxx) cmake_parse_arguments(ARG "" "" "LIBRARIES" ${ARGN}) @@ -671,6 +767,18 @@ macro(xcelium_configure_cxx) endif() endmacro() +#[[[ +# This function is called by the ``xcelium_configure_cxx`` macro, you shouldn't use it directly. +# +# It will add the needed information to IP_LIB and add some flags for the compilation and linking. +# +# **Keyword Arguments** +# +# :keyword 32BIT: Use 32 bitness. +# :type 32BIT: bool +# :keyword LIBRARIES: libraries that needs to be added, possible choice is SystemC or DPI-C +# :type LIBRARIES: list[string] +#]] function(xcelium_add_cxx_libs) cmake_parse_arguments(ARG "32BIT" "" "LIBRARIES" ${ARGN}) # Check for any unrecognized arguments @@ -735,6 +843,19 @@ function(xcelium_add_cxx_libs) endfunction() +# Determine the default Xcelium compilation library name for a given IP_LIB. +# +# It will resolves the logical compilation library associated with it. +# +# :param OUT_LIB: Name of the variable that will receive the resolved library name. +# :type OUT_LIB: string (output variable) +# :param IP_LIB: The target IP library, it needs to have SOURCES property set with a list of SystemVerilog or VHDL files. +# :type IP_LIB: string +# +# **Keyword Arguments** +# +# :keyword LIBRARY: Specify the compilation library name to use. +# :type LIBRARY: string function(__xcelium_default_library OUT_LIB IP_LIB) cmake_parse_arguments(ARG "" "LIBRARY" "" ${ARGN}) if(ARG_UNPARSED_ARGUMENTS) diff --git a/cmake/sim/cocotb/add_cocotb_tests.cmake b/cmake/sim/cocotb/add_cocotb_tests.cmake index 336d4a80..e2596b4a 100644 --- a/cmake/sim/cocotb/add_cocotb_tests.cmake +++ b/cmake/sim/cocotb/add_cocotb_tests.cmake @@ -1,3 +1,15 @@ +#[[[ @module cocotb_tests +#]] + +#[[[ +# This function scans a given directory for cocotb test subdirectories and registers each as a CTest, with support for both simple and multi-testcase cocotb test configurations. +# Multi-testcase tests are auto-numbered into single CTest and a ``check`` target is created to run all the different tests. +# +# :param IP_LIB: The target IP library, it needs to have SOURCES property set with a list of SystemVerilog files. +# :type IP_LIB: string +# :param DIRECTORY: Path to the directory containing the cocotb test subdirectories to scan. Subdirectories prefixed with ``_`` are excluded. +# :type DIRECTORY: path string +#]] function(add_cocotb_tests IP_LIB DIRECTORY) include("${CMAKE_CURRENT_FUNCTION_LIST_DIR}/../../utils/subdirectory_search.cmake") include("${CMAKE_CURRENT_FUNCTION_LIST_DIR}/../../utils/colours.cmake") diff --git a/cmake/sim/cocotb/cocotb.cmake b/cmake/sim/cocotb/cocotb.cmake index b40af6da..91955fca 100644 --- a/cmake/sim/cocotb/cocotb.cmake +++ b/cmake/sim/cocotb/cocotb.cmake @@ -1,11 +1,14 @@ +#[[[ @module cocotb +#]] + include_guard(GLOBAL) -# [[[ -# This function simulated the IP library with the cocotb library. +#[[[ +# Create a target for invoking simulation on IP_LIB using the `cocotb Python verification framework `_. # # The function is a wrapper around supported simulators by cocotb. It is based on the cocotb Makefiles. # -# :param IP_LIB: Name of the IP library to run iverilog on. +# :param IP_LIB: The target IP library. # :type IP_LIB: string # # **Keyword Arguments** @@ -30,11 +33,11 @@ include_guard(GLOBAL) # :type TIMESCALE: string # :keyword PYTHONPATH: List of paths to be added to the PYTHONPATH environment variable to include python modules needed for the simulation. # :type PYTHONPATH: string -# :keyword SV_COMPILE_ARGS: Extra arguments to be passed to the System Verilog / Verilog compilation step. +# :keyword SV_COMPILE_ARGS: Extra arguments to be passed to the SystemVerilog / Verilog compilation step. # :type SV_COMPILE_ARGS: string # :keyword RUN_ARGS: Extra arguments to be passed to the simulation step. # :type RUN_ARGS: string -# ]]] +#]] function(cocotb IP_LIB) # Parse the function arguments cmake_parse_arguments(ARG "NO_RUN_TARGET;GUI" "OUTDIR;RUN_TARGET_NAME;TOP_MODULE;COCOTB_MODULE;COCOTB_TESTCASE;SIM;TIMESCALE" "PYTHONPATH;SV_COMPILE_ARGS;RUN_ARGS" ${ARGN}) diff --git a/cmake/sim/fc4sc/fc4sc_merge_coverage.cmake b/cmake/sim/fc4sc/fc4sc_merge_coverage.cmake index f137db92..eb1e6e06 100644 --- a/cmake/sim/fc4sc/fc4sc_merge_coverage.cmake +++ b/cmake/sim/fc4sc/fc4sc_merge_coverage.cmake @@ -1,7 +1,25 @@ +#[[[ @module fc4sc +#]] + include_guard(GLOBAL) +#[[[ +# This function use fc4sc to merge already existing coverages files in the ``DIRECTORY`` directory (function's argument). +# +# :param DIRECTORY: Directory containing coverage informations +# :type DIRECTORY: path string +# +# **Keyword Arguments** +# +# :keyword OUTFILE: specify a path to an outfile and it name, by default it's set to ${CMAKE_CURRENT_BINARY_DIR}/coverage_merged_db.xml +# :type OUTFILE: string +# :keyword FC4SC_HOME: Path to the home directory of fc4sc +# :type FC4SC_HOME: path string +# :keyword DEPENDS: can be used if any dependencies need to be given for the coverage merging +# :type DEPENDS: string +#]] function(fc4sc_merge_coverage DIRECTORY) - cmake_parse_arguments(ARG "" "OUTFILE;FC4SC_HOME;VERISC_HOME" "DEPENDS" ${ARGN}) + cmake_parse_arguments(ARG "" "OUTFILE;FC4SC_HOME" "DEPENDS" ${ARGN}) if(ARG_UNPARSED_ARGUMENTS) message(FATAL_ERROR "${CMAKE_CURRENT_FUNCTION} passed unrecognized argument " "${ARG_UNPARSED_ARGUMENTS}") endif() @@ -14,15 +32,6 @@ function(fc4sc_merge_coverage DIRECTORY) set(OUTFILE ${ARG_OUTFILE}) endif() - if(ARG_VERISC_HOME AND ARG_FC4SC_HOME) - message(FATAL_ERROR "Specify only one of VERISC_HOME, FC4SC_HOME") - endif() - - if(ARG_VERISC_HOME) - set(SEARCH_HINT "${ARG_VERISC_HOME}/*/*") - elseif(VERISC_HOME) - set(SEARCH_HINT "${VERISC_HOME}/*/*") - endif() if(ARG_FC4SC_HOME) set(SEARCH_HINT "${ARG_FC4SC_HOME}/") elseif(FC4SC_HOME) diff --git a/cmake/sim/ghdl/ghdl.cmake b/cmake/sim/ghdl/ghdl.cmake index a30fc422..e427e5ac 100644 --- a/cmake/sim/ghdl/ghdl.cmake +++ b/cmake/sim/ghdl/ghdl.cmake @@ -1,5 +1,14 @@ +#[[[ @module ghdl +#]] + include_guard(GLOBAL) +# This function is used to set by ``ghdl``, it shouldn't be used directly in your cmake file. +# +# It is used to set a variable that contains the value of the VHDL standard to be used for compilation +# +# :param OUTVAR: The variable containing the retrieved VHDL standard +# :type OUTVAR: string function(__ghdl_get_standard_arg OUTVAR) set(SUPPORTED_VHDL_STANDARDS 87 93c 93 00 02 08) if(ARGN) @@ -12,6 +21,35 @@ function(__ghdl_get_standard_arg OUTVAR) endif() endfunction() +#[[[ +# Create a target for invoking GHDL (compilation, elaboration, and simulation) on IP_LIB. +# +# It will create a target **run__ghdl** that will compile, elaborate, and simulate the IP_LIB design. +# +# :param IP_LIB: The target IP library, it needs to have SOURCES property set with a list of VHDL files. +# :type IP_LIB: string +# +# **Keyword Arguments** +# +# :keyword NO_RUN_TARGET: Do not create a run target. +# :type NO_RUN_TARGET: bool +# :keyword OUTDIR: Output directory for the GHDL compilation and simulation. +# :type OUTDIR: string +# :keyword TOP_MODULE: Top module name to be used for elaboration and simulation. +# :type TOP_MODULE: string +# :keyword EXECUTABLE_NAME: Replace the default name of the generated executable target. +# :type EXECUTABLE_NAME: string +# :keyword STANDARD: Specify the VHDL standard to be used, default value is 93, possible values are 87, 93c, 93, 00, 02 and 08. +# :type STANDARD: string +# :keyword VHDL_COMPILE_ARGS: Extra arguments to be passed to the VHDL compilation step. +# :type VHDL_COMPILE_ARGS: string +# :keyword ELABORATE_ARGS: Extra arguments to be passed to the elaboration step. +# :type ELABORATE_ARGS: string +# :keyword RUN_ARGS: Extra arguments to be passed to the simulation step. +# :type RUN_ARGS: string +# :keyword FILE_SETS: Specify list of File sets to retrieve the sources from +# :type FILE_SETS: list[string] +#]] function(ghdl IP_LIB) cmake_parse_arguments(ARG "NO_RUN_TARGET;" "OUTDIR;TOP_MODULE;EXECUTABLE_NAME;STANDARD" "VHDL_COMPILE_ARGS;ELABORATE_ARGS;RUN_ARGS;FILE_SETS" ${ARGN}) if(ARG_UNPARSED_ARGUMENTS) @@ -131,6 +169,25 @@ function(ghdl IP_LIB) endfunction() +# This function is called by ``ghdl``, it shouldn't be used directly in a cmake file. +# +# It will create an intermediary target to compile VDHL file, using ghdl analyze. +# +# :param IP_LIB: The target IP library, it needs to have SOURCES property set with a list of VDHL files. +# :type IP_LIB: string +# +# **Keyword Arguments** +# +# :keyword OUTDIR: Output directory for the Questa compilation and simulation. +# :type OUTDIR: string +# :keyword LIBRARY: replace the default library name (worklib) to be used for elaboration and simulation. +# :type LIBRARY: string +# :keyword STANDARD: Specify the C++ version to be used. +# :type STANDARD: string +# :keyword VHDL_COMPILE_ARGS: Extra arguments to be passed to the VHDL compilation step. +# :type VHDL_COMPILE_ARGS: string +# :keyword FILE_SETS: Specify list of File sets to retrieve the sources from +# :type FILE_SETS: list[string] function(__ghdl_compile_lib IP_LIB) cmake_parse_arguments(ARG "" "LIBRARY;OUTDIR;STANDARD" "VHDL_COMPILE_ARGS;FILE_SETS" ${ARGN}) # Check for any unrecognized arguments @@ -241,6 +298,19 @@ function(__ghdl_compile_lib IP_LIB) endfunction() +# This function is called by ``ghdl``, it shouldn't be used directly in a cmake file. +# +# It will set values for the HDL and DPI library arguments that will be used for compilation, elaboration and simulation. +# +# :param IP_LIB: The target IP library. +# :type IP_LIB: string +# +# **Keyword Arguments** +# +# :keyword OUTDIR: Output directory for the ghdl compilation and simulation. +# :type OUTDIR: string +# :keyword LIBRARY: replace the default library name (worklib) to be used for elaboration and simulation. +# :type LIBRARY: string function(__get_ghdl_search_lib_args IP_LIB) cmake_parse_arguments(ARG "" "OUTDIR;LIBRARY" "" ${ARGN}) if(ARG_UNPARSED_ARGUMENTS) @@ -269,7 +339,7 @@ function(__get_ghdl_search_lib_args IP_LIB) endif() set(lib_outdir ${ARG_OUTDIR}/${__comp_lib_name}) - # Append current library outdhdl_libs_argsir to list of search directories + # Append current library outdir to list of search directories if(NOT "-P${lib_outdir}" IN_LIST hdl_libs_args) list(APPEND hdl_libs_args -P${lib_outdir}) endif() @@ -280,6 +350,10 @@ function(__get_ghdl_search_lib_args IP_LIB) set(DPI_LIBS_ARGS ${dpi_libs_args} PARENT_SCOPE) endfunction() +# This function add the GHDL tools/include directory to the include directories of the VPI/DPI libraries, to be correctly compiled later. +# +# :param IP_LIB: The target IP library. +# :type IP_LIB: string function(__add_ghdl_cxx_properties_to_libs IP_LIB) if(ARG_UNPARSED_ARGUMENTS) message(FATAL_ERROR "${CMAKE_CURRENT_FUNCTION} passed unrecognized argument " "${ARG_UNPARSED_ARGUMENTS}") @@ -295,7 +369,7 @@ function(__add_ghdl_cxx_properties_to_libs IP_LIB) get_target_property(ip_type ${lib} TYPE) if(ip_type STREQUAL "SHARED_LIBRARY" OR ip_type STREQUAL "STATIC_LIBRARY") if(NOT ghdl_exec_path) - message(FATAL_ERROR "GHDL executable xrun was not found, cannot set include directory on DPI library") + message(FATAL_ERROR "GHDL executable was not found, cannot set include directory on DPI library") endif() # Add tools/include directory to the include directories of DPI libraries # TODO do this only when its needed diff --git a/cmake/sim/iverilog/iverilog.cmake b/cmake/sim/iverilog/iverilog.cmake index ab16a870..6ccac7d0 100644 --- a/cmake/sim/iverilog/iverilog.cmake +++ b/cmake/sim/iverilog/iverilog.cmake @@ -1,12 +1,15 @@ +#[[[ @module iverilog +#]] + include_guard(GLOBAL) -# [[[ +#[[[ # This function runs the Icarus Verilog (iverilog) tool on a specified IP library. # # The function is a wrapper around the iverilog tool and generates necessary scripts # and configurations to compile the specified IP library. # -# :param IP_LIB: Name of the IP library to run iverilog on. +# :param IP_LIB: The target IP library. # :type IP_LIB: string # # **Keyword Arguments** @@ -23,7 +26,7 @@ include_guard(GLOBAL) # :type EXECUTABLE: string # :keyword FILE_SETS: list of file sets to use for simulation. # :type FILE_SETS: list[string] -# ]]] +#]] function(iverilog IP_LIB) # Parse the function arguments cmake_parse_arguments(ARG "NO_RUN_TARGET" "TOP_MODULE;OUTDIR;EXECUTABLE;RUN_TARGET_NAME" "SV_COMPILE_ARGS;RUN_ARGS;FILE_SETS" ${ARGN}) diff --git a/cmake/sim/siemens/questasim.cmake b/cmake/sim/siemens/questasim.cmake index 2c615fad..0ab5af7d 100644 --- a/cmake/sim/siemens/questasim.cmake +++ b/cmake/sim/siemens/questasim.cmake @@ -1,5 +1,43 @@ +#[[[ @module questasim +#]] + include_guard(GLOBAL) +#[[[ +# Create a target for invoking Questasim (compilation, elaboration, and simulation) on IP_LIB. +# +# It will create a target **run__questasim** that will compile, elaborate, and simulate the IP_LIB design. +# +# :param IP_LIB: The target IP library, it needs to have SOURCES property set with a list of SystemVerilog or VHDL files. +# :type IP_LIB: string +# +# **Keyword Arguments** +# +# :keyword NO_RUN_TARGET: Do not create a run target. +# :type NO_RUN_TARGET: bool +# :keyword GUI: Run simulation in GUI mode. +# :type GUI: bool +# :keyword GUI_VISUALIZER: Run simulation in GUI, with Visualizer. +# :type GUI_VISUALIZER: bool +# :keyword 32BIT: Use 32 bit compilation and simulation. +# :type 32BIT: bool +# :keyword LIBRARY: replace the default library name (worklib) to be used for elaboration and simulation. +# :type LIBRARY: string +# :keyword TOP_MODULE: Top module name to be used for elaboration and simulation. +# :type TOP_MODULE: string +# :keyword OUTDIR: Output directory for the Questasim compilation and simulation. +# :type OUTDIR: string +# :keyword RUN_TARGET_NAME: Replace the default name of the run target. +# :type RUN_TARGET_NAME: string +# :keyword VHDL_COMPILE_ARGS: Extra arguments to be passed to the VHDL compilation step. +# :type VHDL_COMPILE_ARGS: string +# :keyword SV_COMPILE_ARGS: Extra arguments to be passed to the SystemVerilog / Verilog compilation step. +# :type SV_COMPILE_ARGS: string +# :keyword RUN_ARGS: Extra arguments to be passed to the simulation step. +# :type RUN_ARGS: string +# :keyword FILE_SETS: Specify list of File sets to retrieve the sources from +# :type FILE_SETS: list[string] +#]] function(questasim IP_LIB) cmake_parse_arguments(ARG "NO_RUN_TARGET;QUIET;GUI;GUI_VISUALIZER;32BIT" "LIBRARY;TOP_MODULE;OUTDIR;RUN_TARGET_NAME" "VHDL_COMPILE_ARGS;SV_COMPILE_ARGS;RUN_ARGS;FILE_SETS" ${ARGN}) if(ARG_UNPARSED_ARGUMENTS) @@ -190,7 +228,29 @@ function(questasim IP_LIB) socmake_allow_topological_sort(ON) endfunction() - +# This function is called by ``questasim``, it shouldn't be used directly in a cmake file. +# +# It will create an intermediary target to compile VDHL and SystemVerilog/Verilog file, using vcom and vlog. It will also compile using sccom if SystemC is a boundary library. +# +# :param IP_LIB: The target IP library, it needs to have SOURCES property set with a list of SystemVerilog or VDHL files. +# :type IP_LIB: string +# +# **Keyword Arguments** +# +# :keyword QUIET: Disable output for informative messages +# :type QUIET: bool +# :keyword 32BIT: Use 32 bit compilation and simulation. +# :type 32BIT: bool +# :keyword OUTDIR: Output directory for the Questa compilation and simulation. +# :type OUTDIR: string +# :keyword LIBRARY: replace the default library name (worklib) to be used for elaboration and simulation. +# :type LIBRARY: string +# :keyword SV_COMPILE_ARGS: Extra arguments to be passed to the SystemVerilog / Verilog compilation step. +# :type SV_COMPILE_ARGS: string +# :keyword VHDL_COMPILE_ARGS: Extra arguments to be passed to the VHDL compilation step. +# :type VHDL_COMPILE_ARGS: string +# :keyword FILE_SETS: Specify list of File sets to retrieve the sources from +# :type FILE_SETS: list[string] function(__questasim_compile_lib IP_LIB) cmake_parse_arguments(ARG "QUIET;32BIT" "OUTDIR;LIBRARY" "SV_COMPILE_ARGS;VHDL_COMPILE_ARGS;FILE_SETS" ${ARGN}) # Check for any unrecognized arguments @@ -363,7 +423,7 @@ function(__questasim_compile_lib IP_LIB) endif() if(VHDL_SOURCES) - set(DESCRIPTION "Compile VHDL sources for ${lib} with questasim vlog in library ${__comp_lib_name}") + set(DESCRIPTION "Compile VHDL sources for ${lib} with questasim vcom in library ${__comp_lib_name}") set(STAMP_FILE "${OUTDIR}/.${lib}_vcom_${CMAKE_CURRENT_FUNCTION}.stamp") add_custom_command( OUTPUT ${STAMP_FILE} @@ -424,7 +484,19 @@ function(__questasim_compile_lib IP_LIB) endfunction() - +# This function is called by ``questasim``, it shouldn't be used directly in a cmake file. +# +# It will set values for the HDL and DPI library arguments that will be used for compilation, elaboration and simulation. +# +# :param IP_LIB: The target IP library. +# :type IP_LIB: string +# +# **Keyword Arguments** +# +# :keyword OUTDIR: Output directory for the Questa compilation and simulation. +# :type OUTDIR: string +# :keyword LIBRARY: replace the default library name (worklib) to be used for elaboration and simulation. +# :type LIBRARY: string function(__get_questasim_search_lib_args IP_LIB) cmake_parse_arguments(ARG "" "OUTDIR;LIBRARY" "" ${ARGN}) if(ARG_UNPARSED_ARGUMENTS) @@ -472,6 +544,10 @@ function(__get_questasim_search_lib_args IP_LIB) set(DPI_LIBS_ARGS ${dpi_libs_args} PARENT_SCOPE) endfunction() +# This function allows to find the path to questasim home directory and to store it in a given variable. +# +# :param OUTVAR: Name of the variable in which questasim_home will be stored +# :type OUTVAR: string function(__find_questasim_home OUTVAR) find_program(exec_path vsim REQUIRED) get_filename_component(bin_path "${exec_path}" DIRECTORY) @@ -480,6 +556,31 @@ function(__find_questasim_home OUTVAR) set(${OUTVAR} ${questasim_home} PARENT_SCOPE) endfunction() +#[[[ +# This function create a target to generate a SystemC wrapper for the IP library, with Questasim scgenmod, if SystemVerilog or Verilog files are in the IP library. +# +# :param IP_LIB: The target IP library, it needs to have SOURCES property set with a list of SystemVerilog or Verilog files. +# :type IP_LIB: string +# +# **Keyword Arguments** +# +# :keyword 32BIT: Use 32 bit compilation and simulation. +# :type 32BIT: bool +# :keyword QUIET: Disable output for informative messages +# :type QUIET: bool +# :keyword OUTDIR: Output directory for the Questa compilation and simulation. +# :type OUTDIR: string +# :keyword LIBRARY: replace the default library name (worklib) to be used for elaboration and simulation. +# :type LIBRARY: string +# :keyword TOP_MODULE: Top module name to be used for elaboration and simulation. +# :type TOP_MODULE: string +# :keyword SV_COMPILE_ARGS: Extra arguments to be passed to the SystemVerilog / Verilog compilation step. +# :type SV_COMPILE_ARGS: string +# :keyword VHDL_COMPILE_ARGS: Extra arguments to be passed to the VHDL compilation step. +# :type VHDL_COMPILE_ARGS: string +# :keyword FILE_SETS: Specify list of File sets to retrieve the sources from +# :type FILE_SETS: list[string] +#]] function(questasim_gen_sc_wrapper IP_LIB) cmake_parse_arguments(ARG "32BIT;QUIET" "OUTDIR;LIBRARY;TOP_MODULE" "SV_COMPILE_ARGS;VHDL_COMPILE_ARGS;FILE_SETS" ${ARGN}) # Check for any unrecognized arguments @@ -589,6 +690,24 @@ function(questasim_gen_sc_wrapper IP_LIB) endfunction() +#[[[ +# This function create a target to compile SystemC boundary library with sccom +# +# :param SC_LIB: IP library, it needs to have SOURCES property set with a list of SystemC files as **cxx_sources**. +# :type IP_LIB: string +# :type SC_LIB: +# +# **Keyword Arguments** +# +# :keyword 32BIT: Use 32 bit compilation and simulation. +# :type 32BIT: bool +# :keyword OUTDIR: Output directory for the Questa compilation and simulation. +# :type OUTDIR: string +# :keyword LIBRARY: replace the default library name (worklib) to be used for elaboration and simulation. +# :type LIBRARY: string +# :keyword TOP_MODULE: Top module name to be used for elaboration and simulation. +# :type TOP_MODULE: string +#]] function(questasim_compile_sc_lib SC_LIB) cmake_parse_arguments(ARG "32BIT" "OUTDIR;LIBRARY;TOP_MODULE" "" ${ARGN}) # Check for any unrecognized arguments @@ -660,7 +779,20 @@ function(questasim_compile_sc_lib SC_LIB) set_property(TARGET ${SC_LIB}_${CMAKE_CURRENT_FUNCTION} PROPERTY DESCRIPTION ${DESCRIPTION}) endfunction() - +#[[[ +# This macro is used to configure the C and CXX compiler to the one used by the tool. +# +# It can also be used to add some libraries, such as SystemC, DPI-C and VHPI in this case, for example if you want to use dpi, you should use this macro like this : +# +# .. code-block:: cmake +# +# questasim_configure_cxx(LIBRARIES DPI-C) +# +# **Keyword Arguments** +# +# :keyword LIBRARIES: Libraries that needs to be added. +# :type LIBRARIES: list[string] +#]] macro(questasim_configure_cxx) cmake_parse_arguments(ARG "32BIT" "" "LIBRARIES" ${ARGN}) @@ -680,6 +812,18 @@ macro(questasim_configure_cxx) endif() endmacro() +#[[[ +# This function is called by the ``questasim_configure_cxx`` macro, you shouldn't use it directly. +# +# It will add the needed information to IP_LIB and add some flags for the compilation and linking. +# +# **Keyword Arguments** +# +# :keyword 32BIT: Use 32 bitness. +# :type 32BIT: bool +# :keyword LIBRARIES: libraries that needs to be added, possible choice are SystemC, DPI-C and/or VHPI +# :type LIBRARIES: list[string] +#]] function(questasim_add_cxx_libs) cmake_parse_arguments(ARG "32BIT" "" "LIBRARIES" ${ARGN}) # Check for any unrecognized arguments @@ -742,6 +886,11 @@ function(questasim_add_cxx_libs) endfunction() +#[[[ +# This macro is here in case the old modelsim SoCMake function has been called, due to a change in the function name, made to fit with the changes made in the past years with Modelsim/Questa. +# +# It will print a deprecation message and redirect the arguments used to the questasim SoCMake function. +#]] macro(modelsim) message(DEPRECATION "${Red}modelsim function is deprecated, questasim() is called instead${ColourReset}") questasim(${ARGV}) diff --git a/cmake/sim/sim_utils.cmake b/cmake/sim/sim_utils.cmake index 1cb46944..fb6f9678 100644 --- a/cmake/sim/sim_utils.cmake +++ b/cmake/sim/sim_utils.cmake @@ -1,5 +1,10 @@ +#[[[ @module sim_utils +#]] + include_guard(GLOBAL) +# This macro is used if a given library as been linked to the IP library. +# It is used by the following functions to check some libraries. macro(__check_linked_interface_lib) get_target_property(linked_libraries ${IP_LIB} LINK_LIBRARIES) @@ -10,21 +15,46 @@ macro(__check_linked_interface_lib) endif() endmacro() + +# This function is used to check if the SystemC library has been linked in the project. +# +# :param RESULT: If true, the SystemC library has correctly been linked to the IP library. +# :type RESULT: bool +# :param IP_LIB: The target IP library. +# :type IP_LIB: string function(__is_socmake_systemc_lib RESULT IP_LIB) set(__lib_to_check "SoCMake::SystemC") __check_linked_interface_lib() endfunction() +# This function is used to check if the DPI-C library has been linked in the project. +# +# :param RESULT: If true, the DPI-C library has correctly been linked to the IP library. +# :type RESULT: bool +# :param IP_LIB: The target IP library. +# :type IP_LIB: string function(__is_socmake_dpic_lib RESULT IP_LIB) set(__lib_to_check "SoCMake::DPI-C") __check_linked_interface_lib() endfunction() +# This function is used to check if the VHPI library has been linked in the project. +# +# :param RESULT: If true, the VHPI library has correctly been linked to the IP library. +# :type RESULT: bool +# :param IP_LIB: The target IP library. +# :type IP_LIB: string function(__is_socmake_vhpi_lib RESULT IP_LIB) set(__lib_to_check "SoCMake::VHPI") __check_linked_interface_lib() endfunction() +# This function is used to check if the IP library is of the type : ``INTERFACE_LIBRARY`` +# +# :param RESULT: If true, the IP library is of the right type. +# :type RESULT: bool +# :param IP_LIB: The target IP library. +# :type IP_LIB: string function(__is_socmake_ip_lib RESULT IP_LIB) get_target_property(ip_type ${IP_LIB} TYPE) get_target_property(ip_name ${IP_LIB} IP_NAME) diff --git a/cmake/sim/synopsys/vcs.cmake b/cmake/sim/synopsys/vcs.cmake index 18521e38..289da42c 100644 --- a/cmake/sim/synopsys/vcs.cmake +++ b/cmake/sim/synopsys/vcs.cmake @@ -1,7 +1,47 @@ +#[[[ @module vcs +#]] + include_guard(GLOBAL) socmake_add_languages(VCS_SC_PORTMAP) +#[[[ +# Create a target for invoking VCS (compilation, elaboration, and simulation) on IP_LIB. +# +# It will create a target **run__vcs** that will compile, elaborate, and simulate the IP_LIB design. +# +# :param IP_LIB: The target IP library, it needs to have SOURCES property set with a list of SystemVerilog or VHDL files. +# :type IP_LIB: string +# +# **Keyword Arguments** +# +# :keyword NO_RUN_TARGET: Do not create a run target. +# :type NO_RUN_TARGET: bool +# :keyword GUI: Run simulation in GUI mode. +# :type GUI: bool +# :keyword 32BIT: Use 32 bit compilation and simulation. +# :type 32BIT: bool +# :keyword OUTDIR: Output directory for the VCS compilation and simulation. +# :type OUTDIR: string +# :keyword EXECUTABLE_NAME: Replace the default name of the generated executable target. +# :type EXECUTABLE_NAME: string +# :keyword RUN_TARGET_NAME: Replace the default name of the run target. +# :type RUN_TARGET_NAME: string +# :keyword TOP_MODULE: Top module name to be used for elaboration and simulation. +# :type TOP_MODULE: string +# :keyword LIBRARY: replace the default library name (worklib) to be used for elaboration and simulation. +# :type LIBRARY: string +# :keyword SV_COMPILE_ARGS: Extra arguments to be passed to the SystemVerilog / Verilog compilation step. +# :type SV_COMPILE_ARGS: string +# :keyword VHDL_COMPILE_ARGS: Extra arguments to be passed to the VHDL compilation step. +# :type VHDL_COMPILE_ARGS: string +# :keyword ELABORATE_ARGS: Extra arguments to be passed to the elaboration step. +# :type ELABORATE_ARGS: string +# :keyword RUN_ARGS: Extra arguments to be passed to the simulation step. +# :type RUN_ARGS: string +# :keyword FILE_SETS: Specify list of File sets to retrieve the sources from +# :type FILE_SETS: list[string] +#]] function(vcs IP_LIB) cmake_parse_arguments(ARG "NO_RUN_TARGET;GUI;32BIT" "OUTDIR;EXECUTABLE_NAME;RUN_TARGET_NAME;TOP_MODULE;LIBRARY" "SV_COMPILE_ARGS;VHDL_COMPILE_ARGS;ELABORATE_ARGS;RUN_ARGS;FILE_SETS" ${ARGN}) if(ARG_UNPARSED_ARGUMENTS) @@ -192,6 +232,31 @@ function(vcs IP_LIB) socmake_allow_topological_sort(ON) endfunction() +# This function is called by ``vcs``, it shouldn't be used directly in a cmake file. +# +# It will create an intermediary target to compile VDHL and SystemVerilog/Verilog file, using vhdlan and vlogan. +# +# :param IP_LIB: The target IP library, it needs to have SOURCES property set with a list of SystemVerilog or VDHL files. +# :type IP_LIB: string +# +# **Keyword Arguments** +# +# :keyword 32BIT: Use 32 bit compilation and simulation. +# :type 32BIT: bool +# :keyword OUTDIR: Output directory for the VCS compilation and simulation. +# :type OUTDIR: string +# :keyword LIBRARY: replace the default library name (worklib) to be used for elaboration and simulation. +# :type LIBRARY: string +# :keyword TOP_MODULE: Top module name to be used for elaboration and simulation. +# :type TOP_MODULE: string +# :keyword SV_COMPILE_ARGS: Extra arguments to be passed to the SystemVerilog / Verilog compilation step. +# :type SV_COMPILE_ARGS: string +# :keyword VHDL_COMPILE_ARGS: Extra arguments to be passed to the VHDL compilation step. +# :type VHDL_COMPILE_ARGS: string +# :keyword ELABORATE_ARGS: Extra arguments to be passed to the elaboration step. +# :type ELABORATE_ARGS: string +# :keyword FILE_SETS: Specify list of File sets to retrieve the sources from +# :type FILE_SETS: list[string] function(__vcs_compile_lib IP_LIB) cmake_parse_arguments(ARG "32BIT" "OUTDIR;LIBRARY;TOP_MODULE" "SV_COMPILE_ARGS;VHDL_COMPILE_ARGS;ELABORATE_ARGS;FILE_SETS" ${ARGN}) # Check for any unrecognized arguments @@ -395,6 +460,19 @@ function(__vcs_compile_lib IP_LIB) endfunction() +# This function is called by ``vcs``, it shouldn't be used directly in a cmake file. +# +# It will set values for the HDL and DPI library arguments that will be used for compilation, elaboration and simulation. +# +# :param IP_LIB: The target IP library. +# :type IP_LIB: string +# +# **Keyword Arguments** +# +# :keyword OUTDIR: Output directory for the VCS compilation and simulation. +# :type OUTDIR: string +# :keyword LIBRARY: replace the default library name (worklib) to be used for elaboration and simulation. +# :type LIBRARY: string function(__get_vcs_search_lib_args IP_LIB) cmake_parse_arguments(ARG "" "OUTDIR;LIBRARY" "" ${ARGN}) if(ARG_UNPARSED_ARGUMENTS) @@ -434,7 +512,7 @@ function(__get_vcs_search_lib_args IP_LIB) set(lib_outdir ${OUTDIR}/${__comp_lib_name}) file(MAKE_DIRECTORY ${lib_outdir}) - # Append current library outdhdl_libs_argsir to list of search directories + # Append current library outdir to list of search directories if(NOT ${__comp_lib_name} IN_LIST hdl_libs) list(APPEND hdl_libs ${__comp_lib_name}) string(APPEND synopsys_sim_setup_str "${__comp_lib_name}: ./${__comp_lib_name}\n") @@ -447,6 +525,29 @@ function(__get_vcs_search_lib_args IP_LIB) set(DPI_LIBS_ARGS ${dpi_libs_args} PARENT_SCOPE) endfunction() +#[[[ +# This function create a target to generate a SystemC wrapper for the IP library, with VCS vlogan, if SystemVerilog or Verilog files are in the IP library. +# +# :param IP_LIB: The target IP library, it needs to have SOURCES property set with a list of SystemVerilog or Verilog files. +# :type IP_LIB: string +# +# **Keyword Arguments** +# +# :keyword 32BIT: Use 32 bit compilation and simulation. +# :type 32BIT: bool +# :keyword OUTDIR: Output directory for the VCS compilation and simulation. +# :type OUTDIR: string +# :keyword LIBRARY: replace the default library name (worklib) to be used for elaboration and simulation. +# :type LIBRARY: string +# :keyword TOP_MODULE: Top module name to be used for elaboration and simulation. +# :type TOP_MODULE: string +# :keyword SV_COMPILE_ARGS: Extra arguments to be passed to the SystemVerilog / Verilog compilation step. +# :type SV_COMPILE_ARGS: string +# :keyword VHDL_COMPILE_ARGS: Extra arguments to be passed to the VHDL compilation step. +# :type VHDL_COMPILE_ARGS: string +# :keyword FILE_SETS: Specify list of File sets to retrieve the sources from +# :type FILE_SETS: list[string] +#]] function(vcs_gen_sc_wrapper IP_LIB) cmake_parse_arguments(ARG "32BIT" "OUTDIR;LIBRARY;TOP_MODULE" "SV_COMPILE_ARGS;VHDL_COMPILE_ARGS;FILE_SETS" ${ARGN}) # Check for any unrecognized arguments @@ -546,6 +647,23 @@ function(vcs_gen_sc_wrapper IP_LIB) endfunction() +#[[[ +# This function create a target to generate a Verilog wrapper file from a SystemC library with with VCS syscan. +# +# :param SC_LIB: Name of an existing CMake target representing the SystemC library. +# :type SC_LIB: target +# +# **Keyword Arguments** +# +# :keyword 32BIT: Use 32 bit compilation and simulation. +# :type 32BIT: bool +# :keyword OUTDIR: Output directory for the VCS compilation and simulation. +# :type OUTDIR: string +# :keyword LIBRARY: replace the default library name (worklib) to be used for elaboration and simulation. +# :type LIBRARY: string +# :keyword TOP_MODULE: Top module name to be used for elaboration and simulation. +# :type TOP_MODULE: string +#]] function(vcs_gen_hdl_wrapper SC_LIB) cmake_parse_arguments(ARG "32BIT" "OUTDIR;LIBRARY;TOP_MODULE" "" ${ARGN}) # Check for any unrecognized arguments @@ -614,6 +732,10 @@ function(vcs_gen_hdl_wrapper SC_LIB) endfunction() +# This function allows to find the path to vcs home directory and to store it in a given variable. +# +# :param OUTVAR: Name of the variable in which vcs_home will be stored +# :type OUTVAR: string function(__find_vcs_home OUTVAR) find_program(exec_path vcs REQUIRED) get_filename_component(bin_path "${exec_path}" DIRECTORY) @@ -622,6 +744,20 @@ function(__find_vcs_home OUTVAR) set(${OUTVAR} ${vcs_home} PARENT_SCOPE) endfunction() +#[[[ +# This macro is used to configure the C and CXX compiler to the one used by the tool. +# +# It can also be used to add some libraries, such as SystemC and DPI-C in this case, for example if you want to use dpi, you should use this macro like this : +# +# .. code-block:: cmake +# +# vcs_configure_cxx(LIBRARIES DPI-C) +# +# **Keyword Arguments** +# +# :keyword LIBRARIES: Libraries that needs to be added. +# :type LIBRARIES: list[string] +#]] macro(vcs_configure_cxx) cmake_parse_arguments(ARG "32BIT" "" "LIBRARIES" ${ARGN}) @@ -634,6 +770,18 @@ macro(vcs_configure_cxx) endif() endmacro() +#[[[ +# This function is called by the ``vcs_configure_cxx`` macro, you shouldn't use it directly. +# +# It will add the needed information to IP_LIB and add some flags for the compilation and linking. +# +# **Keyword Arguments** +# +# :keyword 32BIT: Use 32 bitness. +# :type 32BIT: bool +# :keyword LIBRARIES: libraries that needs to be added, possible choice are SystemC and/or DPI-C +# :type LIBRARIES: list[string] +#]] function(vcs_add_cxx_libs) cmake_parse_arguments(ARG "32BIT" "" "LIBRARIES" ${ARGN}) # Check for any unrecognized arguments diff --git a/cmake/sim/verilator/verilator.cmake b/cmake/sim/verilator/verilator.cmake index 3b5a2222..0a29fbb3 100644 --- a/cmake/sim/verilator/verilator.cmake +++ b/cmake/sim/verilator/verilator.cmake @@ -1,3 +1,59 @@ +#[[[ @module verilator +#]] + +#[[[ +# Create a target for invoking verilator (compilation, elaboration, and simulation) on IP_LIB. +# +# It will create a target **run__verilator** that will compile, elaborate, and simulate the IP_LIB design. +# +# :param IP_LIB: The target IP library, it needs to have SOURCES property set with a list of SystemVerilog files. +# :type IP_LIB: string +# +# **Keyword Arguments** +# +# :keyword COVERAGE: Enable code coverage during compilation and simulation. +# :type COVERAGE: bool +# :keyword TRACE: Enable waveform tracing. +# :type TRACE: bool +# :keyword TRACE_FST: Enable FST waveform tracing format. +# :type TRACE_FST: bool +# :keyword SYSTEMC: Enable SystemC support. +# :type SYSTEMC: bool +# :keyword TRACE_STRUCTS: Enable tracing of SystemVerilog structs. +# :type TRACE_STRUCTS: bool +# :keyword MAIN: Specify a custom C++ main file. +# :type MAIN: string +# :keyword TIMING: Enable timing support in simulation. +# :type TIMING: bool +# :keyword NO_RUN_TARGET: Do not create a run target. +# :type NO_RUN_TARGET: bool +# :keyword PREFIX: Prefix name used for generated output files and targets. +# :type PREFIX: string +# :keyword TOP_MODULE: Top module name to be used for elaboration and simulation. +# :type TOP_MODULE: string +# :keyword THREADS: Number of threads to be used during compilation or simulation. +# :type THREADS: int +# :keyword TRACE_THREADS: Enable waveform tracing per thread. +# :type TRACE_THREADS: bool +# :keyword DIRECTORY: Output directory for generated build and simulation files. +# :type DIRECTORY: string +# :keyword EXECUTABLE_NAME: Replace the default name of the generated executable target. +# :type EXECUTABLE_NAME: string +# :keyword RUN_TARGET_NAME: Replace the default name of the run target. +# :type RUN_TARGET_NAME: string +# :keyword VERILATOR_ARGS: Extra arguments to be passed to the Verilator invocation. +# :type VERILATOR_ARGS: string +# :keyword OPT_SLOW: Enable slow but optimized compilation mode. +# :type OPT_SLOW: bool +# :keyword OPT_FAST: Enable fast compilation optimization mode. +# :type OPT_FAST: bool +# :keyword OPT_GLOBAL: Enable global optimization mode. +# :type OPT_GLOBAL: bool +# :keyword RUN_ARGS: Extra arguments to be passed to the simulation executable. +# :type RUN_ARGS: string +# :keyword FILE_SETS: Specify list of file sets to retrieve the sources from. +# :type FILE_SETS: list[string] +#]] function(verilator IP_LIB) set(OPTIONS "COVERAGE;TRACE;TRACE_FST;SYSTEMC;TRACE_STRUCTS;MAIN;TIMING;NO_RUN_TARGET") set(ONE_PARAM_ARGS "PREFIX;TOP_MODULE;THREADS;TRACE_THREADS;DIRECTORY;EXECUTABLE_NAME;RUN_TARGET_NAME") @@ -41,9 +97,7 @@ function(verilator IP_LIB) # Ensure CMP0144 is set before find_package to get rid of warning cmake_policy(PUSH) cmake_policy(SET CMP0144 NEW) - find_package(verilator REQUIRED - HINTS ${VERISC_HOME}/open/* $ENV{VERISC_HOME}/open/* - ) + find_package(verilator REQUIRED) set(VERILATOR_HOME "${verilator_DIR}/../../") cmake_policy(POP) endif() @@ -150,9 +204,7 @@ function(verilator IP_LIB) if(ARG_SYSTEMC) if(NOT SYSTEMC_HOME) - find_package(SystemCLanguage REQUIRED - HINTS ${VERISC_HOME}/open/* $ENV{VERISC_HOME}/open/* - ) + find_package(SystemCLanguage REQUIRED) set(SYSTEMC_HOME "${SystemCLanguage_DIR}/../../../") endif() endif() @@ -296,6 +348,21 @@ function(verilator IP_LIB) socmake_allow_topological_sort(ON) endfunction() +#[[[ +# This macro is used to configure the C and CXX compiler to the one used by the tool. +# In this specific case, it won't change anything for the compiler use but will add some useful informations to IP_LIB. +# +# The only supported library by this function is DPI-C, it can be used as done in the following example : +# +# .. code-block:: cmake +# +# verilator_configure_cxx(LIBRARIES DPI-C) +# +# **Keyword Arguments** +# +# :keyword LIBRARIES: Libraries that needs to be added. +# :type LIBRARIES: list[string] +#]] macro(verilator_configure_cxx) cmake_parse_arguments(ARG "" "" "LIBRARIES" ${ARGN}) if(ARG_LIBRARIES) @@ -303,6 +370,18 @@ macro(verilator_configure_cxx) endif() endmacro() +#[[[ +# This function is called by the ``verilator_configure_cxx`` macro, you shouldn't use it directly. +# +# It will add the needed information to IP_LIB and add some flags for the compilation and linking. +# +# **Keyword Arguments** +# +# :keyword 32BIT: Use 32 bitness. +# :type 32BIT: bool +# :keyword LIBRARIES: libraries that needs to be added, possible choice are DPI-C only for now. +# :type LIBRARIES: list[string] +#]] function(verilator_add_cxx_libs) cmake_parse_arguments(ARG "" "" "LIBRARIES" ${ARGN}) if(ARG_UNPARSED_ARGUMENTS) diff --git a/cmake/sim/verisc/CMakeLists.txt b/cmake/sim/verisc/CMakeLists.txt deleted file mode 100644 index 1b554942..00000000 --- a/cmake/sim/verisc/CMakeLists.txt +++ /dev/null @@ -1,24 +0,0 @@ -cmake_minimum_required(VERSION 3.25) -project(verisc) - -set(DEPS "SYSTEMC;UVM-SYSTEMC;VERILATOR;FC4SC;ICSC_COMPILER;GCC") - -foreach(dep ${DEPS}) - if(${dep}_VERSION) - list(APPEND VERISC_CFG -D${dep}_VERSION=${${dep}_VERSION}) - endif() -endforeach() - -include(ExternalProject) -ExternalProject_Add(verisc - GIT_REPOSITORY https://github.com/Risto97/verisc.git - GIT_TAG v${VERISC_VERSION} - PREFIX ${VERISC_BUILD_DIR} - INSTALL_DIR ${VERISC_INSTALL_DIR} - - CMAKE_ARGS - -DCMAKE_INSTALL_PREFIX=${VERISC_INSTALL_DIR} - ${VERISC_CFG} - -DCMAKE_VERBOSE_MAKEFILE=TRUE - ) -set_target_properties(verisc PROPERTIES EXCLUDE_FROM_ALL TRUE) diff --git a/cmake/sim/verisc/verisc_install.cmake b/cmake/sim/verisc/verisc_install.cmake deleted file mode 100644 index 7f6bfdd1..00000000 --- a/cmake/sim/verisc/verisc_install.cmake +++ /dev/null @@ -1,91 +0,0 @@ -include_guard(GLOBAL) - -set(VERISC_INSTALL_LIST_DIR ${CMAKE_CURRENT_LIST_DIR} CACHE INTERNAL "") - -macro(verisc_build) - - set(DEPS "SYSTEMC;UVM-SYSTEMC;VERILATOR;FC4SC;ICSC_COMPILER;GCC") - foreach(dep ${DEPS}) - list(APPEND OPTIONS NO${dep}) - list(APPEND ONE_PARAM ${dep}_VERSION) - list(APPEND ONE_PARAM ${dep}_HOME) - endforeach() - list(APPEND ONE_PARAM "CMAKE_CXX_STANDARD;INSTALL_DIR;VERSION") - set(MULT_PARAM "") - cmake_parse_arguments(ARG - "${OPTIONS}" - "${ONE_PARAM};VERISC_HOME" - "${MULT_PARAM}" - ${ARGN} - ) - if(ARG_UNPARSED_ARGUMENTS) - message(FATAL_ERROR "${CMAKE_CURRENT_MACRO} passed unrecognized argument " "${ARG_UNPARSED_ARGUMENTS}") - endif() - - foreach(dep ${DEPS}) - if(ARG_NO${dep}) - set(ARG_${dep}_VERSION FALSE) - endif() - endforeach() - - foreach(dep ${DEPS}) - if(DEFINED ARG_${dep}_VERSION) - list(APPEND VERISC_CFG -D${dep}_VERSION=${ARG_${dep}_VERSION}) - endif() - endforeach() - - if(NOT ARG_VERSION) - message(FATAL_ERROR "Need to specify VERSION for verisc_build() function") - else() - set(VERSION ${ARG_VERSION}) - endif() - - if((NOT ARG_INSTALL_DIR)) - if(FETCHCONTENT_BASE_DIR) - set(INSTALL_DIR ${FETCHCONTENT_BASE_DIR}/verisc) - endif() - else() - set(INSTALL_DIR ${ARG_INSTALL_DIR}) - endif() - - find_package(veriSC ${VERSION} EXACT CONFIG - PATHS ${ARG_VERISC_HOME} $ENV{VERISC_HOME} ${VERISC_HOME} ${INSTALL_DIR} - NO_DEFAULT_PATH - ) - - if(NOT veriSC_FOUND) - message("VERISC package not found looking at:") - message(" ARG_VERISC_HOME: ${ARG_VERISC_HOME}") - message(" ENV(VERISC_HOME): $ENV{VERISC_HOME}") - message(" VERISC_HOME: ${VERISC_HOME}") - message(" INSTALL_DIR: ${INSTALL_DIR}") - elseif(NOT veriSC_VERSION VERSION_EQUAL ${VERSION}) - message("veriSC_VERSION ${veriSC_VERSION} not matching requested version ${VERSION}") - endif() - - set(VERISC_HOME "${veriSC_DIR}/../../../") - - if((NOT veriSC_FOUND) OR (NOT veriSC_VERSION VERSION_EQUAL ${VERSION}) OR FORCE_UPDATE) - - set(BOOTSTRAP_DIR "${INSTALL_DIR}/../verisc-build/") - cmake_host_system_information(RESULT nproc QUERY NUMBER_OF_PHYSICAL_CORES) - - message("UPDATING VERISC TO VERSION ${VERSION}") - - execute_process(COMMAND ${CMAKE_COMMAND} -E make_directory ${BOOTSTRAP_DIR}) - execute_process(COMMAND ${CMAKE_COMMAND} - -B ${BOOTSTRAP_DIR} - -S ${VERISC_INSTALL_LIST_DIR} - ${VERISC_CFG} - -DVERISC_VERSION=${VERSION} - -DVERISC_INSTALL_DIR=${INSTALL_DIR} - -DVERISC_BUILD_DIR=${BOOTSTRAP_DIR} - ) - execute_process(COMMAND make -j${nproc} -C ${BOOTSTRAP_DIR} verisc) - - find_package(veriSC ${veriSC_VERSION} CONFIG REQUIRED - PATHS ${INSTALL_DIR} - NO_DEFAULT_PATH - ) - endif() -endmacro() diff --git a/cmake/sim/xilinx/vivado_sim.cmake b/cmake/sim/xilinx/vivado_sim.cmake index d5c5e291..30d211ba 100644 --- a/cmake/sim/xilinx/vivado_sim.cmake +++ b/cmake/sim/xilinx/vivado_sim.cmake @@ -1,5 +1,39 @@ +#[[[ @module xilinx +#]] + include_guard(GLOBAL) +#[[[ +# Create a target for invoking Vivado (compilation, elaboration, and simulation) on IP_LIB. +# +# It will create a target **run__vivado** that will compile, elaborate, and simulate the IP_LIB design. +# +# :param IP_LIB: The target IP library, it needs to have SOURCES property set with a list of System Verilog or VHDL files. +# :type IP_LIB: string +# +# **Keyword Arguments** +# +# :keyword NO_RUN_TARGET: Do not create a run target. +# :type NO_RUN_TARGET: bool +# :keyword GUI: Run simulation in GUI mode. +# :type GUI: bool +# :keyword RUN_TARGET_NAME: Replace the default name of the run target. +# :type RUN_TARGET_NAME: string +# :keyword TOP_MODULE: Top module name to be used for elaboration and simulation. +# :type TOP_MODULE: string +# :keyword XVLOG_ARGS: Extra arguments to be passed to the SystemVerilog / Verilog compilation step. +# :type XVLOG_ARGS: string +# :keyword XVHDL_ARGS: Extra arguments to be passed to the VHDL compilation step. +# :type XVHDL_ARGS: string +# :keyword XELAB_ARGS: Extra arguments to be passed to the elaboration step. +# :type XELAB_ARGS: string +# :keyword XSIM_ARGS: Extra arguments to be passed to the simulation step. +# :type XSIM_ARGS: string +# :keyword RUN_ARGS: Extra arguments to be passed to the simulation step. +# :type RUN_ARGS: string +# :keyword FILE_SETS: Specify list of File sets to retrieve the sources from +# :type FILE_SETS: list[string] +#]] function(vivado_sim IP_LIB) cmake_parse_arguments(ARG "NO_RUN_TARGET;GUI" "RUN_TARGET_NAME;TOP_MODULE" "XVLOG_ARGS;XVHDL_ARGS;XELAB_ARGS;XSIM_ARGS;RUN_ARGS;FILE_SETS" ${ARGN}) if(ARG_UNPARSED_ARGUMENTS) @@ -132,6 +166,23 @@ function(vivado_sim IP_LIB) endfunction() +# This function is called by ``vivado_sim``, it shouldn't be used directly in a cmake file. +# +# It will create an intermediary target to compile VDHL and SystemVerilog/Verilog file, using xvhdl and xvlog. +# +# :param IP_LIB: The target IP library, it needs to have SOURCES property set with a list of System Verilog or VHDL files. +# :type IP_LIB: string +# +# **Keyword Arguments** +# +# :keyword OUTDIR: Output directory. +# :type OUTDIR: string +# :keyword XVLOG_ARGS: Extra arguments to be passed to the SystemVerilog / Verilog compilation step. +# :type XVLOG_ARGS: string +# :keyword XVHDL_ARGS: Extra arguments to be passed to the VHDL compilation step. +# :type XVHDL_ARGS: string +# :keyword FILE_SETS: Specify list of File sets to retrieve the sources from +# :type FILE_SETS: list[string] function(__vivado_sim_compile_lib IP_LIB) cmake_parse_arguments(ARG "" "OUTDIR" "XVLOG_ARGS;XVHDL_ARGS;FILE_SETS" ${ARGN}) # Check for any unrecognized arguments @@ -262,6 +313,21 @@ function(__vivado_sim_compile_lib IP_LIB) endfunction() +#[[[ +# This macro is used to configure the C and CXX compiler to the one used by the tool. +# In this specific case, it won't change anything for the compiler use but will add some useful informations to IP_LIB. +# +# The only supported library by this function is DPI-C, it can be used as done in the following example : +# +# .. code-block:: cmake +# +# vivado_sim_configure_cxx(LIBRARIES DPI-C) +# +# **Keyword Arguments** +# +# :keyword LIBRARIES: Libraries that needs to be added. +# :type LIBRARIES: list[string] +#]] macro(vivado_sim_configure_cxx) cmake_parse_arguments(ARG "" "" "LIBRARIES" ${ARGN}) @@ -274,6 +340,18 @@ macro(vivado_sim_configure_cxx) endif() endmacro() +#[[[ +# This function is called by the ``vivado_sim_configure_cxx`` macro, you shouldn't use it directly. +# +# It will add the needed information to IP_LIB and add some flags for the compilation and linking. +# +# **Keyword Arguments** +# +# :keyword 32BIT: Use 32 bitness. +# :type 32BIT: bool +# :keyword LIBRARIES: libraries that needs to be added, possible choice are DPI-C only for now. +# :type LIBRARIES: list[string] +#]] function(vivado_sim_add_cxx_libs) cmake_parse_arguments(ARG "32BIT" "" "LIBRARIES" ${ARGN}) # Check for any unrecognized arguments diff --git a/cmake/synth/sv2v.cmake b/cmake/synth/sv2v.cmake index bb4e3fb0..08177c7c 100644 --- a/cmake/synth/sv2v.cmake +++ b/cmake/synth/sv2v.cmake @@ -1,5 +1,24 @@ +#[[[ @module sv2v +#]] + include_guard(GLOBAL) +#[[[ +# This function convert SystemVerilog files to Verilog files. +# +# It will take all the .sv files in ${IP_LIB} and convert them to verilog files, they will be stored in a new folder, which can be parametrized. +# It's also possible to replace the files in case of flattening, using the ``REPLACE`` argument. +# +# :param IP_LIB: The target IP library. +# :type IP_LIB: string +# +# **Keyword Arguments** +# +# :keyword OUTDIR: Path to the location where converted file will be stored, if not set, it's in ``${BINARY_DIR}/sv2v`` +# :type OUTDIR: string +# :keyword REPLACE: Can be set if .sv files need to be replaced by the .v files in the flatten graph. +# :type REPLACE: bool +#]] function(sv2v IP_LIB) cmake_parse_arguments(ARG "REPLACE" "OUTDIR" "" ${ARGN}) if(ARG_UNPARSED_ARGUMENTS) diff --git a/cmake/synth/yosys/yosys.cmake b/cmake/synth/yosys/yosys.cmake index 319375fe..ed098343 100644 --- a/cmake/synth/yosys/yosys.cmake +++ b/cmake/synth/yosys/yosys.cmake @@ -1,14 +1,17 @@ +#[[[ @module yosys +#]] + include_guard(GLOBAL) include(${CMAKE_CURRENT_LIST_DIR}/../sv2v.cmake) -# [[[ +#[[[ # This function runs the Yosys synthesis tool on a specified IP library. # # The function is a wrapper around the Yosys tool and generates necessary scripts # and configurations to run Yosys on the specified IP library. # -# :param IP_LIB: Name of the IP library to run Yosys on. +# :param IP_LIB: The target IP library. # :type IP_LIB: string # # **Keyword Arguments** @@ -27,7 +30,7 @@ include(${CMAKE_CURRENT_LIST_DIR}/../sv2v.cmake) # :type SHOW: boolean # :keyword REPLACE: Replace original sources with the generated Verilog source. # :type REPLACE: boolean -# ]]] +#]] function(yosys IP_LIB) # TODO iterate over linked libraries and replace SYSTEMVERILOG_SOURCES with VERILOG_SOURCES instead diff --git a/cmake/synth/yosys/yosys_build.cmake b/cmake/synth/yosys/yosys_build.cmake index 92ec9926..52475659 100644 --- a/cmake/synth/yosys/yosys_build.cmake +++ b/cmake/synth/yosys/yosys_build.cmake @@ -1,5 +1,16 @@ +#[[[ @module build_scripts +#]] + include_guard(GLOBAL) +#[[[ +# This function can be used to build yosys if needed. A tag or a version need to be given in the arguments, both can't be used at the same time obviously. +# +# :param TAG: Git tag for the version of Yosys that needs to be built +# :type TAG: string +# :param VERSION: Version of Yosys that needs to be built +# :type VERSION: string +#]] function(yosys_build) cmake_parse_arguments(ARG diff --git a/cmake/systemrdl/desyrdl.cmake b/cmake/systemrdl/desyrdl.cmake index 3a02ae74..6dab2a61 100644 --- a/cmake/systemrdl/desyrdl.cmake +++ b/cmake/systemrdl/desyrdl.cmake @@ -1,3 +1,26 @@ +#[[[ @module systemrdl +#]] + +#[[[ +# Generate a VHDL register block and adds it to the IP library. +# +# Function expects that **IP_LIB** *INTERFACE_LIBRARY* has **SYSTEMRDL_SOURCES** property set +# with a list of SystemRDL files to be used as inputs. +# +# :param IP_LIB: The target IP library. +# :type IP_LIB: string +# +# **Keyword Arguments** +# +# :keyword OUTDIR: Path to the location where generated file will be stored, if not set, it's in ``${BINARY_DIR}/${IP_LIB}_${CMAKE_CURRENT_FUNCTION}`` +# :type OUTDIR: string +# :keyword INTF: Interface to be used for the generated registers. By default, it's set to "ibus", "axi4l" (axi4-lite) is also supported. +# :type INTF: string +# :keyword TOP_ADDRMAP: +# :type TOP_ADDRMAP: string +# :keyword ARGS: Arguments to be given to desyrdl tool. +# :type ARGS: string +#]] function(desyrdl IP_LIB) # Parse keyword arguments cmake_parse_arguments(ARG "" "OUTDIR;INTF;TOP_ADDRMAP" "ARGS" ${ARGN}) diff --git a/cmake/utils/alias_dereference.cmake b/cmake/utils/alias_dereference.cmake index 46c8c079..88d204ae 100644 --- a/cmake/utils/alias_dereference.cmake +++ b/cmake/utils/alias_dereference.cmake @@ -1,3 +1,6 @@ +#[[[ @module alias_dereference +#]] + #[[[ # This function returns the original library name if the given one is an alias. # diff --git a/cmake/utils/colours.cmake b/cmake/utils/colours.cmake index 4ec32e89..90c73881 100644 --- a/cmake/utils/colours.cmake +++ b/cmake/utils/colours.cmake @@ -1,3 +1,6 @@ +#[[[ @module colours +#]] + if(NOT WIN32) string(ASCII 27 Esc) set(ColourReset "${Esc}[m") @@ -20,6 +23,31 @@ endif() set(__Colours Red Green Yellow Blue Magenta Cyan White BoldRed BoldGreen BoldYellow BoldBlue BoldMagenta BoldCyan BoldWhite) +#[[[ +# This function is allow to easierly display a text in a colour. +# +# The available colors are the following: +# +# - Red +# - Green +# - Yellow +# - Blue +# - Magenta +# - Cyan +# - White +# - BoldRed +# - BoldGreen +# - BoldYellow +# - BoldBlue +# - BoldMagenta +# - BoldCyan +# - BoldWhite +# +# :param TEXT: Text to be displayed. +# :type TEXT: string +# :param COLOUR: Colour for the text to be displayed. +# :type HELP_COLOURNAME: string +#]] function(msg TEXT COLOUR) cmake_parse_arguments(ARG "" "" "" ${ARGN}) if(ARG_UNPARSED_ARGUMENTS) diff --git a/cmake/utils/copy_rtl_files/copy_rtl_files.cmake b/cmake/utils/copy_rtl_files/copy_rtl_files.cmake index f631d6fd..a7be8ef9 100644 --- a/cmake/utils/copy_rtl_files/copy_rtl_files.cmake +++ b/cmake/utils/copy_rtl_files/copy_rtl_files.cmake @@ -1,3 +1,6 @@ +#[[[ @module copy_rtl_files +#]] + #[[[ # This function copies the RTL sources of an IP to a given location. # @@ -6,10 +9,12 @@ # all the include files and the source files with a preserved hierarchy folder. It uses the vhier tool to parse and build the library # hierachy and copy only the files instantiated in the hierarchy. # vhier is part of a set of tools: +# # https://github.com/gitpan/Verilog-Perl +# # https://metacpan.org/pod/vhier # -# :param IP_LIB: IP library to get RTL sources from. +# :param IP_LIB: The target IP library. # :type IP_LIB: string # # **Keyword Arguments** diff --git a/cmake/utils/copy_rtl_files/read_rtl_sources.cmake b/cmake/utils/copy_rtl_files/read_rtl_sources.cmake index bedbcfaf..1fa4471e 100644 --- a/cmake/utils/copy_rtl_files/read_rtl_sources.cmake +++ b/cmake/utils/copy_rtl_files/read_rtl_sources.cmake @@ -1,3 +1,6 @@ +#[[[ @module read_rtl_sources +#]] + #[[[ # This function reads a file listing RTL files and return a list of paths. # diff --git a/cmake/utils/copy_rtl_files/vhier.cmake b/cmake/utils/copy_rtl_files/vhier.cmake index 2dbd9682..cd1cfb17 100644 --- a/cmake/utils/copy_rtl_files/vhier.cmake +++ b/cmake/utils/copy_rtl_files/vhier.cmake @@ -1,3 +1,25 @@ +#[[[ @module vhier +#]] + +#[[[ +# Creates a target for invoking `vhier tool `_, which gets the hierarchical tree of a given **IP_LIB** and returns the source file of this tree. +# +# :param IP_LIB: The target IP library. +# :type IP_LIB: string +# +# **Keyword Arguments** +# +# :keyword TOP_MODULE: if set, add --top-module ${IP_NAME} flags, that will start looking at the hierarchy by starting at the given top modules. +# :type TOP_MODULE: bool +# :keyword XML: if set, add --xml flags, that creates an output in xml format. +# :type XML: bool +# :keyword FILES: if set, add --module-files flags, that shows all module filenames, in a top-down order. +# :type FILES: bool +# :keyword MODULES: if set, add --modules flag, that shows all module names. +# :type MODULES: bool +# :keyword FOREST: if set, add --forest flags, that shows an "ASCII-art" hierarchy tree of all cells. +# :type FOREST: bool +#]] function(vhier IP_LIB) cmake_parse_arguments(ARG "XML;FILES;MODULES;FOREST" "TOP_MODULE" "" ${ARGN}) if(ARG_UNPARSED_ARGUMENTS) diff --git a/cmake/utils/file_paths.cmake b/cmake/utils/file_paths.cmake index bf64087f..b89b368d 100644 --- a/cmake/utils/file_paths.cmake +++ b/cmake/utils/file_paths.cmake @@ -1,3 +1,6 @@ +#[[[ @module file_paths +#]] + #[[[ # This function converts relative paths to absolute paths relative to ${CMAKE_CURRENT_SOURCE_DIR} # It replicates the behaviour of target_sources() CMake Function diff --git a/cmake/utils/find_python.cmake b/cmake/utils/find_python.cmake index 915b94ed..6c09d311 100644 --- a/cmake/utils/find_python.cmake +++ b/cmake/utils/find_python.cmake @@ -1,5 +1,11 @@ +#[[[ @module find_python +#]] + include_guard(GLOBAL) +#[[[ +# This function can be used to find a python3 interpreter and will set a variable, ``Python3_EXECUTABLE``, to be used in cmake file, to create command for example. +#]] macro(find_python3) if(NOT DEFINED Python3_EXECUTABLE) find_package(Python3 COMPONENTS Interpreter REQUIRED) diff --git a/cmake/utils/get_all_targets.cmake b/cmake/utils/get_all_targets.cmake index 72539a71..58a2403c 100644 --- a/cmake/utils/get_all_targets.cmake +++ b/cmake/utils/get_all_targets.cmake @@ -1,11 +1,26 @@ +#[[[ @module get_all_targets +#]] + include_guard(GLOBAL) +#[[[ +# This function can be use to get all Makefiles targets. +# +# :param OUTVAR: Name of the output variable, a list containing all the Makefiles target. +# :type OUTVAR: list[string] +#]] function(get_all_targets OUTVAR) set(targets) __get_all_targets_recursive(targets ${CMAKE_CURRENT_SOURCE_DIR}) set(${OUTVAR} ${targets} PARENT_SCOPE) endfunction() +# This function, looks recursively in a directory and it subdirectories, to find new target, then it appends them to the target list. +# +# :param targets: List containing all the targets found. +# :type targets: list[string] +# :param dir: Path to a directory +# :type dir: string macro(__get_all_targets_recursive targets dir) get_property(subdirectories DIRECTORY ${dir} PROPERTY SUBDIRECTORIES) foreach(subdir ${subdirectories}) @@ -16,7 +31,12 @@ macro(__get_all_targets_recursive targets dir) list(APPEND ${targets} ${current_targets}) endmacro() - +#[[[ +# This function can be used to get all the IP that are associated with a Makefile target. +# +# :param OUTVAR: Name of the output variable, a list containing all the targeted IPs. +# :type OUTVAR: list[string] +#]] function(get_all_ips OUTVAR) get_all_targets(ALL_TARGETS) diff --git a/cmake/utils/groups.cmake b/cmake/utils/groups.cmake index 2e6b4a8d..3e6e957b 100644 --- a/cmake/utils/groups.cmake +++ b/cmake/utils/groups.cmake @@ -1,3 +1,21 @@ +#[[[ @module groups +#]] + +# This functions can be used to create a a custom group of selected items, with a selected types. It will mainy be called by other function in this file, to create groups. +# +# One of the argument must be used to fill the group, but, it's not possible to use the argument Pattern and List at the same time. +# +# :param GROUP_NAME: Name of the group that needs to be created. +# :type GROUP_NAME: string +# :param TYPE: Type of group, can be TARGET, IP or OPTION. +# :type TYPE: string +# +# **Keyword Arguments** +# +# :keyword PATTERN: if a pattern is given, the item in the group list will be filtered and they must have the pattern to be included +# :type PATTERN: string +# :keyword LIST: if a list is given, the item in the group list are the one given in the list. +# :type LIST: list[string] function(_group_custom_items GROUP_NAME TYPE) cmake_parse_arguments(ARG "" "PATTERN" "LIST" ${ARGN}) @@ -41,18 +59,65 @@ function(_group_custom_items GROUP_NAME TYPE) endforeach() endfunction() +#[[[ +# This function can be used to create a custom group for targets. +# +# :param GROUP_NAME: Name of the group that needs to be created. +# :type GROUP_NAME: string +# +# **Keyword Arguments** +# +# :keyword PATTERN: if a pattern is given, the targets in the group list will be filtered and they must have the pattern to be included +# :type PATTERN: string +# :keyword LIST: if a list is given, the target in the group list are the one given in the list. +# :type LIST: list[string] +#]] function(group_custom_targets GROUP_NAME) _group_custom_items(${GROUP_NAME} TARGET ${ARGN}) endfunction() +#[[[ +# This function can be used to create a custom group for IPs. +# +# :param GROUP_NAME: Name of the group that needs to be created. +# :type GROUP_NAME: string +# +# **Keyword Arguments** +# +# :keyword PATTERN: if a pattern is given, the IPs in the group list will be filtered and they must have the pattern to be included +# :type PATTERN: string +# :keyword LIST: if a list is given, the IPs in the group list are the one given in the list. +# :type LIST: list[string] +#]] function(group_custom_ips GROUP_NAME) _group_custom_items(${GROUP_NAME} IP ${ARGN}) endfunction() +#[[[ +# This function can be used to create a custom group for options. +# +# :param GROUP_NAME: Name of the group that needs to be created. +# :type GROUP_NAME: string +# +# **Keyword Arguments** +# +# :keyword PATTERN: if a pattern is given, the options in the group list will be filtered and they must have the pattern to be included +# :type PATTERN: string +# :keyword LIST: if a list is given, the options in the group list are the one given in the list. +# :type LIST: list[string] +#]] function(group_custom_options GROUP_NAME) _group_custom_items(${GROUP_NAME} OPTION ${ARGN}) endfunction() +#[[[ +# This function can be used to find all the target belonging to a given group. The output list will be stored in the OUTVAR argument. +# +# :param OUTVAR: List containing the targets found. +# :type OUTVAR: list[string] +# :param GROUP_NAME: Name of the group to get the target from. +# :type GROUP_NAME: string +#]] function(get_all_targets_of_group OUTVAR GROUP_NAME) get_all_targets(all_targets) set(filtered_targets) diff --git a/cmake/utils/help/help_utils.cmake b/cmake/utils/help/help_utils.cmake index 7d503d54..8567f7cc 100644 --- a/cmake/utils/help/help_utils.cmake +++ b/cmake/utils/help/help_utils.cmake @@ -1,3 +1,6 @@ +#[[[ @module help +#]] + include_guard(GLOBAL) find_program(JQ_EXECUTABLE jq) @@ -6,6 +9,10 @@ if(NOT JQ_EXECUTABLE) message(WARNING "Could not find \"jq\" executable, help menu's will not be available, please install jq") endif() +# This function is used to convert values coming from cmake to json array to be correctly interpreted by jq. +# +# :param OUTVAR: Variable in which, we store the output +# :type OUTVAR: string function(__cmake_to_json_array OUTVAR) set(values_array "[]") if(ARGN) @@ -19,6 +26,23 @@ function(__cmake_to_json_array OUTVAR) set(${OUTVAR} ${values_array} PARENT_SCOPE) endfunction() +# This function is a generic function to create any type of help message. +# +# It uses ``jq`` to generate a .json file to have a better processing of the data, to display them in the terminal. +# +# :param HELP_NAME: This parameter is used to set the name of the generated target, ``help_${HELP_NAME}``. +# :type HELP_NAME: string +# :param JQ_FILE: .jq file to be given to format the help message to be displayed. +# :type JQ_FILE: string +# :param OUTFILE: file in which the json array generated by jq will be stored. +# :type OUTFILE: string +# :param GROUP_NAME: Name of the group, in case of custom help message, otherwise use ``"*"`` +# :type GROUP_NAME: string +# +# **Keyword Arguments** +# +# :keyword PRINT_ON_CONF: If set, it will print the generated help message in the terminal when doing the cmake configuration/generating the makefiles +# :type PRINT_ON_CONF: bool function(_create_help_target HELP_NAME JQ_FILE OUTFILE GROUP_NAME) cmake_parse_arguments(ARG "PRINT_ON_CONF" "" "" ${ARGN}) if(ARG_UNPARSED_ARGUMENTS) @@ -60,6 +84,16 @@ function(_create_help_target HELP_NAME JQ_FILE OUTFILE GROUP_NAME) endfunction() +#[[[ +# This functions create a target, to display an help message for the available options. +# +# It will show the name, the type, the current and the default value, the description and maybe other information (in case of enumeration or advanced options) for each options. +# +# **Keyword Arguments** +# +# :keyword PRINT_ON_CONF: If set, it will print the generated help message in the terminal when doing the cmake configuration/generating the makefiles +# :type PRINT_ON_CONF: bool +#]] function(help_options) cmake_parse_arguments(ARG "PRINT_ON_CONF" "" "" ${ARGN}) if(ARG_UNPARSED_ARGUMENTS) @@ -114,7 +148,16 @@ function(help_options) endfunction() - +#[[[ +# This functions create a target, to display an help message for the available IPs. +# +# It will show the name and a description for each IPs. +# +# **Keyword Arguments** +# +# :keyword PRINT_ON_CONF: If set, it will print the generated help message in the terminal when doing the cmake configuration/generating the makefiles +# :type PRINT_ON_CONF: bool +#]] function(help_ips) cmake_parse_arguments(ARG "PRINT_ON_CONF" "" "" ${ARGN}) if(ARG_UNPARSED_ARGUMENTS) @@ -160,6 +203,16 @@ function(help_ips) _create_help_target("ips" "ip.jq" ${outfile} "*" ${ARG_PRINT_ON_CONF}) endfunction() +#[[[ +# This functions create a target, to display an help message for the available targets. +# +# It will show the name and a description for each targets. +# +# **Keyword Arguments** +# +# :keyword PRINT_ON_CONF: If set, it will print the generated help message in the terminal when doing the cmake configuration/generating the makefiles +# :type PRINT_ON_CONF: bool +#]] function(help_targets) cmake_parse_arguments(ARG "PRINT_ON_CONF" "" "" ${ARGN}) if(ARG_UNPARSED_ARGUMENTS) @@ -211,7 +264,27 @@ function(help_targets) endfunction() - +#[[[ +# This functions create a target, to display an help message for targets from a specific group, the pattern or a list needs to be given. +# +# :param GROUP_NAME: Name of the group for the help message +# :type GROUP_NAME: string +# +# **Keyword Arguments** +# +# :keyword PRINT_ON_CONF: If set, it will print the generated help message in the terminal when doing the cmake configuration/generating the makefiles +# :type PRINT_ON_CONF: bool +# :keyword DESCRIPTION: if set, it allows to add a custom description, by default it's set to be "Help for ${GROUP_NAME} targets". +# :type DESCRIPTION: string +# :keyword DONT_MAKE_GROUP: if set, a new custom group won't be created +# :type DONT_MAKE_GROUP: bool +# :keyword PATTERN: pattern to be used to filter the custom target group. +# :type PATTERN: string +# :keyword LIST: List to be used to filter the custom target group. +# :type LIST: list[string] +# :keyword HELP_TARGET_NAME: if set, it will change the name of the help target created, by default, the help target is ``help_${GROUP_NAME}`` +# :type HELP_TARGET_NAME: string +#]] function(help_custom_targets GROUP_NAME) cmake_parse_arguments(ARG "DONT_MAKE_GROUP;PRINT_ON_CONF" "PATTERN;DESCRIPTION;HELP_TARGET_NAME" "LIST" ${ARGN}) if(ARG_UNPARSED_ARGUMENTS) @@ -248,6 +321,23 @@ function(help_custom_targets GROUP_NAME) _create_help_target("${help_name}" "target.jq" ${outfile} "${GROUP_NAME}" ${ARG_PRINT_ON_CONF}) endfunction() +#[[[ +# This functions create a target, to display an help message for IPs from a specific group, the pattern or a list needs to be given. +# +# :param GROUP_NAME: Name of the group for the help message +# :type GROUP_NAME: string +# +# **Keyword Arguments** +# +# :keyword PRINT_ON_CONF: If set, it will print the generated help message in the terminal when doing the cmake configuration/generating the makefiles +# :type PRINT_ON_CONF: bool +# :keyword DESCRIPTION: if set, it allows to add a custom description, by default it's set to be "Help for ${GROUP_NAME} targets". +# :type DESCRIPTION: string +# :keyword PATTERN: pattern to be used to filter the custom target group. +# :type PATTERN: string +# :keyword LIST: List to be used to filter the custom target group. +# :type LIST: list[string] +#]] function(help_custom_ips GROUP_NAME) cmake_parse_arguments(ARG "PRINT_ON_CONF" "PATTERN;DESCRIPTION" "LIST" ${ARGN}) if(ARG_UNPARSED_ARGUMENTS) @@ -277,6 +367,23 @@ function(help_custom_ips GROUP_NAME) endfunction() +#[[[ +# # This functions create a target, to display an help message for options from a specific group, the pattern or a list needs to be given. +# +# :param GROUP_NAME: Name of the group for the help message +# :type GROUP_NAME: string +# +# **Keyword Arguments** +# +# :keyword PRINT_ON_CONF: If set, it will print the generated help message in the terminal when doing the cmake configuration/generating the makefiles +# :type PRINT_ON_CONF: bool +# :keyword DESCRIPTION: if set, it allows to add a custom description, by default it's set to be "Help for ${GROUP_NAME} targets". +# :type DESCRIPTION: string +# :keyword PATTERN: pattern to be used to filter the custom target group. +# :type PATTERN: string +# :keyword LIST: List to be used to filter the custom target group. +# :type LIST: list[string] +#]] function(help_custom_options GROUP_NAME) cmake_parse_arguments(ARG "PRINT_ON_CONF" "PATTERN;DESCRIPTION" "LIST" ${ARGN}) if(ARG_UNPARSED_ARGUMENTS) @@ -306,7 +413,14 @@ function(help_custom_options GROUP_NAME) endfunction() - +#[[[ +# This function act as a wrapper, it create an ``help_all`` target that will display an help message for targets, IPs and options. +# +# **Keyword Arguments** +# +# :keyword PRINT_ON_CONF: If set, it will print the generated help message in the terminal when doing the cmake configuration/generating the makefiles +# :type PRINT_ON_CONF: bool +#]] function(help) cmake_parse_arguments(ARG "PRINT_ON_CONF" "" "" ${ARGN}) if(ARG_UNPARSED_ARGUMENTS) diff --git a/cmake/utils/option.cmake b/cmake/utils/option.cmake index e71c7457..c9a720a6 100644 --- a/cmake/utils/option.cmake +++ b/cmake/utils/option.cmake @@ -1,3 +1,20 @@ +#[[[ @module option +#]] + +# This function is used to easierly create new option, and is used in the new options function. +# +# :param NAME: name of the variable. +# :type NAME: string +# :param TYPE: type of the variable +# :type TYPE: string +# :param DESCRIPTION: short description string for the variable +# :type DESCRIPTION: string +# :param DEFAULT: default value of the variable +# :type DEFAULT: integer +# :param ADVANCED: optional, mark options as advanced, it will not show in help menu +# :type ADVANCED: boolean +# :param POSSIBLE_VALUES: possible values variable can have +# :type POSSIBLE_VALUES: list[string] function(__define_socmake_option NAME TYPE DESCRIPTION DEFAULT ADVANCED) cmake_parse_arguments(ARG "" "" "POSSIBLE_VALUES" ${ARGN}) if(ARG_UNPARSED_ARGUMENTS) @@ -31,7 +48,7 @@ endfunction() # :param DEFAULT: default value of the variable # :type DEFAULT: integer # :param ADVANCED: optional, mark options as advanced, it will not show in help menu -# :type DEFAULT: boolean +# :type ADVANCED: boolean #]] function(option_enum VARIABLE DESCRIPTION ENUM_VALUES DEFAULT) cmake_parse_arguments(ARG "ADVANCED" "" "" ${ARGN}) @@ -64,7 +81,7 @@ endfunction() # :param DEFAULT: default value of the variable # :type DEFAULT: string # :param ADVANCED: optional, mark options as advanced, it will not show in help menu -# :type DEFAULT: string +# :type ADVANCED: string #]] function(option_string VARIABLE DESCRIPTION DEFAULT) cmake_parse_arguments(ARG "ADVANCED" "" "" ${ARGN}) @@ -88,9 +105,9 @@ endfunction() # :param DEFAULT: default value of the variable # :type DEFAULT: string # :param ADVANCED: optional, mark options as advanced, it will not show in help menu -# :type DEFAULT: string +# :type ADVANCED: string # :param CHECK_EXISTS: optional, check if the file path exists at the time of configuring the project, default FALSE -# :type DEFAULT: boolean +# :type CHECK_EXISTS: boolean #]] function(option_file VARIABLE DESCRIPTION DEFAULT) cmake_parse_arguments(ARG "ADVANCED;CHECK_EXISTS" "" "" ${ARGN}) @@ -120,9 +137,9 @@ endfunction() # :param DEFAULT: default value of the variable # :type DEFAULT: string # :param ADVANCED: optional, mark options as advanced, it will not show in help menu -# :type DEFAULT: string +# :type ADVANCED: string # :param CHECK_EXISTS: optional, check if the directory path exists at the time of configuring the project, default FALSE -# :type DEFAULT: boolean +# :type CHECK_EXISTS: boolean #]] function(option_directory VARIABLE DESCRIPTION DEFAULT) cmake_parse_arguments(ARG "ADVANCED;CHECK_EXISTS" "" "" ${ARGN}) @@ -152,7 +169,7 @@ endfunction() # :param DEFAULT: default value of the variable # :type DEFAULT: integer # :param ADVANCED: optional, mark options as advanced, it will not show in help menu -# :type DEFAULT: boolean +# :type ADVANCED: boolean #]] function(option_integer VARIABLE DESCRIPTION DEFAULT) cmake_parse_arguments(ARG "ADVANCED" "" "" ${ARGN}) @@ -179,7 +196,7 @@ endfunction() # :param DEFAULT: default value of the variable # :type DEFAULT: boolean # :param ADVANCED: optional, mark options as advanced, it will not show in help menu -# :type DEFAULT: boolean +# :type ADVANCED: boolean #]] function(option_boolean VARIABLE DESCRIPTION DEFAULT) cmake_parse_arguments(ARG "ADVANCED" "" "" ${ARGN}) diff --git a/cmake/utils/print_list.cmake b/cmake/utils/print_list.cmake index 35a8794c..c02ee6ac 100644 --- a/cmake/utils/print_list.cmake +++ b/cmake/utils/print_list.cmake @@ -1,5 +1,14 @@ +#[[[ @module print_list +#]] + include_guard(GLOBAL) +#[[[ +# Macro to print all the item in a given list. +# +# :param LIST: list that need to be printed. +# :type LIST: list[string] +#]] macro(print_list LIST) foreach(item ${LIST}) message(${item}) diff --git a/cmake/utils/sed_wor/sed_wor.cmake b/cmake/utils/sed_wor/sed_wor.cmake index fd4e10b5..1e4f905c 100644 --- a/cmake/utils/sed_wor/sed_wor.cmake +++ b/cmake/utils/sed_wor/sed_wor.cmake @@ -1,6 +1,20 @@ -# sed_wor.cmake -# String replace "wor" with "wire" in all Verilog files files. -# This is a workaround for a Verilator not supporting "wor" and similar keywords... +#[[[ @module sed_wor +#]] + +#[[[ +# This function replace "wor" with "wire" in all Verilog/SystemVerilog files given. +# +# This is a workaround for some Verilator versions not supporting "wor" keywords. +# +# All the **IP_LIB** source files ending with .v or .sv are processed using a simple `sed` command to replace wor with wire. The output file list is stored in ``SED_WOR_SOURCES`` and propagated to the parent scope. +# +# :param IP_LIB: The target IP library. +# :type IP_LIB: string +# :param BINARY_DIR: Path were this function will generate the outputs file, in ${BINARY_DIR}/sed_wor. +# :type BINARY_DIR: string +# :param SOURCES: list of the sources, any file can be given, only the .v/.sv files will be copied and modified. +# :type SOURCES: list +#]] function(sed_wor IP_LIB BINARY_DIR SOURCES) file(MAKE_DIRECTORY ${BINARY_DIR}/sed_wor) set(MODIFIED_SOURCES "") diff --git a/cmake/utils/socmake_graph.cmake b/cmake/utils/socmake_graph.cmake index 5be72de3..49a43278 100644 --- a/cmake/utils/socmake_graph.cmake +++ b/cmake/utils/socmake_graph.cmake @@ -1,9 +1,14 @@ -include_guard(GLOBAL) +#[[[ @module socmake_graph +#]] -# ========================================================== # -# ======== Internal graph flattening functions ============= # -# ========================================================== # +include_guard(GLOBAL) +#[[[ +# this function is the internal graph flattening functions +# +# :param NODE: node to be flattened +# :type NODE: node +#]] function(flatten_graph NODE) alias_dereference(NODE ${NODE}) @@ -29,9 +34,14 @@ function(flatten_graph NODE) set_property(TARGET ${NODE} PROPERTY FLAT_GRAPH ${STACK}) endfunction() -# ------------------------------------------------------------------ # -# Recursive DFS topological sort -# ------------------------------------------------------------------ # +# This function is a recursive DFS topological sort +# +# Will return 0 if the node doesn't have the TARGET keyword set or if it has already been processed, otherwise, it will return 1 after processing it. +# +# :param NODE: node to be processed +# :type NODE: node +# :param RET: value returned by this function +# :type RET: integer function(__dfs_topo NODE RET) alias_dereference(NODE ${NODE}) @@ -85,9 +95,16 @@ function(__dfs_topo NODE RET) set(${RET} 1 PARENT_SCOPE) endfunction() -# ------------------------------------------------------------------ # -# Utility: compare lists (unchanged) -# ------------------------------------------------------------------ # +#[[[ +# Function to compare 2 list, will return 1 if they are equal, otherwise, will return -1. +# +# :param L1: 1st list +# :type L1: list +# :param L2: 2nd list +# :type L2: list +# :param RET: returned value for the comparison +# :type RET: integer +#]] function(compare_lists L1 L2 RET) set(_l1 ${L1}) set(_l2 ${L2}) diff --git a/cmake/utils/subdirectory_search.cmake b/cmake/utils/subdirectory_search.cmake index 62272511..1dd2f91e 100644 --- a/cmake/utils/subdirectory_search.cmake +++ b/cmake/utils/subdirectory_search.cmake @@ -1,7 +1,17 @@ +#[[[ @module subdirectory_search +#]] + include_guard(GLOBAL) # https://stackoverflow.com/questions/7787823/cmake-how-to-get-the-name-of-all-subdirectories-of-a-directory - +#[[[ +# This macro is used to get the name of all the subdirectories of a directory, inspired by `this `_ +# +# :param output_var: list that need to be printed. +# :type output_var: list[string] +# :param dir: Path to the directory +# :type dir: string +#]] macro(SUBDIRLIST output_var dir) file(GLOB children RELATIVE ${dir} ${dir}/*) set(dirlist "") @@ -13,6 +23,16 @@ macro(SUBDIRLIST output_var dir) set(${output_var} ${dirlist}) endmacro() +#[[[ +# This macro can be used to create a filtered list, by selecting patterns to exclude some subdirectories. +# +# :param output_var: list that need to be printed. +# :type output_var: list[string] +# :param dir: Path to the directory +# :type dir: string +# :param dir: Patterns to exclude subdirectories +# :type dir: list[string] +#]] macro(SUBDIRLIST_EXCLUDE output_var dir excluded_patterns) # Get all subdirectories SUBDIRLIST(SUBDIRS ${dir}) diff --git a/cmake/utils/uniquify_files_by_basename.cmake b/cmake/utils/uniquify_files_by_basename.cmake index ad5a9483..9a016759 100644 --- a/cmake/utils/uniquify_files_by_basename.cmake +++ b/cmake/utils/uniquify_files_by_basename.cmake @@ -1,3 +1,6 @@ +#[[[ @module uniquify_files_by_basename +#]] + #[[[ # This function uniquify a list of files based on the basename (name + extension) of the files. # diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt index a685ad86..40974537 100644 --- a/docs/CMakeLists.txt +++ b/docs/CMakeLists.txt @@ -17,9 +17,23 @@ find_python3() set(DOC_INPUT_DIR "${PROJECT_SOURCE_DIR}/../cmake/") set(DOC_OUTPUT_DIR "${PROJECT_BINARY_DIR}/api_source") set(HTML_SPHINX_OUTPUT_DIR "${PROJECT_BINARY_DIR}/api_html") +# List of file or directory to be excluded from the recursive search. +# By forcing recursive search in our cminx config file, we are able to search into the full cmake/ +# to find all the .cmake, but we don't want to have some .cmake file that doesn't have functions +# or repository without .cmake file having an .rst generated. +# Using the config file with the include_undocumented_XXXX parameter does not solve this problem. +# So if a new file is not available in the api doc, it might be excluded with this list. +set(EXCLUDE_FROM_RST + -e "*Config.cmake" + -e "*firmware" + -e "*flows" + -e "*FindYosys.cmake" + -e "*graphviz*" + -e "*sim_utils.cmake" +) # Cminx is used to convert SoCMake function comments into rST format later transformed to a # static html documentation using sphinx -set(VENV_CMD $ENV{VIRTUAL_ENV}/bin/cminx -o ${DOC_OUTPUT_DIR} -r ${DOC_INPUT_DIR}) +set(VENV_CMD $ENV{VIRTUAL_ENV}/bin/cminx -o ${DOC_OUTPUT_DIR} -s ${PROJECT_SOURCE_DIR}/api/api_config.yaml ${EXCLUDE_FROM_RST} -r ${DOC_INPUT_DIR}) # This command trigger the rST to html conversion and copy into the docusaurus static folder for # integration with the latter set(DOC_API_MAKE_CMD make -C ${PROJECT_BINARY_DIR}/api_source/ html) diff --git a/docs/api/api_config.yaml b/docs/api/api_config.yaml new file mode 100644 index 00000000..0ddb0c53 --- /dev/null +++ b/docs/api/api_config.yaml @@ -0,0 +1,167 @@ +input: + # Whether undocumented functions should have documentation + # auto-generated. + include_undocumented_function: false + + # Whether undocumented macros should have documentation + # auto-generated. + include_undocumented_macro: false + + # Whether undocumented classes should have documentation + # auto-generated. + include_undocumented_cpp_class: false + + # Whether undocumented attributes within CMakePP classes should have documentation + # auto-generated. + include_undocumented_cpp_attr: false + + # Whether undocumented members within CMakePP classes should have documentation + # auto-generated. + include_undocumented_cpp_member: false + + # Whether undocumented constructors within CMakePP classes should have documentation + # auto-generated. + include_undocumented_cpp_constructor: false + + # Whether undocumented tests should have documentation + # auto-generated. + include_undocumented_ct_add_test: false + + # Whether undocumented test sections should have documentation + # auto-generated. + include_undocumented_ct_add_section: false + + # Whether undocumented options should have documentation + # auto-generated. + include_undocumented_option: false + + # Whether undocumented CTest tests should have documentation + # auto-generated. This controls whether all vanilla + # CMake add_test() commands should be documented, + # it has no relation to CMakeTest tests. + include_undocumented_add_test: false + + # Whether directories not containing .cmake + # files should be excluded from recursive mode searching. + auto_exclude_directories_without_cmake: false + + # What string should trigger automatic kwargs documentation + # generation when encountered in a doccomment for a function() + # or macro() definition. When this string is encountered + # the defined command parameter list will be modified to include + # "**kwargs" as the last parameter. This will also occur + # if a call to "cmake_parse_arguments()" exists within the + # body of the function or macro. + kwargs_doc_trigger_string: ":keyword" + + # Strips out any string matching this regex + # for parameter names. This is useful for when + # parameter names have a prefix/postfix to prevent + # name collisions. This affects function definitions. + # + # An example regex that strips the prefix "_abc_" + # from parameter names where "abc" is any combination of letters + # is below: + # function_parameter_name_strip_regex: "^_[a-zA-Z]*_" + function_parameter_name_strip_regex: "" + + # Strips out any string matching this regex + # for parameter names. This is useful for when + # parameter names have a prefix/postfix to prevent + # name collisions. This affects macro definitions + macro_parameter_name_strip_regex: "" + + # Strips out any string matching this regex + # for parameter names. This is useful for when + # parameter names have a prefix/postfix to prevent + # name collisions. This affects CMakePP + # class member definitions. + member_parameter_name_strip_regex: "" + + # Whether directories should be documented recursively + recursive: false + + # Whether CMinx should follow symlinks that resolve to directories + # when using recursive mode. + # This can cause infinite recursion if the symlink resolves + # to a parent directory of itself + follow_symlinks: false + + # Optional list of exclude filters + # The full list of filters is combined from all sources, + # and not overridden. + #exclude_filters: + # - __pycache__ + +output: + # The directory to write generated RST files to. If not set, + # will output to STDOUT instead. + # Relative paths will be resolved with regard to the relative_to_config setting + # directory: build/ + + # If false, relative output paths are resolved with regard to the current working directory. + # If true, they are instead resolved with regard to the directory where the highest priority + # output.directory property is specified. If the highest priority config source does not have + # a file, the current working directory is instead used. + relative_to_config: false + +logging: + # Supports all Python logging dict config options + # See https://docs.python.org/3/howto/logging.html#configuring-logging + version: 1 + formatters: + simple: + format: '%(asctime)s - %(name)s - %(levelname)s - %(message)s' + handlers: + console: + class: logging.StreamHandler + # Changing this level changes what's viewable on stdout + level: INFO + formatter: simple + stream: ext://sys.stdout + #Uncomment to add logfile handler +# logfile: +# class: logging.FileHandler +# # Changing this level changes what's viewable in the log file +# level: DEBUG +# formatter: simple +# # File to output the log to, relative paths are resolved with regard +# # to current working directory upon execution +# filename: log.txt +# # Mode used to write the log file. 'a' appends and 'w' writes, erasing original content +# mode: 'w' + loggers: + cminx: + # Changing this overrides log levels in handlers + level: DEBUG + handlers: + - console + #- logfile # Uncomment to add logging to a file called log.txt + propagate: no + root: + level: DEBUG + handlers: + - console + +rst: + # Whether the title of the RST file should contain the CMake file's + # extension. + file_extensions_in_titles: false + + # Whether the module directive should contain the CMake file's + # extension. + file_extensions_in_modules: false + + # Character to use as a separator between CMake directories and modules + module_path_separator: '.' + + # A list of characters to be used for RST headers. + # The character is selected by using the section depth to index + # into this list. It is recommended to have at least 4 characters + # in the list, to support at least 4 sections of nesting. + headers: ['#', '*', '=', '-', '_', '~', '!', '&', '@', '^'] + + # A prefix to use for RST headers and modules + # If not set, the path to the file relative to the input path will be used instead + # prefix: Prefix + \ No newline at end of file diff --git a/docs/docs/api_documentation.mdx b/docs/docs/api_documentation.mdx index f2eb619d..7e77f659 100644 --- a/docs/docs/api_documentation.mdx +++ b/docs/docs/api_documentation.mdx @@ -4,4 +4,4 @@ sidebar_position: 2 # API documentation -SoCMake API [documentation](pathname:///api_html/index.html). +SoCMake [API documentation](pathname:///api_html/index.html) (click on the hyperlink). diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js index 1466510f..a444ce0c 100644 --- a/docs/docusaurus.config.js +++ b/docs/docusaurus.config.js @@ -72,8 +72,13 @@ const config = { label: 'Documentation', }, { - href: 'https://hep-soc.github.io/SoCMake/', - label: 'GitLab', + label: 'API Documentation', + to: 'https://hep-soc.github.io/SoCMake/api_html/index.html', + position: 'left', + }, + { + href: 'https://github.com/HEP-SoC/SoCMake', + label: 'Github', position: 'right', }, ], @@ -88,22 +93,9 @@ const config = { label: 'Documentation', to: '/docs/intro', }, - ], - }, - { - title: 'Community', - items: [ - { - label: 'Stack Overflow', - href: 'https://stackoverflow.com/questions/tagged/docusaurus', - }, - { - label: 'Discord', - href: 'https://discordapp.com/invite/docusaurus', - }, { - label: 'Twitter', - href: 'https://twitter.com/docusaurus', + label: 'API Documentation', + to: 'https://hep-soc.github.io/SoCMake/api_html/index.html', }, ], }, @@ -112,7 +104,7 @@ const config = { items: [ { label: 'GitHub', - href: 'https://github.com/facebook/docusaurus', + href: 'https://github.com/HEP-SoC/SoCMake', }, ], }, diff --git a/docs/src/components/HomepageFeatures/index.js b/docs/src/components/HomepageFeatures/index.js index 0ad64bde..a052a742 100644 --- a/docs/src/components/HomepageFeatures/index.js +++ b/docs/src/components/HomepageFeatures/index.js @@ -26,7 +26,7 @@ const FeatureList = [ function Feature({Svg, title, description}) { return ( -
+