Component Descriptor File JSON Syntax

Initial remarks

---

Note: All paths are relative to the base directory of the descriptor file itself.

Convention: All lowercase is preferred. In case of multiple words, CamelCase is preferred.

Convention: Names and identifiers may only contain alphanumeric characters and dashes. They must not begin with a number, or a dash.

Note: The slash may appear in evaluation results throughout the program. It is a hierarchy seperator and as such reserved for internal use only.

---

File contents

---

The main descriptor file is a regular JSON file containing an object with the following JSON Fields:

• name (String) is the name of the component type that is described by this file
  • By default instances of this component type will be named after thy type, followed by an incremental index
• symbolFile (String)(optional) is the path to a file in the plain SVG format, showing the schematic symbol
  • Schould no symbol file be given, q2d will generate one when loading the descriptor file
  • Note: different components may share the same symbol file
  • The symbol file does not need to contain the port symbols. They will be added by q2d itself
• ports (Array) contains the description of all ports a component of the described type has. (See below)
• configBits (Array of Objects) contains all groups of configuration bits a component of the described type has. (See below)
• functions (Array of Strings) lists all boolean functions that are fulfilled by a component of the described type. (See below)

ports

• name (String) the name of this port
  • Note: make sure the name of the port is unique within this descriptor file
• direction (String) specifies wether the port is an input port (data flows from the outside into the component) or an output port (data flows from the component to the outside world)
  • Allowed values are "in" and "out". Capitalization does not matter, so e.g. "In" or "IN" are fine too.
  • Combined "inout" ports (like in VHDL) are recognized, but not fully supported
    • These kind of ports are just a time-multiplexed way of alternating between an input and an output port.
    • Advice: inout ports should be split into an input and an output port
• pos (Object)(optional) describes the position of the center of a port in the symbol file, relative to the symbol files origin.
  • Port positions must be specified if a custom symbol file is used. Should no symbol file be given, the port position will be ignored, since q2d will determine them on its own.
  • A position is an object, containing the fields "x" and "y" as integers.
  • Note: Be aware of different coordinate system orientations used by different tools. It is strongly advised to test the correct instantiation of the created component before distribution.

configBits

• name (String) is the name of a group of configuration bits
  • The name of an individual configuration bit will be created by adding an underscore and an incremental, zero-based index to the group name (see example below).
• size (Integer) indicates how many bits are in a configuration bit group
  • Note: a size below 1 will result in the group being ignored

Example:

{"name":"myGroup", "size":2}

Will result in the individual configuration bits myGroup_0 and myGroup_1 to be valid.

functions

• The strings in this array represent a boolean term, equation or clause fulfilled by the component each.
  • For details on how to write these down, refer to the Notation of Boolean Formulae page
  • Note: Contrary to the strict CNF definition, q2d can also deal with boolean terms instead of pure literals
  • Advice: It is discouraged to use anything but variables and negated variables as literals in the CNF notation

---

An example file

---

{
 "name":"myComponent",
 "symbolFile":"symbols/mySchematicSymbol.svg",
 "ports":
  [
   {"name":"input0", "direction":"in", "pos":{"x":0, "y":30}},
   {"name":"input1", "direction":"in", "pos":{"x":0, "y":10}},
   {"name":"output", "direction":"out", "pos":{"x":50, "y":20}}
  ],
"configBits":
  [
    {"name":"blockA", "size":2},
    {"name":"blockB", "size":8}
  ],
"functions":
  [
    "output = (input0 and input1) or (blockA_0 xor (not blockB_5 nand input1))",
    "[output, !input1, blockA_1]"
  ]
}