CAPI2

Core API Version 2

Pattern Properties

  • ^name$ (string): VLNV identifier for core.

  • ^description$ (string): Short description of core.

  • ^provider$ (object): Provider of core.

    • Any of

      • object: github Provider. Cannot contain additional properties.

        • name (string, required)

        • user (string, required)

        • repo (string, required)

        • version (string, required)

        • patches (array)

          • Items (string)

        • cachable (boolean)

      • object: local Provider. Cannot contain additional properties.

        • name (string, required)

        • patches (array)

          • Items (string)

        • cachable (boolean)

      • object: git Provider. Cannot contain additional properties.

        • name (string, required)

        • repo (string, required)

        • version (string)

        • patches (array)

          • Items (string)

        • cachable (boolean)

      • object: opencores Provider. Cannot contain additional properties.

        • name (string, required)

        • repo_name (string, required)

        • repo_root (string, required)

        • revision (string, required)

        • patches (array)

          • Items (string)

        • cachable (boolean)

      • object: url Provider. Cannot contain additional properties.

        • name (string, required)

        • url (string, required)

        • user-agent (string)

        • verify_cert (string)

        • filetype (string, required)

        • patches (array)

          • Items (string)

        • cachable (boolean)

  • ^filesets$ (object): A fileset represents a group of files with a common purpose. Each file in the fileset is required to have a file type and is allowed to have a logical_name which can be set for the whole fileset or individually for each file. A fileset can also have dependencies on other cores, specified in the depend section. Cannot contain additional properties.

    • ^.+$ (object): Name of fileset. Cannot contain additional properties.

      • ^file_type$ (string): Default file_type for files in fileset.

      • ^logical_name$ (string): Default logical_name (i.e. library) for files in fileset.

      • ^tags$ (array): Default tags for files in fileset.

        • Items (string)

      • ^files(_append)?$ (array): Files in fileset.

        • Items

          • One of

            • string

            • object: Cannot contain additional properties.

              • ^.+$ (object): Path to file. Cannot contain additional properties.

                • is_include_file (boolean): Treats file as an include file when true.

                • include_path (string): Explicitly set an include directory, relative to core root, instead of the directory containing the file.

                • file_type (string): File type. Overrides the file_type set on the containing fileset.

                • logical_name (string): Logical name, i.e. library for VHDL/SystemVerilog. Overrides the logical_name set on the containing fileset.

                • tags (array): Tags, special file-specific hints for the backends. Appends the tags set on the containing fileset.

                  • Items (string)

                • copyto (string): Copy the source file to this path in the work directory.

      • ^depend(_append)?$ (array): Dependencies of fileset.

        • Items (string)

  • ^generate$ (object): The elements in this section each describe a parameterized instance of a generator. They specify which generator to invoke and any generator-specific parameters.

    • ^.+$: Name of generator to use. Cannot contain additional properties.

      • generator (string, required): The generator to use. Note that the generator must be present in the dependencies of the core.

      • position (string): Where to insert the generated core. Legal values are first, prepend, append or last. prepend (append) will insert core before (after) the core that called the generator.

      • parameters (object): Generator-specific parameters. fusesoc gen show $generator might show available parameters. .

  • ^generators$ (object): Generators are custom programs that generate FuseSoC cores. They are generally used during the build process, but can be used stand-alone too. This section allows a core to register a generator that can be used by other cores.

    • ^.+$: Name of generator. Cannot contain additional properties.

      • command (string, required): The command to run (relative to the core root).

      • interpreter (string): If the command needs a custom interpreter (such as python) this will be inserted as the first argument before command when calling the generator. The interpreter needs to be on the system PATH; specifically, shutil.which needs to be able to find the interpreter).

      • cache_type (string): If the result of the generator should be considered cacheable. Legal values are none, input or generator.

      • file_input_parameters (string): All parameters that are file inputs to the generator. This option can be used when cache_type is set to input if fusesoc should track if these files change.

      • description (string): Short description of the generator, as shown with fusesoc gen list.

      • usage (string): A longer description of how to use the generator, including which parameters it uses (as shown with fusesoc gen show $generator).

  • ^scripts$ (object): A script specifies how to run an external command that is called by the hooks section together with the actual files needed to run the script. Scripts are alway executed from the work root.

    • ^.+$: Cannot contain additional properties.

      • ^cmd(_append)?$ (array): List of command-line arguments.

        • Items (string)

      • ^filesets(_append)?$ (array): Filesets needed to run the script.

        • Items (string)

      • ^env$ (object): Map of environment variables to set before launching the script.

        • ^.+$ (string)

  • ^targets$ (object): A target is the entry point to a core. It describes a single use-case and what resources that are needed from the core such as file sets, generators, parameters and specific tool options. A core can have multiple targets, e.g. for simulation, synthesis or when used as a dependency for another core. When a core is used, only a single target is active. The default target is a special target that is always used when the core is being used as a dependency for another core or when no --target= flag is set.

    • ^.+$: Cannot contain additional properties.

      • ^default_tool$ (string): Default tool to use unless overridden with --tool=.

      • ^description$ (string): Description of the target.

      • ^flow$ (string): Edalize backend flow to use for target.

      • ^flow_options$ (object): Tool- and flow-specific options.

        • ^.+$

          • Any of

            • string

            • number

            • boolean

            • array

            • object

      • ^hooks$ (object): Script hooks to run when target is used. Cannot contain additional properties.

        • ^pre_build(_append)?$ (array): Scripts executed before the build phase.

          • Items (string)

        • ^post_build(_append)?$ (array): Scripts executed after the build phase.

          • Items (string)

        • ^pre_run(_append)?$ (array): Scrips executed before the run phase.

          • Items (string)

        • ^post_run(_append)?$ (array): Scripts executed after the run phase.

          • Items (string)

      • ^tools$ (object): Tool-specific options for target.

        • ^.+$ (object)

          • ^.+$

            • Any of

              • string

              • number

              • boolean

              • array

              • object

      • ^toplevel$: Top-level module. Normally a single module/entity but can be a list of several items.

        • Any of

          • string

          • array

            • Items (string)

      • ^filesets(_append)?$ (array): File sets to use in target.

        • Items (string)

      • ^generate(_append)?$ (array): Parameterized generators to run for this target with optional parametrization.

        • Items

          • Any of

            • string

            • object

      • ^parameters(_append)?$ (array): Parameters to use in target. The parameter default value can be set here with param=value.

        • Items (string)

      • ^vpi(_append)?$ (array): VPI modules to build and include for target.

        • Items (string)

      • flags (object): Default values of flags.

        • ^.+$

          • Any of

            • string

            • number

            • boolean

            • array

            • object

  • ^parameters$ (object): Available parameters.

    • ^.+$: Cannot contain additional properties.

      • datatype (string, required): Parameter datatype. Legal values are bool, file, int, str. file is same as str, but prefixed with the current directory that FuseSoC runs from.

      • default: Default value.

        • One of

          • boolean

          • string

          • number

      • description (string): Description of the parameter, as can be seen with fusesoc run --target=$target $core --help.

      • paramtype (string, required): Specifies type of parameter. Legal values are cmdlinearg for command-line arguments directly added when running the core, generic for VHDL generics, plusarg for verilog plusargs, vlogdefine for Verilog `define or vlogparam for verilog top-level parameters. All paramtypes are not valid for every backend. Consult the backend documentation for details.

      • scope (string): Not used : Kept for backwards compatibility.

  • ^vpi$ (object): A VPI (Verilog Procedural Interface) library is a shared object that is built and loaded by a simulator to provide extra Verilog system calls. This section describes what files and external libraries to use for building a VPI library.

    • ^.+$

      • ^filesets(_append)?$ (array): Filesets containing files to use when compiling the VPI library.

        • Items (string)

      • ^libs(_append)?$ (array): External libraries to link against.

        • Items (string)

  • ^virtual(_append)?$ (array): VLNV of a virtual core provided by this core. Versions are currently not supported, only the VLN part is used.

    • Items (string)