HEP-SoC · mtravaillard · Mar 31, 2026 · Feb 17, 2026 · Feb 17, 2026 · Feb 18, 2026
diff --git a/README.md b/README.md
@@ -2,7 +2,8 @@
 <img src="docs/static/img/SoCMakeLogo3.png" alt="SoCMake" width="40%">
 
   <a href="https://hep-soc.github.io/SoCMake/">Documentation</a> |
-  <a href="https://github.com/HEP-SoC/SoCMake/tree/develop/examples">Examples</a>
+  <a href="https://github.com/HEP-SoC/SoCMake/tree/develop/examples">Examples</a> |
+  <a href="https://hep-soc.github.io/SoCMake/api_html/index.html">API documentation</a>
 </h1>
 
 

diff --git 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 → .../build_scripts/riscv/sail/install_sail.sh b/cmake/riscv/sail/install_sail.sh → .../build_scripts/riscv/sail/install_sail.sh
diff --git a/cmake/riscv/sail/requirements.txt → ...build_scripts/riscv/sail/requirements.txt b/cmake/riscv/sail/requirements.txt → ...build_scripts/riscv/sail/requirements.txt
diff --git a/cmake/riscv/sail/sail_install.cmake → ...ild_scripts/riscv/sail/sail_install.cmake b/cmake/riscv/sail/sail_install.cmake → ...ild_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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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(<ip_lib> 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
@@ -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)