Blackboxes

A blackbox stands in for a cell whose geometry is not shared: it has the cell's outline, ports, parameters and attributes, but none of its shapes. The geometry it stands for is the whitebox. A device designer publishes the blackbox; others design with it, check connections and write GDS, in Laylight or in other tools; whoever holds the whitebox (the designer, or the foundry) puts it back to get the complete layout. A record in each blackbox ties it to its whitebox with signatures.

designer           mmi.lyl             ── laylight blackbox ──▶  mmi_bb.gds
user               mmi_bb.gds          ── any layout tool ────▶  chip.gds
designer/foundry   chip.gds + mmi.lyl  ── laylight unbox ─────▶  chip_full.gds

The record has to survive the trip through the user's tools. Tools rename cells to resolve name clashes, drop GDS properties or text labels, convert database units, flatten or merge cells. So Laylight keeps the record in several places (its carriers), and every check reports what differs and the likely cause, rather than only failing.

Publishing

laylight blackbox mmi.lyl --top MMI1x2 -o mmi.lyir --gds mmi_bb.gds

This writes the blackbox of every top cell (--top picks them) as Laylight IR (-o, or standard output) and as GDSII (--gds). The input can be source, IR text (.lyir) or GDS. A blackbox cell keeps the cell's name, its source cell, its parameter and attribute values and all its markers, and draws:

• the footprint: the bounding box of the whitebox (subcells included) and its ports, on the blackbox layer (254/0 unless the layer table names one). An up arrow is etched out of its middle; it points along the cell's +y and has a foot to the left of its shaft, so a rotated or mirrored placement shows at a glance.
• the outline code: the content signature, drawn as small squares inside the arrow's shaft (see The outline code).
• a pin for every port location on the marker layer: a pentagon as wide as the port, pointing along the port's direction, its shoulders on the port. The markers themselves are written as usual, as texts with their attributes.

Splitter: 45um × 4um, 3 port location(s), outline code, content sha256:927786961fee4638d1e955fc4221b0863cefec7eee20bbf2b40de4ed7f5560a4
wrote mmi_bb.gds
wrote mmi.lyir

Nothing is published that would not survive

Publishing checks that the blackbox's metadata can be written to GDS and IR and read back exactly. If any blackbox fails, laylight blackbox reports every problem and writes no files:

error: cannot publish `Long`: attribute `note`: written to GDS as `attr:note="a fairly long human readable …`, 182 bytes; GDS properties hold at most 126
error: nothing was written

After those checks, the blackboxes are written to GDS and IR in memory and read back. Every record, parameter, attribute, marker and shape must come back the same, and every blackbox must verify. Only then are the files written.

Designing with a blackbox

Import the IR file, or the GDS file, and place its cells like any other:

import "components.lyl"
import "mmi.lyir"                          # or: import "mmi_bb.gds" cell "MMI1x2"

cell Splitter {
    attribute { length m.total_length }

    place MMI1x2 at self.origin as m
    place Waveguide with length = 20um at m.marker.output[0]
    place Waveguide with length = 20um at m.marker.output[1]
}

• A cell from IR or GDS is concrete: it takes no parameters, and its parameter and attribute values are read as attributes (m.mmi_len, m.total_length). Its ports work as anchors, in connection checks and in the language server's completion.
• When the design is built, the cell is copied as it is, so the blackbox and its record end up in the design's IR and GDS. Layers are matched by GDS number (the marker and blackbox layers by name), and the database units must agree. A GDS import converts other cells to the design's DBU, but a signed blackbox is refused unless its DBU matches.
• Every imported blackbox is verified at the import. A blackbox that was edited after it was published is an error that names what changed:

error: blackbox `Splitter` does not match what was published:
  - its interface signature does not match: it changed after it was published
  - attribute `arms` is not as published (now 4)
 --> chip.lyl:2:8
  |
2 | import "tampered.lyir"
  |        ^^^^^^^^^^^^^^^

• A GDS cell that carries an outline code but no record is a blackbox whose metadata was lost: its ports and signatures are gone, so importing it is an error. Import the file the blackbox was published as.
• Two blackboxes with the same name, from different files, can be used together. The second is renamed Name$1 in the output, and it still verifies under the name it was published with.

Any IR file can be imported this way, not only blackboxes: the output of laylight ir lets other projects reuse a library of cells without its source.

Putting the whitebox back

laylight unbox chip.gds --whitebox mmi.lyl -o chip_full.gds

The design and the whitebox libraries can each be source, IR or GDS, so this works on a GDS file received from someone else. For each blackbox:

1. It is verified against itself. See Checking blackboxes.
2. It takes the whitebox whose content signature equals the one it recorded. IR and GDS libraries are searched whole. A source library builds what the design's blackboxes need: each blackbox's source cell with the parameters the blackbox records, so a blackbox of Arm with length = 50um (cell Arm$9bfcf147) is rebuilt from cell Arm(length = 20um). A library also builds its default top cells when some blackbox's source cell is not in it.
3. A blackbox that does not verify (part of its metadata lost on the way) is compared with the blackbox its whitebox makes. It is replaced, with a warning, if nothing but lost metadata differs. Anything that is present and differs (a moved pin, a changed attribute) is an error.
4. A cell that lost its record but carries an outline code is matched by that code and compared the same way.
5. Whiteboxes that contain blackboxes are unboxed in turn, through as many libraries as needed.

The replaced cell keeps the name it has in the design, which may be Name$1. What is not replaced is an error, and no output is written:

error: `Splitter` in rev/splitter.lyl does not match blackbox `Splitter`: its content signature is sha256:000f53cc898c instead of sha256:927786961fee (the interface is the same; --allow-revision accepts it)
  - geometry: slab (2/0) is new, 1 other layer(s) the same; 3 cells and 5 shapes, published with 3 and 4

When the record had to be recovered, unbox says so:

unboxed `Splitter` ← splitter.lyl (checked against the whitebox)
warning: blackbox `Splitter`: its metadata is incomplete (attribute `arms`; marker `input`; marker `output`; marker `probe`); it was checked against its whitebox in splitter.lyl instead and matches

Checking blackboxes

laylight blackbox --verify chip.gds

This lists every blackbox of a file (source, IR or GDS), checks each against its record and reports the problems found while reading. It exits with 1 if anything is wrong. Use it before sending a design back, or to find out why unbox refused one.

blackbox `Splitter$1`: verified (source `Splitter`, published as `Splitter`, format 2, by laylight/<version>, content sha256:927786961fee)
chip.gds: 1 blackbox(es) verified, 0 problem(s)

The same check runs at every import and in unbox. It compares the blackbox with its record:

Geometry is compared as regions, not shapes, so a tool that splits, merges, re-cuts or reorders polygons (as KLayout does on writing) changes nothing.

Reading a GDS file adds the problems only the file shows, with the cell they are in:

What survives other tools

The record

In IR, the record is one line of the cell:

cell Splitter source=Splitter {
  blackbox format=2 name=Splitter dbu=1nm scheme=1 footprint=(0,-2000,45000,2000) interface=sha256:2a90…986b content=sha256:9277…60a4 generator=laylight/<version> parts=name:f129624f3195,source:3208d01fe7d0,dbu:694243990533,footprint:36401866f140,attr.arms:cdd8c1adb3f7,marker.input:fbf189af9a77,marker.output:de951e042640,marker.probe:c5b8460845a9,layer.1/0:7cacc578f8d2,cells:3,shapes:4
  attr arms 2
  polygon blackbox (0,-2000) (45000,-2000) (45000,120) …
  box blackbox 22291 -1097 22304 -1084
  …
  polygon marker (-250,-250) (0,-250) (250,0) (0,250) (-250,250)
  marker input (0,0,0deg) {direction="input", xsection=strip, width=500nm, type="waveguide"}
  …
}

Where the record is kept

In GDS, a blackbox carries its record in these places. They are read together, and copies that disagree are an error.

The writer refuses to write a blackbox whose metadata it would have to drop. Other cells keep the old behavior: a value longer than 126 bytes is left out with a warning.

GDSII limits the properties of one element to 128 bytes in total. The cell metadata and record text exceed that, as Laylight's cell metadata always has. KLayout, gdstk and gdsfactory read them; the record text's string and the outline code do not depend on properties.

The outline code

The outline code is the content signature drawn into the outline, so a blackbox that lost every text can still be matched with its whitebox. It is a grid of 16 columns by 18 rows. The 32 bytes of the digest are followed by 4 check bytes: the first 4 bytes of the SHA-256 of laylight.outline-code 1\n and the digest. Bits are taken most significant first, row by row from the bottom. A set bit is a square, half a grid cell wide, centered in its grid cell; a clear bit is nothing.

The grid's position depends on the footprint alone. Let s be the arrow's size (60% of the footprint's shorter side) and (cx, cy) the footprint's center. Grid cells are 0.01125 s wide, and the grid's lower left corner is at (cx − 0.09 s, cy − 0.46 s), inside the arrow's shaft and clear of the outline. A bit is read by testing whether the center of its grid cell is covered, so squares that a tool merges, splits or turns into polygons read the same. The check bytes keep other geometry from being taken for a code.

Grid cells must be at least 2 DBU, so footprints whose shorter side is under 297 DBU (0.3 µm at 1 nm) carry no code; they rely on the texts.

Signatures

Signatures are SHA-256 digests of a canonical text of the IR, written sha256: and 64 hex digits. The text is the same whether a cell was evaluated from source, read from IR or read back from GDS. Shapes are taken as GDS keeps them, lists are sorted, numbers are rounded to 1e-6, and what GDS does not keep (instance names, connections) is left out.

A blackbox can recompute its interface signature from itself, which catches edits to it. The signatures match blackboxes with whiteboxes and guard against mix-ups. They are not cryptographic signatures of an author: anyone can compute them for any layout.