Device Table Generator (Dtgen)

The dtgen tool is used by the build system to create many artefacts containing top-specific information. See:

• Device Tables artefacts
• Doxygen documentation: look for the (<topname>)/hw/top/dt/ directories.

In addition to the standard definitions generated for each top/IP, dtgen supports extensions. Extensions can be used to add extra definitions to the generated artefacts such as IP-specific constructs.

Python-based extensions

Python extensions can be added by passing a python file on the command-line of dtgen with --extension. This file must contain one or more classes derived from the Extension class in helper.py. The API for such extensions is not considered public or stable. Some IPs currently have these extensions, including pwrmgr, rstmgr and clkmgr.

Ipgen-based extensions

dtgen provides a standard interface to expose ipgen parameters in the DT. For this to work, you must ensure that: dtgen has access to the ipconfig of the IP, e.g. Darjeeling’s GPIO. This is done by passing this file on the command-line using --ipconfig. See the documentation on top creation for more information.

Assuming that dtgen has access to the ipconfig of the IP, it will look for a dtgen dictionary in each of the IP’s parameters. This dictionary can contain the following keys:

• type (mandatory): type of the variable exposed in the DT API (see below)
• name (optional): name of the variable (if not set, same as the parameter name)

Here is an example:

{
  template_param_list: [
    // ...
    {
      name: "num_inp_period_counters"
      desc: "number of input period counters"
      type: "int"
      default: 0
      // This dictionary causes dtgen to include this parameter
      dtgen:
      {
        type: "uint8"
        // The name is optional, if we don't set it then it will use num_inp_period_counters
        name: "input_period_counter_count"
      }
    }
  ]
}

Even though the type of the parameter is already specified in the parameter list (e.g. int), this type is usually not precise enough for a C API. This is why the dtgen dictionary must contain a more precise type. Currently the following types are supported:

• uint8: unsigned 8-bit integer

The IP header generated by dtgen will then be amended to include a function to retrieve each parameter which is named dt_<ip-name>_<param-name>(dt_<ip>_t dt). Here is the generated code corresponding to the example above:

/**
 * Get the number of input period counters.
 *
 * @param dt Instance of gpio.
 * @return number of input period counters.
 */
uint8_t dt_gpio_input_period_counter_count(dt_gpio_t dt);