Provided data

Syntax

Fundamental datatype are:

Strings:

They can be enclosed in simple or double quotes.

Lists:

They are enclosed in brackets ([]).

Dictionaries:

They are a mapping from a string to something else. Syntax is { "key": value, "key2": value2, ... }.

Files contain declarations of different modules. Basic module types are:

Module:

A new module, most of the time an entity.

PortDecl:

A new port type definition. This is actually a superset of a module

Signal:

A new signal type definition. This is actually a superset of a module

These declarations can use fundamental datatypes and statements, among them:

Port:

Usage of a port, see Ports

Uses:

Usage of another module, see Uses.

parameter:

Usage of a parameter, see Parameters.

Root statements

Module, PortDecl and Signal take the declared module name as first argument. All other arguments are named and specify attached metadata.

Module(name, classname, tmpl_parameters =[], header_files =[], implementation_files =[], ports =[], instance_parameters =[])

Defines a new module. Module can be either actual entities, or simple helper modules, like pure C++ classes.

Parameters:

• name – Name of module in Module Index
• classname – Entity name (class with namespace for C++, entity name for VHDL)
• tmpl_parameters – Compile-time parameters, a list of parameters.
• instance_parameters – Run-time parameters, a list of parameters.
• implementation_files – Source files to compile
• header_files – Source files to include in parent modules
• ports – A list of Ports.

Example declaring a component named “caba:my_module” in the Module Index, implemented as the MyModule class, with code in the my_module.h and my_module.cc files:

Module("caba:my_module",
       classname = "MyModule",
       header_files = ["my_module.h"],
       implementation_files = ["my_module.cc"],
   )

Signal(name, classname, tmpl_parameters =[], header_files =[], implementation_files =[], accepts = {})

Defines a new signal type

Parameters:

• name – Like in Module()
• classname – Like in Module()
• tmpl_parameters – Like in Module()
• header_files – Like in Module()
• implementation_files – Like in Module()
• accepts – A dictionnary of port names associated to maximum connection count. If there is no limit, put True.

PortDecl(name, classname, tmpl_parameters =[], header_files =[], implementation_files =[], signal = None)

Defines a new port type.

Parameters:

• name – Like in Module()
• classname – Like in Module()
• tmpl_parameters – Like in Module()
• header_files – Like in Module()
• implementation_files – Like in Module()
• signal – The name in Module Index of a correponding signal

Example defining the bit type:

# A bit signal only supports one driver, but any number of bit input
# ports may be connected on it.

# No specific header files are necessary for these declarations as
# they use builtin SystemC types.

Signal('caba:bit',
       classname = 'sc_core::sc_signal<bool>',
       accepts = {'caba:bit_in'  : True,
                  'caba:bit_out' : 1,
                 },
       )

PortDecl('caba:bit_in',
         signal = 'caba:bit',
         classname = 'sc_core::sc_in<bool>',
         )

PortDecl('caba:bit_out',
         signal = 'caba:bit',
         classname = 'sc_core::sc_out<bool>',
         )

Uses

If the module uses another module internally, we may want to declare this also. Uses() statement serves this goal.

Uses(module_name, **parameters)

Parameters:

• module_name – Module name in Module Index
• parameters – A key/value mapping of parameters

Example with “caba:my_super_module” using “caba:my_module”:

Module("caba:my_super_module",
       classname = "MySuperModule",
       header_files = ["my_super_module.h"],
       implementation_files = ["my_super_module.cc"],
       uses = [
          Uses("caba:my_module"),
          ],
   )

Ports

Port statements declare a port with a given type and name.

Port(type, name, array_size = None, **parameters)

Parameters:

• type – Module name in Module Index
• name – Name of the port.
• array_size – A numeric value. Only relevant if this is actually an array of ports.
• parameters – A key/value mapping of needed arguments of port module.

Supported types are either:

• Built-in port types, depending on language:

  • SystemC types: caba:bit_in, caba:bit_out, caba:clock_in, caba:clock_out, caba:word_in, caba:word_out.
  • HDL types: rtl:bit_in, rtl:bit_out, rtl:word_in, rtl:word_out.

  Example:

  Port("rtl:bit_in", "p_in0")
  

  Word-based ports need a W parameter to set their width:

  Port("rtl:word_out", "p_result", W = 5)
  

• If a port is connected to a specific net, this can be hinted through the auto keyword:

  Port('caba:bit_in', 'p_resetn', auto = 'resetn')
  

• Other composite port types declared with a PortDecl() statement.

Usage in a module with one output IRQ port, and 10 input IRQ ports:

Module("caba:my_super_module",
       classname = "MySuperModule",
       ports = [
          Port('caba:bit_out','p_irq'),
          Port('caba:bit_in','p_irq_in', 10),
          ],
   )