# 8. Ripple annotation

## 8.1. Forward vs. backward annotation

{des8:0} A very common workflow is that the schematics is the only one true source of information; if anything needs to be changed in a later stage of the design process, e.g. during PCB layout or part ordering, the engineer doing the later stage has to go back to ask the schematics designer to change the schematics and do a new forward annotation. In turn the new annotation will change the input for all later stages and brings the project in sync with the requester's intentions.

{des8:1} Cschem also supports "back annotation", which means the engineer of a later phase of the project may change the design there and send back the changes to the abstract model, which in turn has to be used to update the schematics. This is still the same process as described above, just instead of a "paper and pen" (or natural language email) interaction, the back annotation can take place as a data pack.

{des8:2} Below is a simplified flowchart of how the different parts of the design process are connected. The red mark means the schematics is regarded as source of information, the current state of the project.

## 8.2. Back annotation

{des8:3} The forward annotation process, when (TODO: link) a netlist is generated from the concrete model, is described in chapter 5 .

{des8:4} Back annotation: when a change request appears in a later phase of the project, in a 3rd party software (e.g. PCB editor), it can be saved as a computer-readable data pack, called netpatch. Just like a netlist, a netpatch has a wider scope than just describing changes to network connections: it can also describe changes to attributes of components or networks, removal requests for components or networks.

{des8:5} Just like netlist format, netpatch format is also specific to the 3rd-party software that produces it. In a later chapter (TODO: link) a standard cschem netpatch format is described - 3rd party software may chose to use that format for easier access to the back annotation mechanism.

{des8:6} A netpatch is an ordered list of entries; entries are one of the following concepts:

{des8:7} netpatch entries
concept | arguments | description
--- | --- | ---
add_conn | port, network | the port needs to have a connection to the network
del_conn | port, network | the port must not be connected to the network
add_attrib | object, key, newvalue | change the attribute of an object (e.g. port, component or network); if the attribute did not exist, create it
del_attrib | object, key | remove the attribute of an object
del | object, type | delete the object; type specifies the type of the object so that ports can be distinguished from components or networks; the actual syntax of the object argument depends on type
add | object, type | create a new object; type specifies the type of the object so that ports can be distinguished from components or networks; the actual syntax of the object argument depends on type

## 8.3. Ripple annotation

{des8:8} Cschem fully supports the above development model, based on forward and back annotations. However, with a minor shift in how the whole process is regarded, but without any change to the code, the model easily becomes the ripple annotation:

- {des8:9} 1. The real source of information everybody works from is the abstract model.
- {des8:10} 2. In the first phase of the project, a lot of schematics -> abstract model annotations happen, but in the late phase of the project it is more likely that other tools will do more annotation. In other words, in the early phase of the project the schematics drive changes, in later phases simulation, pcb layout, or even part availability will drive changes.
- {des8:11} 3. Anything connected to the abstract model gets updates from the abstract model, and should be sending back change requests to the abstract model.
- {des8:12} 4. The schematics is not necessarily an exception from rule 3.

{des8:13} The following diagram demonstrates this approach:

{des8:14} This diagram is very similar to the previous one; the difference is that the schematics is not in a special place anymore and the focus has been moved to the abstract model. Annotation is not "forward" or "back" anymore, because all participants are equal in working on the abstract model. Annotation originated in one part of the toolchain can hit the other parts without first having to go through the schematics. Thus annotation is called ripple annotation.

{des8:15} After such a ripple annotation, eventually the schematics, just like the pcb or simulation will be updated. The design is fully in sync only if all participants worked from the latest abstract model, there are no outstanding netpatches and no local differences or deviations at any tool in the toolchain.

## 8.3. Implementation of the ripple annotation

{des8:16} The similarity of the two diagrams also suggests this is only a shift in how the user relate to cschem and the schematics, not an actual change in code or specification.

{des8:17} The only difficulty of fully implementing the ideal ripple annotation is that the abstract model does not exist as persistent data, never saved to the disk. Instead, it's a temporary image stored in memory.

{des8:18} The environment in which the ripple annotation is to be implemented is:

- cschem core can be ran without a GUI, as an automated/batch/CLI process
- thus the abstract model can be generated from the concrete model (schematics) any time, automatically
- back annotation works by other software sending back netpatches (TODO: link 8.2)
- because of netlist maps (TODO: link), a netpatch can be easily interpreted in both the abstract and the concrete models.

{des8:19} The implementation of ripple annotation thus assumes that both the schematics and the outstanding netpatches are accessible (as an ordered list of patches). It compiles the vanilla abstract model, then applies the netpatches before generating the (TODO: link) netlists. The annotation happens in the abstract model -> schematics direction too: the schematics editor gets back the patches and the GUI assists the user to make the necessary changes to the schematics.

{des8:20} If a netpatch is fully implemented in the schematics, the resulting abstract complies with the netpatch: that is, if the netpatch is applied onto the abstract model, no change happens and the resulting abstract model matches to the abstract model used as an input for the patch. This is very easy to detect, and the compliant patch can be removed. When all netpatches are removed, the schematics is fully in sync with the current state of the design.