2023/07/29
OPEN SCHEMATIC CAPTURE README FILE
1. Quick start
1.1. What's new in release 0.30
- Moved requirement from Java 11 to Java 17
- Re-converted Magic from C using magic-8.3.169
- Switched form internal lvs to open source Netgen which was translated
to Java
- Various tweeks and bug fixes
1.2. Getting it running
- Ensure java 17 or better is installed.
- Download <rev>_open_sch_capt.zip and unzip to some place we'll
refer to as:
${app_dir} = <some_path>/open_sch_capt
Note: Windows doesn't like unzipping to long path names. If you
have problems unzip output to something short like C:\tmp\osc.
- Open a terminal window, go to ${app_dir}/open_sch_capt and
run run_linux_install_test or run_windows_install_test.cmd to check
the installation and run through the program features.
- Open a terminal window, go to ${app_dir}/open_sch_capt and run
run_linux or run_windows.cmd to run various programs. You can also
double click on these scripts.
2. Introduction
There are 2 possible zip downloads:
<rev>_open_sch_capt.zip -> program only
<rev>_open_sch_capt_development.zip -> development
Note: development release is a super-set, so you don't need both.
This discussion assumes you downloaded and opened the
<rev>_open_sch_capt.zip package. It is sufficient to run the full
range of programs.
The <rev>_open_sch_capt_development.zip package has a more exotic
structure. It is intended for developing the program, is a super set
of the program only version and contains source code and supports an
Ant build.
Open Schematic Capture is a set of programs intended to be a
production grade open source mixed analog/digital IC schematic entry
and layout tool along with a project manager and net listers. A system
level simulator and a data viewer are also included. It has the
following features:
- Java based
- Runs on anything that supports a java virtual machine
- Inherits power of Java graphical interface
- Open source
- Directory based data structure
- Library/tool/set/circuit/view directory structure
- Easy maintenance and re-configuration of data
- Schematic entry:
- XML based ASCII data files
- Human and XML tool readable data
- Robust data structure -> able to track down and fix weird data
problems
- Able to create/modify cells with external tools/programs or by
hand
- Supports if frames
- Allows branching control for net listing to multiple tools
- Supports for frames
- Supports parameter passing
- Supports ability to generate/run transcript files
- Supports undo/redo
- Maintains circuit modifications history
- Supports multiple users
- Simulation
- Supports netlisting and circuit simulation using external
NGSpice program.
- Supports VHDL netlisting and simulation.
- Supports system netlisting and simulation.
- Layout:
- Translation of the "Magic" layout program from C into Java
- Reasonable (and expanding) editing capability
- Supports Magic database format
- Includes extract and LVS
The data structure of the unzipped file is:
open_sch_capt
|-- LICENSE
|-- osc_manual.pdf
|-- README.txt - this file
|-- run_linux
|-- run_linux_install_test
|-- run_windows.cmd
|-- run_windows_install_test.cmd
|-- src
| +-- data
| +-- open_sch_capt_data
| |-- osc_example_projects
| | |-- example1
| | |-- example2
| | +-- example3
| |
| |-- osc_libraries
| | |-- osc_misc_lib
| | +-- osc_std_lib
| |
| |-- osc_process_libraries
| | +-- dummy_process_lib
| +-- osc_shell_scripts
|
+-- target
+-- open_sch_capt.jar - compiled program and resources
The downloaded package consists of three main parts.
- Top level files
The top level files are a license file, this readme file, and
some scripts to test the install and run the program.
- Jar file - target/open_sch_capt.jar
All programs associated with Open Schematic Capture and their
associated support code are compressed into a single Java Archive
(jar) file, which is just a zip file with some extra stuff required
for Java. A specific program is run within Java by giving the
location of the jar and the path to the program within the jar.
- Data base directory - src/data//open_sch_capt_data
The data base contains the data the programs will interact with.
This includes generic schematic libraries, shell scripts, program
scripts, example projects, etc.
Interface to other tools ( system sim / analog sim / digital sim /
mixed mode sim / LVS ) will be through netlists.
Creating a complete design flow ( design, simulation, layout, and mask
generation ) requires that this program interface with simulators and
that everything be tied together with a process library. Also, the
translation of the "C" version of Magic is not far enough along to
stand alone and the "C" version is required for final checks and
back end mask generation. An example project and a "dummy" process
library are included in the data base to give an example of a complete
design flow. Other open source programs will need to be installed to
completely work through the example.
3. Requirements
Open Schematic Capture requires the following:
- Required: Java virtual machine - see discussion below
- Required: Open Schematic Capture installed
- Optional: Java compiler - see discussion below
required only for system and vhdl simulator
The following open source programs are recommended for creating a
complete design flow:
- NGSpice for analog simulation
see ngspice.sourceforge.net
- GHDL, C compiler, & Gtkwave for digital simulation
OSC has a VHDL simulator, but it is less standards compliant
and less well tested
see ghdl.free.fr
see gtkwave.sourceforge.net
- "C" version of Magic layout editor.
This requirement will eventually go away when the Java
translation of Magic is better tested.
see opencircuitdesign.com/magic
Open Schematic Capture should work well on multiple operating systems,
however, other open source software is more particular. Linux is the
best choice for getting a complete design flow up and running, and
Fedora Linux in particular, gives good support for NGSpice, GHDL,
Gtkwave, and the "C" version of Magic.
4. To install
4.1. For Open Schematic Capture
The program suite runs under a Java virtual machine (jvm) and so the
application "executable" is identical for Linux and Windows and
(probably but untested) Apple.
Since the program suite is not targeted to a particular operating
system, no attempt has been made to support any operating system
specific installs. The general philosophy is to unzip it, put it
somewhere, and write/modify a few shell scripts to run it.
- download the zipped application <rev>_open_sch_capt.zip
- unzip it -> top output dir will be "open_sch_capt"
- move "open_sch_capt" directory to final resting place
which will be referred to as ${app_dir}
4.2. For NGSpice, GHDL, Gtkwave, and "C" Magic
In Fedora Linux, pre-compiled versions of these programs can be
downloaded directly from the repository. Other distributions or
operating systems may require installation from program web sites.
5. Projects
5.1. Project structure
A project has a project directory located somewhere on the file
system. The project directory contains various information and
control files and directories for the project. All project data is
maintained in library directories, some of which may be under the
project directory and some of which will be located elsewhere.
Each library has an alias name of @<some_unique_name> whose value
is maintained in the properties.xml file in that library directory.
All OSC tools refer to libraries by their alias name and not by
their true file system location. The proj_file.xml file in the
project directory contains the translation table between alias
name and true file system location.
Common libraries would be at some central location and be
referenced by the project file of multiple projects.
Each project points to a single process library. Process libraries
need to have a fairly rigid structure in order for the program to
find stuff. An example can be seen at
${app_dir}/open_sch_capt_data/osc_process_libraries/dummy_process_lib.
The process library has a file system structure as follows:
<lib_name>_lib - library of circuits
properties.xml - file of properties associated with
library
documentation_tool - directory for documentation
spice_tool - directory for Spice stuff
models - directory for models
vhdl_tool - directory for VHDL stuff
design_tool - directory for design stuff
layout_tool - directory for layout stuff
autoroute_ctrl.txt - file to control autorouting
create_cell_rules_file.txt - this file is not used yet
lvs_control.txt - file to control LVS
technology_files - directory for Magic stuff
mos.24bit.dstyle - Magic styles file
mos.24bit.std.cmap - Magic colors file
scmos.tech - Magic technology file
device_subckts.spice - defines oddball devices Magic
extractor does not recognize
Data libraries also need to have a fairly rigid structure. Libraries
are layed out quite similarly to the process library. Each library
has a file system structure as follows:
<lib_name>_lib - library of circuits
properties.xml - file of properties associated with
library
documentation_tool - directory for documantation
spice_tool - directory for Spice stuff
vhdl_tool - directory for VHDL stuff
java_tool - directory for java sim model source
code
sim_models_sys_set - directory for hand written models
sim_models_vhdl_set - direcotry for models generated from
VHDL
layout_tool - directory for layouts
<set_name>_set - directory for set of similar circuits
<ckt_name>.mag - circuit layout file
ctrl_files_dir - script files to do various things
design_tool - directory for schematic and
simulation data
<set_name>_set - directory for set of similar circuits
<ckt_name>_ckt - circuit directory
symbol_view - symbol view directory
sheet<n>.xml - data files in xml format
schematic_view - schematic view directory
sheet<n>.xml - data files in xml format
vhdl_view - Vhdl circuit models, simulation
control files directory
spice_view - Spice circuit models, simulation
control files directory
system_view - System level simulation control
files directory
<name>_tool - directory for other stuff as required
There is a special data library that provides standard stuff needed by
all projects. It is located at
${app_dir}/open_sch_capt_data/osc_libraries/osc_std_lib.
5.2. Directory and File Naming convention
Directory structure:
<lib>_lib - library directory
<tool>_tool - tool directory
design_tool
documentation_tool
java_tool
layout_tool
scripts_tool
vhdl_tool
<set>_set - directory containing set of related
circuits/objects
<circuit>_ckt - directory for a given circuit
<view>_view - directory containing circuit view
( schematic/symbol/etc )
Files:
<file>.bsh - scripting file in bean shell syntax
<file>.cmd - windows os command script
( linux scripts do not have an extension )
<file>.ext - magic extracted netlist file
<file>.inc - spice include file
<file>.java - java source file
<file>.lck - locks out file from writing by other than owner
<file>.mag - magic layout file
<file>.props - layout properties file for a circuit residing in a
layout set directory ( necessary to stay
compatable with "C" Magic program )
<file>.spi - spice file
<file>.sys - internal system simulator data file
<file>.txt - text file
<file>.vhd - vhdl file
<file>.xml - data/info file in xml format
sheet<n>.xml - default name for data schematic data sheets
Misc:
<circuit>_x_<set>_x_<lib> - circuit naming convention to avoid
name collision in flat net lists
5.3. General Naming convention
This program will interface with multiple operating systems,
simulators, and possibly other tools, some of which are case sensative,
some not. It will be uncertain whether xyz equals XYZ. Therefore, it is
best to stick with only one case throughout the design. Lower case has
been used in all included libraries and examples.
The program assumes the "old school" unix naming convention for
directory and file names, and for many things within the program. For
the schematic entry tool use a character set limited to alph-numerics
and underscores, with the following exceptions:
- Spaces " " are allowed only in "C" like expressions, strings,
and text boxes.
- Never use a double underscore "__".
- For unix/linux, use / for directory or file path separators
- For windows, use \ for directory or file path separators for
shell commands or shell scripts. Java will recognize \ or /
as a path separator, so any path used by the program will
handle either syntax.
- File and directory names may have "." separators for extensions
- [<m>:<n>] for m and n are integers with m > n is a bus with
range m downto n
- $<name> or ${<name>} is a variable called <name>
- @<name> is a library path alias called <name>
- "some string with &@-*^..whatever.." is a string
- expressions use "C" like syntax
For the "Magic" layout tool, consult documentation for the "C" version
of the tool.
The design example uses bus order of [msb:lsb] so that is what has
received the most work. It also has some subtle advantages when
interfacing with the simulators. If you use [lsb:msb], some testing has
been done, but you may still run into net list problems. If you mix bus
order, shame on you.
Care needs to be taken with circuit names. The schematic entry part of
Open Schematic Capture can handle circuits in different libraries or
circuit sets having the same name. However, the layout part is
based on "Magic" which requires all circuits to have a unique name.
Therefore, you should ensure that all circuits have a unique name.
6. Included programs
6.1. Project creation GUI tool - my_proj.open_sch_capt.osc_create_proj
The project creation tool provides a graphical tool to create a new
project.
6.2. Project manager GUI tool - my_proj.open_sch_capt.osc_manager
The project manager tool provides a graphical view of the project
data base. It also executes project management commands in a somewhat
friendlier manner than the schematic entry tool.
6.3. Design entry GUI tool - my_proj.open_sch_capt.osc_design
The design entry tool is used for entering schematics. It can
also execute project management commands. It also includes a
layout viewer for layouts done with the "Magic" layout program.
6.4. Net lister - my_proj.open_sch_capt.osc_netlist_cmd_line
- my_proj.open_sch_capt.osc_netlist_gui
The net lister can be run from the command line or from a GUI tool.
6.5. System simulator - my_proj.open_sch_capt.osc_sim_system
The system level simulator is an event driven, fixed discrete time
simulator, much like a digital simulator. However, it is targeted
toward analog simulations. Schematics are net listed in a flat
Spice like syntax and read in. Standard digital models are built
into the simulator. Java file outlines for custom models can be
auto-generated and must be hand edited. They are compiled and
linked in.
6.6 Vhdl simulator - my_proj.open_sch_capt.osc_sim_vhdl
This release is a first attempt at a vhdl simulator. Schematics are
net listed to hierarchical vhdl. Vhdl file outlines for custom
models can be auto-generated and must be hand edited. All vhdl is
converted to Java, compiled, and then run.
At this point the vhdl syntax understood by the Java converter is
limited. It can understand vhdl generated by the netlister but
only fairly basic syntax when converting custom models.
6.7 Data viewer - my_proj.open_sch_capt.osc_sim_graph
The data viewer is a gui data viewer for output from the system
simulator and for "raw" data output from the NGSpice simulator.
6.8 Layout vs schematic - my_proj.open_sch_capt.osc_layout_vs_schematic
Checks Magic layouts against the corresponding schematic.
6.9 Router - my_proj.open_sch_capt.osc_auto_route
The router will route digital cells. It is rather limited in the
cells it will handle and is not terribly efficient.
6.10 Modify Spice output - my_proj.open_sch_capt.osc_spice_modify_output
This program will reorginize the output of a NGSpice op point text
file to make it more readable.
6.11 Master program - my_proj.open_sch_capt.osc
This program can call other programs. It is mainly used within a
Java Web Start package that is experimental at this point.
6.12 Other
There are a few helper programs for simulation and layout. Look for
examples of their use in shell scripts in the example project.
7. To run
7.1. Java virtual machine (jvm) and java compiler
Java is a complicated beast. You want access to version 8 or
later of java (executable you call). This is the java virtual
machine (jvm) that actually runs the programs contained in
<path>/open_sch_capt/target/open_sch_capt.jar. You also
want the java compiler, javac, which is needed to run the
simulators. It compiles java source that you write or
automatically generate from VHDL.
In Linux, you can download the full package from the appropriate
repository. This will give you the OpenJDK version of Java which
includes the Java Runtime Environment (JRE) package containing the
java executable and the Java Develpment Kit (JDK) package
containing javac.
In Windows, you will need to download from Oracle, which hosts
Java. You want to make sure you download the JDK which includes
the JRE and not the stand alone JRE. For whatever reason, this
will give you 2 JREs after you install:
C:\Program Files\Java\jre<version>
C:\Program Files\Java\jdk<version>\jre
Windows will default to the former, but you must use the latter
in order for java to be able to find the javac compiler. These
issues may disappear with modularized Java 9.
7.2. As mentioned above, you can call the GUI to run programs.
To run included programs from the command line
Usage:
[<java_path>/]java [-cp <class_path_dir>] <program_name> [options]
Args:
java : Path to java virtual machine executable
: Not needed if included in
environmental variable PATH
class_path_dir : Class path is path to dir containing
java classes needed for this app
: Set to <install_path>/java_classes
or to jar files
: Not needed if included in
environmental variable CLASS_PATH
program_name : my_proj.open_sch_capt.<tool_name>
: Ex: my_proj.open_sch_capt.osc_design
Options:
--help|-help|--h|-h : Prints help message
other options : Do help for specific program.
Example:
<some_path>/java \
-cp <some_path>/open_sch_capt.jar \
my_proj.open_sch_capt.osc_design \
-proj <some_path>/proj_file.xml \
-nolic
<program_name> values:
my_proj.open_sch_capt.osc
my_proj.open_sch_capt.documentation
my_proj.open_sch_capt.osc_create_proj
my_proj.open_sch_capt.osc_manager
my_proj.open_sch_capt.osc_design
my_proj.open_sch_capt.osc_netlist
my_proj.open_sch_capt.osc_layout_vs_schematic
my_proj.open_sch_capt.osc_sim_system
my_proj.open_sch_capt.osc_sim_vhdl
my_proj.open_sch_capt.osc_sim_graph
my_proj.open_sch_capt.osc_auto_route
my_proj.open_sch_capt.osc_spice_modify_output
8. Simulation, Synthesis, and Digital Support
For analog, the net lister will generate a net list in NGSpice
format. NGSpice includes a "mixed mode" option that works well for
a limited amount of digital. However, Spice is not very good for
large sections of digital often found in mixed mode designs.
Digital support is something of a problem. As far as I can tell, there
are not any open source synthesis tools for VHDL or Verilog. This
program has limited VHDL simulation support, but no synthesis support.
An attempt was made to optimize the schematic entry tool for digital
schematic entry.
To simulate digital, the net lister has an option to generate VHDL
source from schematics. Simple VHDL models can also be written for
the analog, thus providing full chip simulation. The included
VHDL simulator or GHDL is then used to simulate the resulting
netlist. Gtkwave is used as the viewer for the GHDL output. The
included VHDL simulator is very rudamentary and will choke on
anything but the simplest syntax.
Alternately, the net lister can generate a Spice like net list that
is used by the included system level simulator. Here, Java models
can be written for the analog, again providing full chip simulation.
9. Scripting
Scripting in the schematic entry tool is supported by the "Bean Shell"
scripting program (not to be confused with shell scripts) from an
independent project. See www.beanshell.org for details. Bean Shell has
a number of advantages as a scripting language:
- It is designed to interface with Java, and so has access to main
program functions and data structures.
- It uses Java syntax, so frequently used scripts can easily be pulled
into the main program if desired.
- I didn't have to write it.
Scripts exist as independent files that can be called up from inside
the schematic entry tool and then run through the "Proj->run script"
menu item. The following script directories are automatically
recognized by the program:
${app_dir}/open_sch_capt_data/osc_scripts
${home_dir}/.open_sch_capt/log_files
Additional script directories that contain scripts must be declared in
the project xml file.
${home_dir}/.open_sch_capt/log_files/log_file.bsh contains the
commands run in the most recent schematic entry session as a script
file.
The schematic entry tool also has a command entry line labeled as
"cmd line" and a command history window, both of which can be
displayed or hidden. Commands can be entered on the command entry
line in one of two formats or searched for by tabbing:
- exact cmd syntax example: cmd.shtMove ( "[-220,160]" );
- short cut syntax example: shtmov -200 160
- using tab example: shtm<tab>
In the short cut syntax "cmd." is dropped, case of the command is
ignored, only enough of the command to make it unique is required,
and arguments are separated by spaces. Commands are converted to
exact syntax before being executed.
Note that only exact syntax can be used in script files.
10. Example projects
Documentation is sparse, however, there are example projects located
in ${app_dir}/open_sch_capt_data/osc_example_proj. After you get the
design tool running, you can load an example by using the menu:
Example_Projects -> open example proj 1
Example_Projects -> open example proj 2
Example 1 is a mixed analog/digital design with a MII serial
interface, a simple current steering digital to analog converter
(DAC), and a simple pipe line analog to digital converter(ADC).
Most development was done using bus bit order of [msb:lsb], which is
the recommended bit order. However, Example 2 is a version of
example 1 paired down to just a MII serial interface and using bus
bit order of [lsb:msb], included to allow trouble shooting of the
tool for that alternate bit order.
11. Customization
11.1. Customizing with configuration files
The program can support custom menu items, scripts, methods, and
parameters, all implemented with ASCII configuration files. As an
example, see
${app_dir}/open_sch_capt_data/osc_example_proj/proj_file.xml
and files in
${app_dir}/open_sch_capt_data/osc_example_proj/ctrl_files_dir.
11.2. Customizing some source code
If you want to modify a limited amount of source code and still be
compatible with future releases, then limit your mods to files in
${app_dir}/java_source/my_proj/open_sch_capt/custom and then
recompile.
12. Misc
12.1. File write locking
File permissions of the native operating system must be set
correctly.
In order to write to a schematic/symbol xml data file, there are 2
complementary write locking mechanisms that must both be OK.
Xml data files have an entry of
"<xml_sheet_data ...... writable="true/false" ......... >". If
writable="false" then the program will refuse to write to this
file. Any cells created within the program will have
writable="true". The writable attribute must be hand edited with
a text editor to change it. This is intended mostly for standard
library cells that should never be modified.
When a schematic/symbol drawing window is opened the program
attempts to create a write lock on the corresponding data file
by creating a file named <xml_file_name>.lck. If the
<xml_file_name>.lck file already exists the drawing window will
not be able to do edits on that schematic/symbol. If the drawing
window successfully acquired the lock, the <xml_file_name>.lck
file will be deleted and the lock released when the window is
closed. If a schematic/symbol refuses to allow writes and no one
else is using it, the program probably failed to delete the
<xml_file_name>.lck file. In this case, the program can demand
to override the write lock, or the <xml_file_name>.lck file can
be manually deleted.
12.2. Schematic net listing
Schematic net listing is a 3 step process.
The first step creates a file named
<path_to_circuit>/base_netlist.xml for each circuit required by
the final net list that is a generic base net list for that
particular circuit.
The second step reads the base_netlist.xml files for all required
circuits and outputs a hierarchical Spice net list with some
extra data added as comments.
If required, the hierarchical Spice net list is used to generate a
flat Spice net list or a hierarchical VHDL net list.
For a VHDL net list, if a <path_to_circuit>/vhdl_view/model.vhd file
exists, that file will be incoporated into the netlist, replacing
the schematic for the circuit.
12.3. Multiple schematic sheets, multiple and fragmented symbols
Initially the program supports only 1 schematic sheet and 1 symbol
representation per circuit. Eventually it may support multiple
schematic sheets and multiple symbol representations per circuit
as well as the ability to fragment a symbol into several
independently placable pieces.
12.4. Differences in schematic and layout tool behavior
The schematic entry tool was implemented first and is set up more
or less to have key strokes define an operation and mouse clicks
execute the operation. The layout tool is as faithful a translation
as possible of the "C" version of the program. Here a lot of
operations tend to be based on using the mouse for positioning
and using key strokes to define and execute the operation. This
means that things like select, copy, move, etc behave differently
from the schematic entry tool.
12.5. Separation of schematic and layout data
Schematic and layout data are separated fairly high in the library
structure. This makes life easier for the design and layout guys.
12.6. Run install test
Included in the data base are scripts to test the installation of the
program by exercising the example project included in the data base.
To run the test go to ${app_dir} and run:
run_linux_install_test
or
run_windows_install_test.cmd
This also provides an easy way to become familiar with the program.
12.7. Status of the layout editor
The layout editor is intended to be a faithful as possible
translation of the "C" version of the Magic program, originally from
UC Berkeley. The translation is not yet complete. The layout editor
is now reasonably functional, still with bugs and holes. It will
improve over the comming releases.
12.8. Viewing text files in Microsoft Windows
An attempt was made to save all text files in Microsoft format, but
some may have been saved in Unix format. For these files the
default Microsoft Windows text editor "notepad" won't handle the
format well. For these files, use "wordpad" or a third party text
editor such as "vim".
