VHDL-1076.1 Description Browser
Tianrong Hu
Department of Computer Science and Engineering
Wright State University, Dayton, OH -45435
1. Introduction
VHDL designs can be extremely large and complex, so plain text searches are unwieldy and insufficient for determining the structure and the organization of a design. The browser is a tool for inspecting and for intelligently retrieving information about the analog and digital hardware designs expressed in VHDL-1076.1
1.1 Overall Organization
The VHDL Description Browser consists of a Graphical User Interface written in Java and a search engine written in SWI-Prolog, for use in both the Unix and the Windows95/NT environments. The GUI process communicates with the search engine in a master-slave configuration with the GUI acting as the master and the search engine as the slave.
The GUI shields the user from the Prolog details. In particular, the GUI directs the querying by presenting the user with a set of menus which implement frequently used queries.
The VHDL Browser provides the following basic functionality.
2. Design and Implementation of Java-based GUI
The GUI-process launches the search engine and obtains its input stream and output stream to set up interprocess communication with the GUI.
The GUI preparesI for user actions by setting up ActionListeners for all the functional components. These components can be divided into six groups according to their functions: File, List, View Source, View Doc, Locate and Associations.
Each user action triggers the GUI which then obtains enough information from the user, composes the corresponding query in Prolog and sends it to the search engine. The search engine handles a query by retrieving relevant information from the parse trees (that encode the VHDL descriptions), and writing the query result back to the GUI. Because of asynchronous nature of the communication, in order to match a response with the corresponding query, the GUI maintains a queue of queries. Fortunately, the search engine processes queries one by one and sends out responses in the order in which it receives the queries. On the other hand, the query results are sent back as a sequence of "packets", so the results are demarcated using a start marker and an end marker.
The final results are displayed in a "palatable" form, each of the six groups of actions having separate group of result windows that are placed in different positions to facilitate organization and analysis of the results.
2.1 Launching the Search Engine
The method exec() of class Runtime is used to fork a new Prolog process. The SWI-Prolog binaries in the Unix environment (pl x ) is named differently from that in the Windows environment (plcon x ).
Runtime r = Runtime.getRuntime();
Process p_prolog = null;
String cmd_prolog = "vhdl97_parser -g true -f search_engine.pro";
if( System.getProperty("os.name").equals("Solaris"))
cmd_prolog = "pl -x " + cmd_prolog;
else
cmd_prolog = "plcon -x " + cmd_prolog;
p_prolog = r.exec(cmd_prolog);
The getInputStream() enables connecting the input stream of the main process to the normal output of the subprocess and the getOutputStream() enables connecting the output stream of the main process to the normal input of the subprocess. The GUI can send information to the search engine via dout_prolog and get information from the search engine via din_prolog.
din_prolog = new BufferedReader
(new InputStreamReader(p_prolog.getInputStream()));
dout_prolog = new DataOutputStream(p_prolog.getOutputStream());
2.2 Setting up the GUI
First, we create an instance of GUI to interact with the user.
gui = new Gui();
The GUI constructor is shown as follows:
Gui()
{
super("VHDL Design Browser");
cmd_list = new Vector();
file_list = new Vector();
Font font_menu = new Font("SansSerif", Font.BOLD, 14);
font = new Font("SansSerif", Font.BOLD, 10);
setFont(font);
MenuBar menubar = new MenuBar();
menubar.setFont(font_menu);
menubar.add( m_file = new Menu_File() );
menubar.add( m_list = new Menu_List() );
menubar.add( m_view = new Menu_View() );
menubar.add( m_locate = new Menu_Locate() );
menubar.add( m_assoc = new Menu_Assoc() );
menubar.add( m_help = new Menu_Help() );
setMenuBar(menubar);
add("North", fp = new File_Panel());
add("Center", bp = new Browse_Panel());
pack();
show();
setSize(460, 360);
setLocation(0, 0);
}
This sets up the functional components: (1) menus for creating queries - Menu_File, Menu_List, Menu_View, Menu_Locate, Menu_Assoc, and Menu_Help, (2) File_Panel to wait for the user actions, and (3) Browse_Panel to record user actions. These components are defined as follows:
class Menu_File extends Menu { }
class Menu_Help extends Menu { }
class File_Panel extends Panel { }
class Browse_Panel extends Panel { }
The GUI constructor also initializes two Vecotors: cmd_list (the queue for storing queries) and file_list (a list for storing the names of files loaded so far).
Once the GUI has been instantiated, each functional component needs to be explicitly assigned an ActionListener, to react to the user actions as follows:
// Action of "Load File(.vhdl)" in "File" menu
m_file.item_load.addActionListener (new GuiActionListener(gui, "load_file"));
//Action of "Entities" in "List" menu
m_list.item_entities.addActionListener (new GuiActionListener(gui, "list_entities"));
//Action of "Show Source Code of" "Entity" in "View" menu
m_view.item_entity.addActionListener (new GuiActionListener
(gui, "view_source_entity"));
//Action of "Show Source Code and Doc of" "Entity" in "View" menu
m_view.item_doc_entity.addActionListener (new GuiActionListener
(gui, "view_source_doc_entity"));
//Action of "UserDefinedDataTypeDefn" in "Locate" menu
m_locate.item_datatype.addActionListener (new GuiActionListener
(gui, "locate_datatype"));
//Action of "ComponentHierarchy" in "Associations" menu
m_assoc.item_hierarchy.addActionListener (new GuiActionListener
(gui, "assoc_hierarchy"));
//Action of "FileQueries" in "Help" menu
m_help.item_file.addActionListener (new GuiActionListener(gui, "help_file"));
All ActionListeners are instances of an universal ActionListener (GuiActionListener), which needs two arguments: an instance of the GUI and the name of the method defined in GUI for handling the specific event.
2.3 Communication between the GUI and the Search Engine
Sending the Prolog query to the search engine and fetching the response from the search engine is accomplished as follows:
public void load_file()
{
String file_path = fd.getDirectory() + fd.getFile();
// make sure file separator is always '/' in prolog file path
String mes = "java_vhdl_read('" + file_path.replace('\\','/') + "').";
cmd_list.addElement("Load File");
write(mes);
}
public void list_entities()
{
addcmd("List All Entities");
write("list_all_Entities(_).");
}
while(true)
{
//only packed message("start"..."end") shows up
while(!(mes_prolog = din_prolog.readLine()).equals("start")) ;
command = (String) cmd_list.elementAt(0);
cmd_list.removeElementAt(0);
if(command.equals("Load File")) { }
else if(command.equals("List All Entities")) { }
}
The load_file() method is invoked based on the user action. In load_file(), first, the Prolog query is composed, then, the command "Load File" is added to the queue cmd_list, and then the query is sent out to the search engine. In the meantime, the GUI waits for messages from the search engine, lloking for messages beginning with "start" for later processing. The other "noise" strings are ignored. Obviously the accepted message is the query result corresponding to the command fetched from cmd_list, which in this case happens to be "Load File".
Likewise, list_entities() matches command.equals("List All Entities").
2.4 Results Display in GUI
The methods for displaying the results are listed below:
static void list_all_results(String cmd, Color clr, String proc, Gui g)
throws Exception { }
static void view_results(String command, Color clr) throws Exception { }
static void view_results2(String command, Color clr) throws Exception { }
static void view_doc_results(String command, Color clr) throws Exception { }
static void view_doc_results2(String command, Color clr) throws Exception { }
static void locate_results(String command, Color clr) throws Exceptio { }
static void locate_results2(String command, Color clr) throws Exception { }
static void assoc_results(String command, Color clr) throws Exception { }
void help_results(String title, String contents, int x, int y) { }
Each method instantiates a result window, sets up its position and color, displays the results appropriately and registers the result window into its group for possible deletion later.
3. User Manual
The following presents a brief tutorial on how to use the VHDL Browser.
3.1 Starting the Browser
In Unix (tcsh), the user needs to set the DISPLAY using:
setenv DISPLAY "workstation":0.0
where workstation is the name of the machine.
javac Gui.java
java Gui
A window with title "VHDL Design Browser" pops up in the top-left corner of the screen. There are three parts in this main window: on the top is the menu bar; in the middle is a list showing "Loaded Files(.vhdl)"; at the bottom is a text area for logging all the browsing actions.
There are six menus in the menu bar: File, List, View, Locate, Associations and Help. Each has its own menu items. At the outset, only two menus are enabled: File and Help. The user can either load the VHDL design by clicking on Load File(.vhdl) in File, or terminate the browser by clicking on Exit in File, or view help information by clicking on Help menu items.
3.2 Loading a VHDL Description
A file dialog box pops up. The user can select a file to browse. If the filename does not end with ".vhdl" or the VHDL file has already been loaded, the command is ignored. Otherwise, the file is loaded into the Prolog database via the parser. Furthermore, the VHDL file name (e.g. tp_7.vhdl) shows up in the loaded file list and the action is recorded in the browsing log too as follows:
Load File(tp_7.vhdl)
--- waiting ...
--- succeeded
Also all the menu items that are relevant to browsing the loaded VHDL file are enabled. Thus we provide a context sensitive scheme to guide the user with further browsing.
3.3 Browsing
The results windows are positioned according to the query category (see Figure 1). Each result window has a small horizontal offset from the previous one in the same query category, and is colored according to the query function. E.g., all query results windows about Entity have the same color: List All Entities, View: Show Source Code of Entity, View: Show Source Code and Doc of Entity, etc.
All Browsing actions are recorded in Browsing Log" as:
List All Architectures of Entity(all)
--- waiting...
--- finished
Line 1 is the query, the same as the title of the result window, line 2 shows up when the query is submitted to the search engine, line 3 shows up when the result window pops up. Its better to wait till line3 shows up before issuing the next query because it takes time to process the current query. If line 3 doesnt show up for a long time, an error has occurred.
There is an item CloseAllSubWindows on each menu or submenu. Clicking on it will close all the results windows triggered by items on the menu it belongs to.
Figure 1: The layout of Results windows
The queries are categorized as follows:
Double-click on the item in the Loaded File(.vhdl) list (e.g. tp_7.vhdl).
A result window with title Open File tp_7.vhdl pops up.
File contents in the text area is not editable.
- List All Entities
Click on item Entities on menu List
A result window with title List All Entities pops up
- List All Architectures
Click on item Architectures on menu List
An intermediate query window with title List: architectures pops up
All associated entities are shown in the drop-down list. The user can choose any one of them (e.g. blocks) to list all architectures of this specific entity or choose the default one "all" to list all the architectures
Click on Ok-button to pop up
a result window with title "List All Architectures of Entity (blocks)" or
a result window with title "List all Architectures of Entity (all)".
- View: Show Source Code of Entity
Click on item Entity on sub menu View: Show Source Code of
An intermediate query window with title View: show source code of entity pops up
All entities are shown in the drop-down list, user can choose any of them (e.g. blocks) to show source code of this specific entity
Click on Ok-button to pop up a result window with title "View Show Source Code of Entity (blocks)"
- View: Show Source Code of Architecture
Click on item Architecture on sub menu View: Show Source Code of
An intermediate query window with title "View: show source code of architecture" pops up
All architectures are shown in a drop-down list and all associated entities are shown in another drop-down list. The user chooses one architecture (e.g. blocks) and its associated entity (e.g. blocks or default to be all) to show source code of this specific architecture(e.g. blocks)
Click on Ok-button to pop up a result window with title "View Show Source Code of Architecture (blocks) with Entity (blocks)".
- Double Click on items listed on List results windows
A result window with title "View: Show Source Code of " pops up to automatically show the source code of this item
Browsing process is the same as query View: Show Source Code of
- Locate UserDefinedDataTypeDefn of DataType
Click on item UserDefinedDataTypeDefn on menu Locate
An intermediate query window with title
"Locate: UserDefinedDataTypeDefn" pops up
All UserDefinedDataType are shown in the drop-down list, user can choose any of them (e.g. var_array) to locate the user-defined data type definition of this specific data type or choose the default one all to locate definitions of all the user-defined data types
Click on Ok-button to pop up a result window with title
"Locate UserDefinedDataTypeDefn of DataType(var_array)"
or a result window with title
"Locate UserDefinedDataTypeDefn of DataType(all)".
- Locate Variable with DataType
Click on item Variable on menu Locate
An intermediate query window with title "Locate: Variable" pops up
All variables are shown in a drop-down list and all associated datatypes are shown in another drop-down list. The user chooses one variable (e.g. v0 or default to be all) and its associated datatype (e.g. integer or default to be all) to locate a specific variable (e.g. v0) of a specific datatype(e.g. integer),
or locate all variables of a specific datatype (e.g. integer),
or locate a specific variable (e.g. v0) of any data type,
or locate all the variables of any datatype
Click on Ok-button to pop up
a result window with title "Locate Variable(v0) with DataType(integer)", or
a result window with title "Locate Variable(all) with DataType(integer)", or
a result window with title "Locate Variable(v0) with DataType(all)", or
a result window with title "Locate Variable(all) with DataType(all)"
- Associate ComponentHierarchy with top-level Entity
Click on item ComponentHierarchy on menu Associations
An intermediate query window with
title "Associations: ComponentHierarchy" pops up
All entities are shown in a drop-down list, user can choose any of them (e.g. blocks or default to be all) to show the component hierarchy of this specific entity or show all the component hierarchy
Click on Ok-button to pop up a set of results windows
with title "Associate ComponentHierarchy with top-level Entity(blocks)"
or with title "Associate ComponentHierarchy with top-level Entity(all)",
each result window is associated with an architecture of an entity
- Associate X to be subcomponent of Y
Click on item X_subcomponent_Y on menu Associations
An intermediate query window with title
"Associations: X_subcomponent_Y" pops up
All entities are shown in two drop-down lists, and the user can choose any of them (e.g. X to be vbm1 or default to be all, Y to be vbm0 or default to be all) to check if X (vbm1) is a subcomponent of Y (vbm0), or find all component associations with X (vbm1) as the subcomponent, or find all subcompents of Y (vbm0) or find all possible X_subcomponent_Y associations
Click on Ok-button to pop up a set of results windowswith title "Associate X(vbm1) to be subcomponent of Y(vbm0)" or
a set of results windows with title
"Associate X(vbm1) to be subcomponent of Y(all)" or
a set of results windows with title
"Associate X(all) to be subcomponent of Y(vbm0)" or
a set of results windows with title
"Associate X(all) to be subcomponent of Y(all)" ,
each result window is associated with a X_subcomponent_Y association
- Help: ListQueries
Click on item "ListQueries" on menu Help
A window with title "Help: ListQueries" pops up in the position where all List results windows are located to describe List queries.
3.4 Terminating the Browser
Click on item Exit on menu File to terminate and exit the Browser.
4. Conclusions and Future Enhancement
The important aspect of this Java-based GUI is its portability. Because Java is a platform independent language, this VHDL Browser can be run in both Unix and Windows environments.
The "user-friendly" GUI guides the user in the construction of customized queries by going through the menu bar. Only those menu items that are meaningful in a given context are enabled. The result windows are organized according to the query that determines their color and their position. The result windows belonging to one group can be all closed at once. The user input by typing is minimized by supplying choices via the GUI.
So far the GUI only acts as a browser without any editing capability. Limited editing capability and automatic save and reload are welcome enhancements. The connection between browsing aspects and the corresponding the VHDL file can be strengthened. Overall, this Browser is a first step that deserves further improvements in its functionality and robustness before it can be used widely. It also seems relative slow.