Metropolis Model Structure Viewer User's Guide

Introduction
Installation
Setup
Creating a Metropolis project
Building
Viewing

Introduction

The Metropolis model structure viewer is an Eclipse plugin. It presents a graphical display of the objects in a Metropolis model and the connections between their ports.

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

To date, the Structure Viewer has been tested on Windows XP and Redhat Enterprise Linux Release 4.

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

Download Eclipse 3.1 (or later) from http://www.eclipse.org/ and install it on your system.
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).
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.
Download Metropolis from http://embedded.eecs.berkeley.edu/metropolis and install it according to the included documentation.
Download and install the GraphViz layout programs from http://www.graphviz.org/.

Setup

Before you can use the Metropolis plugin, some initial setup is necessary within Eclipse:

Open the Java perspective:

Window -> Open Perspective -> Java
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.
Disable automatic building:

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

Creating a Metropolis Project

In order to create a graphical view of a Metropolis model, the model must be in a Metropolis project under Eclipse.

Create a project from the File menu:

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 Properties dialog for a Metropolis project will contain two pages, called "Metro Specs" and "Metro Source Files". Here are illustrations of example settings for the producers_consumer example:

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.

Metro Source Files properties page.
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.

To further illustrate, here are settings for the Picture-in-Picture example:

The Metro Specs page for the PiP example.

Metro Source Files properties page.
The Metro Source Files page for the PiP example.

Building

Once your source files are in place and the properties are set correctly for compiling, you can build your model by selecting the project name, or any resource listed under it, in the Package Explorer view and then the main-menu item

Project -> Build Project

This will invoke the Metropolis elaborator backend to compile the model through the elaboration stage. The Console view (Window -> Show View -> Console) displays the output of that process.

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

The layout preferences are accessed from the main Eclipse menus:


Window -> Preferences -> Metropolis -> Layout

Image of the layout preferences page.
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

The display shows the structure of a netlist. The name of the netlist whose structure is being displayed appears in the tab at the top of the Structure Viewer.

Components

The components of the netlist appear as colored rectangles. A rectangle's color corresponds to the type of component it represents. The color key is on the layout preferences page (see above), where the colors are customizable. The name of the component in the netlist is displayed in the middle of its rectangle. Hovering over a component displays its name, the fully-qualified name of its class, and its type in a tooltip.

Ports

Connections between the netlist components are displayed as lines connecting them, attached at their ports. A gray circle on a component rectangle represents an input port (or interface). The name of the interface is displayed in a tooltip when the mouse hovers over it.

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 gray or white circle that is not on a component rectangle is a "shadow port". Its connection ends at a port that is not in the currently displayed netlist. Shadow ports are so called because they can be thought of as the point where a connection casts a shadow on the netlist boundary on its way to an endpoint in some other netlist.

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

If the preferences have been set to do automatic layout, and the GraphViz programs are correctly installed, the netlist components will be automatically layed out in some manner the first time a netlist is displayed. Automatic layout will also happen on subsequent displays of the same netlist, as long as the layout has not been saved.

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)

Currently, saving means saving the layout, and it is done in any of three ways described below.

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.