Changes between Initial Version and Version 1 of Soclib Cc/Meta Data

Timestamp:

Mar 26, 2010, 6:52:17 PM (14 years ago)

Author:

Nicolas Pouillon

Comment:

--

Soclib Cc/Meta Data

@@ +1 @@
+[[PageOutline]]
+
+= Description File =
+
+A soclib description file is a python-parseable file, ending in ".sd".
+
+In fact, it is not so pythonic, using python syntax is just to avoid to write a new parser from scratch and yet having a human-readeable file.
+
+It's currently used by two tools:
+ * Soclib-CC, for compiling a platform with automatic template instanciation
+ * DSX, for complete netlist generation
+
+It contains:
+ * Source-file references
+ * C++ class template instanciation information
+ * C++ class instanciation information
+ * Netlist information
+ * DSX extensions (if needed)
+
+Later, when IP-Xact (Spirit) packaging will be ready, there will be a conversion tool from this format to IP-Xact.
+
+== Module ==
+
+Arguments to those declarations are:
+
+ name (mandatory)::
+   the reference name from anywhere else in SoclibCc. This name is preferably of the form `'type:name'` where type may be:
+   * caba
+   * common
+   * tlmt
+ classname (mandatory)::
+   the C++ class name to instanciate, with full namespace, but no template parameters
+ tmpl_parameters::
+   the template parameters, if any. This must be a list of parameters (see below)
+ header_files::
+   header files to include when using this component, paths relative to the sd
+ implementation_files::
+   implementation files to compile, paths relative to the sd
+ ports::
+   ports in the module
+ instance_parameters::
+   needed parameters to instanciate the module. This must be a list of parameters (see below)
+
+== Signal ==
+
+Arguments are:
+ name, classname, tmpl_parameters, header_files, implementation_files::
+   as above
+ accepts::
+   a dictionnary of port names associated to maximum connection count.
+
+sample: [source:trunk/soclib/soclib/communication/vci/caba/metadata/vci.sd@289 Vci signal description]
+
+== !PortDecl ==
+
+Arguments are:
+ name, classname, tmpl_parameters, header_files, implementation_files::
+   as above
+ signal::
+   connectable signal name (in soclib-cc)
+
+sample: [source:trunk/soclib/soclib/communication/vci/caba/metadata/vci.sd@289 Vci ports description]
+
+= Parameters =
+
+== Instance Parameters ==
+
+'''In any parameter, you may specify a default value using''' `default=`
+
+ * `parameter.IntTab`
+  * arguments: name
+  * usage: an !IntTab for Vci indexes
+  * example: `parameter.IntTab('index')`
+  * sample: [source:trunk/soclib/soclib/module/internal_component/vci_ram/caba/metadata/vci_ram.sd@289#L23 vci_ram.sd, line 23]
+ * `parameter.Module`
+  * arguments: name, typename = module type (name declared to soclib-cc)
+  * usage: passing another module reference, like a mapping table or another component
+  * example: `parameter.Module('mt', typename = 'common:mapping_table')`
+  * sample: [source:trunk/soclib/soclib/module/network_component/vci_vgmn/caba/metadata/vci_vgmn.sd@289#L18 vci_vgmn.sd, line 18], 
+    [source:trunk/soclib/soclib/module/internal_component/vci_ram/caba/metadata/vci_ram.sd@289#L25 vci_ram.sd, line 25]
+ * `parameter.String`
+  * arguments: name
+  * example: `parameter.String('input_file', default = 'input.txt')`
+  * sample: [source:trunk/soclib/soclib/module/internal_component/fifo_reader/caba/metadata/fifo_reader.sd@289#L20 fifo_reader.sd, line 20]
+ * `parameter.Int`
+  * arguments: name
+  * example: `parameter.Int('min_latency', default = 3)`
+  * sample: [source:trunk/soclib/soclib/module/network_component/vci_vgmn/caba/metadata/vci_vgmn.sd@289#L19 vci_vgmn.sd, line 19]
+ * `parameter.Bool`
+  * arguments: name
+  * example: `parameter.Bool('use_atomic_operations', default = False)`
+ * `parameter.StringArray`
+  * arguments: name
+  * example: `parameter.StringArray('tty_names')`
+  * sample: [source:trunk/soclib/soclib/module/connectivity_component/vci_multi_tty/caba/metadata/vci_multi_tty.sd@289#L28 vci_multi_tty.sd, line 28]
+
+== Template parameters ==
+ * `parameter.Module`
+  * arguments: name
+  * example: `parameter.Module('iss_t')`
+  * sample: [source:trunk/soclib/soclib/module/processor_component/iss_wrapper/caba/metadata/iss_wrapper.sd@289#L11 iss_wrapper.sd, line 11]
+ * `parameter.Bool`
+  * arguments: name
+  * example: `parameter.Bool('use_atomic_operations', default = False)`
+  * sample: [source:trunk/soclib/soclib/lib/metadata/vci_target_fsm.sd@289#L11 vci_target_fsm.sd, line 11]
+ * `parameter.Type`
+  * arguments: name
+  * example: `parameter.Type('word_t')`
+  * sample: [source:trunk/soclib/soclib/module/internal_component/fifo_reader/caba/metadata/fifo_reader.sd@289#L24 fifo_reader.sd, line 24]
+
+= Common warnings =
+
+== !ModuleDeprecationWarning: Deprecation ==
+
+Some modules may be marked as deprecated with a friendly warning until they are removed. You'll get this kind of message when using such a module:
+
+{{{
+ModuleDeprecationWarning at /Users/nipo/projects/soclib/soclib/lib/mips/metadata/mipsel.sd:10:
+    Module common:mips deprecated: "Please migrate to Mips32"
+}}}
+
+The message enclosed in quotes at the end is the one specified in [source:/trunk/soclib/soclib/lib/mips/metadata/mips.sd@657#L18 the mips.sd file].
+
+== !PartialNameWarning : Lazyness in declaration ==
+
+{{{
+PartialNameWarning at /Users/nipo/projects/soclib/utils/lib/python/soclib_desc/specialization.py:74:
+    Short name vci_timer is deprecated, please use a full name with caba:, tlmt: or common:
+}}}
+
+Modules have dependencies on other modules. Dependencies can be:
+ * Ports, example:
+   {{{
+Port('caba:vci_initiator', 'p_vci')
+   }}}
+ * Uses, i.e. uses of another module as sub-module. Example:
+   {{{
+Uses('caba:vci_target_fsm')
+   }}}
+ * Module parameters, example:
+   {{{
+tmpl_parameters = [
+       parameter.Module('vci_param',  default = 'caba:vci_param'),
+],    
+   }}}
+
+When such construct are used, you should write the full name of the module.
+Here, it is `caba:vci_initiator`, `caba:vci_target_fsm`, `caba:vci_param`.
+
+Previously, soclib-cc supported to implicitly use the abstraction level from the parent module, but this has limitations with multi-abstraction level simulations, therefore it is deprecated.
+
+
+== !InvalidComponentWarning: Invalid Definition ==
+
+{{{
+InvalidComponentWarning at /Users/nipo/projects/soclib/soclib/module/verification_component/avci/caba/metadata/avci_filter.sd:68:
+    Invalid component caba:avci_filter, it will be unavailable. Error: "NoSuchComponent('`vci_param::val_t`',)"
+}}}
+
+This is most probably a syntax or usage error. As parsing of the `.sd` file cant be done, module is disabled.