[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6. File Formats

All files used by Pcb are read from the standard output of a command or written to the standard input of one as plain seven bit ASCII. This makes it possible to use any editor to change the contents of a layout file. It is the only way for element or font description files to be created. To do so you'll need to study the example files `example/*' and `default_font' which are shipped with Pcb. For an overview refer to 1. Introduction.

The following sections provide the necessary information about the syntax of the files. Netlist files are not created by Pcb, but it does use them. For information on the format of a netlist file see the :rn, 3. User Commands. Rat lines are added on the current layer using the current The commands described allow you to add almost any additional functionality you may need. Examples are compressed read and write access as well as archives. The commands themselves are defined by the resources elementCommand, fileCommand, fontCommand, libraryCommand, libraryContentsCommand and saveCommand. Note that the commands are not saved along with the data. It is considered an advantage to have the layout file contain all necessary information, independent of any other files.

One thing common to all files is they may include comments, newlines, and carriage returns at any place except within quoted strings.

6.1 Basic Types  Basic types used by all data files.
6.2 Layout File Format  
6.3 Element File Format  
6.4 Font File Format  
6.5 Netlist File Format  
6.6 Library Contents File Format  
6.7 Library File Format  


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.1 Basic Types

Here are the basic type definitions used in the other sections of this chapter.

 
Description     = Name
DeltaAngle      = Number
DrillingHole    = Number
Flags           = Number
FontPosition    = Number
Grid            = Number
GridOffsetX     = Number
GridOffsetY     = Number
Group           = GroupMember [,GroupMember]...
GroupMember     = decimal | [cs]
GroupString     = """ Group [:Group]... """
StyleString	= """ Style [:Style]... """
Height          = Number
LayerNumber     = Number
LayoutName      = Name
Name            = quoted_string
Number          = decimal | hex
PinNumber	= quoted_string
Spacing         = Number
StartAngle      = Number
SymbolID        = Number | charconst
Thickness       = Number
TextData        = quoted_string
TextFlags       = Flags
TextScale       = scale
TextX           = Number
TextY           = Number
Value           = Name
Width           = Number
X               = Number
X1              = Number
X2              = Number
Y               = Number
Y1              = Number
Y2              = Number
charconst       = "'" <any character> "'"
comment         = "#" {<any character up to a newline>}...
decimal         = [0-9]+
direction       = [0-3]
hex             = 0x[0-9a-fA-F]+
scale           = [1-<positive integer>]
quoted_string   = """ <anything except \n and \r> """
zoom            = [0-MAX]


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.2 Layout File Format

The layout file describes a complete layout including symbols, vias, elements and layers with lines, rectangles and text. This is the most complex file of all.

 
File            = Header Font PCBData
Header          = PCBName [GridData] [CursorData] [PCBFlags] [Groups]
PCBName         = "PCB(" Name Width Height ")"
GridData        = "Grid(" Grid GridOffsetX GridOffsetY ")"
CursorData      = "Cursor(" X Y zoom ")"
PCBFlags        = "Flags(" Flags ")"
Groups          = "Groups(" GroupString ")"
Styles		= "Styles(" StyleString ")"
Font            = {FontData}...
FontData        = {Symbol}...
Symbol          = "Symbol(" SymbolID Spacing ")"
                      "(" {SymbolData}... ")"
SymbolData      = {SymbolLine}...
SymbolLine      = "SymbolLine(" X1 Y1 X2 Y2 Thickness ")"
PCBData         = {Via | Layer | Element}...

Via             = "Via(" X Y Thickness DrillingHole Name Flags ")"

Element         = "Element(" Flags Description LayoutName Value \
                      TextX TextY direction scale TextFlags")"
                      "(" {ElementData}... [Mark] ")"
ElementData     = {ElementLine | Pad | Pin | ElementArc }...
ElementArc      = "ElementArc(" X Y Width Height
                      StartAngle DeltaAngle Thickness ")"
ElementLine     = "ElementLine(" X1 Y1 X2 Y2 Thickness ")"
Mark            = "Mark(" X Y ")"
Pad             = "Pad(" X1 Y1 X2 Y2 Thickness Name PinNumber Flags")"
Pin             = "Pin(" X Y Thickness DrillingHole Name PinNumber Flags ")"

Layer           = "Layer(" LayerNumber Name ")"
                      "(" {LayerData}... ")"
LayerData       = {Line | Polygon | Text}...
Line            = "Line(" X1 Y1 X2 Y2 Thickness Flags")"
Arc		= "Arc(" X Y Width Height StartAngle DeltaAngle Thickness Flags")"
Polygon         = "Polygon(" Flags ")" \
                      "(" {Points}... ")"
Points          = "(" X Y ")"
Text            = "Text(" X Y direction scale TextData Flags")"

`PCBName'
is used to define the layout's name which is independent of its filename. It is displayed in the lower left corner of the main window.

`GridData'
is optional and is used to save the grid setting and offset which were set at the time the layout was saved.

`CursorData'
also is an optional parameter to save the last cursor location and zoom value. The real zoom factor is calculated by scale = 1:(2 power value).

`PCBFlags'
determine how to draw lines and which name of the elements should be displayed.
 
    bit 4:  do rubberband moves and rotates if set
    bit 5:  display description of elements if set
    bit 6:  display unique name of an element if set
    bit 7:  use absolute grid if set
    bit 8:  don't clip lines to 45 degrees

`Groups'
Layergroups are saved by using this optional parameter. The only way of changing them is to use an editor and alter the appropriate line. The characters c,s idenify the component- and solder-side for SMD objects.

`Symbol'
See the description of font files in this chapter.

`Via'
Vias are always connected to all layers which also means vias are one logical level ahead of layers. Vias are defined by position, size, name and by some flags.
 
    bit 0:  always clear
    bit 1:  always set
    bit 2:  set if via was found during a connection search
    bit 4:  set if via is a hole (has no copper annulus)
    bit 5:  display the vias name
    bit 6:  via has been selected
    bit 12: set if via has octagonal shape
    Other bits have special meaning and should not be changed
    by the user.  See const.h for more information

`Element'
See the description of element files in this chapter.

`Layer'
A layer is the central object from the user's point of view. It holds all connections and all text objects. Up to 8 may be used individually. Its number, starting with one, and its name are read as arguments.

`Line'
All lines are identified by their start and endpoints together with their thickness and some flags. They have to fit a 45 degree scheme.
 
    bit 2:  set if line was found during a connection search
    bit 4:  line is a rat-line
    bit 6:  line has been selected

`Polygon'
used to fill a larger area with `copper'. The coordinates specify the corners. The flags are:
 
    bit 2:  set if polygon was found during a connection search
    bit 4:  polygon is a 1.5 style polygon that automatically clears pins
    bit 6:  polygon has been selected

`Text'
You may use text objects to add information to your board. An example would be naming a connector or marking pin one of it. The position marks the lower left corner of the string which is also a fixpoint for rotations. Text directions are independent to those of lines. They are counted from zero to three with a meaning of zero to 270 degree rotations counter-clockwise. The scaling value is a positive integer which determines a zoom factor in percent.
 
    bit 6:  the text has been selected
    bit 7:  the text is on the solder (back) side of the board
    bit 10: the text is on the silkscreen layer


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.3 Element File Format

Element files are used to describe one component which then may be used several times within one or more layouts. You will normally split the file into two parts, one for the pinout and one for the package description. Using m4 allows you to define pin names as macros in one file and include a package description file which evaluates the macros. See the resource elementCommand for more information. The pins (and pads) must appear in squential order in the element file (new in 1.5) so that pin 1 must be the first PIN(...) in the file.

Doing things this way makes it possible to use one package file for several different circuits. See the sample files `dil*'.

The lowest x and y coordinates of all subobjects of an element are used as an attachment point for the cross hair cursor of the main window.

 
File            = {Element}...
Element         = "Element(" Flags Description LayoutName Value \
                      TextX TextY direction scale TextFlags")"
                      "(" {ElementData}... [Mark] ")"
ElementData     = {ElementLine | Pad | Pin | ElementArc }...
ElementArc      = "ElementArc(" X Y Width Height
                      StartAngle DeltaAngle Thickness ")"
ElementLine     = "ElementLine(" X1 Y1 X2 Y2 Thickness ")"
Mark            = "Mark(" X Y ")"
Pad             = "Pad(" X1 Y1 X2 Y2 Thickness Name PinNumber Flags ")"
Pin             = "Pin(" X Y Thickness DrillingHole Name PinNumber Flags ")"

`Element'
Objects of type element are determined by flags, some names, a canonical and a layout name as well as a value. Additional fields are text position, their direction counted from zero to three (n * 90 degrees counter-clockwise) and element data.

`Flags'
The flag field determines the state of an element. The bit values are:
 
    bit 4:  the element name is hidden
    bit 6:  element has been selected
    bit 7:  element is located on the solder side

`TextFlags'
`scale'
`direction'
See the description of text object earlier in this chapter.

`ElementLine'
A line is defined by its start and end points and by its size, or width.

`ElementArc'
Defines an arc by its center, width, height, startangle, its length in degrees and its size. Remember the y axis on the screen grows downwards.

`Mark'
is just a hint to make positioning easier. The cross hair will be positioned here. Its center is passed as the two arguments.

`Pad'
A pad is very similar to a line except it may not be disconnected from its element and it has an associated name. Is is defined by two end point position, size, name and by some flags.
 
    bit 2:  set if pad was found during a connection search
    bit 5:  display the pads name
    bit 6:  pad has been selected
    bit 7:  pad is located on the solder side

`Pin'
A pin is very similar to a via except it may not be disconnected from its element.
 
    bit 0:  always set
    bit 1:  always clear
    bit 2:  set if pin was found during a connection search
    bit 3:  set if pin is only a mounting hole (no copper annulus)
    bit 5:  display the pins name
    bit 6:  pin has been selected
    bit 8:  pin is drawn as a square
    bit 12: set if pin is drawn with an octagonal shape


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.4 Font File Format

A number of user defined symbols are called a font. There is only one per layout. All symbols are made of lines. See the file `default_font' as an example.

The lowest x and y coordinates of all lines of a font are transformed to (0,0).

 
File            = Font
Font            = {FontData}...
FontData        = {Symbol}...
Symbol          = "Symbol(" SymbolID FontPosition ")"
                      "(" {SymbolData}... ")"
SymbolData      = {SymbolLine}...

`Symbol'
The two arguments are the ASCII code of the symbol and its distance to the next symbol. Undefined symbols are drawn as filled rectangles. The ASCII code may be passed as a character constant or as a hexadecimal value.

`SymbolLine'
The symbol data itself is made up of several entries of type SymbolLine.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.5 Netlist File Format

Netlists read by Pcb must have this simple text form:

 
netname [style] NAME-PINNUM NAME2-PINNUM2 NAME3-PINNUM3 ... [\]

for each net on the layout. where "netname" is the name of the net which must be unique for each net, [style] is an optional route-style name, NAME is the layout-name name given to an element, and PINNUM is the (usually numeric) pin number of the element that connects to the net (for details on pin numbering see 1.3 Elements). Spaces or tabs separate the fields. If the line ends with a "\" the net continues on the next line and the "\" is treated exactly as if it were a space. If a NAME ends with a lower-case letter, all lower-case letters are stripped from the end of the NAME to determine the matching layout-name name. For example:

 
     Data U1-3 U2abc-4 FLOP1a-7 Uabc3-A9

specifies that the net called "Data" should have pin 3 of U1 connected to pin 4 of U2, to pin 7 of FLOP1 and to pin A9 of Uabc3. Note that element name and pin number strings are case-sensitive. It is up to you to name the elements so that their layout-name names agrees with the netlist.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.6 Library Contents File Format

There is nothing like a special library format. The ones that have been introduced in 1.4.1 just use some nice (and time consuming) fetures of GNU m4. The only predefined format is the one of the contents file which is read during startup. It is made up of two basic line types:

 
menu entry      = "TYPE="name
contents line   = template":"package":"value":"description
name            = String
template        = String
package         = String
value           = String
description     = String
String          = <anything except ":", "\n" and "\r">

No leading whitespaces or comments are allowed in this file. If you need either one, define a command that removes them before loading. Have a look to the libraryContentsCommand resource.

The menu entry will appear in the selection menu at the top and of the library window.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.7 Library File Format

This section provides an overview about the existing m4 definitions of the elements. There are basically two different types of files. One to define element specific data like the pinout, package and so on, the other to define the values. For example the static RAM circuits 43256 and 62256 are very similar. They therefore share a common definition in the macro file but are defined with two different value labels.

The macro file entry:

 
define(`Description_43256_dil', `SRAM 32Kx8')
define(`Param1_43256_dil', 28)
define(`Param2_43256_dil', 600)
define(`PinList_43256_dil', ``pin1', `pin2', ...')

And the list file:

 
43256_dil:N:43256:62256

The macro must define a description, the pin list and up to two additional parameters that are passed to the package definitions. The first one is the number of pins whereas the second one defines for example the width of a package.

It is very important to select a unique identifier for each macro. In the example this would be 43256_dil which is also the templates name. It is required by some low-level macros that Description_, Param1_, Param2_ and PinList_ are prepended.

The list file uses a syntax:

 
template:package:value[:more values]

This means that the shown example will create two element entries with the sam package and pinout but with different names.

A number of packages are defined in `common.m4'. Included are:

 
DIL packages with suffix D, DW, J, JD, JG, N, NT, P
PLCC
TO3
generic connectors
DIN 41.612 connectors
zick-zack (SD suffix)
15 pin multiwatt

If you are going to start your own library please take care about m4 functions. Be aware of quoting and so on and, most important check your additional entry by calling the macro:

 
CreateObject(`template', `value', `package suffix')

If quoting is incorrect an endless loop may occur (broken by a out-of-memory message).

The scripts in the `lib' directory handle the creation of libraries as well as of their contents files. Querying is also supported.

I know quite well that this description of the library implementation is not what some out there expect. But in my opinion it's much more useful to look at the comments and follow the macros step by step.


[ << ] [ >> ]           [Top] [Contents] [Index] [ ? ]

This document was generated by Build Daemon user on November, 19 2004 using texi2html