cschem implementation - 2. Schematics data

Goals

{imp2:0} This chapter should try to define the "first-class" objects cschem handles. The list of these objects should be as small as possible and as orthogonal as possible. All extra features and mechanisms, like slotting, hierarchy, name mangling, etc. should be implemented on top of these features (usually by dealing with attributes). This is in accordance with {pol:1}, {pol:2}, {pol:4}, {pol:9}

{imp2:1} The model can be considered as a stack:

   +------------------------+
   |  output, e.g. netlist  |
   +--+------------------+--+
      |  abstract model  |
   +--+------------------+--+
   |    concrete   model    |
+--+------------------------+--+
|      drawing  primitives     |
|      and data schematics     |
+------------------------------+

{imp2:2} The main objective should be to keep the abstract model as simple as possible, since most of the complex logics and methods and mechanisms will operate on this model.

{imp2:3} The concrete model can be more redundant, offering alternatives; the most common example is that a network can be realized drawing wire-segments, or drawing bus-segments or implying connections via attributes.

{imp2:4} The input for the concrete model can be even more elaborate; most notably the same concrete model elements can be created graphically or from data, manually or programatically.

{imp2:5} The final output is usually also a larger model that can be derived from the abstract model.

Abstract vs. concrete

{imp2:6} At the end, all that matters is the abstract model. Most plugins, export formats, checkers, etc. are interested in that. That's what really describes the actual circuit. We have concrete objects to provide an easier access for the user to manipulate the abstract model.

{imp2:7} Electronic example: in the abstract model the project needs a quad NAND gate (7400). One of the possible implementations in the concrete model:

• in the lib, there are two symbols, a generic NAND gate with 3 gates and a TTL power symbol
• the user places an instance of the power symbol and 4 instances of the NAND symbol
• the users sets the name attribute of all 5 symbols to the same, unique value, e.g. U15
• cschem now knows that the abstract component called U15 depends on these five concrete symbols
• a slotting mechanism plugin and/or potentially other plugins affect (calculate) attributes of the five symbols and their ports (details to be discussed by later chapters)
• now that the final values are known, cschem attempts to combine the five concrete symbols into an abstract component (details to be discussed by later chapters)
• the rest of the code, e.g. netlist generator plugins, will often deal with abstract model only

{imp2:8} A much simpler example is when a single symbol instance of the concrete model becomes a single component in the abstract model. However, the above steps are all the same, except the 4 or 5 symbols are reduced to 1.

{imp2:9} The UI should present both the concrete and the abstract model. The user should be able to edit the objects of the concrete model and see the effect on the abstract model.

{imp2:10} Letting the user directly edit the abstract model is probably not practical: there are multiple ways the concrete model can be changed to cause the desired change in the abstract model. It is like if we wanted to fix a bug in the executable of a program and expect the debugger or compiler to go and fix the source code accordingly.

{imp2:11} Thus the UI should present the abstract model as read-only. But just like debuggers can assist the user to navigate to the source line(s) that contributed to a specific instruction or runtime situation, cschem UIs should be able to navigate the user to the source(s) in the concrete model that caused a specific effect in the abstract model. How the source references are stored in memory is up to the implementation, but when the model is saved/exported (e.g. to disk), it should use UIDs as specified.

{imp2:12} A common example is (abstract) networks. The user, looking at a PCB or simulation, wants to find the network named "Address6". This information is clearly interpreted in the scope of the abstract model, where there is a network with name "Address6" and a list of ports it connects (and a list of attributes). A search can be made to find all graphical connections, wire-nets, bus-nets, attribute connections and data that contributed to the final list of ports (and attributes) of the network.

{imp2:13} Note the terminology: the same terms are not reused in both the concrete and the abstract models, e.g. a symbol in the concrete model can become (or contribute to) a component in abstract model.

Core attributes

{imp2:14} A very few aspects of the abstract model are implemented through attributes. These attributes are used by the core implementation and are relied upon by all plugins. These attributes are called the core attributes.

{imp2:15} The number of core attributes shall be as small as possible as per {imp2:16}, {imp2:17}, {imp2:18} and {imp2:19}.

{imp2:20} Currently the core attributes are restricted to deal with:

• identification of objects in the abstract and concrete models
• realizing the simplest forms of attribute based network connections (not excluding other, more complex forms calculated by plugins; the result of those calculations will be translated to connections specified in this simple form; scope of later chapters)

Port implicit network vs. chan connection

{imp2:21} A port (or a channel of a bus-port) can be non-graphically connected to a network using the connect attribute. This always forms a connection (even at the cost of creating the given network).

{imp2:22} Another way is connecting the port graphically, using wire-nets in the concrete model.

{imp2:23} The two methods are orthogonal and can be used in parallel. If the same port is connected to two differently named networks, the usual network collision mechanism is used (will be discussed in a later chapter). If the port is connected to a named network via attribute and an unnamed wire-net, the wire-net automatically joins the named network (via the port).

{imp2:24} The third orthogonal idea is channels of a bus. A channel is really a network, which most often "stays within the scope of the bus", that is, won't have a connect attribute that would make it a globally known network. If a port is connected to a bus, the port's chan attribute determines which channel of the bus is connected.

{imp2:25} But this connection is again orthogonal to the above two. Which means a port can be connected to a network in multiple different ways:

• using the connect attribute of the port
• using the connect attribute of the parent component
• graphically, using a wire-net, assuming the wire-net is already associated with a network
• graphically, using a bus-net, assuming the bus-net channel is already connected to a network (via graphical connection to another port or wire-net or via the channel's connect attribute)

Avoid attribute overloading

{imp2:26} A symbol has a name field for binding it to a component. This seems like redundant to refdes (also, gschem uses refdes for this purpose). The reason for this decision is that refdes is also the identifier printed on a PCB. In a complex hierarchic setup it makes more sense to use a shorter refdes generated from a longer name; the refdes can even be sequential.

{imp2:27} If cschem tried to use refdes for both, it would be sort of overloading the attribute with two different purposes:

• logical identification of the component in the hierarchy or on the schematics page
• physical identification of the component e.g. on a PCB