Getting Started with SNiFF+ and TornadoII

Thank you for your interest in SNiFF+ and Tornado.

SNiFF+ provides you with advanced source code comprehension, navigation, editing, build, and configuration management tools. It is a rich, highly integrated toolset that makes the daily work with your Source Code easier, more organized, and more productive. In conjunction with Tornado, SNiFF+ Project and Make Facilities will help you to manage large projects; and the SNiFF+ Browsing tools will particularly help to understand and work with legacy source code or code licensed from other companies.

This guide describes how to install SNiFF+ into an existing Tornado environment. You don't have to work through the entire guide: each chapter takes you a step further to understanding the full power of all SNiFF+ tools.

We will be happy to assist you with evaluating this product. Particularly, we'd like to point you to

For any more technical information or feedback, please contact mailto:sniff-tornado-beta@takefive.co.at . For license related inquiries, please contact your local WindRiver Representative (contact information see below).

What you Should Have Prepared by Now

You must have a working installation of Tornado on your computer; to completely go through this tutorial, you should also have a VxWorks simulator installed (the VxSim-Lite will do).

You will need the Tornado patch for SPR28340 from WindSurf at http://www.windriver.com in order to use the SNiFF+ Debugger Adaptor. For your convenience, we have made an unbundled version of this patch available on ftp://ftp.takefive.com/pub/SNiFF/integrations/TornadoII/SPR28340/, which will save you download time because you can restrict the download to those Platforms that you really need. Please read the Tornado integration release notes in README.html to learn more about latest issues or patches required.

It is assumed that you have already worked through the "plain" Tornado Getting Started Guide. Knowing plain Tornado, this tutorial is organized in a way that allows you to successfully use SNiFF+ in your own projects once you have worked through the first three chapters.

The SNiFF+ Tornado Integration has been tested with this Guide on Microsoft Windows NT 4.0SP6, Sun Solaris 7 and HP-UX10.20. It has not been tested on Windows 95 or Windows 98, or any of the Tornado 1.0.1 supported platforms (IBM RS6000, SunOS 4). Any feedback regarding these Platforms is welcome.

Installing SNiFF+ for Tornado

The SNiFF+ Tornado Integration works with SNiFF+ 3.2 or higher. To get all current bug fixes, we recommend to download the latest version of SNiFF+ from ftp://ftp.takefive.com/pub/SNiFF. In particular, the SNiFF+ for Windows Debugger Adaptor will work only with SNiFF+ 3.2.1 (build date February 18, 2000).
When you run the SNiFF+ Setup Program, we recommend to use the following options: Once SNiFF+ and Tornado are installed, you need to run the Tornado integration install script, which is located in the root of the Tornado Integration directory. On UNIX, just execute $SNIFF_DIR/integrations/TornadoII/install.sh , on Windows double click on %SNIFF_DIR%\integrations\TornadoII\install.exe to run it.. You may accept all defaults during the installation process.

Licensing

SNiFF+ comes with a pre-installed personal license, which will allow you to use the product for evaluation and non-commercial projects of up to 200 files. This will suffice for working through most of this guide. For working with Board Support Packages (BSPs) in SNiFF+, we recommend that you obtain a full evaluation license. This will enable all SNiFF+ features for projects of arbitrary size, but for a limited time. You can request both evaluation and full product licenses from your local WindRiver Representative. Contact information is available from For the Far East, South America, Australia, New Zealand and any other countries not listed here, please refer to http://www.windriver.com/corporate/html/contact.html for contact information.

Starting SNiFF+

The Tornado integration install script should have placed startup files into your Tornado installation at $WIND_BASE. You must start SNiFF+ with these startup scripts to make the integration work! This means, When you first start SNiFF+, the Welcome Dialog will appear. You can close this dialog. The Launch Pad will remain on the screen. You may choose the Question Mark at the right end of the menu bar to open the Help Menu and see the online documentation (note: on UNIX, this requires the Netscape Browser).
On the left end of the menu bar, you see the Tools menu. On Windows, this is identified by the word "Tools" whereas on UNIX, you can open it by clicking on the Launch Pad's icon. Open the Tools menu; if you later want to quit SNiFF+, you can do so by choosing "Quit" at the end of the Tools menu.

Browsing

Single-User Project Setup

The Single User Project Setup, also known as Browsing-Only Setup, is the easiest way to look at your code with SNiFF+. It enables you to use all the Browsing and Editing Tools. SNiFF+ Makesupport can not be used in this configuration, but you may use your own hand-written Makefiles together with SNiFF+. If you have ClearCase as your CM tool, it is also possible to do Version Control and Configuration Management with the Browsing Only Setup (for information on how to enable this, see the SNiFF+ User's Guide or Online Documentation). If you use other CM tools, you will need to set up a Team Project (see below) to use these features (see Using SNiFF+ Team Support and Configuration Management, below).

We have created Tornado-specific SNiFF+ Project Templates to make it easier to set up your projects. We explain the steps to be taken in terms of the factory C++ example, which is also part of your Tornado installation (in the %WIND_BASE%\target\src\demo\cplusplus\factory directory). We ship this example also together with the SNiFF+ Tornado Integration, just in case it should be missing in your installation.
We chose to use a C++ example to show also the object-oriented SNiFF+ Browsing Tools; for more information about the plain C browsing tools, see also the next chapter (using SNiFF+ Make Support). For other Languages like Ada or Java, see the respective SNiFF+ Tutorials, which are available from the Help Menu in the Launch Pad.
To work through the factory example:

  1. In the Launch Pad, choose Project -> New Project -> With Template
  2. Select the "Tornado_BrowsingOnly.ptmpl" Template
  3. At the lower end of the Dialog, click on the "Change Directory" button to open the Directory Browser
  4. Navigate to the $SNIFF_DIR/example/Tornado/1_BrowsingOnly/factory directory (Note: You may use the Directory Browser's Directories menu to access a history list of directories you have visited before) and click the "Select" button
  5. Back in the Project Templates Dialog, click on the "OK" button: the Project Attributes Dialog appears.
  6. Thanks to the Project Template, you may leave all settings as they are. Don't be confused by the many options you can set; the Template will be good for most of your own C/C++ projects, too. In fact, there are only two settings that are important at this point:
  7. For more information, please refer to the SNiFF+ Reference Guide, Chapter 15 (Project Attributes) or Online Documentation. For now, you may just press "OK" to set up your project.
  8. SNiFF+ will set up the project and parse your files. In the "Generate Crossref Information Dialog", you may answer "No" since SNiFF+ will automatically generate Crossref information as soon as it is needed.
You now see the new project in the SNiFF+ Project Editor. This is the tool for finding files and modifying project structure. In the next step, we will now add a subproject for the VxWorks C++ Headers to get full browsing information.

Adding Subprojects for Browsing

We have created ready-made SNiFF+ Project Descriptions for all the VxWorks headers, and some VxWorks Sources as well. For other target operating systems, such project descriptions can easily be created, and we will make some of them available as extra packages on the TakeFive FTP Site at ftp://ftp.takefive.com/pub/SNiFF/integrations/TornadoII .
Having structured project descriptions for VxWorks has the advantage that you can focus your interest exactly on those protions of code that you need, and you won't be distracted by parts that you are not interested in. You may select Code portions for browsing simply by selecting SNiFF+ Project Descriptions (= source modules) as subprojects. We will do this for the "Factory" example now:
  1. Select the "factory.proj" project in the lower pane of the Project Editor
  2. Choose Project -> Add Subproject
  3. In the Directory Browser, navigate to $SNIFF_DIR/PDFs/VxWorks5.4 and choose the VxWorks5.4_h_Cplus.proj project
  4. SNiFF+ will add the VxWorks C++ Headers to your Project Tree. This means a modification to your factory.proj project description, therefore you will see a "caution" sign in front of it. This "caution" sign is always shown when an item is modified but not yet saved. Click on factory.proj and click the diskette button in the button bar to save the project.
The VxWorks5.4_h_Cplus projects you just added are separated into the C++ Standard Classes (Strings, Exceptions and Iostream), the Standard Template Library (STL) and the Wind Foundation Classes (WFC). You may now apply SNiFF+ Filtering by putting a green checkmark into the square beside each of the project's names in the Project Tree. The filelist in the Project Editor's upper pane gets filtered by your selection in the Project Editor's lower pane. This filtering concept allows you to focus your interest on what you really need; similar filters are available in all SNiFF+ tools.

Using SNiFF+ Browsing Tools

You may now use the various SNiFF+ Browsing Tools: Hierarchy Browser and Class Browser for Object-Oriented Browsing, Symbol Browser, Include Browser and Cross Referencer for plain C browsing, and the Retriever for Text-based global search and replace actions. Note that you can start all tools through the Tools menu at the left side of the menu bar.

In most cases, however, it will be better to open a tool in a particular browsing context: Double Click on the factory.cpp file to open the SNiFF+ Source Editor. Click on testfactory in the right window pane to directly jump to this function. In the Source Code of testfactory(), click on objectCreate and choose Show -> Symbol(s) objectCreate. It will take you the objectCreate() function. This navigation functionality is also bound to the Ctrl-Q (Windows) or Meta-Q (UNIX) keyboard shortcut! Use the Source Editor's green back arrow in the button bar to go back to the place where you have been before. Now, choose Info -> testfactory refers to to see a nice call graph in the Cross Referencer. Double click on object_t to open the Source Editor again and see how this structure is defined; choose Info -> factory.h includes to see an include tree. Note how the context-sensitive menus "Show", "Info" and "Class", and the buttons allow you to focus on your source code for browsing; this is the best way of using SNiFF+ in daily work.

What's next?

Set up a browsing project onto your own sources.
For adding or removing files or subprojects to your SNiFF+ Project, go to the Project Editor and choose Project -> Add New File, Project -> Add/Remove Files, and Project -> Remove Subproject, respectively. For each of these actions, the corresponding SNiFF+ project must be selected in the Project Editor's lower pane.
As a next step, we recommend to set up a SNiFF+ project on your own sources, to see how SNiFF+ can help you improve your productivity. If you rather choose to follow our example track, the next section will cover how to make, run and debug your programs.

Using SNiFF+ Make Support

This section shows you how SNiFF+ interacts with your Tornado Environment to Make, run and debug your programs. It uses an already-setup example program and thus shows you, how easy it is for developers to work with SNiFF+ Makesupport. By looking at the Project Attributes we have set, you will also learn how to set up your own projects. The next chapter, "Using SNiFF+ Team Support" will then explain the Configuration Management and Version Control features of SNiFF+.

Show the SNiFF+ Launch Pad (the initial Window that turned up when you started SNiFF+). It has two tabs: the Projects Tab and the Working Environments Tab. If you have not closed the "factory.proj" project from the example below, you can do so now by selecting it in the Projects Tab and choosing Project -> Close Project.

Now, switch to the Working Environments Tab. A SNiFF+ Working Environment is a managed area for a developer to work in (see the next section, "Setting Up a Team Project", on how to create Working Environments). You should see three Working Environments: one for the SNiFF+ Standard C++ Example "Filebrowser", one for your favourite Real Target and one for your Host's Simulator. To open the example project:

  1. Double Click on the Working Environment that matches your Tornado Simulator type:
  2. If there is no Simulator for your Host type, you may use any other "adm PWE:Gizmo (anyTarget)" instead. Build support will work just the same way as in the Simulator Environments.
  3. In the upcoming dialog, click on the "Update List" button to display a list of all SNiFF+ Projects that can be found in this working environment.
  4. Double Click on the "gizmo.shared" project to open it.
The SNiFF+ Project Editor will open and show the "gizmo" downloadable application, which is a modified version of the example shown in the original Tornado Getting Started Guide. The example is modified to contain both a Library and a main module to demonstrate SNiFF+ automatic linking of submodules.
All SNiFF+ Tools to invoke compilation, Run and Debugging can be found in the Project Editor,s Target menu. To build the gizmo application:
  1. Select gizmo.shared in the Project editor's lower pane (the Project Tree).
  2. Select Target -> Update Makefiles to generate SNiFF+ Make Support files.
  3. Select Target -> Make -> All to recursively build both the library (which is a subproject) and the main application.
  4. In the Project Editor, select Tornado -> Launch Simulator... to start a VxWorks simulator on your machine.
  5. Select Tornado -> Target Server... to see your Target Server's properties. Note:
  6. Select Tornado -> Download [...]/gizmo.out to download your application to the target. Note:
  7. Select Tornado -> WindSh to connect a WindShell to the Target. In the WindSh, type moduleShow to verify that the module has loaded and type progStart to run the program.
  8. Back in the Project Editor, select Target -> Debug to open the SNiFF+ Debugger tool. It will automatically connect to your currently selected target server (this is only possible if an application has already been downloaded). In the SNiFF+ Debugger tool, type "attach tMonitor" to attach to the running program. Depending on where the program is currently executing, the SNiFF+ Source Editor should open up with an additional button bar for debugging.

  9. If the Source Editor doesn't open automatically:
The advantage of the SNiFF+ Debugger as opposed to CrossWind is that it has full browsing support, and thus it is particularly useful for object-oriented programs. You may particularly like the Cross Referencer's "Refers To" query to show call graphs which allow you to quickly set breakpoints.
The disadvantage of the SNiFF+ Debugger tool is its limited capability of data display. Basically, data structures can just be printed or watched in the SNiFF+ Debugger Tool, which is a pure text-based interface to gdb. However, on UNIX it is possible to use the DDD (Data Display Debugger) as a front-end between the SNiFF+ Debugger Tool and the Tornado gdb backend. This will allow for very advanced data display capabilities. For more information about DDD, see http://www.gnu.org/software/ddd/

Understanding SNiFF+ Makesupport

To understand how SNiFF+ Makesupport works, you should now close the Editor and the Debugger tool (On Microsoft Windows, the Tornado gdb may issue an Application Error message, which can be safely ignored since all data is saved at that point).
Look at the file list in the Project Editor: you will notice that there are a file called Makefile and a file called Makefile_sniff in each project. The Makefile is the one which is automatically created by Tornado; the Makefile_sniff is automatically generated and maintained by SNiFF+, so both Make systems work in parallel. While Tornado re-writes its entire Makefile whenever the Project is changed, SNiFF+ takes a different approach. Double Click on Makefile_sniff to open it in the Source Editor: you will see that this is a Template, which includes other files like macros.incl from the directory .sniffdir. Macros.incl is one of 4 different Make Support Files which are generated by SNiFF+ when you choose the "Target -> Update Makefiles" menu. Together with a set of general Makefiles from the $SNIFF_DIR/make_support directory, these configure the Make Support. The Makefile_sniff itself, however, is never modified by SNiFF+; it can be used to change any settings that are not available through the GUI.

The standard way of customizing SNiFF+ Makesupport is not by editing the Makefile, but in the GUI, by editing the SNiFF+ Project Attributes. To look at (or modify) the attributes of the hotLib.shared project, double click on hotLib.shared  in the Project Editor's lower pane (the Project Tree). You will see the SNiFF+ Project Attributes Screen. For Makesupport, the following settings are important:

Now, close the Project Attributes screen (you won't ever need the Advanced Node) and open the Project Attributes of gizmo.shared by double clicking at it:

Using Tornado Target Tools from SNiFF+

Next Steps

Using SNiFF+ Version Control and Configuration Management

This section will show you how to use SNiFF+ Version Control and Configuration Management Tools in an already-setup project. Understanding Version Control is necessary in order to understand SNiFF+ Team Support, which we will cover in the next section. This is under construction!

Using SNiFF+ Team Support

This section will show you how to use SNiFF+ Team support in an already-setup project. It will cover the steps necessary to add a new target platform, or to add a new member to an existing team. The next section, "Setting Up a Team Project", will then guide you through the steps of creating a new shared project from scratch yourself. Under Construction!

Setting Up a Team Project

Under Construction!

Working with BSPs

SNiFF+ Browsing Facilities can help you to create or configure your Board Support Packages (BSPs) for Tornado. Depending on your team size and configuration management setup, there are different levels of sophistication how the environment can be set up. We explain everything in terms of a Pentium BSP here, but the steps can be followed in the same manner for any other BSP you may use.

BSP Setup for Tornado-Only Makesupport

This very simple setup will suffice for most applications, and because only original Tornado Makesupport is used it is safe that your BSP will compile correctly. To create a modified version of the Pentium BSP under SNiFF+ control, we do the following:
  1. First, we copy the original $WIND_BASE/target/config/pcPentium directory into a new directory, for instance $WIND_BASE/target/config/pcPentium_T5 . This is necessary because Tornado Makesupport will write into the $WIND_BASE tree during the "make release" process, and we do not want to overwrite original Tornado files. Note: If you do not have write access to the $WIND_BASE tree, you may also copy the BSP into your PWE (for instance $HOME/Sniff_WS/PWE/config/pcPentium_T5) and work there.
  2. Next, we set up a SNiFF+ Project onto the newly copied BSP:
  3. In the Project Editor, double click on the Makefile and change all occurences of "pcPentium" to "pcPentium_T5" to make sure Tornado will create correct output files.
  4. Choose Target -> Make -> bootrom to verify that the original BSP compiles correctly.
  5. In the Project Editor, choose "Project -> Add Subproject" to add any SNiFF+ Projects you would like to see for browsing. If you just need to make some simple customizations, you probably don't even need to do this; for larger customizations or writing additional drivers, you may want to add some or all of the following project descriptions:
  6. Note that you may need a full SNiFF+ product license or a time-limited full evaluation license to be able to add these projects, because some of them may contain more than 200 files. See section "Licensing" for how to get an evaluation or product license. Also note that the BSP Browsing Sources may be interesting only for the BSP developer, but not for an application developer who just uses the BSP; so, it is often a good idea to create a new wrapper project which allows to keep the core BSP project and the browsing projects separate. For more info on doing this, see the section "Working with Bootable Applications", below.
  7. Check in all files of the BSP project, so that you can track your later modifications to the original BSP.
  8. When you are done with any modifications you need to do, choose Target -> Make -> release to build the entire BSP and create a Tornado Template projects in $WIND_BASE/target/proj/pcPentium_T5_vx.
From that point on, your BSP is released and other users can build their bootable applications based on it. In a multi-user environment on Windows, where every developer has his private copy of Tornado, the released BSP needs now be copied into the other Tornado Installations. This can be simplified by putting the released Tornado template project under SNiFF+ Control as well:

Putting a Released BSP under SNiFF+ Version Control

Having your released BSP and template projects under SNiFF+ Version Control allows every developer to quickly get new versions by simply synchronizing his workspace. In a multi-team environment with two SSWEs, this can even be done automatically at night with the update scripts. All you need to do, is create a SNiFF+ "Master Project" for your Tornado installation, which will contain all your BSPs and template projects as subprojects. Again, we explain everything in terms of our pcPentium_T5_vx project, but the instructions apply equally to other BSPs.
  1. First, we create a "Workspace.shared" project which will be the common root of all released BSPs. If you already have a such a Workspace Project, you may skip this step, open your Workspace Project and continue with (7), below. If not, this is what you do:
  2. In the Project Editor, select your "Workspace.shared" project. If it is read only, check it out.
  3. Select Project -> Add Subproject and add your BSP project from config/pcPentium_T5/BSP_pcPentium_T5.shared .
  4. Select Project -> Add New Subproject -> With Template.
  5. Choose the "Tornado_Customized_VxWorks.ptmpl" Template.
  6. Press the "Change Directory..." button and navigate to the $WIND_BASE/target/proj/pcPentium_T5_vx directory.
  7. In the Project Attributes Dialog, click OK to accept all defaults.
  8. Check all files from the pcPentium_T5_vx.shared project, and the modified Workspace.shared project.
Now, any user who opens the "Workspace.shared" project and synchronize his workspace, will automatically get the latest version of the released BSP. For full SNiFF+ Workspace Support without absolute directory references, it may be necessary to replace absolute paths created by Tornado in the pcPentium_T5_vx.wpj project with relative paths. For more information, see "Working with Bootable Applications", below.

Enabling SNiFF+ Makesupport for a BSP

One disadvantage of using the plain Tornado Makesupport for your BSP is, that you cannot use SNiFF+ Recursive Make for your entire workspace to build a complete product. The other disadvantage is that you cannot switch Build Specifications (for instance, Relase and Debug Build) for your BSP and that object files are not redirected into a Platform-specific subdirectory. All these drawbacks can be amended easily by enabling SNiFF+ Makesupport for your BSP. Again, we show the steps necessary in terms of the pcPentium_T5, but they can be done in just the same way for any other BSP.

Modifying the Makefiles to Avoid Write Access to the Tornado Installation

Original Tornado Makefiles for BSPs are written in a manner that requires write access to the Tornado Installation, at least for doing the "make release". This may be problematic in UNIX-Based environments, or in large installations where everything should be under proper Configuration Management.
SNiFF+ can avoid writing to the Tornado Installation either by completely migrating to SNiFF+ Makesupport (we have prepared the "MakeBSP" template as a blueprint for this), or by modifying original Tornado Makefiles. If this is an issue for you, please get in contact with us by E-Mail to mailto:sniff-tornado-beta@takefive.co.at.

Working with Bootable Applications

Under Construction!

Working with WindRiver Source Products

Under Construction!

Advanced Issues and Customization

Under Construction!

Appendix: Reference Section