Schematics as Documentation – How to Use Symbols and Annotations Effectively

You might call me a “reverse convert” – I began as a software undergraduate, who later jumped to the hardware side, pretty rare huh? I can save my personal story for another day, but what I learned from the software side remained impactful in my work today. The importance of documentation was chiseled into my brain after a few programming courses. I remember distinctly when a TA showed us how Javadoc could turn my code’s inline comments into pre-formatted and intuitive HTML documentation. Your IDE (Integrated Development Environment) becomes a one-stop shop for most of your programming needs.

Now let’s compare that with what IC designers do. We all have made one too many slides, probably some Word docs as formal documentation, and countless spreadsheets for configuration settings. Microsoft is really the winner here.

I pose the question (and challenge) whether schematic capture tools can be used to meet our documentation needs as well. Before taking the leap to talk about “AI assisted schematics” , my simpler conjecture is that adopting the mindset of “schematics as documentation” and some basic practices will already have huge benefits. In this post, I will share some key ways of utilizing good symbols and annotations in order to document our circuits’ architecture, analog and digital aspects.

Architecture documentation

Think back on the last time you WANTED to draw a good block diagram for your circuit, probably for a design review or a journal paper. Now take that desire and put it into schematics and symbols drawing, which is the very first place we can document circuit architecture at all scale. Here are my three guidelines to ensure architectural information is conveyed clearly in schematics and symbols.

1. Draw block diagrams on symbols with the right level of abstraction

Below are three different example PLL symbols. A bad one won’t have any information about what the block is, so it’s virtually the same as a netlist block. An OK one will at least have a description of the block (i.e. block names like PLL, LNA, ADC, etc.) on the symbol. There are situations where this might be acceptable. It’s marginally better than the bad one, but putting a big visible name makes it easier to find in a complex high level schematic. A good symbol will show some level of architectural information on symbol. It can depict the critical sub-blocks and immediately show the signal flow with the right pin placements. Depending on your personal preference, the big block name could be optional.

2. Use meaningful cell, instance, pin and net names

There isn’t a “golden reference” for naming convention, but definitely have one within your group and enforce it. For basic primitives, there are some rules (“R” for resistors, “C” for capacitors, “L” for inductors, “V” for voltage sources, “M” for devices, and so on), but even those aren’t strictly followed sometimes in the crunch of time (I plead guilty). When it comes to pin/net names, the problem could be even worse like the example below. Obviously I exaggerated the bad symbol to make a point, but I hope the message is delivered.

One suggestion on cell names is to embed a similar schematic hierarchy in the name itself. This scheme not only helps with hierarchical thinking, but it also automatically sorts the cells in the library manager (easier to find later). One example would be to name the bias block in the charge pump pll_core_cp_bias. The name does get long sometimes, so exercise tradeoffs when using this scheme (might be a good indicator that you have too many levels).

Most schematics I have seen so far tend to have good pin names, but once in a while you run into pin names directly taken from the alphabet soup. Similar to cell names, I also recommend embedding some hierarchy. Also, group the pins according to function or sub-blocks. For example, the main signal path pins (e.g. clk_ref, clk_out) should be a part of the block diagram, the bias current pins can be grouped together, and the configuration pins for PD/CP should be grouped together.

Lastly, something is wrong when a counter determines the instance name of your circuits, especially for higher level blocks. The issue isn’t really about schematic readability, but debuggability when you study and modify netlists. I learned this the hard way when I had to trace “I0/I12/I034/I5/net067” in a netlist. So if you care about an internal net, give it a good name.

3. Use note shapes/colors to highlight local or higher level connectivity

Schematic capture tools are essentially drawing tools, so we have shapes and colors at our disposal. Weirdly enough, we rarely use them in schematics. Later in my career, I started experimenting with using shapes and colors more and I loved it. Architecturally, it adds another dimension to explaining the circuits.

One example is when I can’t find a good way to avoid the “connect by net name” crime. By using different color nets or explicit note arrows, you can emphasize critical connection even though they might be further apart in a big schematic. The goal here is to catch the attention of whoever reads the schematic, especially when feedback loops are involved. I still prefer using note arrows because it shows directionality , but colors might work better for special nets like biases and clocks.

Another example is when such loops need to be broken during simulation (PLL, LDO, common mode feedback, switched-cap circuits, etc.). We can use an arrow to indicate higher level net connectivity. Sometimes we can even draw connectivity to other blocks so that we don’t lose sight of the overall architecture. Below are two examples

Analog documentation

Let’s move onto the more analog specific documentations that are valuable in schematics. We have already seen a glimpse of this in the examples above, in which current consumptions are also annotated along with the higher level components in the schematics. Most designers already have a personal style for documenting analog blocks, and my Big Three is listed below

1. Highlight circuit parameters and performance

One widely used annotation is putting in parasitic capacitance on critical nets after layout extraction. This practice reduces the gap between pre and post layout simulations, and it can help designers pinpoint where the limitations are. I think we can go a bit further to annotate other circuit parameters and simulated performance numbers in the schematics, including input capacitance, mismatch, noise, etc. It’s almost like keeping a journal of your circuit’s health.

2. Draw a layout floorplan

Layout notes are also essential in serving as the first interface between layout and design engineers. I would recommend drawing actual cartoon placements in addition to writing simplified notes like “minimize resistance” and “match routing”. Sometimes a well drawn floorplan automatically enforces these requirements. My personal preference is to put these notes in the floorplan cartoon so that the schematic itself looks clean. So think about creating a “layout corner” in your schematics.

3. Keep a record of your thinking process

Last but not least, use your schematics as a notepad to record your design decisions or experimental tweaks. It’s especially important when you are close to the tape-out finish line. We could keep having deja vu and wasting our time to “rediscover” the reasons behind a weird sizing choice, so writing down a note can save us some energy and trouble later. We can also use notes as reminders for revisiting design choices in the future. This is very similar to writing comments on small code snippets that catch edge cases when programming.

Combining these suggestions, one can draw and annotate a differential amplifier schematic as below. On the other hand, be wary of the risk of having a schematic look too heavy with too much text. So again, use your artistic senses to exercise tradeoffs when annotating schematics.

Digital documentation

Digital programmability has become inevitable in mixed signal designs today (i.e. digital-assisted analog designs). As a result, documenting configurations could now be a full-time job itself. It is especially challenging when multiple stakeholders are involved in a big system. Some poor soul will have to chase down individual block owners asking for default settings, power-on sequences, and so on. After some experimentations, I find the following guidelines the most helpful for in-situ digital documentation.

1. Use wide wires for digital buses

This is a personal choice but I use wide wires in both schematics and symbols to indicate a digital bus. It can show right away which block has a more complex interface, and needs more careful higher level routing plan.

2. Write down critical config tables in schematics

Putting down a digital table becomes more natural as soon as you have the habit of using notes in schematics. We don’t need to include all configurations, just the ones that we will refer to the most later. Some example tables might be for a LDO’s output voltages or a VCO’s coarse tuned frequencies. We can also use such tables to note down functional behaviors, like clock source selection or reset sequences.

Another benefit is that we would already have a reference even if we need to document in excel again later. It would be much easier because we have already done so in schematics at the earliest chance bit by bit, instead of taking an all-at-once approach when the design is complete.

3. Explain custom decoders or digital controller whenever possible

We use custom encoders/decoders all the time (binary to thermometer, one-hot, gray coding, and so on), but we can’t draw much for their symbols. Therefore, the next best thing is to write the decoder’s name in easy to read fashion whenever possible. There are some tricks that simplify drawing custom digital decoders as well, like using bus notations and regular expressions.

4. Create block sections for analog and digital pins

This practice immediately separates the analog and digital portions of a block on the symbol. It also provides a quick view of each sub-cell’s programmability respectively. Together with tip #5, we can have a crystal clear symbol that well documents the digital interface.

5. Write default attribute values next to pins in symbol (at mid or high level)

I learned this trick from a co-worker, and find it extremely intuitive. The key here is to “hide” the default settings next to the symbol pins with smaller fonts. This way, they won’t obstruct the entire schematic when viewed from afar, but provide critical information when you zoom in. Perhaps I am late to the party, but this is extremely cool! The final finished PLL symbol might look something like this

Putting it together

Let’s finish with another cartoon schematic and symbol for an example regulator. The sub-cell pin/instance/cell names are not explicitly drawn in this example, but we should still give them meaningful names like mentioned above. I hope you can look and agree that the LDO’s critical architecture, analog and digital information is well documented. We now can stay in the schematic land a bit longer before diving into Office.

Lastly, this isn’t and shouldn’t be the only way to draw schematics and symbols as documentation. That’s where your individuality and creativity come in. Nevertheless, I would be thrilled if you find these recommendations useful and want to give them a try.

The day when our schematic environments turn into our IDEs might not be far. My personal wish is to see more built-in documentation features in EDA tools. Even a simple note section similar to the foot notes in PowerPoint can already provide some value. If you agree, please let your EDA friends know.

As always, my goal is also to strike up discussions, so please share your neat ways of documenting in schematics and thoughts on the topic!