Changes between Initial Version and Version 1 of Soclib/DsxMetadata

Timestamp:

Apr 14, 2010, 10:57:12 AM (14 years ago)

Author:

Nicolas Pouillon

Comment:

--

Soclib/DsxMetadata

@@ +1 @@
+[[PageOutline]]
+
+= 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',
+],
+}}}