Requirements

Requirements for the GreenBus Configuration Framework

Definitions

Before we start, we need some definitions:

Tool

We can consider two types of tools:
  • Internal tools, i.e. a configuration/debug library linked to the model
  • External tools may assist in verification of the model by providing increased visibility and control during simulation, and assisting the user in configuring the model in various ways before and during simulation.

Configurable Parameter

By the term configurable parameter we denote sc_module members that can be accessed (get/set value) by means of a config API.

Config API

A config API is an interface to a configuration framework with the goal, that
  • the user can create and access (get/set) parameters
      • during construction/elaboration
      • at simulation runtime

Additional features may include

  • tracking of parameter value changes (e.g., using event notification or callbacks)
  • initalize parameters from a configuration file
  • search for parameters in the model
  • get a list of all parameters in the model
  • dump parameters to a trace or config file
  • add constraints / assertions to parameters
  • synchronize parameters between SystemC model and external tool (push / pull)
  • ...

Examples for different config APIs are:

  • CoWare SCML
  • ARM CASI
  • Intel DRF
  • GreenSocs Simple Configuration Framework

requirements_API_overview3.gif

Basic idea: the GreenConfig Core

The GreenConfig Core implements all functionality required to manage configurable parameters in SystemC models (implementation details follow below). It provides a generic GC-API which is used to built heterogeneous User APIs on top of it.

Hence it has to be well designed to support virtually all functions other APIs might ask for. User API adaptors translate between the GreenConfig framework and the vendor's interfaces / APIs.

requirements_API_overview_GreenConfig6.gif

Main requirements

  • Support most config APIs (as much as reasonable regarding effort)
  • Ease of use (i.e. usage requires minimal to no additional implementation effort)
  • Extensibility (e.g., support more datatypes, add new config file formats, add additional functionality)

Requirements classification

We consider three classes of requirements:

  1. Requirements for GreenConfig to support known configuration APIs
  2. :2. Functionalities we from our point of view would like to see in GreenConfig
  3. :3. Requirements for future directions

1. Requirements for GreenConfig to support other parameter configuration APIs

These requirements are made from the view of supporting the tool and user APIs of all other vendors.
  • Provide an interface for the user and the tool (eventually uniform interface). This 'GreenConfig API' named interface is GreenConfig internal and is used by the specialized 'User API adaptor' for a special vendor. The GC API has to support all thinkable functionality of any user and tool API of any vendor.
  • Interface to user API (GreenConfig User API adaptor 1, see figure 2) must allow:
    • Registering a parameter (The user can add a parameter to the configuration framework.)
    • Set default value (Set value of a parameter during elaboration)
    • Get value (Get the initial value of a parameter; set by default value or by tool)
    • Change value during runtime (The user may change value of a parameter even during simulation runtime.)
    • Notify changes to user (Register observer for a parameter either a parameter of the own module or a parameter of another module.)
  • Interface to tool API (GreenConfig User API adaptor 2, see figure 2) must allow:
    • Configuration during elaboration / runtime (Set value of a parameter during elaboration and runtime)
    • Notify changes to tool (Register observer for a parameter which can be changed by the user during runtime)
    • Get value during elaboration / runtime (Get the value of a parameter during elaboration and runtime)
    • This interface may be used by a GUI tool
  • The User API adaptors must be specialized for each vendor, using the GreenConfig API and providing the vendor's APIs.
supported by
CoWare ARM TI
no parameters		 Intel GreenS. Simple
Config.
Framew.
Data types int, unsigned int,
double, bool, std::string 		std::string unknown, however presentation
implies that strings and
number formats are supported		 "Instrumented Datatype"
user implemented
implement interfaces		 PODs, STL, SystemC
User defined types - yes (user implemented) yes (instrumented datatype) yes (template specialized)
Permanent storage XML - - file file
Registering a parameter yes (global registry) yes - drf module finds
parameters itself		 yes (addParam or macro GS_PARAM
Set default value yes (constructor) user may implement user may implement yes yes (constructor)
Get value yes (e.g. getIntProperty(key) yes (getParameter
(string key))		 yes (pushed by method call) yes (Interface I_dr_dump) yes (get)
Config. during runtime
Done by other module or tool		 - - yes (task_start) - yes (set)
Change value during runtime
Done by module itself		 yes yes (user implemented) yes (user implemented) yes (user implemented) yes (set or direct)
Notify changes to user - - yes (task call) yes (event as member of instr. datatype) -
Configuration during elaboration yes (instantiation, with global registry) yes (in user module setParameter(string
key, string value))		 no (but task_start) yes (Interface I_dr_config) yes (constructor or set)
/ runtime - - method calls - yes (set)
Notify changes to tool - - task-finished event - -
Get value during elaboration - - - yes (dump) -
/ runtime - - - yes (dump) -

Table 1: This spreadsheet shows the capabilities of the reviewed configuration systems.

2. Requirements for GreenConfig in General from bottom-up

These requirements describe the framework from our view without regarding special other APIs but to achieve a many-sided framework.

  1. Usage
    1. New datatypes can be easily added by the user (to provide as many datatypes as possible)
      1. Methods to set and get the value of the parameter use std::string:
        void set(const std::string &str) and const std::string get()
        This allows easy adaption of the tools to set a parameter and is universal.
      2. The datatype of a template should be given as template parameter.
      3. Usage of a templated parameter (gc_param<datatype>) should be as easy as the usage of the datatype itself by overloading the operators (&, =). This is the instrumentation of a member variable to use it as a parameter. The usage of the parameter is transparent due to the overloaded operators.
    2. Support all imaginable parameter types and usages, e.g.
          • Setup parameters: Setup parameter is set during elaboration. The module complies with the value of the parameter to act variedly.
          • Change setup parameters: Parameter which changes during runtime to take influence on the behavior of the module.
          • Status parameters: Status parameter represent the status of a module. They are set by the module itself. Observers are notified when it changes.
          • Output parameters: Parameters to send output (debug values etc.) to the tool outside the simulation.
          • ...
  2. Configuration
    1. Configuration during elaboration
    2. Configuration during runtime
    3. Use same configuration system (same methods etc.) for initial configuration during elaboration and runtime configuration during simulation
    4. Provide setting of parameters to other IPs (e.g. tools)
          • Setting of a parameter: setParameter(std::string hierarchical_name, std::string value)
    5. Provide getting of parameter values to other IPs (e.g. tools)
          • Getting of a parameter value: std::string getParameter(std::string hierarchical_name)
    6. Provide setting of parameters inside user code. There are two different types:
      1. Setting of the parameter in the module which contains the parameter:
        Inside the parameter holding module the user may choose out of two ways of setting the value.
              • The user can set the value with the setting method (see requirement 1.1.1) using the parameter's string representation.
              • The value can be set with the instrumentation of the member variable by simply assigning the value (see requirement 1.1.3).
      2. Setting of the parameter of module in another module
      3. : We have two options to realize the access to parameters of another module: First we can access them directly by pointer. This assumes the availability of the pointer which has to be provided by a central unit. It is clearer to provide the setting of a parameter by a function contained in the API of the library. Here the same method can be used which is also used by the tool API to set parameters (see requirement 2.4).
    7. A default value can be set during instantiation/construction of the parameter: gc_param(const char *name, T value).
  3. Core
    1. Efficient data management (database) for runtime (how parameters are saved during runtime, e.g. map, list,...)
    2. Efficient data management (database) for permanent storage (e.g. config file, XML file, Access database,...)
    3. Find local and global identification system for parameters (names): Unique name inside module, full name composed of hierarchical names leading to parameter name (module_name.submodule_name.parameter_name)
          • Name a parameter during instantiation with my_param = gc_param<datatype>(my_name).
          • Get the parameter name with const std::string &getName().
  4. Observation / notification
    1. Provide a complete parameter list: e.g. multimap<const char * hierarchical_prefix, const char * name> getParameterList() or list<std::string hierarchical_name> getParameterList()
    2. Allow an observer to register for a parameter to be notified with an event when it changes
      1. Allow many observers per parameter
      2. Additional one event per configurable module config_changed?
    3. Provide to the module itself an event which is notified when any parameter of the module is changed (function callback and sc_event) (see requirement 4.2.2).
    4. Either the parameters have to register themselves at the library or the library finds the parameters or modules due to the implementation of the config interface (e.g. gs_configurable).
  1. Additional requirements resulting on conference call on 21st May 2007
      • Secure IPs which allow disabling their configuration abilities.
      • Some kind of privacy tags to protect parameters being changes from outside the module.
      • Recording actions (who is when setting or getting etc.) in the Core

3. Requirements for the support of other control interfaces

These requirements (3.x) are formed by additional control issues. Here not the parameter configuration must be provided but more general control methods. E.g. configuration or starting a task with the call of a configuration method which is provided by a given or user defined interface .

This part is for future use and has no priority at this moment.

Sorted and prioritized requirements

  1. Default value during construction
  2. Configuration during elaboration
  3. Configuration during runtime (Callback/event on change)
  4. Supported data types (set and get with strings, addition of parameter types easy)
  5. User defined data types
  6. Notify changes to tool (Callback/event on change)
  7. Notify changes to user module (Callback/event on change)
  8. Permanent storage in file

Implementation ideas for the configuration framework

‹ Parameter Structure ArraysupTIIntelRequirements ›

Posted January 8th, 2008 by ChristianSchroeder