###########################################
cmake.peakrdl/peakrdl_socgen/peakrdl_socgen
###########################################

.. module:: cmake.peakrdl/peakrdl_socgen/peakrdl_socgen


.. function:: peakrdl_socgen(IP_LIB **kwargs)

   Create a target for invoking PeakRDL-socgen on IP_LIB.
   
   PeakRDL-socgen generates top verilog file that connects the IP blocks.
   
   PeakRDL-socgen can be found on this `link <https://gitlab.cern.ch/socmake/PeakRDL-socgen>`_
   
   Function expects that **IP_LIB** *INTERFACE_LIBRARY* has **SYSTEMRDL_SOURCES** property set with a list of
   SystemRDL files to be used as inputs. To set the SYSTEMRDL_SOURCES property use the ip_sources()
   function from SoCMake (internally using `set_property()
   <https://cmake.org/cmake/help/latest/command/set_property.html>`_ CMake function):
   
   .. code-block:: cmake
   
      ip_sources(IP_LIB LANGUAGE [SYSTEMRDL|SYSTEMVERILOG|...] ${PROJECT_SOURCE_DIR}/file.rdl)
   
   Additionally it is possible to inject custom Verilog code inside the generated verilog code.
   In order to inject files its necessary to do 2 things:
   * Name of the file needs to be <name-of-the-subsystem_<whatever>.v/sv for
   example apb_subsystem_plic_irq.v
   * Set the SOCGEN_INJECT_V_FILES property of IP_LIB like shown below, it is
   possible to provide multiple files. Another option is to pass the parameter INJECT_V_FILES
   as parameter to the function.
   
   .. code-block:: cmake
   
      set_property(TARGET <your-lib> PROPERTY SOCGEN_INJECT_V_FILES
                   ${PROJECT_SOURCE_DIR}/apb_subsystem_plic_irq.v)
   
   
   This function will append verilog files generated to the **SOURCES** property of the **IP_LIB**.
   
   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
   
   **Keyword Arguments**
   
   :keyword USE_INCLUDE: use verilog include preprocessor directive instead of embedding injected
   code directly into generated verilog. By default embedding is used.
   :type USE_INCLUDE: option
   :keyword GEN_DOT: enable generation of graphviz dot file along with verilog files
   :type GEN_DOT: option
   :keyword OUTDIR: output directory in which the files will be generated, if ommited
   ${BINARY_DIR}/socgen will be used.
   :type OUTDIR: string path
   :keyword INJECT_V_FILES: list of Verilog or SV files to be injected into the subsystems.
   :type INJECT_V_FILES: List[string path]