n2ktoc - need to know Body, chapter 4.3

last updated 17 oct 97 - mjh

4.3) schematic capture

This section addresses specific issues related to the use of the VeriBest Design Capture (VBDC) tool. This is not intended to be a general introduction to the tool. Such (4.1.3) documentation can be found online, as well as in print. Look for the so-called "quick start" manuals. Also talk to other users.

What you will find here are explanations of some of "inner workings" of the tools, and a bit of how/why we do what we do.

4.3.1) seed projects

To provide a degree of uniformity, several seed projects have been created. For better or worse, these can be found in:

   I:\Apps\UofI\VBPCB\seeds

Granted, it may seem a bit out of place for the seed jobs to be "closer" to the printed circuit board file tree (VBPCB) than the design capture file tree (VBDC). The reason for this is tool sensitivity. VBDC is a fairly robust tool. Not a lot changes, or really needs to change, to make this tool work effectively. VBPCB on the other hand, is a layered product in flux, and as a result we find that the seed jobs more frequently need "adjustment" due to PCB-related issues than DC-related ones. Hence the jobs are near the PCB stuff.

We have several seed jobs types available:

Each seed contains a project file, a (dummy) schematic, a pcb folder (complete with all of the pin/pad/aperture/drill tables that you will need, already in place), a pcb_fab folder (with sample fabrication documents), and hdl/genhdl folders related to simulation.

You typically start a project by copying a seed folder from the above path into an appropriate work area, then change/edit the names of your copy to reflect your project.

4.3.2) files, pages, folders

The VeriBest tools endeavor to present a "user friendly" environment where all you need to do is find the "right button" to solve every problem.

Our experience is that you really need to have at least a passing familiarity with goes on under-the-hood of these tools, and especially to know what files are critical to what processes. BE CAREFUL! Don't edit any of the files described here unless you know what you are doing, and be *VERY* aware that even small mistakes can lead to really subtle failures. Nevertheless, you need to know about these things...

4.3.2.1) veribest.cfg

The story starts with the "veribest.cfg" file found in your "home" folder (H:). This ASCII text file contains:

You may find occasion to want to "adjust" your project list. The most common case is that your "most recent" (topmost listed) project no longer exists, either because you changed its name, or moved it. When VBDC starts, it really tries to match you up with your most recent project. If that can not be found, VBDC is unhappy. Normally, you just let VBDC sulk a bit, then use Project - Open to reset your "most recent" project to something else. But it something really funky happens, you may need to use Notepad to edit the veribest.cfg file to "adjust" your project list.

*** EXIT VBDC FIRST!!! *** Exit all VeriBest tools before even thinking about touching veribest.cfg, or the [project.prj] file described next.

This "most recent" project aspect is important to remember. As you lauch various tools, they are going to try very hard to reconcile what your are asking the tool to do *in the context of* the "most recent" project. For this reason, it is unwise to ever "double-click" on a schematic file from the NT Explorer. VBDC will be launched and the schematic will be opened, but it will *also* attempt to add *that* schematic to your "most recent" project, whether this makes sense or not!

4.3.2.2) [project].prj

All of the project-specific controls for VBDC (and a few other tools) are kept in the [project].prj file in your project folder. This is also an ASCII text file. Typically, you would have no reason to edit this file, *except*...

We have control files and libraries that we keep in central locations, and use the symbolic variable "UofI14PATH" to define where to look. If you examine the [project].prj file, you will find a number of "UofI14PATH" entries along side a multitude of "VBEST14PATH" entries. This "parallel" structure makes keeps life simple. Unfortunately, the VBDC tool does not understand environment variables. If you try to redefine your library set (for example), the menu will not allow you to provide anything but a full pathname. We prefer the symbolic pointers, so sometimes the [project].prj file must be edited.

*** EXIT VBDC FIRST!!! *** Exit all VeriBest tools before even thinking about touching [project].prj or the veribest.cfg file described previously.

There is one other occasion where editing the [project].prj file may be handy, compared to modifying it via the VBDC - Project menu. If you have just copied over a (4.3.1) seed project then the [seed].prj file will point at [seed].sbk, [seed].cdb, etc. Normally, you would rename your copy of [seed].prj to [project].prj; this would be a handy time to edit [project].prj and change all (three, probably) occurrences of [seed] to [project].

If you read the online (4.1.3) documentation it will suggest that you create new projects from the VBDC - Project - New menu, and to select the "From Existing Project" option. There is nothing intrinsically wrong with their method. Just be *very* careful to specify a full pathname for the new project, and look at the Project - Files and Project - Settings when you are done to make sure you didn't miss something. The alternative is to do it our way: copy the [seed] folder, rename/edit the [seed].prj file, rename the [seed].sbk, and go to work.

4.3.2.3) [project].sbk

The schematic design in contained one or more .sbk files. The "top level" schematic should be named [project].sbk to be consistent with your project name. From a tool standpoint, it is necessary to define the top of the design tree. From a user standpoint it just helps a lot.

Each .sbk file can contain up to 99 pages; they are all peers of each other, and have little or no order specificity.

Schematics can contain blocks that point at other schematics. This defines a design hierarchy, or tree, rooted at the [project].sbk file. Typically, all of the .sbk files of a project will reside at the same top level of the [project] folder. You can hide them in subfolders, but this is asking for trouble...

Also, keep in mind the notions of "project" and the design "tree" if you want to have any non-design .sbk files (e.g. for documentation). Your [project].prj file contains a list of schematics that are *believed* to belong to the project, regardless of whether they are connected to the design tree. Unconnected schematics can easily get attached to a project, simply by opening that schematic. When it comes time to "compile" the design, different tools will either take

  1. all listed schematics, or
  2. only those connected by the tree.
This can easily lead to rampant confusion as to what *is* the design and what is not. You are strongly advised to keep non-design-tree schematics in a separate folder, and to be watchful as to whether they have crept into you Project - Files list.

4.3.2.4) [project].cdb

The [project].cdb folder contains both instance-specific information and "compiled" information from the schematics. The second is good, the first is bad.

Instance-specific information refers to the idea that you *could* draw one schematic diagram, then reuse it many times in the same circuit to represent similar "channels" or subassemblies. The problem is that in real life, the repeated circuitry is actually represented by repeated components with distinct identities. Thus while one schematic diagram might describe the "pattern" of repetition, it can not simultaneously carry all of the individual (instance-specific) names.

VeriBest addresses this through the notion of "instance" editing, and the distinction between editing "a block" as opposed to "an instance" of the block. The information itself is kept in the [project].cbd folder somewhere, and shown on the schematic (in purple) as if it is really there. But in fact it is not (there).

We can not live with this!

Information on the schematic must be *on the schematic*! It is not acceptable for there to be "layers" of hidden specifications that only appear in certain contexts. We have already been *badly* burned by "invisible" instance-specific names and values taking precedence *without warning(!)* over the clearly *visible* non-instance information on the schematic.

The answer to this is simple but costly. No instance-specific information shall be tolerated. If you want repeated circuitry, you will need repeated schematic pages to carry the specific names and pin numbers. End of story.

Well, almost. Crafty, lazy, underhanded people that we are, the notion of editing N copies of the same page is offensive. So we routinely:

This is done *outside* of VBDC, with all VeriBest programs exited, of course. Once you have set up the .bat file to do the transformation, the rest is easy.

To complete this section, the [project].cdb also contains the "compiled" information from the schematic set. This is fine. Whenever you compile, remember to disable the "Incremental Compile" option. All of our machines are fast enough that there is no benefit to incremental compilation, and there seem to be bugs in the decision process that sometimes cause the incremental compile to miss files.

If you have properly followed the above discussion about (not allowing) instance-specific information, you should be able to *delete* the [project].cdb folder and rebuild it (through compilation) at any time, with no side effects.

4.3.2.5) hdl, genhdl

There are two folders that you will need later, when working on the (4.5) simulation of your design. The "genhdl" folder is the location where Verilog descriptions generated from your schematics will go, and the "hdl" folder is the place where you should keep your own models.

4.3.2.6) pld, altera, xilinx, etc.

If there are any programmable devices in your designs, you should keep all of the relevant design files in appropriately named folders along with your project. Keep in the back of your mind that someday, your project will be archived (2.2.1) online so it is important that everything worth knowing can be found under one folder/file tree.

4.3.2.7) BOM

The BOM folder contains a utility to help you extract a Bill of Materials from your design, which is necessary for (5) ordering parts for your project.

The BOM folder is also where you should keep your *renamed* BOM file (renamed to the generator utility won't trash it if someone runs the utility again!) for (2.2.1) online documentation purposes.

4.3.2.8) pdb_src

The pdb_src folder contains a dummy Parts Database source file (readme_pdb.txt) as well as the pdb_comp.tcl compiler utility, needed for (4.4.2) pdb creation/editing for your design.

4.3.2.9) pcb

The pcb folder contains a large number of files need for the (4.6) layout and routing of a pc board for your design.

4.3.2.10) pcb_fab

The pcb_fab folder contains a sample set of fabrication (4.6.14.1) text files. Edit them according to your design specifications.

4.3.3) style issues

To a fair extent, you can do whatever you want. And somewhere downstream one or more of the tools will gag and force you back to the beginning. We are trying to keep a list of "known traps" in the next section, but you are advised to avoid anything fancy.

A few simple suggestions, not required, but generally good ideas:

Read through (4.7.2) "A schematic is done when..." as well as (4.7.3) "A design is done when..." for further guidance.

4.3.4) tool impositions

4.3.2) symbol creation

Creating symbols for use by VBDC is something of a specialized art. Read through the (4.1.3) documentation online, and talk to Mike Haney. Also read (4.7.1) "A symbol is done when..." for more.

4.4) packaging