------------------------------------------------------------------- A Tcl-wrapped version of magic ------------------------------------------------------------------- This file contains details on the compilation, installation, and execution of the Tcl interpreter-based version of Magic. ------------------------------------------------------------------- Compiling and Installation ------------------------------------------------------------------- Compiling and installing have been simplified, but are not exactly the same as the "standard" compile and install procedure, so be sure to read these instructions first. 1) Software prerequisites: You will need Tcl and Tk versions 8.2+. Testing has been done on Tcl and Tk versions 8.3 and 8.4. Some commands are only compatible with versions 8.2 and newer; these should be #ifdef'd sometime in the near future to make the program compatible with Tcl versions at least back to 8.0. For use with the wrapper GUI, it is preferable to have BLT version 2.4 or newer to get the tree view of the cell hierarchy, although the presence of BLT is not mandatory. For digital simulation, you should have IRSIM version 9.6 revision 1 or newer. Presence of IRSIM is not mandatory. Note that unlike magic versions 7.1 and older, the IRSIM module is not selected at compile-time; in Tcl it is a run-time loadable module. 2) At the top level, do "./configure" and any other options (such as "--prefix=DIR" for non-default installation location). "prefix" determines the value $CAD_ROOT, which is set to ${prefix}/lib, unless "--libdir=DIR" is set, in which case $CAD_ROOT is set to this value. The "configure" script will determine if Tcl is on the system, and enable it if it appears to be usable. Note that if Tcl is installed in a non-standard location, it will be necessary to pass the option "--with-tcl=<DIR>" to "configure", indicating the directory where the file "tclConfig.sh" can be found. Likewise, the "configure" script attempts to find OpenGL include files and libraries on the system, and enables the option if it can find them. Again, if in a nonstandard location, it is necessary to pass the option "--with-opengl=<DIR>" indicating the directory where OpenGL include files may be found. It is assumed that the libraries are in a standard directory; if not, it may be necessary to make symbolic links to them from a standard directory like /usr/X11R6/lib/. 3) Do "make". This should complete the compilation of the Tcl-compatible shared library file "magic/tcl/tclmagic.so". 4) Do "make install". This should place all the necessary executables, library files, etc., into the proper places. The main executable is "magic" (a script). Normally, it runs Tcl from a console window ("tkcon", at least for now). With a command-line argument "-noconsole", it runs Tcl from the terminal (runs "magicexec", a stand-in for "wish"). Original executables "ext2spice" and "ext2sim" have been changed to magic command-line commands. They are available as separate packages to Tcl and are loaded automatically by the startup Tcl script. 5) Any other ".tcl" files (packages) for magic go in $CAD_ROOT/magic/tcl/. Magic's Tcl startup appends this directory to Tcl's search directory for Tcl/Tk executables. 6) Make sure that the default .magic script and any user .magic scripts do not have embedded control characters (see below in "Known Bugs"). The one installed by the distribution is correct; the warning applies to any legacy files. ------------------------------------------------------------------- Running Tcl-based magic ------------------------------------------------------------------- 1) The startup script works out namespaces so that all magic commands become directly available from the command line. A number of commands have to be specially handled because of conflicts with existing Tcl/Tk commands. These are: "flush", "clockwise", "array", "load", "label", and "grid". From magic version 7.2 revision 31, all of these commands can be run as either the original Tcl/Tk command or as the magic command, and the correct function will be called (because the syntax of the two forms is mutually exclusive). In cases such as starting magic from another application like irsim or netgen, all magic commands are prefixed by the namespace "::magic::" to differentiate them from command names in other applications. Note that some commands (ones which are not often used) have simply been renamed. The command "list" has been replaced (and its functionality extended) by commands "cellname" and "intance". Command "split" has been changed to "splitpaint" (which matches the "spliterase" command). Commands "source" and "send" are superceded by Tcl methods and no longer exist as their former selves in magic. In particular, "send" (sends a magic command to a window) is superceded by the syntax of the window name followed by the magic command (see item 4, below). Because magic extends Tcl, the "source" command is equivalent to Tcl's "source" command). Commands for separate packages (namely, ext2sim and ext2spice) share the magic namespace: magic::ext2sim and magic::ext2spice. The magic startup script automatically loads these packages and makes the commands available from the root namespace, i.e., "ext2sim" and "ext2spice". 2) Command entry works as follows: Because the underlying Tcl interpreter is *supposed* to look and act like a normal Tcl interpreter, single-key macros are only allowed from inside windows. The use of the ":" macro (long-command) is implemented as faithfully as allowed by the interpreter. When using the terminal as a console, it is not possible to enter a command partially in the terminal or window and complete it in the other. Also, the status of the background DRC is not reflected in the cursor. The "tkcon" console-based version has a cursor which reflects the DRC status, and commands may be entered partially or in full in either the layout or the console windows. The cursor is "%" for normal operation, "]" for DRC-in-progress, and ":" for commands initiated by the long-command macro. Note that due to inherent limitations of the Tk "text" widget, the insert cursor is not displayed in the console when the cursor is in the layout window. Queries to the user force focus into the console window; this will probably be reimplemented in dialog boxes in the future. 3) Tcl-magic should work with "tclreadline". The "tkcon" console-based version has its own working readline-like capability. Note that internally defined completion functions like cellname completion are not available. 4) Window commands: Note that in addition to the standard magic commands, the Tcl/Tk version makes it possible to direct commands to a particular window; e.g., ".magic2 paint m1" can be run from the command line in place of putting the cursor in window ".magic2" and executing the command "paint m1". This allows any possible magic command to be run from a script. The deprecation of magic's "send" command has repercussions on window commands, particularly when using non-layout windows. For example, the [non-TCL-based magic] command "send netlist shownet" is supposed to execute the "shownet" command in the context of the netlist window ("specialopen netlist"). However, under Tk, "netlist" is not a valid window path; the correct command is to note the window name (usually something like ".magic2") and to use it to direct the command: ".magic2 shownet" will execute the command "shownet" in the context of window ".magic2". 5) Command tags: A command called "tag" has been added with the following syntax: magic::tag <command_name> <tcl_procedure> This allows an arbitrary Tcl procedure to be associated with any magic command. The usual reason to do this is to allow GUI functions to be updated in response to command-line entry or key macros in a window. The method can also be used to re-organize Tcl output from a command, or send commands to another Tcl application in response to actions in magic. <command_name> is a simple command name without any namespace qualifier (e.g., "select" or "paint"). <tcl_procedure> is a string which may be either an inline procedure or a call to a defined Tcl procedure. This string may contain certain embedded escapes which will be substituted prior to evaluation. The escapes are: %W Full Tk pathname of the layout window %R Tcl result of <command_name>. The result is absorbed. %r Tcl result of <command_name>. The result will be returned to the calling function as usual. %0 .. %5 Arguments passed to <command_name>. %% A single percent character. 6) Windows can be generated as internal Tk windows instead of top-level windows by using the command magic::openwindow <cellname> <tk_window_path_name>. For example, the script: toplevel .layout magic::openwindow "(UNNAMED)" .layout.magic1 pack .layout.magic1 -expand true -fill both bind .layout.magic11 <Enter> {focus %W} generates a new window inside a toplevel frame named "layout", which can be customized. In this case, the layout window does nothing except contain the magic window. The fourth line ensures that the magic window can generate keyboard events. Generation of full-frame GUIs is facilitated by the "-n[owindow]" option, which brings magic up with the indicated graphics package but no actual window displayed. It is up to the calling application to call "magic::openwindow" and arrange the geometry and packing of the windows. 7) Another method for generating windows is to use the "image create layer" method. For example, the command 'openwindow "(UNNAMED)" .magic2' creates a new Tk window which starts off unmapped. Followed by "image create layer img_layout -name .magic2 -width 300 -height 300", an internal (offscreen) pixmap is created in place of the Tk window, and will be updated with changes to the layout just as any window would be. The image "img_layout" can be used to drop the layout image into any Tk widget which accepts images (such as the canvas and button widgets). The syntax is "image create layer <image_name> -name <tk_window_path> -width <width> -height <height>". Note that the Tk window is destroyed when the image is instanced; this does not occur with the "image create" command, but when the image is first mapped to the screen. Here's an example which generates a button containing the magic layout: openwindow "(UNNAMED)" .magic2 image create layer img_layout -name .magic2 toplevel .new button .new.b1 -image img_layout pack .new.b1 Layout may be painted in the window using command-line commands. Entering the button with the cursor will refresh the layout view. IMPORTANT NOTE: When magic is run with OpenGL graphics ("-d OGL" command-line option), the implementation uses the off-screen rendering functions to draw layout onto pixmaps for the button image feature mentioned above. There are a number of video card drivers that do not correctly implement these functions, and will crash magic if the toolbar is used. 8) Some commands have been altered in the Tcl environment to return results to the interpreter rather than simply print them as messages on stdout. One example is "getnode", which returns the string value of the selected node: set n [.magic1 getnode] Others implemented: "path sys|cell|search" returns a string containing the indicated path. "box values" returns the box coordinates. "windowcaption" returns the window title caption. "cellname" and "instance", with the option "list", return their results as Tcl lists. 9) Environment variables and Tcl global variables: A few environment variables are queried for backward compatibility; eventually all of these should be either replaced or duplicated by Tcl global variables. Currently, "$CAD_ROOT" is a duplicated variable. It can be set in the UNIX shell environment prior to running Tcl-magic, and the Tcl variable "$CAD_ROOT" will be duplicated from it. Otherwise, the Tcl variable "$CAD_ROOT" will be set to the value determined by the "make config" process. The use of "~cad" is completely deprecated. The new "make" process encourages the use of standard directory trees such as "/usr/local/lib" for CAD_ROOT, rather than the oddball "/home/cad/lib". The new system works well with user-installed versions having no access to root filesystem directories for installation. 10) Modes of operation: Tcl-based magic runs in all graphics modes, including 8-bit PseudoColor, 16- and 24-bit TrueColor, and OpenGL. When using a console and/or GUI wrapper in PseudoColor mode, magic redefines all of the Tk colors in the console and the wrapper frame so that they match the magic color scheme. The console gets the magic layout colormap so that one can move between the layout windows and the console without altering the colormap of either one. 11) A "wrapper" GUI is in "wrapper.tcl" and is normally present; it can be disabled with the command "magic -nowrapper" (or "magic -now"). This wrapper removes magic's own title bar and frame and replaces them with a frame managed by Tcl/Tk. The features of the wrapper are: A) Scrollbars are replaced by Tk scrollbars, but the functions are essentially the same. B) The caption is replaced by a Tk widget, with the same function. C) The box coordinates are displayed at the right-hand side of the title bar. D) A menubar is provided at the top left-hand corner. This has entries "File" and "Options". "File" takes care of many read and write functions (including CIF and GDS). Options are: a) "Toolbar" enables a toolbar to the right of the layout. This toolbar contains all of the layer types in the technology file. Entering the button displays the name of the layer type in the title bar. Clicking with mouse button 2 or keystroke "p" paints the layer type in the box on the layout window. Keystroke "e" erases the layer type in the box. Clicking with mouse button 3 hides the layer type in the layout window, and clicking mouse button 1 restores it. Keystroke "s" selects all paint of the layer type within the cursor box. b) "Cell Manager" pops up a display showing the hierarchy of layout cells in memory. This option is only available if the BLT package for Tcl/Tk has been installed on the system. When BLT is installed, the option will simply appear. c) "Tech Manager" pops up a display showing various properties of the currently loaded technology and provides a convenient way to change technologies or CIF read/write and extraction styles. d) "Pinout List" is a simple list widget that can search a layout for layer type "pad", and enumerates all of the pad instances found in the layout. This aids in the task of generating the pin names in the final stages of a chip design. 12) Extraction: The Tcl version of magic makes use of the interpreter variable space to work around some former deficiencies of the extractor. Power and ground nodes can be explicitly defined by setting variables $VDD and $GND in the Tcl global variable space (e.g, "::set VDD VDD" and "::set GND GND"). If these are not defined, then magic reverts to its original behavior of looking for node names ending with "!". The Tcl variable names (or any Tcl variable names) can be added to the techfile definition of a device's default substrate node name (include the "$" in front of the variable). Normally, this would use the two built-in variables $GND and $VDD. These variables should be set in the ".magic" file of each project directory, so that the default device substrate connections will match the power and ground definitions in a layout. If $GND and $VDD are defined but do not match any node names in the layout, a warning is flagged. 13) IRSIM simulation: Starting with revision 14, magic 7.2 supports interactive digital simulation with IRSIM. It is necessary to compile IRSIM version 9.6 or better with Tcl enabled, and it is necessary to have the Tcl package "BLT" for the graphing window to work. IRSIM version 9.6 has a "make" procedure which is exactly like magic's. It is preferable to set CAD_ROOT to the same value for both programs when doing "make config", so magic can find and automatically load the IRSIM package when it needs to. The Tcl procedure "startirsim" loads and runs IRSIM. Since both programs get loaded into the same interpreter, commands for both magic and IRSIM can be executed on the command line. When IRSIM is started with magic running, a number of commands are added to the interpreter which communicate between the two packages. Examples are "watchnode", "watchtime", and "drawnode". See the "README" file in the IRSIM source for more information on running IRSIM under magic and an explanation of the full set of commands available. ------------------------------------------------------------------ Tcl-specific bugs and annoyances: ------------------------------------------------------------------- 1) The Tcl prompt ("% ") appears at all times when the terminal is used for command entry. The desired behavior is that the magic prompt ">" (or "]" while DRC is pending) should appear when the cursor is in a window, indicating that the input is accepting keyboard macros. When outside of the window or after using the macro ":" to get to the command-line entry from magic, the Tcl "%" prompt appears, indicating that all valid Tcl commands may be entered at the prompt. Because it is not possible to detect if a partial Tcl command is on the command line, it is only possible to enter part of a command in the terminal window and complete the command in the magic window if ":" is typed in the magic window to redirect keyboard input to the terminal. The "tkcon" console-based version does not have this limitation and operates more or less like the original magic prompt. 2) Magic's original ".magic" file has control characters embedded. This is the only magic command syntax which is illegal Tcl syntax. However, magic 7.1 allows control characters to be written either as "^X" (two characters, with a caret) or "Control_X". If the original .magic is used (i.e., Tcl-magic is compiled and run, but not installed), the embedded controls should be changed to printable ASCII format. 3) There are routines which handle 8-bit pseudocolor mode by mapping tk colors to magic colors by the magic "short name" as listed in the dstyle file. This generally works well, except: 1) if the cursor is inside a layout window when it comes up, the colormap gets installed permanently; the window manager no longer reverts to the original colormap when leaving the window. 2) there is currently no routine to revert the console back to its original colors and revert to the original colormap. 3) the colors could use a bit of tweaking. ------------------------------------------------------------------