Config

Description of this Merge Request

This merge request addresses the current ambiguity in project configuration by centralizing module configuration within the FWK environment. It introduces modules to create a synthesizable VHDL code by exporting the Config namespace variable.

Introduction

Imagine a Module-A is instantiating Module-B inside a FWK project.

In the IP integration environment, you need to make sure Module-A will dictate the default settings of Module-B. You can later have Module-C dictating how Module-A and Module-B should work when it encapsulates Module-A.

You need a software environment to resolve these configuration dependencies. In our FWK world, this software environment is module namespace (::fwfwk::src:<module_c>, ::fwfwk::src:<module_c>::<module_a>, ::fwfwk::src:<module_c>::<module_a>::<module_b) Pay attention how namespaces are constructed with a proper hierarchy.

The problem statement

Defining configuration per IP/Module is currently not centralized leading to ambiguity in project configuration.

Explanation

There are currently 2 ways to configure a Module that is inside the FWK environment:

1. Users can directly append information into the Config variable (::fwfwk::src::<module_a>::Config) in their respective namespace using main.tcl of the module (at the init stage). This information can be used inside the DesyRDL environment,can effect how Sources are set, how documents created etc. However when you use this method, The config variables cannot change how HDL logic is configured. This is precisely what is missing right now.

2. Using FWK utility functions, a module can give a VHDL package, and export VHDL constants as namespace variables (::fwfwk::src::<module_a>::Config) This method can change how HDL logic is configured.

Solution

The configuration of a Module should come from a single parameter space and everything else (DesyRDL register configuration, HDL configuration, tcl configuration etc.) should be done using this single parameter space (which is ::fwfwk::src::<module>::Config)

From this point onwards, a module should just rely on Config parameter to configure their HDL side and not hand-write a HDL package (DesyRDL already relies on the Config parameter)

Implementation

Config variable concept is already there in FWK however what is missing is the generate a HDL file that programmable logic can use.

1. After the INIT stage is completed, the entire Config parameter space is resolved (ie: Module-C now overwritten default values of Module-A and Module-B)

2. ::fwfwk::genHdlFromConfig procedure gets called at the beginning of Create Project stage. This procedure fetches all Config parameters of each child namespace of ::fwfwk::src

3. Procedure checks if the Module wants to have this HDL file being generated by querying the existence of addConfigAsHdl variable on the module's namespace.

4. If module has such a variable in their namespace, script will then:

4a. convert Config variables to a JSON string.

4b. Call Jinja2 Template engine with a pre-written VHDL template.

4c. Add the path of the rendered template into the child's Sources variable (::fwfwk::src::<module_a>::Sources)

Results

How does the HDL configuration package looks like?

Imagine Module-A uses the following Config variable

proc init {} {
  variable Config

  # Declaring to FWK that Config variables should be rendered 
  # as VHDL package and added to the project
  variable addConfigAsHdl 1

  set Config(parameter_a) 10
  set Config(parameter_b) 0
  set Config(parameter_c) (0, 2, 5, 9)
  set Config(parameter_d) "Apple"
}

After users create the tool project, the following VHDL package gets automatically added to the project:

pkg_module_a_config.hdl

------------------------------------------------------------------------------
--          ____  _____________  __                                         --
--         / __ \/ ____/ ___/\ \/ /                 _   _   _               --
--        / / / / __/  \__ \  \  /                 / \ / \ / \              --
--       / /_/ / /___ ___/ /  / /               = ( M | S | K )=            --
--      /_____/_____//____/  /_/                   \_/ \_/ \_/              --
--                                                                          --
------------------------------------------------------------------------------
-- @copyright Copyright 2018-2024 DESY
-- SPDX-License-Identifier: CERN-OHL-W-2.0
------------------------------------------------------------------------------
-- @author FWK (Generated)
------------------------------------------------------------------------------
-- @brief This VHDL package is generated automatically by FWK using Jinja2 Template Engine
-- Each Module that gets added to the FWK project can have a "Config" variable
-- inside its namespace (eg. ::fwfwk::src:daq)
-- FWK takes the Config variable from this namespace and exports it to a HDL file
-- such that FPGA logic can use these Configuration

-- This file is automatically generated on:
-- @date 2024-09-18
-- @timestamp 14:27:02 CEST
------------------------------------------------------------------------------

library ieee;
use ieee.std_logic_1164.all;
use ieee.numeric_std.all;

package pkg_module_a_config is

  type t_natural_vector_cfg is array (natural range <>) of natural;

  constant C_VERSION : natural := 16#02010001#;

  constant C_PRJ_TIMESTAMP : natural := 1726662421;

  constant C_PRJ_SHASUM : natural := 16#2abe78b6#;

  constant C_TIMESTAMP : natural := 1726662421;

  constant C_PRJ_VERSION : natural := 16#02040001#;

  constant parameter_a : natural := 10;

  constant parameter_b : natural := 0;

  constant parameter_c : t_natural_vector_cfg(4-1 downto 0) := (0, 2, 5, 9);

  constant parameter_d : string := "Apple";

end package pkg_module_a_config;

The generated files are located inside prj/<tool_project>/<tool_project>.hdl_config/

Please pay attention how 2D natural vector type is self-defined inside the pkg_module_config.vhd and how it doesn't require desy_vhdl library.

Impact on an older project

This feature is fully backward compatible with the module which is not actively using the Config variable. Since the auto-generated files get only triggered when the user wants (adding the addConfigAsHdl variable), prevents any surprises when users Bump FWK to a higher version.

Changelog:

• Added the ability to convert Config parameters as VHDL packages
• Improved tutorial to cover the Config parameter explanation
• added new print proc ::fwfwk::printDebug (Purple color)
• added ::fwfwk::format_json proc to print JSON data in a prettier way