From Vi/EMACS to SVEditor

Background

This tutorial is intended to help an HDL user transition to using Eclipse with SVEditor as a plug-in. The tutorial will cover setup and installation of Eclipse and the SystemVerilog Editor and then take you through a quick tour of what Eclipse offers you over and above a normal editor like VI / EMACS.

First off Eclipse is an IDE, as opposed to an editor. Hopefully as the tutorial progresses the distinction will become more clear, but in it's simplest terms, an IDE is aware of the all the files in the project, and not just the file(s) that is/are open. This brings:

True syntax awareness, highlighting errors as you type, no more waiting 5 minutes for a compile to complete to discover you missed a semi-colon!
Easy navigation through the entire design
Class and class hierarchy awareness
Easy module / class member instantiation
Platform independence, delivering the same experience whether you work on Windows / Unix / Linux or Apple.

Setting Expectations

Eclipse is to Vi/EMACS, what Vi/EMACS is to Notepad. This is really good news, hang on to that thought. That said, this is a significant jump in functionality, and will take a bit of getting used to and to learn to take advantage of. Remember that it took a while to really start taking advantage of the features Vi/EMACS. Now you'd never go back to Notepad, would you?

It is going to take a little while to re-train your fingers. There are GOING to be functions that you are used to using that you either behave differently, or, occasionally are missing entirely in Eclipse. Eclipse has a significant number of features that your previous editor didn't have. In my experience, Eclipse brings enough "extra" that it significantly outweighs the "missing/different".

Installing Eclipse

There are several ways of installing Eclipse and the SVEditor plugin for Eclipse. These are detailed on the Installing SVEditor page. If you do not have Eclipse and the SVEditor plugin installed please follow the directions on the link above.

First Eclipse Launch

The following sections take you through launching Eclipse, and some of the concepts that you'll come across when you first launch Eclipse including:

The Workspace
Perspectives
Projects

The Workspace

The first thing Eclipse asks you to do when launched is to Choose a Workspace. For this tutorial, choose the default location.

If you are asking yourself what a workspace is... a workspace is a place that Eclipse uses to do it's cache'ing. The following is an example of items that may be stored in the cache:

All your preferences
- The color scheme you are using for this workspace
- The keybindings you are using in this workspace
- Tabs vs spaces, indent size etc.
- Code formatting preferences
- etc. etc. etc.
The list of files you have open at any given time so that next time you launch Eclipse, you pick up where you left off
Eclipse's "compiled code"
- In the same way that a simulator compiles code before running, Eclipse "indexes" your code and stores the compiled output in the workspace

Please refer to the Appendix Workspace vs. Projects further on in this tutorial for more details.

Opening the SVEditor Perspective

First off, What is a perspective? In its simplest terms a perspective is a combination items associated with a given task / context including:

Window layout
Menus

A perspective customizes the user interface for a given task. Developers will commonly switch between a JAVA perspective (where the window layout is primarily dominated by the code being edited) and a DEBUG perspective where the window layout is likely dominated by Watch windows, Breakpoint lists, console etc. You can change perspectives within a given workspace.

To open the SVE perspective Window>Open Perspective>Other>SystemVerilog. The System Verilog perspective can also be opened using the icon in the image below. Unused perspectives can be closed by right-clicking on the perspective and hitting Close.

Eclipse Projects

A project in Eclipse terminology is a group of code that needs to be treated as a set. As HDL designers this is usually a group of files that we can synthesize and or simulate. Examples of projects include:

A piece of RTL IP
A piece of IP, including both RTL and test bench
A full chip, containing multiple pieces of IP, the supporting infrastructure and supporting code that may be external to the project on the file system

A Workspace could contain multiple projects. For example if you are working on 2 separate pieces of IP, they can both be open in Eclipse simultaneously.

Loading Your First Project

This section of the tutorial will walk you through creating an SVEditor project in Eclipse, setting some environment variables and guiding you through the point where Eclipse has "compiled" or "indexed" your code. The following zip file contains two "dummy" chips, chip1 and chip2. These could be chips, modules, or any other piece of IP.

Download the zip file EclipseTutorialRTL.zip
Unzip the source code to the following location, "C:\<some_place_other_than_workspace>\Tutorial". There will be 2 top level folders - chip1 & chip2
Next we will create a new SVEditor project:
1. File>New>Other>SVEditor>SVE Project
2. Next

Set up the project name and root of the project
1. Set the Project name to Chip 1. The name is a way to uniquely identify the project. Any string can be used here.
2. Un-check Use Default Location
3. Browse to the un-zipped project location, in this case:
4. "C:\<some_place_other_than_workspace>\Tutorial\chip1"
5. Hit Next

Next give Eclipse the information it needs to properly parse files in the design. This is usually a argument (".f") file. There may be one or more of argument file in real-world projects. In this tutorial there is are two argument files, one for RTL and another for the test bench.
1. The Specify Filelists dialog is one place where an argument (.f) file(s) can be added.
2. Select Add Project Path
3. Select the "sim/files_rtl.f" file which contains an inventory of all the RTL in the design.
  1. The argument file referencing test bench files can be added here, but will be skipped in this step to show a different way to do this same task.
4. Hit Next

Finish the project creation
1. Hit Finish (no referenced projects)
Eclipse will scan the file system, creating an inventory of all files from chip1 down.
Now we will add an argument file (files_tb.f) from the Project Explorer window (which is an alternative to the previous steps)
1. In the Project Explorer window, browse to "sim/files_tb.f"
2. Right-click on files_tb.f, and select Add Argument file to Project
At this point, Eclipse knows what files matter to your design, and parses them appropriately.

Setting Environment Variables

Environment variables are often used for various things in a design project. An environment variable could be used to point to a given place on the file system where libraries are used, or can be used to point to a location on the file system which contains locally checked out code.

Eclipse has the ability to store environment variables in it's .project file (which was created by Eclipse earlier in the tutorial). When an environment variable is called Eclipse will look:

In the Project's configuration file
In the environment available when Eclipse was launched

For now though, we are going to set an environment variable that chip1 uses in it's files.f.

Open the project properties by right clicking on the Chip1 in the Project Explorer > Properties

Open the Linked resources Resource>Linked Resources> Path Variables>New
We are going to set what is a project environment variable called CHIP. CHIP is used by files.f and is the root of the project.

At this point you will have a screen that looks something like this

Advanced Notes

Eclipse stores it's project settings at the root of your project (these are the only files that Eclipse generates outside the workspace). The two files are .project and .svproject. These are xml files and can be browsed at your convenience.

Compiling (Indexing) the Code

Eclipse is aware of more than what is required to do basic code colorization. Eclipse is aware of the design hierarchy, class hierarchy and so on. To do this Eclipse needs to compile the code in your project. The compiled output will be stored in the workspace (note that this is not the same location as where the project is stored) leaving the area where the source code resides unaffected.

As you work (type) Eclipse will continually update the index, so you do not need to re-compile each time the code is edited.

A complete rebuild of all the code can be forced at any time by:

Project>Clean

Congratulations. You've just loaded and compiled your first project bit of Verilog code!!!

Terminology Note: SVEditor stores the compiled code in an Index, hence the fact that index is used somewhat interchangeably with compile.

Playing with the New Project

Basic Key Bindings

Editing in Eclipse with the default keybindings is the same as editing in any Microsoft product (no, don't run away screaming, it isn't that bad, there are alternatives. Just go with it for now.)

Here are some common key bindings that will get you around for now:

Opening Files (Ctrl+Shift+R)

There are many ways of opening files in Eclipse. The obvious one is to use the mouse! The mouse can be used to traverse through the hierarchy in the "Project Explorer" view that comes up on the left hand side of the screen, expanding and collapsing directories. Double clicking on a file will open it.

Now for something fun. Type Ctrl+Shift+R, and start typing the name of the file you are looking for (in this case type "*mod").

Note that eclipse will filter all files in the project, narrowing the choices down as additional information is entered. Wildcarding etc makes finding a file anywhere in the design a breeze. No longer do you have to traverse the hierarchy to open a file. Naming conventions often dictate that module/class names match the file name. This makes opening up any module or class in the design a breeze.

Command Line: The command line also works believe it or not: eclipse <filename>

Outline View

This portion of the tutorial will introduce you to the outline view and covers:

A description of the outline view
Filtering in the outline view
Navigation in the outline view

The outline view is a birds-eye view of items within a given file. There are a number of icons on the top of the view that allow filtering of various constructs. For instance, always blocks are typically not named, so including these in an outline view is just clutter. Module instantiations on the other hand are useful. Clicking on items within the outline view will take you to that location in the file.

Open up top_module.sv
1. Keystrokes: Ctrl+Shift+R, top_module.sv
Bring up the outline view (this is likely already up in the lower left corner of the screen)
1. Window>Show View>Other>General>Outline

Click on various items in the outline view, turn items off on the icons at the top of the view

Instantiating a Module, Function or Task (Ctrl+Space)

The goal of this exercise is to instantiate a sub-module (called sub_module) in the design. To instantiate a sub-module:

Open top_module.sv
1. Keystrokes: Ctrl+Shift+R, top_module.sv
Open sub_module.sv
1. Keystrokes: Ctrl+Shift+R, sub_module.sv
2. Note that this could have been done by wildcarding \*mod\* and selecting both modules simultaneously.
3. Look through sub-module, you'll see it is essentially an AND gate and a FLOP.
Now switch to top_module
1. Keystrokes: Ctrl+E
Search for the Exercise_Submodule
1. Keystrokes: Ctrl+F, Exercise_Submodule
Go to the insertion point shown below and type:
1. sub_mod<Ctrl+Space>

You will see code that looks like one of the following depending on the preferences you have selected as described further down.

 sub_module1 sub_module1 (clk, rst, a, b, y);

 sub_module1 sub_module1 (.clk (clk), .rst (rst), .a (a), .b (b), .y (y));

 sub_module1 sub_module1 (

     .clk  (clk ),

     .rst  (rst ),

     .a    (a   ),

     .b    (b   ),

     .y    (y   ));

The way modules, tasks & functions are instantiated as specified in the SVEditor preferences: Window>Preferences>SVEditor>ContentAssist.

Instantiating Common Constructs (Ctrl+Space)

Ctrl+Space supports all common constructs (if, else, always_ff etc.). Try instantiate an always_ff block.

Type always<Ctrl+Space>
Select the always block required, and hit Enter

These templates can be modified in the code templates selection of the preferences.

These can be edited/removed pretty easily as follows:

Open up the SVEditor Code Template preferences
1. Window>Preferences>SVEditor>Code Templates
Edit/Add/Remove templates as you see fit

Class Member Instantiation (Ctrl+Space)

SVEditor is also class aware, and is able to instantiate class members (functions and variables) for you using Ctrl+Space.

Open up top_module.sv
1. Ctrl+Shift+R (or Ctrl+E if it is already open)
Search for Exercise_ClassCompletion
In this area you'll see an instance of a class (another_package_class - acp) that has two functions in it.
Call the function div within acp
1. Type acp.<Ctrl+Space>
You will see a pop-up within this dialog, which shows all the methods/variables available to you
Select the function you want, hit Enter.

Word Completion (Alt+/)

Another way to do code completion, similar to Ctrl+Space is to hit Alt+/. This differs from code completion in that the index isn't searched, but text is extracted from anywhere in the current file.

A good place to use Alt+/ is to save time on typos. Using Alt+/ like you use the Linux command line Tab completion when typing variable names that are local to the file. This will ensure that variable names are correctly spelled, saving valuable debug time.

Search for Exercise_CodeCompletion
1. Keystrokes: Ctrl+F, Exercise_CodeCompletion
Type the following:
1. assign this_<Alt+/>
2. Release the "/", but still holding Alt. Each time "/" is typed, a new suggestion will be displayed.
3. Fix your selection by releasing Alt

Commenting Code

Commenting Code (Ctrl+/)Code can easily be commented out.

Select a couple of lines of code.
1. Use the mouse OR
2. Shift+Up or Shift+Down
Comment these lines out
1. Ctrl+/
Restore these lines
1. Ctrl+/
You can also use block commenting (/\*...\*/) to comment out code.
1. Ctrl+Shift+/
Restore the code
1. Ctrl+Shift+\ (Note the backslash instead of a forward slash here)

Opening a Random file in the Environment

This is so awesome it deserves it's own chapter!!!

Ctrl+Shift+R

Code Browsing

This is one area where Eclipse starts differentiating itself from a "normal" Editor. Because Eclipse parses the entire design that is loaded, it is able to navigate through the design. The following sections describe the primary means of navigating a design.

Open Declaration (F3)

Source code browsing is done using the F3 button. Open "top_module.sv" (Ctrl+Shift+R). Find where the module "sub_module1". Put the cursor in on the module name and hit F3. The file containing "sub_module1" will open up. Hitting F3 on any signal name, class instance etc. will take you to it's declaration.

F3 works on most items:

Modules
Classes
Variables
Functions / Tasks

Hit Alt+Left Arrow which will bring the cursor "back in history", the same way as Firefox/Internet Explorer allow you to go back and forward through web pages.

Ctrl+Q will take the cursor to the last edit location, which is a huge timesaver.

Class Hierarchy (F4)

This feature is awesome for verification engineers. You can browse class hierarchy as follows.

Ctrl+Shift+R
my_package.sv
Search for the class "another_class_package" using incremental search (Ctrl+J)
1. Ctrl+J
2. Type "another_pkg_class"
While on the class name hit
1. F4

While the class hierarchy view is open, you can click up and down any class hierarchy that exists, double click on any of the class names, will open up the class. Clicking on any of the functions will take you to that function in the class.

Design Hierarchy

System Verilog Editor can show the complete design hierarchy. To open the design hierarchy view:

Window>Show View>Other>SVEditor>Design Hierarchy

Move the view to on top of the project explorer view
Hit the "Refresh" icon to populate the view
- This view is not dynamically maintained and you will need to hit refresh to rebuild the view
Browse the hierarchy
Double-click on any of the modules in the hierarchy window to open the source

Code Checking as you Edit

Now that you have opened the second project, you'll note that due to some poor coding there is an error in top_module. The "x's" in the Project

Explorer window highlight files that have issues. This makes it easy to find issues when in the design.

The error checking isn't exhaustive, and at this point there are still some false errors, error misses etc. That said, it is pretty good and

will catch most syntax errors saving you a 5 minute compile to find a missing semicolon.

If you find issues with the parser, please [https://sourceforge.net/p/sveditor/bugs/|file a bug] on Sourceforge. The parser is continually being improved.

Buffer Management

One of the things that you'll need to get used to when you first start using Eclipse is that you don't launch Eclipse to "Quickly edit a file". Eclipse is launched, a project is imported and Eclipse is left running permanently. File / buffer management in Eclipse is superb. You'll quickly find you have > 20 files open.

Before starting this exercise open up lots of .sv files

Ctrl+Shift+R
Type in *.sv
Select multiple files using Shift or Ctrl and either the mouse or keyboard
Hit Enter

Buffer switching can be accomplished in any of the following ways:

Ctrl+Shift+R
- ** Use this even if a file is open. If the file is already open, Eclipse will simply switch to this file, without reloading it.
Ctrl+E
- Type Ctrl+E
- A dialog that allows wild-cards makes it easy to find an open buffer
- Type *odule
- Use keyboard / mouse to get to sub_module1.sv
- Type Ctrl+E
- Type top
- Hit the Delete button - this is a convenient way of closing open buffers!!!
Ctrl+Shift+E
- Type Ctrl+Shift+E
- A variation of the Ctrl+E dialog
Cycling between buffers
- This is similar to Alt+Tab for switching between windows applications on a PC
- Type Ctrl+F6, releasing F6 but keeping Ctrl depressed
- You will see a dialog pop-up that shows you a list of buffers, in the order they were most recently used
- Press F6 till you get to the buffer you want to edit
- Release Ctrl at this point
- Type Ctrl+Shift+F6
- Release F6, while still depressing Ctrl+Shift
- This will cycle backwards through buffers
- Note: These are often re-bound to Ctrl+Tab and Ctrl+Shift+Tab

Splitting Windows

Type Ctrl+Shift+[
This will toggle splitting the window vertically
Type Ctrl+Shift+-
This will split the window horizontally

Duplicating Editors

An editor can be duplicated (opened twice). Once cloned, these are viewed as seperate entities, and can be move around the screen independently. Editing in one, will impact the other. An editor can be cloned as follows:

Window>Editor>Clone

Additional Topics

Column Mode

Eclipse supports column editing.

Firstly the default key-binding is pretty much never available... so it needs to be re-bound.

Window>Preferences>General>Keys. Re-bind Toggle Block Selection to Alt+C

Trying it out:

Enter Column Mode (Alt+C). The cursor will change to a "+". Note that this is a toggle function, and Alt+C will return to normal mode.
Now select some code. VI users will recognize the "start position" and stop position concept, and the area selected is just the square of that code.
Toggle back to normal mode Alt+C
Toggle back to column mode Alt+C
Cut the code out Ctrl+X. The Block will disappear.
Paste it back in Ctrl+V. Block will re-appear
Go to the start of a line
1. Type the Home key till the cursor is at the start of the line
Select a couple of lines (you will just see a thin vertical strip appear).
1. Shift+Down
Start typing. The typing will appear on every line that you have selected. Hit BackSpace. Backspace works on all lines too!

The font in the editor probably changed when column mode was enabled. The column mode font can be changed in the preferences:

Open font preferences
1. Window>Preferences>General>Appearance>Colors and Fonts
Set "Text Editor Block Selection Font" the same as "Text Font".

Indentation (Ctrl+I)

Eclipse will auto-indent code as it is typed. Type in the initial block below, watching how Eclipse moves begin / end etc as you type (most leading whitespace will work out without having to Tab or Shift+Tab to fix it).

i.e. Don't indent / out-dent as you type. You'll find that as you type the "d" in "end" the end statement will out-dent automatically.

Indentation of pasted code

Try pasting this un-indented code into top_module. Eclipse will fix the indentation for you.

 initial

 begin

 if (j=1) begin

 k=6;

end

end

Fixing Indentation (Ctrl+I)

Code that is poorly indented can be easily fixed. Select the block of code (mouse or keyboard) that is poorly indented and type Ctrl+I. Eclipse will fix the indentation.

Search for Exercise_CodeIndentation and follow the instructions in the comment.

If Ctrl+I is typed with nothing selected, the indentation of the entire file will be fixed. You can try this out as follows:

Remove all leading whitespace in the file
1. Bring up the search dialog box - Ctrl+F
2. Set the find string to \n[ \t]*
3. Set the replace string to \n
4. Make sure Regular Expressions is enabled
5. Hit Replace All
Now to fix the indentation:
1. Type Ctrl+I

Find & Grep (Ctrl+H)

This is pretty awesome. No longer do you have to go to the command line to do a search through the directory tree of a project to find the file containing a cryptic log message. Hit Ctrl+H. This will bring up a very complicated dialog box that looks something like this:

Every language installed probably has its own search dialog. Search boxes that you don't use can be hidden by clicking on the "Customize..." button in the lower left.

Type Ctrl+H
Search for "RESET_STATE1_DEFINE". You will end up with a screen that looks like this:

Now go ahead and double click on the one in top_module.sv.
1. You will be taken to the appropriate place in the design
If you modify RESET_STATE1_DEFINE, the search box will update when you "save" and the entry will disappear.

Diff'ing files

The in-editor diff feature is convenient. Eclipse keeps a history of the file as it is edited. To diff a file against an earlier edit, or against a version in the repository is easy. Just Right-Click the file being edited, Compare With> Local History (or repository version if enabled) which will give the following screen. Click on the saved of choice and the diff will appear. In this case between 3:36pm and December 12, 2011, a comma was removed after "out2".

Appendix

Workspace vs. Projects

A Project is the equivalent of a chip or a design you are working on.

A Workspace, is an Eclipse concept which specifies:

A location to do caching
A set of window-layouts
A set of Projects that are loaded (there can be multiple projects loaded at any given time)
Switching between workspaces is as easy as File>Switch>Workspace

A common question is "Should I have multiple Workspaces with a single project per Workspace or a single Workspace with multiple Projects loaded. For most scenarios it doesn't matter. The following table highlights some of the pros and cons of each usage model.

Usage Tip: On larger projects you can speed Eclipse up by making sure that your workspace local to the computer you are running on. i.e. Not on the network.

Refreshing the Design / Workspace / SV Database

Once in a while you may choose to do things outside of the workspace (copy in a directory tree etc). F5 is used througout Eclipse refresh, in this

case refresh the data on the disk. For example, if you refresh your design from the revision control system on the command line, outside of Eclipse. Go to the Project

Explorer, and hit F5. Eclipse will refresh the file tree.

At times like this it is also worth re-building the System Verilog Database. Note that this is a separate activity from a file-system refresh.

Make sure you are in the System Verilog Perspective (ribbon near the top right of the screen)
Project>Clean

Eclipse will automatically "Rebuild the SV Index" from time to time (when file system differences are detected). You can disable this in the SV Preferences Screen: Window>Preferences>SVEditor>Enable Index Auto-Rebuild

Eclipse Preferences

Eclipse preferences are managed in Window>Preferences. It can be somewhat difficult to find a specific preference. The search box is invaluable. Here are some of the commonly used preferences:

Line Numbers: General>Editors>Text Editors>Show line numbers
Tab Width: General>Editors>Text Editors>Displayed tab width
Spaces vs.Tabs: General>Editors>Text Editors>Insert spaces for tabs
Key bindings: General>Keys
Colors/Fonts:
- General>Editors>Appearance>Colors and Fonts
- General>Editors>Text Editors>Appearance color options
- General>Editors>Text Editors>Annotations
- SVEditor>Syntax Coloring
- Search for 'Color'. Each language has it's own, semi-independent overrides
File associations:
- General>Editors>File Associations

Natural Docs

If code is documented using a "Natural Docs" style of coding, pop-ups will appear as the mouse moves over documented constructs. If the mouse is held over the mult function in top_module as shown, a pop-up will appear showing a description of the function.

How is this done? Jump to the mult function by putting the cursor on the mult instantiation and hitting F3. Look at the comment above the mult function, you'll see that this code has been replicated in this pop-up. The syntax is pretty intuitive. The long term benefit to people unfamiliar with the code base will pay huge dividends in the longer term.

Natural docs allows you to document variables, functions, tasks, modules etc. this way.

A Natural Docs compliant comment can be generated above Modules, Packages, Classes, Functions Tasks etc. by typing "/**<Enter>" on the line above one of these elements, or by simply typing Shift+Alt+J with the cursor in one of these elements.

Preference Management

Preferences are stored in the workspace. Switching between workspaces or creating new ones doesn't port preferences (key-bindings, colors etc.) automatically. This is both good and bad. On the one had it allows a different color scheme for each workspace, on the other they need to be managed. Fortunately this is really simple. It is also a good idea to back up preferences as you customize Eclipse.

Exporting preferences is easy:

File>Export>General>Preferences
Save the preference file somewhere you can find it easily (MyDocuments or ~).

Importing preferences in a new workspace is just as easy:

File>Import>General>Preferences
Browse to the preference file that was exported (MyDocuments or ~).
Select the perferences to import (typically all)
Restart Eclipse to make sure all preferences are applied
1. File>Restart

Revision Control Support

Eclipse does an excellent job of connecting to various revision control systems.

Keyboard Shortcuts

Below is a short list of keyboard shortcuts to get you going.

Changing Keybindings

Like any good editor, key bindings can be remapped. For the EMACS & VI users (which is pretty much all of us) there are plugins that give Eclipse a EMACS/VI keybindgs and feel.

Keybindings can be changed at:

Window>Preferences>General>Keys

Updating Eclipse

The SVEditor plugin is being actively developed. Updates based on user feedback are released fairly frequently. To update both the Eclipse installation and all installed plugins:

Help>Check for Updates

To update a specific plug-in:

Help>About>Installation Details>Select the plugin>Update

Last updated April 2017, 1.9.9

Google Sites

Report abuse