[_CD4_]<datools7.0>CDDoc25>ChipNDaleProgramsDoc.tioga!2

ChipNDaleProgramsDoc.tioga

Christian Jacobi, November 30, 1984 6:07:50 pm PST

Christian Jacobi, April 7, 1987 10:58:37 am PDT

ChipNDale

ChipNDale 2.5 — FOR INTERNAL XEROX USE ONLY

ChipNDale

An interactive editor for VLSI designs

Programmers Manual

Release 2.5

Christian Jacobi, April 7, 1987

A relatively incomplete documentation.

Filed on: [Indigo]<ChipNDale>7.0>CDDoc25>ChipNDaleProgramsDoc.tioga

Abstract: ChipNDale, is an interactive graphic layout tool made to run in Cedar. This document document tells you how to write additional programs for the ChipNDale environment. It assumes you know how to program in Cedar generally. For documentation on the bare interactive usage of ChipNDale, there is more appropriate documentation.

XEROX Xerox Corporation
Palo Alto Research Center
3333 Coyote Hill Road
Palo Alto, California 94304

For Internal Xerox Use Only

00. Contents

0. Introduction

1. Uncomplete List of Definition Modules

2. Rules

3. Integration level

4. Using Designs in different environments

5. Registering commands

6. An example object generator

7. All the fuss about Coordinate systems

8. Garbage Collection Of Designs

0. Introduction

This documentation has some rules and hints; it is NOT intended to replace reading the definition modules. The definition modules are the primary place to find documentation.

There is some further quite specific documentation on particular features. This may not be included here, because it is not so of general interest. As pointer to these documentation: either look in the DF file or in the documentation subdirectory. There does not exist a list of these additional documentations. This documentation serves both tool maker and designers creating designs by program.

Toolmakers: be carefull: Whatever you do, try not to wedge a designer; designer keep work worth years in .dale files. They tend allways to use your newest feature, before it is even finished. You then get the problem of supporting their files for the next 200 years.

1. Uncomplete List of Definition Modules

Browsing is a good idea! Look also in the .df files.

Basic Structures

CD, CDDirectory, CDBasics, CDInstances

Basic Objects

CDCells, CDRects, CDSymbolicObjects

Less Basic Structures

CDExtras

Less Basic Objects

CDImports, CDRepetitions, CDAtomicObjects, CDTexts, CDCurves

Generator stuff

CDGenerate, CDGenerateBackdoor

Some Generators

CDGenerateImports, CDRemote

Utilities for generators (not all automatically loaded)

CDUtil, CDCreateLabels

TerminalIO, CDIO, CDEnvironment

Implementors IO

TokenIO, CDRopeViewer

Extension Mechanism

CDProperties, CDValue, CDEvents

Introducing commands

CDSequencer, (CDGenerate)

Registering a technology

CDEnvironment, CDPanel, CDColors, CDAtomicObjects, CDDefaultProcs, CDLayers

Handy stuff on command level

CDOps, CDCommandOps, CDViewer, CDDirectoryOps, CDPropertyTools, CDCleanUp

Getting hand on

CDSimpleRules, CDViewer

Crazy stuff

CDStretchyBackdoor, CDImportsExtras, CDPrivate

Displaying special things

CDViewHighlight, CDViewer, CDErrors

Private viewer stuff

CDVScale, CDVArrow, CDVTicks, CDVPrivate, CDViewerBackdoor

Internal stuff

CDDrawQueue, CDLayers

Technology stuff

CMos stuff

CMosB, CMos, CMosObjects

NMos stuff

NMos, NMosTransistors, NMosContacts

Related stuff

CStitching

2. Rules

Style rules

The style rules make it possible for new people to maintain code, without learning for years about tioga formatting and such crap. (I personally refuse to maintain any program where editing shows to be too painful)

No formats except "code".

Only Cedar style.

No looks which do not appear with the <CTRL>-M command; optional exception: to make interim warnings. You may use XXX or ??? to mark warnings. I hate greek characters in program code and I never have the Idea that a variable "greek lambda" and a variale "l" is the same for the compiler...(nor do I know [or want to know] how to edit that) Greek characters in comments are ok, as long as the size of the font does not change.

Names of procedures are bold, independant if their type is an identifier or a PROC constructor. Names of procedures types are NOT bold.

Use Mesa convention for smaller-uppercase... (optional exception: multiword-constants may be made with lower case letters only, are also acceptable).

Use -- for comments in the middle of code, it's easier to read than looking at the font.

Don't use Cedar's object notation for your own types. Exception where usage of object notation is ok are Cedar types which are very well known, like IO.STREAM, Rope.ROPE and Imager.Context.

Interfaces

Avoid non-readonly public variables in public interfaces.

Is the interface complete?

Are the procedures commented?

There is always a client who wants to use it for something you havn't thought at.

Release Rules

Df files must be verifyed, with 0 errors and 0 warnings.

Do the release version number crap, it's necessary: if the amount of existing code increases we cannot do nice releases of everything at the same time; different releases must be able to coexist.

A Df file has an owner, do not change it nor its contents without notifying him.

Registration rules

Where ever properties are provided for clients, there MUST be comment whether clients have to follow the CDProperties registration rules or not (This 1 bit decision is mandatory, and there exists no maybe). If the CDProperties registration rules do not hold for some property lists, these lists MUST NOT be written out on ChipNDale files. (It would be really a show stopper, not just a style violation)

There is a file ChipNDale-Registrations.tioga which lists some registered features.

Working hints

Do write new modules, change existing ChipNDale modules only later when the new stuff is tested and accepted. This rule has two exceptions: 1) small bug corrections [Feature adding is NOT bug correction, please]. 2) The owner or maintainer of a module owns it and may change it without following this rule.

Your free to write your own extensions, but your extension should not restrict other people to write other extensions; violaters will end up with their code not beeing used.

If you're for limitted time here only

Please think at the maintenance problem. Even if your code is good and bug free, ChipNDale is still evolving, therefore your code has to be updated.

It's better to write a small peace of code which does a complete job, than to have a big module which needs some finish; remember whoever makes the finish will not know your style and intentions by hart.

When your job ends in changing an existing module, try not just to add the new feature. Try to add it such that improving the existing code is not more difficult than without extension. Some modules (of mine) are really not (yet) perfect, and improving the functionality must not prevent later improving the structure.

3. Integration level

There are different classes of programmers needing this documentation.

-Creating a design by program.

-Implementing generators to generate objects; patchWork, PWCore

-Implementing new simple commands. (eg. Split wire)

-Implementing new object classe. (eg. Repetitions, RoutingObjects)

-Implementing new technologyes. (eg. ChipNSil)

-Implementing new complex commands or features, which might need new properties.... (eg. Spinifex)

-Working on ChipNDale itself.

ChipNDale is keep very flexible to ease all these kind of extensions. Mainly the registration rules bother for friendly coexistence of unrelated features.

Properties and objects are saved on files for permanent storage; this is a great area of problems.

The registration mechanism might look like the ultimate solution for extensability, but it is not. The current version of ChipNDale is able to allow arbitrary extensions; however, designs which use some extensions might not be able to be edited with a ChipNDale without implementation of the extension anymore!. Use uttermost care and precautions please.

4. Using Designs in different environments

There are several methods to get your hand on a design for input.

For debugging:

Use the ^-middle command; a popup menu allows you to make an event handler which has access to the design.

For most simple modules which implement a command to operate on one singular design:

Register a command with CDSequencer; Your command procedure will be called and the design is given as a parameter to the command procedure. The command procedure is either called because of an tip-table entry; or, your module registers an entry in a popup menu using the module CDMenus.

Some more complex applications may require commands registered with the (Cedar)commander. It is possible to get a filename and read in that design, using CDIO. On the other hand it is possible to search for an existing design, using CDViewer.FindDesign. Note: this procedure is in the viewer module, because it allows you only to acces designs which have a viewer. (Yes, there are others, but you do NOT want to access them anyway)

An other way is to use any generator environment: CDGenerate.GeneratorProc or PWCore. This is handy if your procedure is supposed to return an object. If your procedure is a generator, it can be called interactively in a design, through a commandtool (if it can run in an emty design) and by programmed calls of the generator.

Which method to chose is dependent on the application, but here some criteria:

If interactive access is important: use a CDSequencer command.

If it returns an object: use a CDGenerate.GeneratorProc or PWCore.

If running from commandfile is important: use the Cedar commander.

There different methods to get your hand on a design for output either:

Create the design; specially good for commandfile usage.

Modify an input design

and keep it visible on screen

and write it on a file

I think that non interactive programs shoud be simple, they read some designs and create and write a NEW output design. Interactive programs may well work on a design, which was found through a viewer, and stays there at the end. More complex mixtures might confuse designers.

5. Registering commands

Use CDSequencer to register a command. You have either to make a tiptable entry or use the pop up menus to call your command. Typically $RectProgramMenu or $ProgramMenu are good pop up menus to register further entries. Commands which create objects can also be registered as generators (CDGenerate).

Aborting

The command should check for abort! well short commands which are immediately finished don't have to. There are several ways to check for abort.

Calling CDSequencer.CheckAborted will signal if the user aborted the command; this signal is catched by ChipNDale's command execution.

For applications which can not spend the time of busyly calling a check procedure, an Event mechanism exist. The event (CDEvents) $Abort is called when an abort is issued.

Applications which involve drawing some objects may use the stop flag of the drawrecord to cause finishing the drawing.

A handy feature is CDCommandOps.CallWithResource; this procedure catches an abort event and sets you an abort flag.

Resources

Certain modules use global variables which must be protected; CDCommandOps.CallWithResource is the tool to manage such resources.

Generally CDCommandOps is a module which gives you some "creaturecomfort-level" help in implementing commands. (CDCommandOps is not considered a part of the kernel of ChipNDale, but is loaded with any ChipNDale config which contains commands)

6. An example object generator

Example 1

Example.mesa

Example of ChipNDale usage

by Christian Jacobi, June 5, 1985 8:02:35 pm PDT

Last Edited by Christian Jacobi, July 10, 1985 10:28:49 am PDT