Metadata

For SoCLib components, metadata is in .sd files, parsed by soclib-cc.

In these files, there is an optional extensions = statement. This statement is a list of string formatted as "namespace:keyword=value". An example for the dsx namespace is:

extensions = [
    'dsx:cpu=wrapper:iss_t',
    'dsx:addressable=target_index',
],

Here we'll make a list of these extensions and their effects

Pure C++ module constraints

Module without a name as first parameter

Some pure-C++ (i.e. not SystemC) modules do not need a name as first parameter. There is an extension telling the netlister to generate a correct constructor invocation for the module:

"dsx:noname",

Memory mapping & organization

VCI srcid / tgtid, ports and mapping tables

VCI uses (r)srcid to route response packets back to the originating initiator. As it is decoded, the srcid field attributed to an initiator is directly equivalent to the port it is connected to on peer interconnect. A module then has to be able to retrieve:

• srcid field value (or initiator index as an IntTab parameter)
• mapping table associated to the interconnect
• correspondance between ports and indexes

Likewise for targets.

Target components

For a simple target component, we'll probably have:

• a VciTarget port
• a mapping table as parameter
• a target index as parameter

ports = [
    Port('caba:vci_target', 'p_vci_port_name'),
    …
    ],
instance_parameters = [
    …
    parameter.IntTab('target_index_parameter_name'),
    parameter.Module('mapping_table_parameter_name', typename = 'common:mapping_table'),
    …
],

Needed metadata are:

"dsx:get_ident=target_index_parameter_name:p_vci_port_name:mapping_table_port_name",
"dsx:addressable=target_index_parameter_name",

dsx:get_ident associates a given index to a port and a mapping table. Actual index value and mapping table to use will be implicitly retrieved through the module connected to the port.

dsx:addressable tells the target is accessible through this target index.

Maximum target segments

Sometimes targets can only have a limited number of addressable segments. You can enforce this limit telling DSX to do so.

For instance, a simple controller may only need one segment:

extensions = [
    'dsx:max_segments=1',
],

Addressable segments associated to a srcid

For coherent platforms, we sometimes need to associate a source id to a segment. Thus when creating the segment, we have to add an id. This is done through "dsx:on_segment= extension. Example in the vci_cc_xcache_wrapper_v1:

Syntax: target_segment_mapping_table:add_index:initiator_index_name

instance_parameters = [
    parameter.Int('proc_id'),
    parameter.Module('mtp', 'common:mapping_table'),
    parameter.Module('mtc', 'common:mapping_table'),
    parameter.IntTab('initiator_rw_index'),
    parameter.IntTab('initiator_c_index'),
    parameter.IntTab('target_index'),
    …
    ],
extensions = [
    'dsx:get_ident='
       'initiator_rw_index:p_vci_ini_rw:mt,'
       'initiator_c_index:p_vci_ini_c:mc,'
       'target_index:p_vci_tgt:mc',
    'dsx:on_segment=mc:add_index:initiator_rw_index',
    'dsx:addressable=target_index',
    …
    ],

Initiator

For a simple initiator component, we'll probably have:

• a VciInitiator port
• a mapping table as parameter
• a source index as parameter

ports = [
    Port('caba:vci_initiator', 'p_vci'),
    …
    ],
instance_parameters = [
    …
    parameter.Module('mt', 'common:mapping_table'),
    parameter.IntTab('index'),
    …
    ],

This works the same way as for targets. Let's have an example with real names:

extensions = [
    'dsx:get_ident=index:p_vci:mt',
],

dsx:get_ident associates a given index to a port and a mapping table. Actual index value and mapping table to use will be implicitly retrieved through the module connected to the port.

Interconnects

In order to get the two preceding points working, interconnects need to provide a way to get a source / target identifier. When DSX reaches an interconnect, it looks for the following extension:

extensions = [
    'dsx:interconnect=root',
    'dsx:obtain_ident_method=port',
    ],

dsx:interconnect may either have no value, or "root". "root" means the interconnect is the root of the routing tree, for instance a VGMN. Local interconnects (like the vci_local_crossbar) only need "dsx:interconnect".

dsx:obtain_ident_method may value either port or param.

port

The identifier is directly related to the port number in a port array, this is the usual value for all port-array based interconnects like VGMN or crossbars.

param=some_parameter_name

Use a given instance parameter as identifier for associated component. This is the usual value for one-wrapper-per-component interconnects like ring or dspin.

CPUs / ISS wrappers

Processor type

For DSX software deployment system, we need to highlight CPUs and their types. This is the "dsx:cpu=" extension.

As ISS are wrapped in caches, and wrapping may be nested (GDB, memchecker, …) a recursive way, a recursive lookup is achieved.

"dsx:cpu=" may be:

wrapper:some_template_parameter_type

used in caches and iss wrappers, to tell the iss is unknown, but given as a parameter

some_arch

used for actual CPU implementations, tells what the cpu architure is. Current known architectures are mips32el, mips32eb, powerpc405, arm.

Processor identifier

CPU are associated to an unique identifier for the platform, usually a sequential name. DSX needs to know what parameter corresponds to this identifier. This is done with the "dsx:mapping_type=processor:parameter_name":

instance_parameters = [
    parameter.Int('ident'),   # processor identifier
    parameter.Module('mt', 'common:mapping_table'),
    parameter.IntTab('index'),
    …
    ],
extensions = [
    'dsx:mapping_type=processor:ident',
    ],

Devices

Devices may be declared, in order to be able to map specific options to them. For now, only ttys are supported.

extensions = [
    'dsx:device=tty',
    ],

C++ hacks

Sometimes, you have to call a C++ static function once per class, or a method once per object instance. These two things will help, even if this obscure feature is mostly undocumented. Use source code for reference.

Static configuration lines

'dsx:static_config_lines=%(class)s::init(%(env:mapping_table)s,%(env:loader)s,"%(meta:all_peripherals)s")'

This is an excerpt from iss_memchecker metadata, telling the netlister must generate a line with a given template once for each IssMemchecker?<…> type, taking references from envorinment and all peripherals.

Instance configuration lines

Likewise, there is

'dsx:config_lines=…', emitted once for each object. See dsx soclib's component handling code for usage.

MutekH configuration

Some modules may want to influence MutekH's own configuration. This is only available when using DSX software-generation feature. Using a given module may then change some configuration tokens in MutekH's build system.

For instance, when putting an iss_memchecker in the netlist, we want MutekH to be built with memchecker support code activated, thus we can add in iss_memchecker's metadata the following extension:

extensions = [
    'dsx:set_config=CONFIG_SOCLIB_MEMCHECK',
],

Examples

DMA

Let's describe a DMA. It has

• one initiator port
• one target port
• an initiator index
• a target index
• a mapping table associated to this all

It only supports one addressable segment

ports = [
    Port('caba:vci_target', 'p_vci_target'),
    Port('caba:vci_initiator', 'p_vci_initiator'),
    …
],
instance_parameters = [
    parameter.Module('mt', typename = 'common:mapping_table'),
    parameter.IntTab('srcid'),
    parameter.IntTab('tgtid'),
    parameter.Int('burst_size'),
],
extensions = [
    'dsx:addressable=tgtid',
    'dsx:max_segments=1',
    'dsx:get_ident=srcid:p_vci_target:mt,tgtid:p_vci_initiator:mt',
],