[Indigo]<Chipndale>documentation>ChipndalePrograms21.tioga!1

ChipndalePrograms21.tioga

Ch. Jacobi, November 30, 1984 6:07:50 pm PST

Ch. Jacobi, June 28, 1985 4:18:59 pm PDT

CHIPNDALE

CHIPNDALE 0.21 — FOR INTERNAL XEROX USE ONLY

Chipndale

An interactive editor for VLSI designs

Programmers Manual

Release 0.21

Ch. Jacobi, Kim Rachmeler Jan 3, 1985, (May 6, 1985)

A relatively incomplete documentation.

Filed on: [Indigo]<Chipndale>Documentation>ChipndalePrograms21.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 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

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.

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 than get the problem of supporting their files for the next 20 years.

1. Definition Modules

Basic Structures

CD, CDDirectory, CDDraw, CDOrient, CDBasics, CDApplications

Basic Objects

CDCells, CDRects

Less Basic Structures

CDInterestRects, CDExtras, CDMarks

Less Basic Objects

CDImports, CDRepetitions

TerminalIO, CDIO

Implementors IO

TokenIO, CDRopeViewer, CDMark

Extension Mechanism

CDProperties, CDValue, CDEvents, CDCallSpecific, CDObjectProcs

Introducing commands

CDSequencer, CDMenus

Registering a technology

CDTipEtc, CDDefaults, CDLRUCache, CDPanel, CDColors

Handy stuff on command level

CDOps, CDCommands, CDCommandOps, CDViewer

Crazy objects

CDConditions, CDMarkObjects, CDTexts

Crazy stuff

CDStretchyExtras, CDImportsExtras, CDPrivate, CDDirectoryExtras

Private viewer stuff

CDVScale, CDVFurtherPainters, CDVArrow, CDVTicks, CDVPrivate

Technology stuff

CMos stuff

CMos, CMosTransistors, CMosContacts

NMos stuff

NMos, NMosTransistors, NMosContacts

Related stuff

CornerStitching

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.

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

No 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 hav'nt 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)

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, therfore 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.

-Working on chipndale itself.

-Implementing new object types. (eg. Conditions)

-Implementing new technologyes. (eg. Chipnsil)

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

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

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)

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

If interactive access is important: use a CDSequencer command.

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. (Module CDMenus) Typically $RectProgramMenu or $ProgramMenu are good pop up menus to register further entries.

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. To be written

to be written