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:

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):

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):

Class "Tag" (element "tag")

A Tag object declares a tag for the items. It has the following attributes (the XML element names are shown):

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):

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):

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):

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:

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.