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 function fulfilled by the component each.
  • The left hand side of the equals sign has to be an output port name.
  • The right hand side is an boolean expression
    • Valid variables are either input port names or configuration bit names
      • Note: Names of configuration bit groups are not valid variables
    • Valid infix operations are:
      • and, nand
      • or, nor
      • xor, xnor
    • Valid prefix operations are:
      • not
    • Parentheses may be used to priorize expressions
      • Otherwise expressions will be evaluated left to right
      • Advice: If there might be any doubt about how an expression is evaluated, the use of parentheses is strongly encouraged.
    • Alternative notation symbols may be used:
      • ! or ~ instead of not
      • * or & instead of and
      • + or | instead of or
      • Advice: As long as the function string is not excessively long, using a mnemonic notation is to be preferred.
• Instead of function strings, clause normal forms (CNFs) may be specified as well
  • Each function string may only contain one clause
    • Each clause is a set of disjuncted literals
  • Clauses are to be embedded into square brackets like […]
  • Literals are to be seperated by commas
  • 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]"
  ]
}