CBOLD Reference: Basic Capabilities

Coolquest, Inc.

C⁺⁺BOLD Reference Manual

11.1.2. Basic Capabilities

Because the part file format is rather intuitive, examining example part files may be the best way to become familiar with the basic capabilities of pt_to_h.

A general understanding of the processing pt_to_h performs is also helpful. pt_to_h parses the part file into lines, tokens and comments. The tables in this and the next section list pre-defined tokens. Some tokens, such as the names of parts and ports, are not pre-defined.

pt_to_h maintains a state variable called the context. The initial context is Global. As the part file is parsed, the context changes when certain tokens are encountered:

Some tokens are restricted to appear only in certain contexts. The restrictions are tabulated in the token tables below.

In addition to checking the part file for legal syntax, pt_to_h makes numerous checks in an attempt ensure a valid output file. For example, pt_to_h checks that:

part names are unique within the file

port names are unique within a part

pin names are unique within a part

the specified pin count matches the number of pins listed in port declarations

When pt_to_h detects an error, it prints an error message that identifies the offending line and token. In general, unless noted otherwise, the error should be assumed to be in the source file. A special message will be printed if the error is in a file included via the -i command line flag.

Basic Tokens

Token	Parameters	Legal Contexts	Description
$PART_NAME	part name	Global	Specifies a part name and begins a Part Block.
$FOOTPRINT $JEDEC_TYPE	layout footprint	Part	Specifies, for the current part, the footprint to be passed to the CAD system in the layout netlist.
$REF_PREFIX	reference prefix	Part	Specifies the reference prefix for the current part
$PIN_COUNT	number of pins	Part	Specifies the number of pins for the current part. This number is used to verify that all pins have been specified.
$PORTS $IPORTS $OPORTS $IOPORTS	port declarations	Part	Begins/continues a Ports Block and specifies the type of ports (in/out/io/nonspecified) in the following port declarations. A Part Block typically has one Ports Block (terminated with $ENDPORTS) containing one or more of these tokens. The format of the port declarations is described below.
[ : ] ;		see -->	Used in port declarations (discussed below).
$ENDPORTS		Ports	Terminates a Ports Block.
$ENDPART		Part	Terminates a Part Block.
//		see -->	Begins an end-of-line comment (discussed below).
/*		see -->	Begins a block comment (discussed below).

Port declarations specify the name and type of each port as well as the pin(s) connected to the port. A port declaration may only be made within a Ports Block. The declaration begins with the port's name, which is optionally followed by a pin count or range within square brackets. The declaration continues with a list of the port's pin(s), and concludes with a semicolon. The pins can contain any alphanumeric character as well as the underscore. CBOLD supports three port forms:

Port Form	Declaration Example	Description
single-pin port	CE_N 22;	A port that has only one associated pin.
multi-pin port (bus)	A[5:0] 13 11 9 5 3 1;	A port that has a range and pin(s) associated with the range. The two numbers in brackets are the range. The pins must be listed in order corresponding to the range. In the declaration example, A(5) is associated with pin "13", A(4) with pin "11", etc.
multi-pin node	GND[4] 6 7 18 19;	A port that has two or more pins, all of which are to be connected together electrically. The number in brackets is the number of pins in the node. *1

*1. If a design connects a multi-pin node to the no-connect net, then in the CAD netlist the pins will not be connected to each other or to any other pins. It is not unusual for parts to have no-connect or do-not-connect pins. These pins must not be omitted from the part file. The Style Guide recommends that they be declared in a single port named NC.

The only difference between the $PORTS, $IPORTS, $OPORTS, and $IOPORTS port declaration tokens is the type used to declare the port in the destination file: port, iport, oport, and ioport, respectively. In general, $PORTS is preferred for all ports, because CBOLD does not contain an electrical rules checker. I.e., the type of the port declaration is irrelevant unless the user has provided custom code that relies on port types. Each of the four port declaration tokens remains in effect until either (1) another port declaration token is encountered or (2) the $END_PORTS token is encountered.

End-of-line comments begin with two forward slashes as in C++. All characters following the // will be ignored, except that in some cases the entire comment will be copied to an appropriate place in the destination file. pt_to_h performs the comment copy when an end-of-line comment is found on the same line as these tokens:

$PART_NAME

$FOOTPRINT

$JEDEC_TYPE

$REF_PREFIX

Block comments are like C++ block comments. They begin with /* and end with */. All text within the block comment is ignored. In general, end-of-line comments are preferred for most comments, but block comments are convenient for commenting out large blocks of text.

Some tokens cause one or more lines to be processed without parsing. Unexpected behavior may result if a block comment is used in conjunction with these tokens. When in doubt, do not use block comments when these tokens are in effect:

#

$BASE_CLASS

$PART_LINES

$REGISTER

$CONSTRUCTOR

$INSERT