Contents

Metropolis Model Structure Viewer User's Guide

Contents

1. Introduction
2. Installation
3. Setup
4. Creating a Metropolis project
5. Building
6. Viewing

Introduction

Below is an example of the display of the top-level netlist of the Picture-in-Picture modeling example.

Double-clicking on an object representing a netlist (displayed as a gray box by default) opens another view showing the structure of that netlist. Double-clicking on another object opens a text editor on the source code for that object.

Requirements

The Structure Viewer requires Eclipse 3.1 or later, using Java version 1.5 or later, and the Graphical Editor Framework (GEF) Eclipse plugin, release 3.1.1 or later. It also requires a local installation of Metropolis. Also, in order to do automatic layout, the open-source GraphViz layout programs from AT&T must be accessible.

Installation

1. Download Eclipse 3.1 (or later) from http://www.eclipse.org/ and install it on your system.
2. Download the Graphical Editor Framework (GEF) plugin from http://www.eclipse.org/gef/. (The runtime version is sufficient, as opposed to the development-kit version.) Unzip the downloaded .zip file in the folder containing your Eclipse installation (i.e., containing the folder called "eclipse"), and its contents should be extracted into their proper places (the plugins, features, and readme folders).
3. Download the metro_ui plugin from http://embedded.eecs.berkeley.edu/metropolis/forum/10.html and unzip it into your Eclipse installation in the same way.
4. Download Metropolis from http://embedded.eecs.berkeley.edu/metropolis and install it according to the included documentation.
5. Download and install the GraphViz layout programs from http://www.graphviz.org/.

Setup

1. Open the Java perspective:

   
   Window -> Open Perspective -> Java

2. Specify the location of your Metropolis installation and your Java compiler:

   
   Window -> Preferences -> Metropolis
   Fill in the paths by typing, or by using the Browse tool.

3. Disable automatic building:

   
   Project menu:
   Click on Build Automatically (if it shows a checkmark) to disable.

Creating a Metropolis Project

File -> New -> Project... -> Other -> Metropolis Project

You are first prompted to give the project a name. The name must be the name of the root package of your model. The top-level folder of the project is where you will put any metamodel (.mmm) source files belonging to the top-level package, and any subfolders containing sub-packages.

After entering the name, you can hit Finish.

Source Code

Your Metropolis metamodel (.mmm) source code can be created in place using Eclipse's text editor, or it can be imported into your project.

To import files that are accessable from your file system, select the project title in the Package Explorer view, right-click to bring up the context menu, and select the "Import..." menu item. On the first page of the resulting wizard, select "File system" as the source and navigate to your files in the subsequent wizard pages.

If your files are in CVS, you can instead use the "Team -> Share Project..." context menu item to check out your files from CVS. The details of using CVS with Eclipse are outside the scope of this document, but are fairly straight-forward.

Properties

The specifications for compiling your model (i.e., the information you would include on the command line of a metacomp command that would build it) are entered as properties of the Eclipse project containing your model. To enter that information, right-click on the project resource in the Package Explorer view:

Select Properties in project context menu:

The Metro Specs page, for entering Java classpath and Metropolis classpath (each initially set to default values), and the fully-qualified name of the top-level model package, and the name of the top-level netlist.

The Metro Source Files page, with tools for browsing to files in the project, in the Metropolis library, and elsewhere in the local file system, respectively. Use the Add... button to add entries. Select entries and click the Delete button to delete them.

The Metro Specs page for the PiP example.

The Metro Source Files page for the PiP example.

Building

Project -> Build Project

A successful build will create a folder inside the project called metro0.tmp. (Subsequent builds will create metro1.tmp, metro2.tmp, etc. To avoid this accumulation, delete unwanted metroX.tmp folders before building.) Inside metro0.tmp is a binary representation of the model structure called NET.

Below is a screendump of an Eclipse window showing the output of a successful build of the producers_consumer example, and the file NET which it creates.

Output of a build.

Viewing

Double-clicking on the file NET in metrox.tmp will bring up a display of the elaborated netlist described by that file. The initial appearance of the graphical display depends on the layout preference settings.

Before describing the preferences, a note about auto-layout is in order: Automatic layout is provided as a helpful starting point for laying out a diagram. It may not provide a suitable finished layout, but can help provide an initial layout that is understandable and easily modifiable by hand. The preferences can be helpful in getting the most out of auto-layout.

Layout preferences

Window -> Preferences -> Metropolis -> Layout

Layout preferences.

• Do automatic layout...

  Never

  All objects will initially appear stacked on top of each other in the upper-left corner, and must be positioned by hand to create and understandable display.

  When no layout has yet been done

  Automatic layout will be done, as long as no layout has yet been saved for this netlist.

• Auto layout style

  spring tension (GraphViz neato)

  Use GraphiViz neato to do layout, which uses a spring-force algorithm. This is probably the most generally useful choice, although the others may be worth experimenting with.

  hierarchical, in rank and file (GraphViz dot)

  Use GraphViz dot to do layout. dot is most applicable to hierarchical directed graphs.

  radial (GraphViz twopi)

  twopi tries to arrange things in circular arcs.

  circular (GraphViz circo)

  circo tries to arrange the graph in concentric circles.

  More information about these layout schemes is available on the GraphViz website.

• Stretch the distance between components...

  This slider allows adjusting the distance between objects provided by the auto-layout program.

• Location of GraphViz programs

  This file-specification tool must be filled in to tell the plugin where to find the layout programs, if auto-layout is desired.

• Fit MObjects around their names / Use default MObject size:

  The initial size of netlist components is set here to either fit snugly around their name labels, or else to be a set width and height in pixels.

• Color Editors

  Color editors are provided to change the colors used to identify the types of objects displayed.

The Display

Components

Ports

A white circle on a component rectangle represents an output port. The name of the port is displayed in a tooltip when the mouse hovers over it.

Shadow Ports

A shadow port can appear either as a free-floating symbol, when it represents a connection endpoint outside of the current netlist, or as a port symbol on a netlist object, when it represents a connection endpoint inside that netlist. The following figure illustrates:

Layout

The rectangular component symbols and the free-floating shadow port symbols can be dragged into any position. They can also be resized by selecting them and dragging their handles. Multiple symbols can be selected at once by dragging a selection box around them, or by doing Shift-Click to add them to the current selection.

Saving (and a caveat)

An important caveat: If multiple views of the model are open when one is saved -- i.e., views of multiple netlists in a hierarchical structure -- it is important to realize that the layout for all views will be saved. That is, the layout for the entire model is saved in one place and saving any view saves the layout for all views.

Actions

Open a sub-netlist

Double-clicking on a netlist symbol will open another viewer displaying the structure of that netlist.

Edit source code

Double-clicking on a non-netlist component figure will open a text editor on the source code for that component, if that source code file resides in the local Metropolis project under Eclipse.

Reposition and resize objects

Objects can be repositioned by dragging them, and resized by selecting them and dragging their handles.

Undo and redo

Layout changes can be undone and re-done in three ways:

• The Edit menu contains Undo and Redo items.
• The Eclipse workspace toolbar contains icons for Undo and Redo.
• Right-clicking on the diagram background brings up a pop-up menu containing Undo and Redo items.

Save

The graph layout can be saved in three ways:

• The File menu contains a Save item.
• The workspace toolbar contains a Save icon.
• If layout changes have been made when a graph page is closed, the user is prompted whether to save the layout or to close without saving.

Export Image

The view image can be saved to a file by right-clicking on the background and selecting "Export Image..." from the popup menu. This will bring up a dialog to use to specify the file type, file name, and location of the exported image file.

JPEG and BMP formats have been tested to work on Windows and Redhat Linux platforms. The underlying Java API theoretically also supports PNG and GIF, but success with those is yet to be seen.