CapFast for EPICS Database Configuration Tool (DCT) 

(Motif Version)

Original (non-Motif version) at http://www.ast.cam.ac.uk/EPICS/capfast/capref.html

Table of Contents

1. BACKGROUND
2. USING CAPFAST TO DESIGN AN EPICS DATABASE
3. CREATING THE SHORT REPORT
4. APPENDIX A: E2SR (v.2.1.0)


1. BACKGROUND


Since many of the concepts of the EPICS database design are quite similar to electronic design tasks, an effort has been made to create tools that utilize off-the-shelf hardware design packages to create EPICS databases. This concept has the advantage of providing robust, feature-rich tools for a small fraction of the amount it would cost to develop and maintain them.

CapFast, a schematic editor that has been proven both powerful and reliable over several years by the AT-8 hardware section, has been modified by the addition of a symbol library that represents all standard record types of the EPICS database. Users can create schematics with this library that are translated into an EDIF file, the computer aided engineering (CAE) netlist standard, which is then translated by an EDIF to short report translator (currently E2SR) into an EPICS short report. The short report can then be read by the DCT and used to create a database.

It is important to note that ANY schematic capture tool with EDIF capabilities can be used in this way, which allows a wide choice of editors based on the user`s preference; thus, the user is not constrained to use CapFast. Users should realize that schematic editors such as CapFast are part of the CAE world, which until recently has been devoted strictly to hardware design, so hardware designers and the hardware industy have determined the look and feel of these editors. Users who are used to more recent standards — such as the Mac, Sun’s Open Windows, or MOTIF standards — will find things very strange at first. Nevertheless, though different, the schematic editor tools have been improved over 20 years of use and are extremely efficient in the hands of an experienced user.

1.1. Basic Concepts

A schematic editor package comprises two distinct parts, a symbol editor and a schematic editor. The schematic editor allows the user to connect graphical symbols representing logical entities by connecting their input and output ports with lines known as wires. Symbols, also called records, and wires can be named and have attributes known as properties, also called fields, which can be either instance-specific, or generic to all symbols and wires of a given type. The schematic editor recognizes ONLY symbols and wires. Text can be easily entered on the schematic, but has no logical significance.

The symbol editor allows users to create custom symbols for use by the schematic editor. Normally, a schematic editor will come with an extensive symbol library for commonly used devices. A library of all standard EPICS record types has been created for EPICS database design. The symbols themselves can represent any logical entity. Certain symbols known as primitives represent the lowest level of functionality. These primitives are the building blocks of all schematics, just as database records are the building blocks of the EPICS databases.

Other symbols can represent entire schematics. This ability allows schematics to be hierarchical, to support multiple instantiation, and to support top-down design methodologies. Normally, these hierarchical symbols are the only type created by users, as the user will not normally need to create primitives. In general, hierarchical schematic designs are easier to create, maintain, and understand than multi-page flat schematics. Spending some time at the beginning of the design effort dividing the design into functional blocks will improve readability and maintainability in the future. While this top-down approach is generally considered to be the correct way, in the real world designs are often bottom-up, or even middle-out. Schematic editors do not limit the designer to a particular design methodology, allowing the designer to use the most convenient method at hand. It is important to note, however, that the EDIF to EPICS short report (E2SR) translator does NOT handle multi-page flat schematics.

1.2. Hierarchical Naming

A critical issue in the creation of an EPICS database (which is flat or non-hierarchical), from a hierarchical schematic is determining rational naming rules for the EPICS records. The EDIF to EPICS short report translator concatenates the record name to the hierarchical path to generate a unique record name. This method also aids in relating the flat database to the schematic for debugging purposes. For example, a schematic dtlpos_1, which contains a hierarchical symbol vertp_1, whose schematic contains a steppermotor record m1, would generate the record name dtlpos_1:vertp_1:m1 for the steppermotor record. The colons are added by the translator to separate the elements of the hierarchical path.

In many systems, though, the naming standards for EPICS records are defined by system engineers who have little relation to the creation of the functional databases. In this case, the design hierarchy can be made to fit the prescribed standard so that the correct names are obtained by default; or, the database names can be changed after the short report is generated. Designing the schematic hierarchy to fit the naming standard constricts the designer’s freedom, but it improves the clarity of the system design. A drawback of this approach is that a poor naming standard will have a significant negative effect on all database designs. By utilizing several advanced features of the translator, it is possible to override normal database record naming. This allows the the database names to fit a naming standard, but puts the burden on the user to insure duplicate names are not generated. The details of this approach will be postponed until after the basics of creating a database are covered.


2. USING CAPFAST TO DESIGN AN EPICS DATABASE


CapFast is a commercial schematic editor sometimes used as a companion product to Mentor Graphics CAE systems and used with PC board layout packages for electronic hardware design. Its main advantages are its ability to handle arbitrarily large hierarchical designs, its availability on multiple hardware platforms (Sun, PC, HP), and its low cost. This section will walk the user through the creation and translation of a simple EPICS database using CapFast.

2.1. Getting Started

CapFast consists of two main programs, the schematic editor Schedit, and the symbol editor Symed. Of the additional programs in the package, only the EDIF translator, sch2edif, is used. The path to these programs must be added to the user’s .login or .cshrc file as follows:

  • set path = ($path ~p3/wcs/bin)

It is also good practice to copy the startup configuration files for Schedit and Symed to the user’s root directory. This allows the user to customize the configuration of the editors. The configuration files are:

  • ~p3/wcs/lib/cad.rc — command-line options, such as the search path for symbol libraries
  • ~p3/wcs/lib/schedit.rc — the user specific startup commands for Schedit
  • ~p3/wcs/lib/symed.rc — the user specific startup commands for Symed

It is best to leave the configuration files unchanged until gaining some experience. Once the path has been set and the configuration files copied, the editors can be started with the commands xschedit and xsymed.

2.2. Schedit Screen

Start Schedit with the xschedit command. A full screen window will appear. The window is internally divided into two parts, a small message area at the bottom of the screen, and a large editing area (with white grid dots). At the top of the window is the main, static menu bar. Each entry represents a drop-down menu. These menus may contain commands or other sub-menus. All commands — the commands that bring up menus, and the commands within those menus — can be invoked in the following manner:

  • Point on the menu or command with your mouse’s pointer, which is the symbol.
  • Click the left mouse button. If the selected command is a command Schedit will either perform the command or prompt you for more information; otherwise, it will bring up a sub-menu.

You can also select and invoke commands or menus simply by typing the underlined letter of the command on the keyboard. For instance, to select and invoke the Wire menu, simply type w.

At the top of the screen, notice the white bar. From left to right, it shows the coordinates of the last point to be placed, and the function of the left, center, and right mouse buttons. While in the editing area (and not in any command’s interactive mode) the left button is for placing points, the middle button is for repeating the last command, and the right is for unplacing points (placing points will be addressed later). Depending on what you are doing, the mouse buttons will change function to allow most commands to be fully executed by the mouse alone.

2.3. Basic Operation

There are several basic rules to remember when using Schedit.

  • The most important is that the or “Escape” key will immediately abort a command and exit the command mode, bringing you back to the edit mode. When in doubt, hit Escape.

The arrow keys on the keypad scroll the edit area up and down, and left and right. The number 5 key on your keyboard automatically centers your schematic in the edit area and scales it so that all of it is visible. Schedit does not automatically redraw the screen after every command. Pressing the v, then r keys on your keyboard will force a redraw any time you are in the edit mode (as opposed to the command mode).

Note: This document describes CapFast with the Motif or MS-Windows interfaces, and the latest menu set. Such things as the keyboard shortcuts just mentioned, the functions of the mouse buttons, and the names of the commands and menus may be different if you are using an older, SunView or X-Windows version. Notwithstanding, the differences are very slight. For example, you may have to invoke a command by clicking the middle mouse button instead, or the name of a menu might be Get Parts instead of Part, as it is referred to in this tutorial. If you want to get the EPICS-specific menus which are used in this tutorial, you can download them from:
ftp://ftp.phase3.com/pub/phase3/menus.EPICS.tar
Extract them to ~p3/wcs/lib/menus.new/ (or your home directory if you don’t want to replace your current menus). Then restart xschedit. The complete new menu set is available at:
ftp://ftp.phase3.com/pub/phase3/menus.new.tar.Z

With this information in mind, you are ready to start.

2.4. Options and Borders

The first step in creating a schematic is to change to an appropriate directory (your root directory is a poor choice) and place the border. The border will define the physical size of the finished schematic (this is important for printing) and is influenced by several settings under the Options menu.

First we will change the directory:

  • Select the Options menu.
  • Select the Search Path sub-menu.
  • Then select Change Current Directory.
  • Enter the directory path where the schematic will reside.

Defining the scale of the border involves a setting called Inter-pin distance, also in the Options menu.

To define the border’s scale:

  • Select the Options menu.
  • Then select the Inter-pin Distance menu.
  • Then in the Inter-pin Distance menu select 125 mils.

Note that you are prompted with the message save change? [n]: press y <Return> to save the setting. The scale is now set to the value 125, a good compromise between print out legibility and the density of the schematic. Now for the border:

  • Select the Part menu.
  • Then the Border menu.
  • Then the Complete border menu.
  • Then select B size.

A green border will appear; move it with the mouse to a centered position and drop it in place by clicking the left or middle mouse button. Use the number 5 key on the keypad to center and scale the drawing, and then from the Select menu choose Clear to deselect the border.

2.5. Creating the Schematic

The schematic itself is created by selecting EPICS record symbols, placing them within the border, and connecting them with wires. To bring up the EPICS library containing the EPICS record symbols:

  • From the Parts menu, select EPICS Library (all).

Then:

  • Select binary in (large).
  • A green binary input symbol appears near the border. Move the symbol with the mouse to the desired spot (near the top, in the middle of the schematic) and click the middle or left mouse button to place the symbol.

Now place another symbol within the border:

  • Select calculation (large) from the EPICS library.
  • Once again the symbol appers near the border of the schematic. Drop this symbol to the right of and below the binary input symbol.

At this point, it would be helpful to check your schematic against figure 1 to make sure that the relative positions of the symbols are correct.

To move a symbol:

  • First move the pointer over it.
  • Place a point by clicking the left mouse button. A +0 sign appears indicating a point.
  • Invoke Items from the Select menu (the symbol turns red when selected).
  • Now invoke Move from the Edit menu.
  • A green symbol in addition to the red one appears: move it with the mouse, and drop it in the desired place by clicking the left mouse button.
  • De-select the symbol by invoking Clear from the Select menu.

Note that you can select multiple items and move them as a group if desired. At this point, depending on the size of the monitor on your workstation, you may want to zoom in for a closer look. To zoom in:

  • Select Zoom In Under Cursor from the View menu.
  • Place the pointer midway between the two symbols and and click the middle mouse button repeatedly until the text within the symbols is easily legible.
  • You can also zoom in using the Zoom Area or Zoom In commands from the View menu.

Insure both symbols are completely visible on the screen; otherwise, naming them will be difficult. If the zoom is too close to view them in full, use the Zoom Out command from the View menu. If things become messy, press 5 on the keyboard to center the schematic and try again.

The next step is to rename the symbols. Doing this will define the database record names.

  • Select both symbols by invoking Items from the Select menu and clicking the left mouse button on each symbol. Press the middle mouse button or the <Space> bar to end the selection process.
  • Invoke Relabel from the Text menu.

You will be prompted for a symbol name. The symbol that is being named has some green text just below it on the left-hand side; the first one to be labeled is the one you selected last.

  • Enter bi0 for the binary input record and calc1 for the calculation record.

Now that we have placed two symbols, we can wire them together. We will connect the VAL output port of the binary input symbol to the INPA input port of the calculation symbol. Notice that the output and inut ports are small lines that stick out from both sides of each symbol: the output ports are the lines that have little arrowheads at the end and are on the right-hand edge of each symbol; the input ports are the lines that have arrow tails at the end and are on the left-hand side of each symbol.

Use the mouse to place a point on the little arrowhead at the end of the VAL output port of the binary input symbol, and one on the arrowtail of the INPA input port. While only two points are necessary to define a wire (the software routes the path for you), it is usually better to fix the wire’s path yourself (especially in schematics that have many connections).

  • Place several points along the path you wish the wire to follow. (Place a point by left-clicking the mouse; you can undo the last point placed by right-clicking.)
  • Invoke Draw Wire from the Wire menu.

A green wire will appear along this path and you may be prompted for a name. Since the EPICS translator ignores wire names, you can safely let the software name it by pressing <Return>.

It is important to understand that a wire that defines data flow in an EPICS schematic cannot join more than one output port. Such a wire can, however, join multiple input ports. This is because the wire cannot carry more than one datum, or piece of data, yet it can carry this datum to multiple input ports of other records. It is also important to understand that a wire that defines forward processing links, on the other hand, cannot join more than one input port, but can join multiple output ports, called flinks, shorthand for forward links (these are the output ports that are labeled FLNK). This is because a forward link or flink is essentially an ouput port containing an address of another symbol or record; multiple symbols can have flinks of one address, but there can be only one address in each of the flinks.

During the creation of a schematic, it is common to move symbols, to reroute wires, and to delete symbols and wires. Since a wire connects at least two symbols, moving a symbol reroutes all the wires connected to it. Let’s move the binary input symbol to the right hand side of the calculation symbol to illustrate this.

  • Select the binary input symbol by placing a point on it and invoking Items from the Select menu.
  • Move it (Edit -> Move), and place it to the right of the calculation symbol (click the left or middle mouse button).

Notice that the wire has been rerouted through the calculation symbol. Reroute the wire so that it does not pass through either symbol:

  • Select the wire by invoking Items from the Select menu and clicking the left mouse button when the wire is highlighted (green). Press the middle mouse button or the <Space> bar to end the selection process.
  • Invoke Re-Route from the Wire menu.
  • Notice a green box which appears around the node of the wire nearest to the pointer. Select a node by pressing the left or middle mouse button. The wire will turn green, and you will be able to move it with the mouse.
  • Move the pointer to route the wire and click the left button to set the new path.

You may have to go through this procedure several times to get the desired route. Sometimes it is actually easier to delete the wire and create a new one than to reroute it several times. To delete a wire or a symbol:

  • Select it and invoke Delete from the Edit menu.
  • Use Edit -> Undo to get it back.
  • Move the symbols back to their original positions, rewire as needed, and add a new wire between the FLNK port of the binary input symbol and the SLNK port of the calculation symbol. (Remember when you add your wire to press <Return> if prompted for a wire name — if you press <Escape> when it prompts you for a name, you will lose your wire.)

The SLNK port requires some explanation. In order to resolve forward links graphically, EPICS symbols require a dummy port for forward links (flinks) to connect to. This dummy or SLNK port does not show up in the short report, but the connection information is used for the FLNK field in the connecting records.

2.6. Properties

In order for the schematic to define a useful database, the default properties of the EPICS symbols must be altered to implement the desired functions.
??? Since Schedit was not designed specifically for an EPICS database, the menus provided by CapFast for certain fields are currently unavailable. ???

Also, Schedit allows you to cut text from other applications and paste it into the popup windows, including the Properties window, but NOT into the command area. It’s a good idea to keep this in mind.

We will configure the binary input symbol as Xycom 240, to be scanned at .1Hz.

  • Select the binary input symbol.
  • Invoke Edit from the Properties menu to bring up the Properties window.

The properties window displays all the attributes (or properties) of the symbol. Scroll the list in this window with the scrollbar. If you resize this window (Motif version only), the size of the list box will change. Notice that many of the properties are field names in the EPICS database. To enter a new value for a property:

  • Move the pointer over the property, and click the left mouse button.
  • The property name and value will appear in the Name and Value boxes at the top of the window. Enter the new value in the Value box and then click on the Add/Modify button.

Schedit checks the entry if you have a Property Rules File loaded. To load a rules file, first close the Properties window. Then, make sure you have a rules file ready. (For detailed information on creating rules files, see the CapFast documentation on it, either in the new User’s Guide or in the Release Notes for version 3.02.23.) Then, select Read Rules File… from the Properties menu. At the prompt, enter the name of the rules file and press <Return>.

Now, open the Properties window and modify some properties of the binary input symbol:

  • Locate the DTYP property and enter the value Xycom 240.
  • Locate the SCAN property and enter the value .1 second.

If you have a property rules file loaded and it has an entry for either or both of these properties, a small window will pop up if you entered a value that is not valid according to those rules. If this happens, select a value from the list in the window or type in a new, valid value.

Another way of modifying property values for properties that have rules defined is:

  • Double-click, with the left mouse button, on the property in the list box.
  • The small popup window just described will pop up. Select a value from the list of valid values and click on OK.

Click on the Close button to exit the property window. At this point, you may have to invoke View -> Redraw to see the new property values on the symbol.

2.7. Hardware Channels and Constants

As you may have noticed by now, the EPICS database fields that have to do with data flow and the fields that have to do with forward links are implemented as ports on the symbols. To connect these ports to hardware channels or constants, two special symbols, hardware input and hardware output, have been created to represent ports that connect to hardware channels. We will add a constant port to the calculation record.

  • Bring up the EPICS library. (Invoke EPICS library (all) from the Parts menu.)
  • Select the symbol hardware input from the menu.
  • Place the symbol close to, but not adjacent to, the INPB input port of the calculation record.
  • Open the Properties window (Properties -> Edit).
  • In the property list you will notice a property named val(in); change the value of this property to a constant (123.5 for example).
  • Exit the Properties window and redraw the screen.
  • Wire the hardware input symbol to the INPB input port of the calculation record to finish the job (drop points along the desired path and invoke Draw Wire from the Wire menu). Schedit may have already wired it for you if you placed it close enough.

To understand the significance of port properties in EPICS symbols requires some understanding of the translation process. A user only needs to know that in the case of hardware input and output symbols, the port properties need to be edited. For those who are interested, the translation process is outlined below.

The translation process finds each primitive symbol and traces each connected wire to its source. The source of the wire is defined as the first primitive symbol port of opposite direction. Once the source of the wire is determined, the properties of the source port are examined to determine what information to extract. In most cases, the name of the source port and its symbol are required. This covers almost all connections between database records. However, in the case of hardware channels or constants, the value of the constant, the string that defines it — Xycom 240, for instance — is required. The port property typ(port) is used to switch between these two modes of operation. If the typ(port) property has the value val, another port property, val(port), is used as the source of the information returned. (Do not confuse val(port), the port property, with val, the typ port’s value. If the typ(port) property has either the value path, or no value at all, the source port and symbol name are used.

Another port property, def(port) defines the default value for the port in the absence of connections. The port property username allows the user to define connections to database fields not defined as ports on the EPICS symbol. Many times in database design, it is useful to connect to record fields that are not generally considered to be direct outputs. The large EPICS symbols have several uncommitted output ports for this purpose. These ports are labeled FLD0, FLD1, FLD2 . . . , but the properties are named username(U0), username(U1), username(U2) . . . ; all have this username property. Open the property window for the calculation record and scroll down to see an example. You will notice the property username(U1) and its value FLD1 (field1). Change its value to HOPR:

  • Move the pointer over it and click the left mouse button.
  • Enter HOPR in the Value box and click on the Add/Modify button.

Exit the property window, and redraw the screen.

The string HOPR now appears on one of the uncommitted output ports. Connections made to this port will connect to the HOPR field of the calculation record.

2.8. Hierarchy

We have now gone through all the steps necessary to make flat schematics, but in order to make full use of these tools, hierarchy needs to be addressed. Hierarchy allows the user to create a symbol that represents an entire schematic. Encapsulating functional blocks, that is, representing an entire schematic with a symbol, is a powerful method of creating readable and maintainable designs. In order to use this, we will first prepare our existing design for encapsulation and then create a symbol to represent it using the symbol editor Symed. To prepare a schematic for encapsulation, we need to add hierarchical connectors on all the inputs and outputs that we intend to connect to the database records of other schematics. If all we want to do is to make a channel access connection, however, no connector is required. Before we start, insure that your schematic looks similar to figure 2.

  • From the Part menu bring up the Schematic Connectors submenu.
  • Select Hierarchical Input, and place the connector near the INP port of the binary input symbol.
  • Schedit will prompt you for an instance name; enter in0 and press <Return>.
  • Wire this connector to the INP port. (If it prompts you for a wire name; you should press <Return> without entering a name; if you press <Escape> you will lose the connector.)

Before we continue, let’s add a few more binary input channels. First, we must select the binary input symbol along with the hierarchical connector.

From the Select menu, invoke the Area command.

  • Drop a point above the top of the binary input symbol and to the left of the in0 connector, move the mouse below and to the right of the binary input symbol so that the green box completely encloses the binary input and the hierarchical connector.
  • Left-click the mouse.

The binary input, the in0 connector, and the wire for the connector to the binary input should all be selected. If not, try again. Next, place three new binary inputs below the existing one. Before you do this you may want to zoom out so that there is room in the current view for three new binary inputs. However, Schedit will zoom out to fit the selection in the view, and you can use the arrow keys or the scroll bars to scroll while you are in Copy mode.

  • From the Copy menu, invoke Copy With Instance Properties.
  • A green symbol will appear on top of the existing one: move the new symbol to the desired location and left-click the mouse. A new, red symbol will appear along with the green one. Thus, you can see that you can copy and re-copy a symbol without re-invoking the copy menu.
  • Place two more symbols and press <Escape>

Rename the new symbols bi1, bi2, and bi3, and rename the hierarchical ports in1, in2, and in3. To do this, select each symbol and hierarchical port and invoke Relabel from the Text menu. You will then be prompted to enter the name for each symbol. When renaming the ports make sure you do not select the wire that connects the hierarchical ports to the symbol on accident and give it the port’s name. In addition, you will notice that the last symbol copied remains selected: you can invoke the Relabel command and Schedit will prompt you to name the symbol, the hierarchical port, and the wire; be careful not to give the wire either the symbol or port name.

Now wire the VAL output port of each new symbol to the inputs INPC, INPD, and INPE of the calculation record, respectively. Remember to route the wire so that they do not pass through symbols.

Now change the CALC property of the calculation record.

  • Select the symbol and invoke the Properties -> Edit command.
  • In the Properties window left-click on the CACL property, enter A+B+C+D+E in the Value box, click on Add/Modify, and close the Properties window.
  • Insure that your schematic looks similar to figure 3.
  • Save your work by invoking Save from the File menu, choosing the appropriate directory to save it in, entering the name exp in the filename Selection box, and clicking on OK. Quit the schematic editor with the Exit command, also in the File menu.

2.9. Creating a Symbol

The symbol editor Symed is very similar to the schematic editor in most respects. There are minor changes in the command menus, but most commands are the same. Start the symbol editor with the command xsymed. After it has initialized, change to the directory that has the schematic you just created:

  • From the Options menu bring up Search Path.
  • From there invoke Change Current Directory, enter the correct directory path, and press <Return>.

In the white status bar, just below the editing area, it says Align:X, where X is a number. If this number is not 16, change it to 16 by invoking the Snap Grid Size command from the Configure menu, entering 16 at the prompt, and typing y <Return> when prompted to save the change. The snapgrid automatically aligns objects to the nearest number of points specified by X. The value 16 will serve for most work. We are now ready to create a symbol.

  • When creating a symbol, it is usually best to start by defining a port, and then duplicating and renaming it to define the remaining ports.
  • Bring up Drawing Aids from the Insert menu.
  • This will bring up a menu of pre-drawn parts you can use in your symbol; from that menu select In w/stem, bub (input with stem).
  • Drop the port in the editing area by left-clicking. It should be aligned to the grid so that the arrow tail is centered on a grid dot and the bubble is right next to a dot. If it isn’t, use the Edit -> Move command to make it so.
  • While the part is still selected, invoke the Relabel command from the Text menu, and enter the name in0.

Notice that we have given it the same name as the hierarchical connector in the schematic, and that it is also an input. THEY MUST BE OF THE SAME TYPE AND HAVE EXACTLY THE SAME NAME FOR THE SCHEMATIC EDITOR TO MAKE A LOGICAL CONNECTION BETWEEN THEM. Many designers prefer that input ports have the port name appear to the right of the port, instead of above it. To move the text:

  • First change the snap grid’s value to 1 or 2 (this allows finer positioning of the text).
  • From the Text menu, invoke Move, then move the text to the desired position with the mouse, and drop it in place by left-clicking.
  • Change the snap grid’s value back to 16.

Now make three copies of the port, including the stem and bubble, by selecting them with Select -> Area and invoking Copy from the Edit menu. Be sure to space the symbols far enough apart — about two of the spaces defined by the white points.

Now we need to name each of the ports just copied:

  • Select all the ports the same way you selected the binary input symbol and its hierarchical connector (invoke Area from the Select menu, surround with the green box, and left-click) and invoke the Relabel command from the Text menu.
  • Enter in1, in2, and in3 for the ports, respectively.

Now for the rest of the symbol:

  • Add the text exp about 1 grid below and to the right of the ports with Add from the Text menu.
  • Draw a box around everything using Rectangle from the Draw menu: when the pointer is above and to the left of the port labels, left-click, and move the mouse so that the bubbles of the port stems are against the left side of the box and the text exp is enclosed.

The symbol is now finished; save it under the filename exp with the Save command in the File menu. Notice that we have given it that same name as the schematic: the symbol and schematic names must match in order for the schematic editor to make a logical connection between them.

2.10. Creating a Hierarchical Schematic

Now that we have created a schematic and a symbol that represents it, a hierarchical schematic can be created. Open Schedit again and invoke New from the File menu. As before, place a B size border and center.

  • Call up the symbol we have just created by invoking the Get By Name command in the Part menu, and entering exp, the symbol’s name, when prompted.
  • Place the symbol in the edit area.You can invoke Descend from the File -> Hierarchy menu to view the sub-schematic (after first saving the current schematic) and Ascend to return to the top level.
  • Select the exp symbol and invoke Copy With Instance Properties from the Edit menu.
  • Create two more copies of the symbol, select them all and name them ch0, ch1, and ch2. (If all three are not selected by the region, choose More Items or Additional Area from the Select menu and left-click on each symbol or enclose them in another box.)

There are now three copies of the same logic. Many times in database design there is a need for many logically identical channels connected to different physical hardware. Implementing the hardware input channels of the binary input symbols on the exp schematic as hierarchical ports allows the hardware connections to be made on a higher level, making this task an easy one:

  • Select a hardware input symbol from the EPICS Library (all) menu in the Part menu, and place it near the in0 port of the symbol ch0, on the port’s input (arrow tail) end.
  • Wire the hardware input to the port (remember to ignore the wirename prompt by pressing <Return> if appropriate).
  • Place and wire three more hardware inputs to the other ports of ch0.
  • Select all these hardware inputs, and edit their val(in) property to be #CO B0, #C0 B1, #C0 B2, and #C0 B3, respectively. (After you enter the property for one input and click on Add/Modify, you can switch to the Properties window of the next one by clicking on the Close button.)
  • Select all four ports and their wires and copy them so that they connect to the inputs of ch1 and ch2. Edit their val(in) properties to be #C1 B[0-3], and #C2 B[0-3], respectively.
  • Save the schematic with the Save command in the File menu.

A hierarchical schematic implementing three logically identical channels with different hardware inputs is now complete and should look similar to figure 4.

2.11. Advanced Schematic Elements

The schematic we have just created represents the minimum number of concepts and schematic objects required to implement most simple databases. CapFast supports several other connection schemes that minimize clutter on complex designs. We will briefly discuss two of these drawing aids: busses and onpage connectors.

A data bus is a single wire that represents a group of wires in the schematic. By convention, these wires usually have a related function, so it is logical to group them together. Individual wires join a bus through a special symbol, called a bus tap, which is obtained by invoking Bustap Symbol from the Wire menu. The names of the wires to be joined must adhere to the naming formula wirename[index], where wirename is the base name of the wire, and index is a non-negative integer. All wires in a bus MUST have the same base name, and the index of each wire must be one integer in a range of consecutive integers, usually starting from 0. The bus naming rule is wirename[index-range], where wirename is the base name of the individual wires which make up the bus, and index range is the range of integers. An example is a bus named ai[0-7], which is made up of eight wires ai[0], ai[1], . . . ai[7]. We have been ignoring wirenames in this primer; if you want to use a bus tap, you must remember to name each wire accordingly.

The bus tap symbol has two ports, one connecting to the bus and one to the individual wire. The advantage of using busses is that a large amount of related wires can be routed together – reducing clutter significantly, and if done properly, enhancing the designs’s clarity. On the schematic, busses show up as thick blue wires, as opposed to the thin white of individual wires. Busses can also be connected directly to hierarchical ports, which should be named following the same naming rule as the bus. When connecting through levels of hierarchy, the port base wire name and the bus names need not remain the same, but the index range MUST be EXACTLY the same. An example is a bus named t[0-3], which connects to a hierarchical connector named t[0-3], and is connected to bus q[0-3] one level up. The CapFast manual gives a more comprehensive treatment of this subject (pages 3-21 to 3-23 and 4-5 to 4-9), and is recommended as a reference.

Onpage connectors allow the designer to “break” wires into two sections, reducing clutter on complex schematics. These connectors are obtained by invoking Onpage from the Schematic Connectors sub-menu in the Part menu. An onpage connector is obtained for each segment of the wire and usually named the same as the wire. Note that the onpage connector is the only symbol which can have exact duplicates on the same schematic sheet.

2.12. Special Properties

While most symbol properties have to do with either EPICS fields or CapFast specific information, the translator recognizes several properties that allow the user to modify default operation. These properties are set, which allows hierarchical string substitution, and PV, which overrides default naming. These properties are not included by default in any symbol, but can be added by the user when desired. To add a property:

  • Select the desired symbol and bring up the Properties window.
  • Enter the property name in the Name box — in this case PV or set.
  • Enter the value you want for the property in the Value box.
  • Click on Add/Modify.

The set property directs the translator to perform a string substitution in all hierarchical levels below the current symbol. It has the form set:string1 string2, where string2 replaces string1. Only the value fields of primitive symbol properties are checked for string replacement. The set property only has meaning for hierarchical symbols, so it is useless when added to a primitive symbol. In fact, the translator will only check hierarchical symbols for this property. Multiple instances of set are supported on the same symbol, but because of a restriction imposed by CapFast, need to follow a special rule: CapFast does not allow any two properties on a symbol to have the same name, so the set property name must be slightly different for each instance. In the case of the set property, the translator only checks the first three letters for a match with the string set. Thus set, set0, and seta will all be identified as the set property, yet will appear to be distinct properties to CapFast.

The PV property directs the translator to override the default process variable naming method. It has the form PV:string, where string replaces the hierarchical path in the process variable name. The PV property only has meaning for primitive symbols, and has no effect on hierarchical symbols. The resulting process variable is the string concatenated with the symbol name (stringsymbolname). While PV is moderately useful when used in this form, combining set and PV hierarchically creates a powerful alternate naming method. Using set on a higher level symbol, with PV in its sub-schematic allows multiple instances of generic logic with special naming. For example, a generic logic block named aiproc contains four records which have the PV property set to DEV (PV:DEV). The symbols for each instance of aiproc have the set property substituting a string for DEV (set:DEV string). Each instance of aiproc will generate process variable names defined by the instance specific string and the primitive symbol instance names.

2.13. Creating a New EPICS Symbol

New EPICS symbols are created when additional record types are added to the EPICS database. The procedure for creating these symbols is essentially the same as hierarichical symbols, with several important exceptions. Normally an existing EPICS symbol is used as a template, and modified to represent the new record type. An outline of the process follows.

2.13.1. Record Fields:

Each field in an EPICS record (all of which are modifiable by the DCT) has a corresponding property in the symbol. The field name must be EXACTLY the same as the property name. You might even hear the terms field and property used interchangebly. But symbol ports can also represent fields. Normally, link fields and the VAL field are represented as ports, with the remaining fields repesented as symbol properties. Use the Add/Modify and Delete commands in the Properties window to edit properties. There is no limit to the number of properties in a symbol.

Each port can also have properties associated with it, and EPICS symbols utilize this capability. EPICS link fields require several properties to define process passive, alarm propagation, default value, and link resolution. Of these, link resolution requires further discussion.

When resolving wire connections in the schematic, the netlist translator needs to determine what information to extract from the remote symbol. This is accomplished with the typ port property. Two types of information may be extracted, path and val. In the case of path, the translator will return the port and field of the remote symbol. In the case of val, the translator will attempt to find a port property of val on the remote symbol’s connecting port, and return its value. If the remote port has a typ property, its value will override the local port’s typ value. By default, all ports are given typ values, even though only the remote port’s value is normally used. A typical example of this feature is the calculation record’s INPA field connected to a binary VAL field (or port), and its INPB field connected to a hardware input’s in port. In the first case, path information is extracted (because the VAL port has no typ property), and in the second case a value string is extracted (because the in port’s typ field overrides the calulation’s). The syntax of port properties is propname(portname):valuestring. Since the translator is hard coded to search for certain property names, they MUST be:

  1. Process passive – pproc(portname):NPP or PP
  2. Alarm propigation – palrm(portname):NMS or MS
  3. Default value – def(portname):valuestring
  4. Link resolution – typ(portname):path or val

Users may choose to define non-link fields as ports. In this case, no additional port properties are required. An example of this is the VAL field, which is typically implemented as an output port.

In addition to the record’s fields, the primitive property MUST exist in all base EPICS symbols. This property flags the the symbol as a primitive, or non-hierarchical symbol. The value of the primitive property identifies the symbol type. The edb.def file is used by the translator to determine what information to extract for the netlist when it creates the short report. Normally, a schematic file will contain considerably more information than is of interest to EPICS. This includes borders, comment text, non-EPICS symbols, wire names, ect. Each EPICS record type must have an entry in this file to be extracted in the short report. The format of the file is as follows:

(RECORD "type0" "type1" ... "typen" - value of "primitive" property
  (fieldname (datatype))
  ...
)

Example - the analog input record's entry:
(RECORD "eai" "eais" "eaim" "eaisim"
  (PV (char))
  (Type "ai")
  (DESC (char))
  (SCAN (char(default("Passive"))))
  (PINI (char(default("NO")))) 
  (PHAS (int)) (EVNT (int))
  (DTYP (char(default("Soft Channel"))))
  (DISV (int))
  (SDIS (char(default("0.000000000000000e+00"))))
  (DISS (char(default("NO_ALARM"))))
  (PRIO (char(default("LOW"))))
  (FLNK (char(default("0.000000000000000e+00"))))
  (INP  (char(default("0.000000000000000e+00"))))
  (PREC (int)) 
  (LINR (char(default("NO CONVERSION"))))
  (EGUF (float))
  (EGUL (float))
  (EGU  (char))
  (HOPR (float))
  (LOPR (float))
  (AOFF (float))
  (ASLO (float))
  (SMOO (float))
  (HIHI (float))
  (LOLO (float))
  (HIGH (float))
  (LOW  (float))
  (HHSV (char(default("NO_ALARM"))))
  (LLSV (char(default("NO_ALARM")))) 
  (HSV  (char(default("NO_ALARM"))))
  (LSV  (char(default("NO_ALARM"))))
  (HYST (float))
  (ADEL (float)) 
  (MDEL (float))
  (SIOL (char(default("0.000000000000000e+00"))))
  (SIML (char(default("0.000000000000000e+00"))))
  (SIMS (char(default("NO_ALARM")))) )

3. CREATING THE SHORT REPORT


Now that the schematic is complete, it can be translated into an EPICS short report. The translation process has two basic steps, translation from CapFast format to standard netlist (EDIF), and translation from standard netlist to EPICS short report. Translation to standard netlist format is accomplished by the sch2edif utility provided with the CapFast tools. The recommended format is sch2edif -n exptop.sch exptop.edf, which produces an EDIF file named exptop.edf. The -n option causes the translator to leave out graphics data which is not needed for EPICS, and only serves to make the file several times larger. The translation can fail if non-primitive symbols do not have associated schematics, or there are mismatches between symbol port names and hierarchical connector names. If this happens, an error message will be printed by sch2edif, and you must find and fix the problem in the schematic.

The E2SR utility developed by AOT-8 then translates the exptop.edf file to the EPICS short report format. E2SR replaces an earlier utility called edif2sr. It has several advantages over edif2sr; for instance, it performs more error-checking and has higher performance. In the Appendix you will find a full list of its new features, some usage tips, and several important utilities that accompany it.

The short report is then read into the database configuration tool (DCT), after which the database may be tested. It is very important to remember that an EPICS database is flat, while the schematic file can be hierarchical. Changes made in the DCT during debugging can destroy the hierarchical representation, and must be made with care. In many cases it makes more sense to create a makefile to build a short report from schematics, and make any changes at the schematic level. Figure 5 diagrams the the process of creating the database from the CapFast files.

3.1. References

The CapFast manual is an excellent reference for Schedit and Symed (xschedit and xsymed). The main areas of interest are Chapter 5, the Command Reference Guide, Chapter 6, Properties, and Appendix A, Customizing CapFast. Chapter 5 lists all the commands, their functions, and the complete menu tree. Chapter 6 discusses properties, including the CALC property, and property rules files. Appendix A provides information on the setup files, macros, and library definition. Also, AOT-8 has an abridged on-line CapFast Command Reference that describes the basic commands .

The following people at AOT-8 can be contacted for further information about anything covered in this document:

Matthew Needes: mcn@atdiv.lanl.gov
Matthew Stettler: matthew@atdiv.lanl.gov

In addition, you can contact Phase Three Logic for questions that are not EPICS-specific:

Phase Three support: support@phase3.com

Figure 5. The Translation Process


4. APPENDIX A: E2SR v.2.1.0


  • Components of E2SR
  1. e2sr ( e2sr.c e2sr.h e2srOut.c + edb.o + edifLib.a ) — EDIF to short report translator. Run e2sr with no arguments for a description of usage.
  2. edb_filter ( edb_filter.c ) — removes a bug in old edb.def files. This filter can be run again even if it has already been applied.Usage: edb_filter < old.edb.def > new.edb.def
  3. libEdif.a ( edifLib.h edifLib.c edifLibH.c edifMsg.c edifRead.c ) — EDIF library includes the EDIF reader, EDIF error message and diagnostic library, and a host of routines to ease parsing the EDIF file’s image in memory.
  4. lib/sym.tar — symbol library. Manually un-tar this and it will create the lib/sym directory. Add a reference to the following directory into your cad.rc files:EPICS/extensions/src/edif/lib/sym
  5. lib/edb.def — new edb.def. NOTE: edb_filter has already been used to correct this file. Either reference this file from EPICS extensions, or copy it into an application directory.
  6. lib/epics.mnu — CapFast menu for EPICS symbols. Install this file manually into your ~p3/wcs/lib directory.
  • CHANGES
  1. Now uses EDIF library – which (hopefully) simplifies EDIF-related code development.
  2. Increased performance (~ 10% – 30% over original tool). Further performance gains are not fruitful because most of the conversion time occurs during the “sch2edif” invocation (sch2edif converts a multi-file hierarchical schematic into a single hierarchical file). sch2edif is a vendor supplied program.
  3. Supports new $(VAR) variable syntax in addition to old VAR syntax. The new syntax is less ambiguous and results in faster conversion.
  4. E2SR now uses the default values specified in edb.def files. Package includes an edb.def file fixer which fixes a bugs in the original edb.def file (edb_filter).
  5. E2SR now performs more error checking. However, it still does not perform field correctness checking. This is a 4.0 planned change.
  6. Uses UNIX-like argument syntax.
  7. {}s no longer have to be used in place of ()s in property strings.
  8. Compatibility mode generates short reports for older-version schematics. Tested on PSR iss2 database (929 records with lots of hierarchy and buses) and APT injector database (~300 records).
  9. Special characters such as ‘”‘ and ‘%’ are now translated properly, instead of being converted into %NUM% substrings.
  10. -p <name> argument allows several databases to be created from the same schematic hierarchy. (<name> specifies the path to the start of database generation). This allows CA links to be specified in a sane manner, makes certain designs more flexible, and can simplify development.
  • INSTRUCTIONS

Perform sch2edif conversions using the -n, -a, and -p options. Then invoke E2SR with its appropriate command-line options.

E2SR reports its usage when run without arguments:

Usage: e2sr [options] [option args] design.edf

-d <file> EDB file name, default is edb.def
-n <file> Output file name, default is design.sr
-p <path> Schematic path to start of database output, default is top schematic
-o Support old variable syntax, i.e.: VAR instead of $(VAR). WARNING: AVOID OLD VARIABLE USAGE IF POSSIBLE, FOR IT IS AMBIGUOUS AND SLOW TO INTERPRET
-l <file> Log debugging messages to <file> -e Increase error checking
-c Convert {} -> () in property strings. THIS CONVERSION IS NO LONGER REQUIRED
-a Remove leading ‘&’ from numeric names
-t Remove trailing ‘_#’ from repeated names

NOTE: For highest efficiency, avoid options ‘l’ and ‘e’. However, it is recommended that ‘e’ be used occasionally for large databases and ALWAYS for small databases. Use ‘co’, and perhaps ‘a’ or ‘t’ for old schematics.

  • ERROR CHECKING

This version of the translator performs more schematic error-checking than the original tool. However, it does not by default check for all the errors that it is capable of. This is because some error checks impact conversion performance. If the -e flag is used, schematic error-checking will be increased, but with a 50%-100% cost in conversion performance.

Unfortunately, E2SR still does not perform EPICS field checking. This will come later, most likely in the form of a short report or ASCII database file post-processor that anyone can use with their preferred method of database generation.

Because of the performance penalty, it is suggested that you run with the -e flag during initial development and occasionally during the “checkout” phase of a project.

Note that these performance penalties only really matter if you are converting LARGE designs. Small designs ( < 300 records ) should ALWAYS use the -e flag.

  • SPECIAL CHARACTERS

All special characters such as parentheses are ALLOWED in the new version of E2SR. To convert curly braces to parentheses, use the -c option. It is not recommended to perform these conversions anymore, because they are unnecessary and only slow down conversions.

  • VARIABLE SUBSTITUTION

A new method of variable substitution has been added to the translator. With the new method, variables are defined as before with “set” properties, only variable usage differs. To use a variable in a property string, use the “$(VAR_NAME)” syntax instead of just “VAR_NAME” as before.

Variable substitutions using the improved method result in: A. Less ambiguity; B. Higher conversion performance.

The old variable syntax is still supported, use -o to turn on this feature. THOUGH IT IS NOT RECOMMENDED.

example:

(two set properties on a hierarchical symbol at some level above sheet) set:area North Linac seta:dtl 4

(property on a schematic somewhere below that hierarchical symbol) DESC:$(area) $(dtl)

  • EDB.DEF FILE

Unfortunately, the edb.def file is still a part of the translation process.

You may have never noticed it before, but the old edif2sr never actually used the default values specified in the edb.def files. The new version does, but only if you run a conversion program on your original edb.def files.

To use these default values with an existing edb.def file, run the enclosed edb.def file fixer (edb_filter). edb_filter.c describes the exact nature of the bug. This filter can be run repeatedly on the same edb.def file without incident.

  • HIERARCHICAL PATH TO START OF DATABASE OUTPUT

Before version 2.1.0, the translator generated every record at or below the top level schematic. This version, however, allows users to override this and begin database generation from any level of the design.

This allows, in an elegant crude fashion, to partition a design so that CA links may be used between IOCs (before hwins and hwouts were used for this purpose). It can also make development easier, allowing smaller, easier to manipulate databases to be generated without requiring PV name modifications throughout your system (this includes DM screens, ARR archive files, save/restore, etc.). Note that PV naming overrides can accomplish this same task, but are more difficult to deal with.

Suppose you wanted to start database generation from a subschematic of a design called inj. If the instance of this subschematic were named vac, for example, you would use either “-p inj:vac” or “-p inj:vac:” to generate records at or below the vac subschematic.

Note that unless PV naming overrides are used, all record names generated from this example will begin with “inj:vac:”. A future version of the translator will allow the default naming scheme to be overridden at any level of the design.

  • FIELD VALUE RESOLUTION

The following rules apply to field initializations:

  1. A port with a typ(NAME)=”path” or “val” property has highest priority in field value resolutions.An output port can only be initialized by an input field reference or another input port with a typ(PORT_NAME) equal to “val” (e.g.: hwout). Likewise, an input port can only be initialized by an output field reference or another output port with a typ(PORT_NAME) equal to “val” (e.g.: hwin).If a port is not connected correctly E2SR attempts to use the value of the def(NAME) port property of the symbol. If this property does not exist see RULE 3 below.It is bad practice to use a typ(NAME) of “val” for links, even though they will still resolve properly. A typ() of “val” is only supposed to be used on hwout or hwin-like symbols. E2SR will warn about the proper use of “val” when the -e option is used with the translator.
  2. A user-defined port with a properly defined typ(U?) port property works exactly in the way above, except it has SECOND priority in field initializations.
  3. If a port is not found for the field in question, or a port of the name in question does not have a typ(NAME) property set, E2SR will check for a property of that name on the symbol.
  4. If neither a port nor property of that name is found on the symbol, E2SR will attempt to use the default value in edb.def. It will warn you when it uses a default value. If there is no default value it will enter a ” ” string for the field. It will warn you in this situation also.
  5. Ports without typ(NAME) properties are treated as field references. The VAL ports on most of the symbols are examples of field references. When connected to a field reference, the following string is inserted into the database:If the field reference is SLNK,record_name.VALotherwiserecord_name.NAME .(PROCESS PASSIVITY).(SEVERITY MAXIMIZATION)where process passivity and severity maximization are defined by the pproc(LINK) and palrm(LINK) port properties of the symbol originating the link. If the pproc(LINK) property does NOT exist the string “record_name.NAME” will be used. If the pproc(LINK) property is specified but the palrm(LINK) property is unspecified, a warning is generated. BE WARNED.
  6. Ports with typ(NAME) properties equal to “val” are treated as field initializers. The hwin and hwout symbols use ports with such properties. When a port of this type is found during field resolution, the value of the “val(NAME)” port property is used. If the property is NOT set to “val” an error is flagged, and a value of ” ” is substituted in the short report. If typ(NAME) is defined to be “val” but the val(NAME) port property does NOT exist, a warning is flagged, and the port is treated as a field reference. BE WARNED.