Open Schematic Capture Files

                                                                  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".