The GDSII Stream Format

See also, for download: stream_utils

Jim Buchanan
6/11/96

---------------------------------------------------------------
------------

This file is for use by people having

experience with GDSII format stream
files and the CAD systems that read/write
them. It won't make a lot of sense
without that background.

Since knowing the library structure without

knowing about records and data
types would be of marginal use, and
knowing about records and data types
without knowing about the library structure
would be worse, you might have
to scan through this s few times before it
makes sense.

Beyond that, let me say that the stream

format is quite simple. I suspect
that the people at Calma put a lot of thought
into creating a file that
would be as easy to read in and parse as
possible.

I suspect that they did this due to the

modest computers that they had to
work with. Their results were impressive
here and with the GDSII system as a
whole. A bit dated now, but in its day...

Speaking of dated, Stream Format allows

records to be written out to
multiple reels of tape. Handy on those old 9
track drives. When a file was
written to a tape, it was written in 2048 byte
physical blocks. The file was
padded with NULL characters so that it was
always a multiple of 2048 bytes.

I've noticed that some (OK, many) stream

files that were originally written
to disk using more modern software also pad
the file to a multiple of 2048
bytes using NULL characters.

---------------------------------------------------------------
------------

A stream file consists of records.

These records are built up of 16 bit words.

This means that all stream files
should have an even number of bytes.

The first two words, or four bytes, are called

the "Record Header"

A record can be as small as 4 bytes long.

The GDSII Stream format manual
says that a record may be infinitely long, but
frankly, I don't see how it
can get over 65535 bytes long, since the
first two bytes of the record
header are an unsigned integer that defines
the length of the record. The
leftmost bit of the first byte is valued at
32768, the rightmost bit of the
second byte is valued at 1.

The third byte is the record type. This will

tell what part of the library
this record describes. There are values for
such things as the beginning of a
structure, the beginning of a boundary, the
end of a structure, and so on.
There is a section below with hexadecimal
values of the various record types
and a brief description of the types.

The fourth, and last, byte in the record

header is the data type. This,
along with the record length, tells the parser
what to expect in the rest of
the record. There may be more than one
piece of data, but the rest of the
record will be of this type. You can tell how
many pieces of data are in the
record by knowing the number of bytes in
the record and the size of the data
type.

Actually, the data type seems redundant,

since each record type has only one
valid data type. Perhaps the Calma people
were thinking of future needs?
They sure did that with the layer numbers
and data types. Calma allowed only
64 layers and data types, but the Stream
Format has room for 65535 of each.

---------------------------------------------------------------
------------

There are seven data types listed in the

GDSII Stream Format Manual v6.0,
one is listed as not being used at the time. I
doubt anyone has had the
chutzpah to start using it since.
The first is "No data present". The code is
0x00. This means that the entire
record is 4 bytes long. An example of an
element with no data would be
ENDLIB which marks the end of a library.

The second is called a "Bit array". The code

is 0x01. It's simply two bytes.
The meaning of each bit depends on the
record type that the bit array is
found in.

The third data type is a "Two-Byte Signed

Integer". The code is 0x02. It is
an integer between -32768 and 32767. It is
stored in twos complement format,
with the most significant byte first.

Some examples from the book:

0x0000 = 1
0x0020 = 2
0x0089 = 137
0xffff = -1
0xfffe = -2
0xff77 = -137

The fourth data type is a "Four-Byte Signed

Integer". The code is 0x03. Same
basic thing as a two byte integer, but with
four bytes.

The fifth data type is the "Four-Byte Real".

The code is 0x04. This is the
one that seems to have never been used, so
I'll describe the eight byte real
in a bit more detail.
Basically though, the first bit is the sign (1 =
negative), the next 7 bits
are the exponent, you have to subtract 64
from this number to get the real
value. The next three bytes are the
mantissa, divide by 2^24 to get the
denominator.

value = (mantissa/(2^24)) * (16^(exponent-

64))

In the above, we use the actual values of the

fields in the stream file for
the mantissa and exponent.

The sixth data type is the "Eight Byte Real".

The code is 0x05. This one
gets a little more use.

The first (most significant) bit of the first

byte is the sign, one means
negative, 0 means positive.

The 7 least significant bits of the first byte

are the exponent in "excess
64" notation. You must subtract 64 to get
the true value. I'll show the
subtraction in the formula below.

The remaining 7 bytes are the mantissa,

with a binary point to the left of
the most significant figure. The formula
below uses the unsigned integer
value of these 7 bytes as the numerator of a
fraction.

value = (mantissa/(2^56)) * (16^(exponent-

64))
The seventh and final data type is the "ASCII
String". The code is 0x06. The
length of this string is always equal to the
length of the record minus the
four bytes used for the record header. If this
number is not even, a NULL
character (0x00) is added to the end. This is
another artifact of the 16 bit
words that the stream file format assumes.

---------------------------------------------------------------
------------

This is the format of a stream file. The

records shown within square
brackets '[]' are optional. The or bar '|'
indicates one or the other.
The structure '{}+' is used to indicate one or
more instances.
The angle brackets '<>' indicate that further
definition is below. Sort of an
"include" element.

The actual stream file:

HEADER
BGNLIB
[LIBDIRSIZE]
[SRFNAME]
[LIBSECUR]
LIBNAME
[REFLIBS]
[FONTS]
[ATTRTABLE]
[GENERATIONS]
[FORMAT | FORMAT {MASK}+ ENDMASKS]
UNITS
[{BGNSTR STRNAME [STRCLASS]
[{<element>}+] ENDSTR}+]
ENDLIB

An element portion of a stream file:

<boundary> | <path> | <sref> | <aref> |

<text> | <node> | <box>
[{PROPATTR PROPVALUE}+]
ENDEL

Boundary portion of an element:

BOUNDARY
[ELFLAGS]
[PLEX]
LAYER
DATATYPE
XY

Path portion of an element:

PATH
[ELFLAGS]
[PLEX]
LAYER
DATATYPE
[PATHTYPE]
[WIDTH]
[BGNEXTN]
[ENDEXTN]
XY

SREF portion of an element:

SREF
[ELFLAGS]
[PLEX]
SNAME
[STRANS [MAG] [ANGLE]]
XY
AREF portion of an element:

AREF
[ELFLAGS]
[PLEX]
SNAME
[STRANS [MAG] [ANGLE]]
COLROW
XY

Text portion of an element:

TEXT
[ELFLAGS]
[PLEX]
LAYER
TEXTTYPE
[PRESENTATION]
[PATHTYPE]
[WIDTH]
[STRANS [MAG] [ANGLE]]
XY
STRING

Node portion of an element:

NODE
[ELFLAGS]
[PLEX]
LAYER
NODETYPE
XY

Box portion of an element:

BOX
[ELFLAGS]
[PLEX]
LAYER
BOXTYPE
XY

---------------------------------------------------------------
------------

A stream file may be broken up over

multiple reels of tape. I haven't seen
this since the days of 9 track tapes on reels,
but just in case, here we
go...

Tape 1:

HEADER
several complete stream records
TAPENUM
TAPECODE
LIBNAME

Intermediate tape(s):

TAPENUM
TAPECODE
LIBNAME
more complete stream records
TAPENUM

last tape:

TAPENUM
TAPECODE
LIBNAME
more complete stream records
ENDLIB

A concatenation of all of the tapes, without

the tape id stuff (and I
presume w/o the extra LIBNAMEs) should be
a valid stream file as described
above.

---------------------------------------------------------------
------------

OK, here's the part you've been waiting for,

what the records mean...

Record type Data type

0x00 HEADER 0x02 INTEGER_2 Start of

stream, contains version number of
stream file.
< v3.0 0x0000 0
v3.0 0x0003 3
v4.0 0x0004 4
v5.0 0x0005 5
v6.0 0x0258 600

0x01 BGNLIB 0x02 INTEGER_2

Beginning of library, plus mod and access
dates.
Modification:
year, month, day, hour,
minute, second
Last access:
year, month, day, hour,
minute, second

0x02 LIBNAME 0x06 STRING The name

of the library, supposedly following
Calma DOS
conventions. Using later tools,
such as ISS LTL-100, it
seems more flexible
 than that, but it won't
allow any old thing
you want. If memory
serves, Calma DOS allowed
6 characters in a file
name, with a 2
character extension.

0x03 UNITS 0x05 REAL_8 Size of db

unit in user units, size of db
unit in meters. To
calculate the size of
a user unit in meters,
divide the second
number by the first.

0x04 ENDLIB 0x00 NO_DATA End of the

library.

0x05 BGNSTR 0x02 INTEGER_2 Begin

structure, plus create and mod dates in
the same format as the
BGNLIB record.

0x06 STRNAME 0x06 STRING Name of

a structure. Up to 32 characters in
GDSII, A-Z, a-z, 0-9,
_, ?, and $ are all
leg
al characters.

0x07 ENDSTR 0x00 NO_DATA End of a

structure.

0x08 BOUNDARY 0x00 NO_DATA The

beginning of a BOUNDARY element.

0x09 PATH 0x00 NO_DATA The

beginning of a PATH element.
0x0a SREF 0x00 NO_DATA The
beginning of an SREF element.

0x0b AREF 0x00 NO_DATA The

beginning of an AREF element.

0x0c TEXT 0x00 NO_DATA The

beginning of a TEXT element.

0x0d LAYER 0x02 INTEGER_2 Layer

specification. On GDSII this could be
0 to 63, LTL allows 0 to
255. Of course a
3 byte integer allows
up to 65535...

0x0e DATATYPE 0x02 INTEGER_2

Datatype specification. On GDSII this could
be 0 to 63, LTL allows 0
to 255. Of course a
3 byte integer allows
up to 65535...

0x0f WIDTH 0x03 INTEGER_4 Width

specification, negative means absolute
In data base units.

0x10 XY 0x03 INTEGER_4 An array of

XY coordinates. An array of
coordinates in data
base units.
Path: 2 to 200 pairs in
GDSII
Boundary: 4 to 200
pairs in GDSII
Text: Exactly 1 pair
SREF: Exactly 1 pair
AREF: Exactly 3 pairs
 1: Array reference
point
2:
column_space*columns+reference_x
3:
row_space*rows+reference_y
Node: 1 to 50 pairs in
GDSII
Box: Exactly 5 pairs

0x11 ENDEL 0x00 NO_DATA The end

of an element.

0x12 SNAME 0x06 STRING The name

of a referenced structure.

0x13 COLROW 0x02 INTEGER_2

Columns and rows for an AREF. Two 2 byte
integers. The first is the
number of columns.
The second is the
number of rows. In an AREF
of course. Neither may
exceed 32767

0x14 TEXTNODE 0x00 NO_DATA "Not

currently used" per GDSII Stream Format
Manual, v6.0. Would be
the beginning of a
TEXTNODE element if it
were.

0x15 NODE 0x00 NO_DATA The

beginning of a NODE element.

0x16 TEXTTYPE 0x02 INTEGER_2

Texttype specification. On GDSII this could
be 0 to 63, LTL allows 0
to 255. Of course a
 3 byte integer allows
up to 65535...

0x17 PRESENTATION 0x01 BIT_ARRAY Text

origin and font specification.
bits 15 to 0, l to r
bits 0 and 1: 00 left, 01
center, 10 right
bits 2 and 3: 00 top 01,
middle, 10 bottom
bits 4 and 5: 00 font 0,
01 font 1,
10 font 2, 11
font 3,

0x18 SPACING UNKNOWN

"Discontinued" per GDSII Stream Format
Manual, v6.0.

0x19 STRING 0x06 STRING Character

string. Up to 512 char in GDSII

0x1a STRANS 0x01 BIT_ARRAY Bits 15 to

0, l to r
15=refl, 2=absmag,
1=absangle, others
reserved for future use.

0x1b MAG 0x05 REAL_8

Magnification, 1 is the default if omitted.

0x1c ANGLE 0x05 REAL_8 Angular

rotation factor in ccw direction.
If omitted, the default
is 0.

0x1d UINTEGER UNKNOWN User

integer, used only in V2.0, when
 instreamed, should be
converted to property
attribute 126.

0x1e USTRING UNKNOWN User

string, used only in V2.0, when
instreamed, should be
converted to property
attribute 127.

0x1f REFLIBS 0x06 STRING Names of

the reference libraries. Starts with
name of the first library
and is followed by
the second. There are
44 bytes in each, NULLS
are used for padding,
including filling in an
entire unused field.

0x20 FONTS 0x06 STRING Names of

the textfont definition files. 4 44
byte fields, padded
with NULLS if a field is
unused or less than 44
bytes.

0x21 PATHTYPE 0x02 INTEGER_2 Type of

path ends.
0: Square ended paths
1: Round ended
2: Square ended,
extended 1/2 width
4: Variable length
extensions, CustomPlus
The default is 0
0x22 GENERATIONS 0x02 INTEGER_2
Number of deleted or backed up structures
to
retain. Seems a bit odd
in an archive...
From 2-99, default is 3.

0x23 ATTRTABLE 0x06 STRING Name of

the attribute definition file. Max
size 44 bytes.

0x24 STYPTABLE 0x06 STRING

"Unreleased feature" per GDSII Stream
Format
Manual, v6.0.

0x25 STRTYPE 0x02 INTEGER_2

"Unreleased feature" per GDSII Stream
Format
Manual, v6.0

0x26 ELFLAGS 0x01 BIT_ARRAY Flags for

template and exterior data.
bits 15 to 0, l to r
0=template,
1=external data, others unused

0x27 ELKEY 0x03 INTEGER_4

"Unreleased feature" per GDSII Stream
Format
Manual, v6.0.

0x28 LINKTYPE UNKNOWN

"Unreleased feature" per GDSII Stream
Format
Manual, v6.0.
0x29 LINKKEYS UNKNOWN
"Unreleased feature" per GDSII Stream
Format
Manual, v6.0.

0x2a NODETYPE 0x02 INTEGER_2

Nodetype specification. On GDSII this could
be 0 to 63, LTL allows 0
to 255. Of course a
3 byte integer allows
up to 65535...

0x2b PROPATTR 0x02 INTEGER_2

Property number.

0x2c PROPVALUE 0x06 STRING Property

value. On GDSII, 128 characters max,
unless an SREF, AREF,
or NODE, which may
have 512 characters.

0x2d BOX 0x00 NO_DATA The

beginning of a BOX element.

0x2e BOXTYPE 0x02 INTEGER_2 Boxtype

specification. On GDSII this could be
0 to 63, LTL allows 0 to
255. Of course a
3 byte integer allows
up to 65535...

0x2f PLEX 0x03 INTEGER_4 Plex

number and plexhead flag. The least
significant bit of the
most significant byte
is the plexhead flag.
Because of this, you
ca
n "only" have 2^24 plex groups. Or is that
 2^24-1? I'm not sure if
0 is a valid plex
gro
up in a stream file.

0x30 BGNEXTN 0x03 INTEGER_4 Path

extension beginning for pathtype 4 in
CustomPlus. In
database units, may be
negative.

0x31 ENDTEXTN 0x03 INTEGER_4 Path

extension end for pathtype 4 in
CustomPlus. In
database units, may be
negative.

0x32 TAPENUM 0x02 INTEGER_2 Tape

number for multi-reel stream file.

0x33 TAPECODE 0x02 INTEGER_2 Tape

code to verify that the reel is from the
proper set. 12 bytes
that are supposed to
for
m a unique tape code.

0x34 STRCLASS 0x01 BIT_ARRAY Calma

use only. In stream files created by
non-Calma programs,
this should be missing or
all field should be 0.

0x35 RESERVED 0x03 INTEGER_4 Used to

be NUMTYPES per GDSII Stream Format
Manual, v6.0.

0x36 FORMAT 0x02 INTEGER_2 Archive

or Filtered flag.
 0: Archive
1: filtered

0x37 MASK 0x06 STRING Only in

filtered streams. Layers and
datatypes used for
mask in a filtered stream
file. A string giving
ranges of layers and
datatypes separated by
a semicolon. There may
be more than one
mask in a stream file.

0x38 ENDMASKS 0x00 NO_DATA The

end of mask descriptions.

0x39 LIBDIRSIZE 0x02 INTEGER_2 Number

of pages in library director, a GDSII
thing, it seems to have
only been used when
Calma INFORM was
creating a new library.

0x3a SRFNAME 0x06 STRING Sticks

rule file name.

0x3b LIBSECUR 0x02 INTEGER_2 Access

control list stuff for CalmaDOS,
ancient. INFORM used
this when creating a new
library. Had 1 to 32
entries with group
numbers, user
numbers and access rights.