Non-graphical sheets

Sometimes a design is easier specified by text than drawing. Typical examples:

"wiring diagram": there are two large-pin-number components, e.g. two connectors and a bunch of connections between them (not necessary 1-to-1 wiring)
"breakout boards": large pin number central component and mostly 1-to-1 wiring to other, smaller pin number components (e.g. connectors).
"fpga", "ram": multiple large pin number components, with a lot of 1-to-1 connections (that would often have the same name as the terminal on both ends, by the way); for example when connecting ram to a CPU: D0..D16, A0..A20, etc.

Non-graphical sheets are implemented in plugins and provide different methods and syntax for specifying abstract components, abstract networks and their relations. The cschem compiler can use this as an input on the same level as a graphical sheet. That means, a non-graphical sheet can be an Nth sheet in a multisheet project. For example draw the power and analog parts on graphical sheets and have the 28 pin parallel bus connections to the CPU, ram, I/O chips and connectors specified in one more more non-graphical sheet in the same project.

Below are different methods and syntax to describe non-graphical sheets.

tEDAx (declarative)

tEDAx is very easy to parse, well specified, and is relatively easy to read and write as human. Implemented by io_ngrp_tedax.

Here are a few small examples, all describing the same "7805 with 2 bypass caps" circuit using different approaches:

small1.tdx: component-centric
small2.tdx: network-centric
small21.tdx: mixture of component-centric and network-centric
small3.tdx: compact, netlist-like

These are not different sets of syntax, but they are all just different usage and combination of the same few blocks that are all available. As a proper declarative description, order of blocks or order of attributes/connections within a block doesn't matter.

The verbose versions are perhaps more practical if there are a lot of attributes to specify. The compact version is more practical for listing a lot of connections and few attributes.

Another way of mixing different blocks is big32.tdx, which is an imaginary CPU board with 2 SRAM chips, an I/O chip and an extension port. It uses the verbose component description for the chips and capacitors, also connects power and gnd there and then uses the compact, table-like description for the address/data/control networks. It's also an example of combining graphical and non-graphical sheets: U5 is a network of gates that controls chip-select; it's better drawn for clarity.

Summary of blocks:

block description cschem_acomp name create a new (abstract) component; name is the name of the component (e.g. "R17"); can add component attributes and create connections from ports of the component to nets cschem_anet name create a new (abstract) network; name is the name of the net (e.g. "Vcc"); can add net attributes and create connections from the net to ports of components cschem_acompact compact syntax that can describe both components and nets, multiple of them

block	description	cschem_acomp name	create a new (abstract) component; name is the name of the component (e.g. "R17"); can add component attributes and create connections from ports of the component to nets	cschem_anet name	create a new (abstract) network; name is the name of the net (e.g. "Vcc"); can add net attributes and create connections from the net to ports of components	cschem_acompact	compact syntax that can describe both components and nets, multiple of them

Content of a cschem_acomp block: each line is one of these:

if first field is a dash, the second field is a port number of the current component and the third field is the name of a net; e.g. "- 4 Vcc" will connect port 4 to the Vcc net
else the first field is an attribute key and the rest of the fields is an attribute value; e.g. "footprint 1206" adds a footprint=1206 attribute to the current component; or "comment hand solder" adds a comment=hand solder

Content of a cschem_anet block: each line is one of these:

if first field is a dash, the second field is a component name and the third field is a port name; e.g. "- U12 4" will connect the current net to port 4 of component U12
else the first field is an attribute key and the rest of the fields is an attribute value; e.g. "current 250mA" adds a current=250mA attribute to the current net; or "comment do not cover with mask" adds a comment=do not cover with mask

Content of a cschem_acompact block: each line is one of these:

line description comp cname [attrs...] create a new (abstract) component; cname is the name of the component (e.g. "R17"); followed by zero or more attributes (see below) net nname [attrs...] create a new (abstract) network; nname is the name of the net (e.g. "Vcc"); followed by zero or more attributes (see below) conn nname ports... creates one or more connections from the network called nname to ports (see below)

line	description	comp cname [attrs...]	create a new (abstract) component; cname is the name of the component (e.g. "R17"); followed by zero or more attributes (see below)	net nname [attrs...]	create a new (abstract) network; nname is the name of the net (e.g. "Vcc"); followed by zero or more attributes (see below)	conn nname ports...	creates one or more connections from the network called nname to ports (see below)

Attrs are specified in key=value syntax, e.g. footprint=1206. If key or value contains whitespace, it needs to be escaped, as per tEDAx syntax, using backslash.

Ports are specified in a comp=port syntax, e.g. U12=4 for port 4 of component U12. If component or port name contains whitespace, it needs to be escaped, as per tEDAx syntax, using backslash.

fawk (Turing-complete)

In some cases parts of the design can be specified using repetitive patterns. An easy way to handle this is to write a script that generates a graphical sheet or a non-graphical sheet using a declarative syntax.

If that script is written in fawk, sch-rnd can run it without having to generate and parse the declarative intermediate. Implemented by io_ngrp_fawk. This feature is limited to fawk because:

fawk is always available in librnd
fawk supports execution limit and memory allocation limit so opening a non-graphical sheet specified as a fawk script is safe, an attacker won't be able to force sch-rnd into an infinite loop or into allocating all system memory.

A simple example script, r2r.fawk generates 5 bits of the classic R2R DAC. It can be configured by changing the values in main().

The script doesn't emit a netlist or declarative tEDAx non-graphical sheet. The result can be observed in sch-rnd by loading only the fawk script as a sheet and using the abstract model dialog.

(An alternative is implementing the cschem functions locally, as vararg fawk functions and make them print to stdout using fawk_print(). Then the script can be ran and debugged independently of cschem, using the example libfawk command line interpreter.)

Functions provided by sch-rnd:

function description
acomp_attr(name, key, val, ...); create a component by name, or add to existing component by that name; add key=val pairs of attributes; this is a vararg function, accepting zero or more key,val pairs.
anet_attr(name, key, val, ...); create a network by name, or add to existing network by that name; add key=val pairs of attributes; this is a vararg function, accepting zero or more key,val pairs.
aconn(netname, compname, termname, ...); create a network by netname, or extend existing network by that name; connect terminal(s) addressed by (compname-termname); this is a vararg function, accepting one or more compname,termname pairs.

function	description
acomp_attr(name, key, val, ...);	create a component by name, or add to existing component by that name; add key=val pairs of attributes; this is a vararg function, accepting zero or more key,val pairs.
anet_attr(name, key, val, ...);	create a network by name, or add to existing network by that name; add key=val pairs of attributes; this is a vararg function, accepting zero or more key,val pairs.
aconn(netname, compname, termname, ...);	create a network by netname, or extend existing network by that name; connect terminal(s) addressed by (compname-termname); this is a vararg function, accepting one or more compname,termname pairs.