+A non-hierarchic design has a single sheet or a set of sheets, with or +without a project file. The latter is also called flat multisheet +design. +
+In a non-hierarchic case every component and network are in a single +global namespace. In practice this means: +
+In a hierarchic design a schematic sheet contains a symbol that represents +a subsheet. This symbol is called the sheet reference symbol or +sheet ref sym for short; the sheet it is referring to is called the +child sheet. The sheet ref sym may have zero or more terminals and the +child sheet must have the same number of terminals placed directly on the sheet. +(In practice these terminals are typically placed from the symbol library; they +are called misc/shterm_* and they are not really symbols but terminals.) +
+The abstract model is produced by the compiler by compiling each root sheet +of the current project. Root sheets are all sharind the common namespace at +the hierarchy root. When compiling a sheet, the sheet ref sym is +detected and the compiler recurses into compiling the child sheet into a +new level of hirearchy. The terminals of the sheet ref sym are +connected to the terminals of the child sheet. +
+Child sheets can contain sheet ref syms to further child sheets, making up +a multi-level hierarchy. The only restriction is that the hierarchy needs to +be free of loops (circuilar references). + +
+In the simplest setup each child sheet is used only once. There are two +ways to make connections across sheets: +
+The same child sheet can not be referred twice because it would create the +same components and networks again. +
+This is a typical setup for the so called "CPU board" case, where a top +level (root) sheet acts as a block diagram connecting terminals of sheet ref +syms of a single level of sheets, each realizing a different section of +the design, as shown in this example: +TODO: example +
+A large CPU is not specified in a single symbol but is split up into a set +of different "slot" symbols by functional blocks (this is called heterogenous +slotting). At the end all these slot symbols are merged into the same final +abstract component referencing the whole CPU, because they all +have the same name (U1). Global nets, such as gnd and Vcc are easy to +address simply by referencing them by name - this happens in the stock +gnd and Vcc rail symbols. +
+The sheet reference symbol is manually crafted, one symbol for each child +sheet. Such symbols can be constructed right on the root sheet using the +graphical editor, or from text files using the utility boxsym-rnd. The sheet +ref sym has an attribute called cschem/child/name which holds the +name of the child sheet (with or without the .rs ending). The top sheet +must be added to the project file as a root sheet and all child sheets must +be added to the project file as an aux sheet. The project file needs to be +loaded when running sch-rnd. This ensures all sheets are availabel and can be +found by name and the project is self-contained (if the directory is packed up +and shared, it will load on anyone else's system as well). +
+The extra functionality that this setup provides over the plain flat multisheet +setup is that the same child sheets can be used by a different project in a +slightly different way by doing the wiring between sheet ref syms on the +project-specific top (root) sheet differently. + +
+Hierarchy can also be used to produce repetitve parts. In this (oversimplified) +example circuit the root sheet cotnains a +microcontroller that is controlling two LEDs using PWM. The "power +electronics" of driving the LED is the same on both channels so it makes +sense to draw it only once and reference it twice from the root sheet by +simply placing the sheet ref symbol twice, using different name for each +instance. +
+To avoid the two instances of the child sheet creating the same +components and nets twice, there is a mechanism for creating objects in the +sheet local scope. This is done by prefixing the component or net name +by ./ (a dot and a slash). This prefix is removed by the compiler and the +name is transformed into something unqiue - by default this is done prepending +the hierarchic path, which is a slash separated list of sheet ref sym +names from root to the given object. This is how Q1 becomes two FETs: +S1/Q1 and S2/Q1. This system works side by side with the basic +mechanism from the previous chapter: +
+So all in all, the intermediate method uses two different addressing +methods: the ./ name prefix to keep something sheet-local and +no-prefix prefix names, which are called automatic and simply end +up being global in the intermediate use case. + + +
+A slightly modified version of the same example is TODO +. This removes the net name pwm1a in the top sheet but the control +net is named on the child sheet. In this case the same number of networks +are generated and generally the same abstract model is produced, but the +network that was called pwm1a in the previous example becomes S2/gate, +because that's the second best name sch-rnd could find. +
+In case the child sheet did not name the control net, a globally unique +anon net name would have been generated for this net. + +
+Another modification of the original LED example is TODO +. This introduces a common enable singal, controlled by the +microcontroller, that can cut off both LEDs at once. To avoid having to +have an extra terminal on the both sheet ref syms and having to draw the +enable signal to both syms, child sheets simply refer to the blink_enable +net without the ./ prefix, which means this is a global scope net and all three +sheet instances will join its references into a single net. +
+This is the same mechanism that the GND symbol uses. + +
+The intermediate setup covers the situation of reusable single-sheet +modules, locking internal networks and components into the sheet local scope +using the ./ name prefix. In some cases the reusable module is large enough +that it needs to be a multi-sheet hierarchy. In that case there should be +a single root sheet of the module that references all other sheet of +the same module using sheet ref syms. The module is then instantiated +by a bigger design by: +
+(The bigger design is generally not interested in the internals of the +multi-sheet module, the interface ("API") between the module and the +bigger design should be the terminals of the module's root sheet and a few +well documented global nets, such as GND.) +
+When a common signal needs to be distributed among all subsheets within the +module the most trivial solution is to create a new terminal on all the +sheet ref syms and do the wiring on the module's root sheet. However this +leads back to the same problem of having too many terminals and too many wires +on the module's root sheet. It would be easier to use a global net that is +accessible from all the module's sheets. However, using a true global net +for this purpose is a bad idea, as it may unintentionally merge with the same +named global net in the bigger design or with the same named global net of +a second instance of the same module thta should have been independent. +
+The solution is using subtree local objects (nets and components). This works +by declaring the object (net or component) on the module's root sheet using +a v/ prefix to the name. The v/ prefix means this object is mergable ownly +downward in the hierarchy so only subsheets of this module, all somewhere +under the module's root sheet will see the object, but it will not +merge with anything above the module's subtree. +
+TODO: example +
+TODO: + - describe the example once the net names are known + - explain how auto is searching + + +
+A special use case fr hierarchic designs is "unslotting" a symbol +that was drawn as monolithic symbol. E.g. a dual opamp drawn +as a single symbol can be split up into two separate opamps +This use case is described in + the spice +export plugins documentation. + + + +