RDB Format
This is a brief description of the report database format used by KLayout to represent the content of
a report database. KLayout uses a report database to present results of checks or extraction operations.
A report database can be viewed with the marker browser, available in the "Verification" menu.
KLayout can import other report database formats. Writing is supported only in the format described here.
This description covers the structure of the file. This structure closely matches the internal structure (for
example accessible through RBA), and this document may be helpful to understand that internal API as well.
Basic structure
The suffix used by KLayout for report databases is ".lyrdb". The file format is XML representing the object
structure of the report database. The root element is "report-database". This is an abbreviated sample file:
<?xml version="1.0" encoding="utf-8"?>
<report-database>
<description>Diff of 'x.gds, Cell RINGO' vs. 'x.gds[1], Cell INV2'</description>
<original-file/>
<generator/>
<top-cell>RINGO</top-cell>
<tags>
<tag>
<name>red</name>
<description>Red flag</description>
</tag>
...
</tags>
<categories>
<category>
<name>1/0</name>
<description>Differences in layer 1/0</description>
<categories>
<category>
<name>A</name>
<description>Shapes in A but not in B, on Layer 1/0</description>
</category>
...
</categories>
</category>
</categories>
<cells>
<cell>
<name>RINGO</name>
<variant>1</variant>
<references>
...
</references>
</cell>
...
</cells>
<items>
<item>
<tags/>
<category>'1/0'.A</category>
<cell>RINGO:1</cell>
<visited>true</visited>
<multiplicity>1</multiplicity>
<image/>
<values>
<value>text: 'item: polygon'</value>
<value>polygon: (1.4,1.8;-1.4,1.8;-1.4,3.8;1.4,3.8)</value>
</values>
</item>
...
</items>
</report-database>
The components of a report database are:
- Items: Items represent one basic element of the report. Usually an item represents a
marker indicating a geometric entity with a shape. Items can also represent texts such
as errors or warnings not related to geometry.
Items carry information with a set of values.
Values are the parts forming the information of an item. Currently, each item has an ordered
list of values. KLayout does not make an assumption about the type or order of the values.
Items can also be flagged with "tags" (see below) and have an image attached. Currently an
image is a special property of the item, not part of the values.
- Values: A value represents an information part of the database item. In the report database context,
a value is a string encoding the type of the value and the actual value.
- Categories: The report database defines a hierarchy of categories and sub-categories. Each database item is
associated with a category or sub-category within that tree.
- Cells: The report database also defines a hierarchy of cells. The cell hierarchy may be complete, i.e.
a copy of a layout hierarchy or specify representative instances or no instances at all.
Database items can be associated with a cell which allows KLayout to display a marker in the
context of a certain cell.
KLayout supports cell variants. A cell is not only identified with a name by may also
carry a variant identifier. An item can be associated with a particular variant of a cell
if necessary.
- Tags: Tags are basically flags that can be attached to database items. KLayout uses tags to
mark items as "waived" or "important".
The following figure shows how the marker databases' objects are related with elements of the marker browser dialog:
Detailed description
The marker databases' structure is conveniently described with a UML class diagram. It shows the objects of
the database and their relationship. Aggregation in XML is implemented by including the object in the XML, association
is implemented with an element carrying a suitable reference string. In the class diagram, some container classes
appear (i.e. "Cells") which represent a list of individual objects (in that case "Cell"). They are present to
match the XML structure, which uses an enclosing element around the list (in that example "<cells>...</cells>").
The attribute names in the UML class diagram match the XML element names where the underscore is replaced by the hyphen
(i.e. attribute "top_cell" is represented in XML as "top-cell"). This convention is a tribute to the usual XML
convention which contrasts with the attribute names used in the code.
The following is a detailed description of some classes and important attributes. As a general rule, the marker
database uses micron units. It is independent of the layout database unit.
Class "Database" (element "report-database")
This is the root element of the XML file and the object representing the whole database. It has the following
attributes (the XML element names are shown):
- description: A general description text shown in the marker database browser for that database.
- original-file: (optional) The file from which the report was generated.
- generator: (optional) A string describing information about the module that generated the report database.
It is intended to formalize the generator information so it is possible to re-run a reporting tool.
- top-cell: The name of the top cell in the layout from which the report was created from.
- tags: A list of Tag objects (child elements "tag") declaring the tag identifiers available.
- cells: A list of Cell objects (child elements "cell") declaring the cells, optionally specifying a partial or complete hierarchy in the form of a cell graph.
- category: A list of Category objects (child elements "category") declaring the first level of categories.
Class "Category" (element "category")
A Category object specifies one category and optional sub-categories forming a branch in the tree of categories.
It has the following attributes (the XML element names are shown):
- name: An arbitrary string identifying a category in a "category path" (see "Item" class).
The name is also shown in the category tree. A category name must be unique in the
context of the category list (not across the category hierarchy).
- description: A description string shown in the title of the item panel.
- sub-categories: An optional list of child categories (further Category objects).
Class "Tag" (element "tag")
A Tag object declares a tag for the items.
It has the following attributes (the XML element names are shown):
- name: An arbitrary string identifying a tag in item's tag list. The tag name must be unique in the context of the database.
- description: An optional description string.
Class "Cell" (element "cell")
A Cell object declares a cell and optionally the cell's relationship, hence forming a cell graph.
It has the following attributes (the XML element names are shown):
- name: An arbitrary string identifying the cell. The cell name is matched against cell names in
the layout when displaying geometrical markers to locate the marker in the layout. The
instantiation information is used to locate the marker in the top-level context if the
specific cell is not available. A geometrical marker is always specified in the context
of the cell it refers to.
- variant: An arbitrary string identifying the variant of the cell.
- references: An list of Reference objects which specifies from which cells and how this cell is instantiated.
Hint: if a cell exists with an empty name, it is displayed as "All cells". All items which are not associated
with a cell (i.e. global warning messages), can be associated with this special cell by specifying an empty
cell name for that item.
Class "Reference" (element "reference")
A Reference object represents a cell reference and states parent cell and transformation.
It has the following attributes (the XML element names are shown):
- parent: The parent cell name. If multiple variants exist for a cell, this must be a qualified name: the cell name, a colon and the variant id (for example "A:1").
- trans: The transformation by which this cell's content is transformed into the parent cell (??? correct?).
The transformation is specified in KLayout's transformation notation.
The transformation specification follows the standard notation in KLayout (see Transformations in KLayout).
For example, "r90 *1 17.5,-25" describes a rotation by 90 degree (in the mathematical sense), no scaling and a displacement of
17.5 micron in x-direction and -25 micron in y direction. Since "*1" is the default, this is equivalent to "r90 17.5,-25".
Also, the order of the parts is not important, so "17.5,-25 r90" gives the same results.
Class "Item" (element "item")
Items are the basic elements of the report database.
An Item class has the following attributes (the XML element names are shown):
- tags: A comma-separated list of tag names attached to this item.
- category: A category path describing the category this item is attached to. A category path
is a list of category names joined with dots. For example "A.B" is the "B" sub-category
of the "A" category. The category path notation allows to quote category names by
single or double quotes so that category names can also contain dots.
- cell: The cell that this item is associated with. The cell name can be empty indicating that
the item is not associated with a specific cell. In that case, the item is listed under "All cells". Currently, in that case a
dummy cell declaration is required that declares a cell without a name (see "Cell" class).
The cell name is a "qualified name". That means it consists of a cell name, optionally followed by a colon and the variant string.
For example, "A:1" is the "1" variant of the "A" cell. This specification is only required if
there are cell variants.
- visited: A value indicating whether the item has been visited already ("true" or "false").
- multiplicity: This value specifies if an item represents multiple actual instances of an item. This value can be used to compute
total number of markers within a category for example. The value can be necessary if for example
the cell given by the "cell" attribute has just one reference instantiation but in reality
represents a large number of actual instances. By specifying the multiplicity, the item
is given the appropriate weight.
- image: An optional image attached to the item. This string is a text representation of a image file
in one of the standard formats supported by KLayout (preferred format is PNG) in base64 encoding.
- values: The list of values for this item.
Class "Value" (element "value")
A value is not class for it's own, although in the code, values are represented by specific classes.
In the report database, a value is simply a string representing various types of values. The general format
is a type code, followed by a colon and a specific value string.
If a value represents a geometrical object, the coordinates are given in micron units and the object is
located inside the associated cell and is transformed by the marker browser into the currently active cell using the reference information
derived from the database or the current layout. This implies that all values with geometric interpretation must be
associated with a cell.
Currently these value formats are supported:
- "text: <text>": A message text (no geometry).
- "box: (<x1>,<y1>;<x2>,<y2>)": A box (geometrical object).
- "edge: (<x1>,<y1>;<x2>,<y2>)": An edge (geometrical object).
- "polygon: (<x>,<y>;...)": A polygon (geometrical object). The points in brackets form the polygons' outline.
"polygon: (<x>,<y>;.../<x>,<y>;.../...)": A polygon with holes. The points in brackets before the slash form the polygons' outline, the point sequences after the slash form the hole contours. Each slash enters a new hole.
- "label: ('<text>',<trans>)": A text (geometrical object). "trans" is the text transformation in KLayout's transformation notation.
- "path: (<x>,<y>;...) w=<width> bx=<begin-ext> ex=<end-ext> r=<round-flag>": A path (geometrical object). The points in brackets form the path's center line. "ex" and "bx" specify begin and end extension, "w" specifies the width and "r" is "true", if the path has round ends.
The value string of the geometrical objects is derived from KLayout's string representation which
can be created within RBA with the "to_s" method for example.