{des6:0} The abstract model is flat, but the source (the concrete model) from which the abstract model is generated may be hierarchic. Since each object of the flat abstract model remembers which concrete model object(s) it was derived from, the output can again be hierarchical.
{des6:1} In that flat abstract model, there is only one namespace for components and one namespace for networks. The component namespace consists of component names (and uuids), and the network namespace consists of network names (and uids).
{des6:2} Since networks are often referenced by name from the schematics, an auxiliary global namespace is provided for networks that are used in the concrete model, where they are identified by their netname and scope.
{des6:3} A multi page project is called hierarchical if at least one sheet references to another sheet. The system of references forms one or more loop-free trees, each with a single root sheet. The list of root sheets is considered the "top level list of root sheets" or in short, "root sheets" (or "top level sheets") for the project.
{des6:4} Hierarchy affects how networks are created and referenced. When a network is referenced by netname, the reference is either:
{des6:5} If a project contains multiple schematics pages without hierarchical cross-references, its topology is called a multi-page flat project. In other words the top level consists of multiple root sheets but no sheet has references to other sheets. It is possible to connect networks between the pages using global nets.
{des6:6} There is a single root sheet and all other sheets are accessible through sheet references. In other words, the top level consists of only one sheet and that sheet has references to other sheets. This setup can exploit the subtree based netname references. The root sheet is very often a map of the first level sheets and the connections between them.
{des6:7} There are multiple root sheets, some of them with sheet references. In other words, the top level consists of a list of trees. This setup can exploit the subtree based netname references and global nets. The root sheets are often a map of the first level sheets and the connections between them, but there's no explicit map of the root sheet interconnects, only the implicit binding of global networks. Sheets are typically listed in the project file and marked whether they are root sheets or not.
| scope | syntax | description |
|---|---|---|
| global | /netname | visible from anywhere in the hierarchy |
| subtree-local | v/netname | visible only from within a subtree of the hierarchy |
| sheet-local | ./netname | visible only from within the same sheet |
| auto | netname | bind to an existing sheet-local net if available, else to a subtree-local net, else to a global net, else create a new global net |
| subtree-auto | ^/netname | similar to auto, but is looking only for subtree-local (v/) networks - no locals and no globals; when subtree-local net is not found, an error is generated
|
{des6:9} Global nets are accessible from any point from the hierarchy. If a subtree-local or sheet-local network has the same name as a global net, it is shadowing the global net: the auto references will prefer those local networks. However, the global network can always be referenced using the / prefix, which overrides the auto search.
{des6:10}
Global networks are created when first referenced (with the explicit /
prefix syntax or with the auto or subtree-auto syntax).
{des6:11}
A subtree local net can be regarded as a "group local" network, is
visible under a subtree. It is intended to provide a mechanism for creating
a "global net" locked into a local tree of sheets, allowing the tree to
be reused as part of a larger project without introducing interfering global
networks.
{des6:12}
Defining a new subtree-local network is done by using the netname prefix
{des6:13}
A sheet local net is visible only within the same sheet. It is
intended to provide a mechanism for creating a local network in a sheet
that is going to be reused as a part of a hierarchy, without the local
netname interfering with global netnames.
v/; this anchors the netname to the current sheet. Auto netnames from
this sheet and sheets below this sheet will find this network if looking
for a sheet-local network failed. To prefer the nearest subtree-local
network over local networks, the subtree-auto ^/ prefix can be
used: this will start walking up in the hierarchy to find the closest
subtree-local net of matching netname. If that fails and the root sheet
is reached, the compilation fails (no abstract model is produced).
| attribute key | value syntax | meaning |
|---|---|---|
cschem/child/uuid | uuid | first the project then the hlibrary is searched for a sheet with matching uuid |
cschem/child/name | string | first the project then the the hlibrary is searched for a sheet with matching file name; if contains any slash character, it's a path within the hlibrary relative to the current sheet's path within the hlibrary |
cschem/child/path | string | path relative to the directory the current sheet is last saved in |
{des6:18} Configuration setting hlibrary is a list of paths where schematics sheets for use in hierarchy are stored on the file system. It is similar, but orthogonal to the symbol library paths (but upon the user's decision there might be overlap between the two).
{des6:29} An implementation that supports project files typically keeps a list of all root sheets in the project file and another (auxiliary, aux) list of all other referenced from the root sheets. When a new reference is made (new symbol is placed with cschem/child/* attribute), the aux list of the project file is extended with the new file. Thus the project file always contains a full list of sheet files needed for reproducing the hierarchy.
{des6:19}
Networks between the current schematics and the referenced schematics are
connected in explicit and implicit ways. Implicit (non-graphical) connections
are done by referencing a netname,
using the "connect=" attribute.
{des6:20} The explicit way of connecting networks is using the terminals of the symbol. On the parent sheet, symbol terminals and bus-terminals can be connected to local or global networks. On the child sheet, these connections are realized by terminals and bus-terminals placed directly on the sheet, outside of symbols.
{des6:21} Explicit passing of a network using terminals helps keeping the namespaces clean: the short, virtual "network segment" between the parent and the child has no global name, only sheet-local representations as terminals on both sides of the relation. It can also be regarded as a "network parameter" for the subcircuit instance.
{des6:22} The number, the type (terminal vs. bus-terminal) and the name attribute of the ports of the symbol and the child sheet must match. Any mismatch results in a compilation error (no abstract model is created).
{des6:23}
If the parent symbol contains attributes whose key start with the
cschem/param/ prefix, those attributes are copied into the child sheet
instance, with the same key and value, as sheet attributes.
{des6:24}
This mechanism is provided as a safe, explicit way for passing attributes
as arguments. Because of the key prefix limit, the parent can not
accidentally overwrite child sheet attributes. The API (the list
of cschem/param/* keys the child sheet will understand) can be specified
by the user and made known for both the implementor of the child sheet
and the parent sheet.
{des6:25}
In a typical application, on a child sheet, symbol, terminal and other
object attributes will symlink to "sheet::cschem/param/" keys to access
the parameters specified by the parent.
{des6:26}
Unnamed wire-nets are always treated as being local (as if they had a
./ prefix in their netname) as they shall never connect to a global network
by name.
{des6:27}
Abstract model netname generation: since the netname in the abstract model
must be project-wise unique, it can not be the same name used in a hierarchical
schematics. The exact details of the name translation is up to the plugin
that implements the translation. A typical example would be:
" {des6:28}
Similar to netnames, abstract component names may be required to be unique
by the exporter plugin. In this case either the exporter plugin or an
intermediate plugin is used to attach human readable unique names deduced
from the hierarchy (e.g. "refdes/refdes/refdes/netname" where refdes is the hierarchy down-reference
symbol's refdes attribute and netname is the netname attribute of the network
with the scope prefix removed. If the user doesn't chose a plugin, the default
behavior is to use the network's uuid as abstract netname. Normally the
renaming does not affect global nets, only subtree-local and sheet-local nets.
refdes/refdes/refdes"). Just like with the netnames,
this name translation is optional. The same name prefixes
can be used
(global, sheet-local, auto, subtree-local, subtree-auto)
on symbol names to control how they are merged into components.