ChipndalePrograms18.tioga
Ch. Jacobi, November 30, 1984 6:07:50 pm PST
CHIPNDALE
CHIPNDALE 0.18 — FOR INTERNAL XEROX USE ONLY
Chipndale
An interactive editor for VLSI designs
Programmers Manual
Release 0.18
Ch. Jacobi, Kim Rachmeler (Nov 30, 1984)
A relatively incomplete documentation.
Filed on: [Indigo]<Chipndale>Documentation>Chipndale18.tioga
© Copyright 1984 Xerox Corporation. All rights reserved.
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 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 10 years.
1. Definition Modules
Basic Structures
CD, CDDirectory, CDDraw, CDOrient, CDBasics, CDApplications
Basic Objects
CDCells, CDRects
Less Basic Structures
CDInterestRects, CDExtras, CDMarks, CDX
Less Basic Objects
CDImports, CDRepetitions
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, CDPropertiesExtras
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.
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.
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