Overview

Navigation: »No topics above this level«

Overview

 Return to chapter overview

Welcome to the VM Validator help manual.

This section provides a brief overview of the capabilities of VM Validator.

This help manual is available in Compiled HTML Help (Windows Help files), PDF, and online.

Windows Help | https://www.softwareverify.com/documentation/chm/vmValidator.chm
PDF | https://www.softwareverify.com/documentation/pdfs/vmValidator.pdf
Online | https://www.softwareverify.com/documentation/html/vmValidator/index.html


Introducing VM Validator

Navigation: Overview >

Introducing VM Validator

 Return to chapter overview

VM Validator is an tool for visualizing the virtual memory of a process for Windows XP and any subsequent version, for both 32 bit (x86) and 64 bit (x64) processors.

VM Validator reads the virtual memory information for a given process on a regular basis and displays the results graphically. This allows you to identify the impact that virtual memory paging is having on your program's performance.

The user interface is split into three separate sections, each section dedicated to a different task. Typically when using VM Validator a user will use one section to analyse a problem that is present in the target program. The four main sections are:

· Summary

An high level overview of the main memory statistics of the program. Additional data relating to DLLs and page faults is also available.

· Virtual

A visual display of the allocation state of each memory page in the program. This is a similar view (that has different functionality) to the Virtual view in VM Validator.

· Pages

A tabular display of all the virtual memory pages in the program. This is a similar view (that has different functionality) to the Virtual view in VM Validator.

· Paragraphs

A tabular display of all the virtual memory paragraphs in the program. This is a similar view (that has different functionality) to the Virtual view in VM Validator.

A memory paragraph is the smallest amount of memory that the VirtualAlloc() function can allocate. This size is defined by the operating system dwAllocationGranularity returned from Win32 API call GetSystemInfo()).

For 32 bit x86 Windows Operating Systems a memory paragraph is 64Kb.


Why VM Validator?

Navigation: Overview >

Why VM Validator?

 Return to chapter overview

VM Validator allows you to analyse a program's virtual memory performance in a graphical manner. This is much more useful than a binary dump of page addresses that can be found in various books on undocumented secrets about Windows NT® books. As the display changes you can identify areas that are repeatedly paged in and then paged out. When these areas have been identified you can make changes to your program's memory management to try to reduce the page swapping.

Reliable

VM Validator has been created with the following criteria in mind.

1) VM Validator must have no adverse effect on the program's behaviour.

The program must behave in the same way when being inspected by VM Validator as when the program is running without being inspected by VM Validator.

2) VM Validator must be reliable and avoid causing the target program to crash.

3) VM Validator must be capable of having as little impact on the target programs performance as possible.

4) VM Validator's user interface must be independent of the target program.

VM Validator's user interface is independent of the target program.

·If the VM Validator user interface crashes, your target program will not crash.

·If the target program crashes the VM Validator user interface will not crash - you will still have data to work with.

·If the target program is stopped in the debugger, VM Validator's user interface will continue to work.

5) Flexibility

Where there are multiple ways of presenting the data, the user should be given a choice over how that display works. Not all users like the same choices, so providing some choice over the display is always better than forcing all users to use the same settings.


What do you need to run VM Validator?

Navigation: Overview >

What do you need to run VM Validator?

 Return to chapter overview

·User Privileges

A standard user account is required.

·Operating System

VM Validator requires Windows XP or better.


How to get VM Validator

Navigation: Overview >

How to get VM Validator

 Return to chapter overview

VM Validator is free commercial use. VM Validator can be downloaded for Software Verify's website at https://www.softwareverify.com.

Whilst VM Validator is free for commercial use, VM Validator is copyrighted software and is not in the public domain. You are free to use the software at your own risk.

You are not allowed to distribute the software in any form, or to sell the software, or to host the software on a website.

Contact Software Verify at:

Software Verify Limited

Suffolk Business Park

Eldo House

Kempson Way

Bury Saint Edmunds

IP32 7AR

United Kingdom

email | sales@softwareverify.com
web | https://www.softwareverify.com
blog | https://www.softwareverify.com/blog
twitter | http://twitter.com/softwareverify


How does VM Validator work?

Navigation: Overview >

How does VM Validator work?

 Return to chapter overview

VM Validator monitors the target process in a non-invasive manner collecting data about the target process using the Win32 API.


What does VM Validator do?

Navigation: Overview >

What does VM Validator do?

 Return to chapter overview

VM Validator provides functionality to allow virtual memory information to be inspected so that virtual memory status and swapping can be detected and analysed.

As the display changes you can identify areas that are repeatedly paged in and then paged out. When these areas have been identified you can make changes to your program's memory management to try to reduce the page swapping.

An additional display shows the classification that the Windows NT® memory manager gives to each area of memory.


The User Interface

Navigation: »No topics above this level«

The User Interface

 Return to chapter overview

This section describes the various functions of the user interface so that you can get the most from using VM Validator.

Typical usage of VM Validator is:

·Start the target program.

·Examine the virtual memory paging behaviour of the target program as you use the target program to perform actions of interest.

·Close the program.

However there is much more to VM Validator than the above. Whilst your program is running you can display data in VM Validator and using the information from VM Validator you may gain insight into a bug you are looking at in the debugger.


Menu Reference

Navigation: The User Interface >

Menu Reference

 Return to chapter overview

This section lists the various menus in VM Validator and provides links to the appropriate section of the help manual.

File

· Load Session

· Save Session

· Load Minidump

· Save Minidump

· Exit

Launch

· Start Application

· Re-Start Application

· Inject

· Wait For Application

· Abandon Application

Inspect

· View Memory Dialog

· Search Memory Dialog

Settings

· Settings

Data Views

The Data Views provides easy control of which tabs are displayed in the main view.

· Summary

· Virtual

· Pages

· Paragraph

Selecting any of the items shows the relevant tab (if it's not visible already), and makes it the current selected tab.

·Hide All Views instructionStep hides all tabs except the one that's currently visible

·Show All Views instructionStep shows all the listed tabs, and in that order

·Reset All Views instructionStep shows the original settings tabs.

Software Updates

The Software Updates menu controls how often software updates are downloaded.

This is discussed in detail in Software Updates.

Help

· Tips

· About VM Validator

Version and licence information for VM Validator.

·Readme and Version History

Displays the VM Validator readme and version history.

· Help Topics

Help in compiled HTML format.

· Help PDF

Help in PDF format.

·Help on softwareverify.com

Displays the documentation page on the software verify website.

·Blog

Displays the Software Verify blog.

·Library

Displays the Software Verify library - our best articles grouped by related topics.

·Contact customer support

Click a link to contact customer support

·How Do I?


Toolbar Reference

Navigation: The User Interface >

Toolbar Reference

 Return to chapter overview

This section describes the toolbar in VM Validator and provides links to the appropriate section of the help manual. The icons are described in sequence from left to right in the toolbar.

· Settings

· Inject into application

· Launch application

· Re-Launch application

· Stop application


The main display

Navigation: The User Interface >

The main display

 Return to chapter overview

The main display of VM Validator consists of four tabbed windows. Each tabbed window allows the data collected by VM Validator to be viewed, inspected and queried in different and complimentary ways. Typically when using VM Validator a user will use one window to analyse a problem that is present in the target program. The four tabbed windows are:

· Summary

· Virtual

· Pages

· Paragraphs


Summary

Navigation: The User Interface > The main display >

Summary

 Return to chapter overview

The Summary view allows you to get an overview of your application's memory usage.

Four main panels highlight key statistics and a lower panel with two tabs provides information about DLLs and page faults.

Overview

Virtual Memory - statistics about the virtual memory usage of the application.

·Committed. Committed memory.

·Reserved. Reserved memory.

·Free. Free memory.

·Private. Memory private to this application.

·Image. Executable files (EXE, DLL, etc).

·Mapped. Memory mapped files.

·Stack. Memory used for thread stacks.

·Shareable. Memory shared with other applications.

·Swapped. Memory swapped in/out of memory.

·Wasted. Memory allocated by VirtualAlloc() but not available to the application to use. What is wasted memory?

Clicking on one of these bars will take you to the Pages tab to display data about the type of memory that was clicked on.

Contiguous Regions - data about the largest contiguous region for each type of virtual memory. These values will let you easily determine if there is enough memory to satisfy a particular allocation request.

·Committed. Committed memory.

·Reserved. Reserved memory.

·Free. Free memory.

·Private. Memory private to this application.

·Image. Executable files (EXE, DLL, etc).

·Mapped. Memory mapped files.

·Stack. Memory used for thread stacks.

·Shareable. Memory shared with other applications.

Clicking on one of these bars will take you to the Pages tab to display data about the type of contiguous memory that was clicked on.

Page File - data about the working set and the page file.

·Peak Virtual Size

·Virtual Size

·Peak Working Set Size

·Working Set Size

·Peak Page File Usage

·Page File Usage

Quota - data about the paged and non-paged pool used by the operating system and device drivers.

·Quota Peak Page Pool Usage

·Quota Page Pool Usage

·Quota Peak Non Paged Pool Usage

·Quota Non Paged Pool Usage

For more information about paged and non-paged pool see https://blogs.technet.microsoft.com/markrussinovich/2009/03/10/pushing-the-limits-of-windows-paged-and-nonpaged-pool/

DLLs

A list of all DLLs in the application with statistics on page faults, load address, dll size, amount of committed memory, amount of reserved memory, the CPU it was built for (x86, x64, AnyCPU) and the type of DLL (native, managed, mixed-mode).

Note that AnyCPU, managed and mixed-mode only apply if a .Net application is being examined.

A context menu is available for the DLLs grid, to allow DLL inspection using PE File Browser, and to copy the DLL name to clipboard.

Page Faults

A list of all page faults that have been monitored, which DLL they were in (if any) and what symbol, filename and line number are related to that address.

If you have problems getting symbols you may want to change the settings used to obtain symbols.

This display doesn't include all page fault information. If you want detailed page fault information, download Page Fault Monitor from https://www.softwareverify.com/cpp-page-fault-monitor.php

A context menu is available for the page faults grid, providing source code editing, DLL inspection, and copy the DLL name or filename to clipboard.


Virtual

Navigation: The User Interface > The main display >

Virtual

 Return to chapter overview

The Virtual tab displays a visual representation of all the memory in the target program. This is known as the virtual view. A visual display of the allocation state of each memory page in the program.

The virtual view displays information about a process's virtual memory usage whilst the process is running. If there is no target program being monitored, the virtual view does not display any data. The display will be black.

Virtual Memory Information

When the mouse cursor is moved on the display area, some information on the page address, start and end of the region of memory, and the use of the memory are displayed.

If the mouse is over a region of memory that is a DLL the name of the DLL is displayed.

The Page Address field displays the start address of the page of virtual memory that the mouse cursor is pointing at.

The Region Address field displays the start address and the size of the region of virtual memory that the mouse cursor is pointing at.


Pages

Navigation: The User Interface > The main display >

Pages

 Return to chapter overview

The Pages tab displays a tabular representation of all the memory in the target program. This is known as the pages view.

The pages view displays information about a process's virtual memory usage whilst the process is running. If there is no target program being monitored, the pages view does not display any data.

The data displayed is data per virtual memory page (as defined by the operating system). For 32 bit x86 Windows Operating Systems a page is 4Kb.

Filtering

The displayed data can be filtered by Type and by Working Set.

Type

Filtering by type filters memory for the following types of memory:

·All. All types of memory.

·Committed. Committed memory.

·Reserved. Reserved memory.

·Free. Free memory.

·Private. Memory private to this application.

·Image. Executable files (EXE, DLL, etc).

·Mapped. Memory mapped files.

·Stack. Memory used for thread stacks.

·Shareable. Memory shared with other applications.

·Swapped. Memory swapped in/out of memory.

·Wasted. Memory allocated by VirtualAlloc() but not available to the application to use. What is wasted memory?

The above image shows the pages display filtered by Private memory, showing memory that is in the working set and memory that is not in the working set.

Working Set

Filtering by working set filters memory for the following working set criteria:

·All. Displays all memory.

·Working Set. Only displays memory that is in the working set.

·Not Working Set. Only displays memory that is not in the working set.

The above image shows the pages display showing memory that is in the working set.

Sorting

Each column can be sorted by clicking the column header to move sorting to that column. Clicking the current column header again reverses the sort direction.

Context menu

A context menu is available to allow DLL inspection using PE File Browser, and to copy the DLL name to clipboard.

Viewing swap behaviour

To view virtual memory being swapped select the Swap column so that the sort arrow points downwards.

The display will show pages that have been swapped with the number of times they have been swapped shown in the Swap column.

When a page gets swapped it will be promoted at the top of the swap column for 1 second then be displayed back in it's regular sorted position.

When combined with the highlight swapped memory option on the Display Settings dialog you can very easily see pages being swapped.

View data

Clicking View data... opens a memory inspection dialog, allowing you to view the memory as BYTEs, WORDs, DWORDs or QWORDs.


Paragraphs

Navigation: The User Interface > The main display >

Paragraphs

 Return to chapter overview

The Paragraphs tab displays a tabular representation of all the memory in the target program. This is known as the paragraphs view.

The paragraphs view displays information about a process's virtual memory usage whilst the process is running. If there is no target program being monitored, the paragraphs view does not display any data.

For memory paragraphs where more than one memory status (or swap count etc) is present for the pages in the memory paragraph the display will list the aggregate values (if two pages have been swapped a total of 33 times (18 and 15 times each) the display will show a swap count of 33).

The data displayed is data per virtual memory paragraph (as defined by the operating system dwAllocationGranularity returned from Win32 API call GetSystemInfo()).

A memory paragraph is 64Kb.

Filtering

The displayed data can be filtered by Type and by Working Set.

Type

Filtering by type filters memory for the following types of memory:

·All. All types of memory.

·Committed. Committed memory.

·Reserved. Reserved memory.

·Free. Free memory.

·Private. Memory private to this application.

·Image. Executable files (EXE, DLL, etc).

·Mapped. Memory mapped files.

·Stack. Memory used for thread stacks.

·Shareable. Memory shared with other applications.

·Swapped. Memory swapped in/out of memory.

·Wasted. Memory allocated by VirtualAlloc() but not available to the application to use. What is wasted memory?

Working Set

Filtering by working set filters memory for the following working set criteria:

·All. Displays all memory.

·Working Set. Only displays memory that is in the working set.

·Not Working Set. Only displays memory that is not in the working set.

Sorting

Each column can be sorted by clicking the column header to move sorting to that column. Clicking the current column header again reverses the sort direction.

Context menu

A context menu is available to allow DLL inspection using PE File Browser, and to copy the DLL name to clipboard.

Viewing swap behaviour

To view virtual memory being swapped select the Swap column so that the sort arrow points downwards.

The display will show pages that have been swapped with the number of times they have been swapped shown in the Swap column.

When a page gets swapped it will be promoted at the top of the swap column for 1 second then be displayed back in it's regular sorted position.

When combined with the highlight swapped memory option on the Display Settings dialog you can very easily see pages being swapped.

View data

Clicking View data... opens a memory inspection dialog, allowing you to view the memory as BYTEs, WORDs, DWORDs or QWORDs.


Load Session

Navigation: The User Interface >

Load Session

 Return to chapter overview

Load Session allows you to load a previously saved virtual memory session that was saved using Save Session.

To load a session, choose File menu instructionStep Load Session...

A Microsoft file browser dialog is shown. Choose the session you wish to load.

When the session is loaded the displays will show the virtual memory information, dll names, thread names, page fault information that were in the session when it was saved.

File extensions

32 bit session files have extension vvm.

64 bit session files have extension vvm_x64.


Save Session

Navigation: The User Interface >

Save Session

 Return to chapter overview

Save Session allows you to save the current virtual memory information so that you can inspect it in the future or send it to a colleague for inspection.

To save a session, choose File menu instructionStep Save Session...

A Microsoft file browser dialog is shown. Choose where you'd like to save the session.

When the session is saved all the virtual memory information, dll names, thread names, page fault information that are in the session when are saved to the file.

You can keep this data for future reference, provide to a colleague for examination or send to a vendor to help debugging a product.

File extensions

32 bit session files have extension vvm.

64 bit session files have extension vvm_x64.


Load Minidump

Navigation: The User Interface >

Load Minidump

 Return to chapter overview

Load Minidump allows you to load a previously saved minidump that was saved using Save Minidump, or a minidump from any other source.

To load a minidump, choose File menu instructionStep Load Minidump...

A Microsoft file browser dialog is shown. Choose the minidump you wish to load.

When the minidump is loaded the displays will show the virtual memory information, dll names, thread names, that were in the minidump when it was created.

Page Faults

Minidumps don't contain any page fault related information - the page fault display will be empty when a minidump is loaded.


Save Minidump

Navigation: The User Interface >

Save Minidump

 Return to chapter overview

Save Minidump allows you to save a minidump based on the process being viewed by VM Validator.

To save a minidump, choose File menu instructionStep Save Minidump...

A Microsoft file browser dialog is shown. Choose where you'd like to save the minidump.

You can keep this minidump for future reference, provide to a colleague for examination (with Minidump Browser or a debugger) or send to a vendor to help debugging a product.


Settings

Navigation: The User Interface >

Settings

 Return to chapter overview

VM Validator settings allow you to control the colours of displayed data and units used to represent memory usage, and how symbols are fetched.

Settings are grouped into two sections, colours and symbols.

Opening the settings dialog

To view the settings dialog, choose File menu instructionStep Settings...

Or use the option on the Session Toolbar:

Keyboard shortcuts:

Using the settings dialog

The dialog has a scrolled list on the left hand side, grouping the topics. When a topic is clicked, its related controls are displayed on the right hand side.

The default display of the dialog is shown below with the first topic selected.


Symbol Paths

Navigation: The User Interface > Settings > Symbols >

Symbol Paths

 Return to chapter overview

The Symbol Paths tab allows you to specify which directories VM Validator should look in for source PDB files.

The default settings are shown below:

File locations

Sometimes the information VM Validator has access to consists of the file name, but not the directory.

When this happens VM Validator scans a set of directories that it knows about in order to find the file.

The options below allow you to specify those directories that should be searched for PDB files.

If a file can't be found, you'll get prompted for its location, but you can control this below as well.

Manually adding path type directories

Once you have chosen your path type you can modify the list of files for each path type in the following ways:

·Add instructionStep appends a row to the directory list instructionStep enter the directory path

Edit a directory path by double clicking the entry. The usual controls apply for removing list items:

·Remove instructionStep removes selected items from the list

·Remove all instructionStep clears the list

Alternatively, press [image] to delete selected items, and [image] + [image] to select all items in the list first.

Reset All - Resets all global settings, not just those on the current page.

Currently, the four checkbox items at the bottom of this page are not reset as part of the global settings.

Reset - Resets the settings on the current page.


Symbol Servers

Navigation: The User Interface > Settings > Symbols >

Symbol Servers

 Return to chapter overview

Show/Hide Hidden Text

The Symbol Servers tab allows you to specify Symbol Servers to retrieve symbols used in your application.

note You do not need to specify symbol servers if you do not wish to, and VM Validator will work correctly without them.

interactive Read on, or click on a setting in the picture below to find out more.

Symbol servers

Symbol servers are entirely optional, but are useful for obtaining symbols from a centralized company resource or for obtaining operating symbols from Microsoft.

The default symbol server is the Microsoft symbol server used for acquiring symbols about Microsoft's operating system DLLs. You may also wish to add some symbol servers for any software builds in your organisation.

A symbol server is defined by at least the following:

·the symbol server dll to be used to handle the symbol server interaction

·a directory location where symbol definitions are saved

·the server location - a url

Each symbol server can be enabled or disabled allowing you to keep multiple symbol server configurations available without constantly editing their definitions.

You can define up to four symbol servers and more than one can be enabled at a time.

Symbol Server Errors

Any symbol server entry shown in red indicates there is a problem with parts of the definition of that symbol server.

In the image shown above the symbol server at http://127.0.0.42:8000 cannot be reached. It is either offline or does not exist.

Managing symbol servers

·Add... instructionStep displays the symbol server dialog described below

·Remove instructionStep remove selected symbol server(s) in the list

·Remove All instructionStep remove all symbol servers

·Enable All instructionStep enables all symbol servers in the list

·Disable All instructionStep disables all symbol servers

You can also enable or disable an item in the list via the yellow check box at the left of each row.

To edit the details for a symbol server, just double click the entry in the list to show the symbol server dialog again.

Symbol server dialog

The dialog initially appears pre-populated with some default values and allows you to set up or edit the definition of a symbol server. Some of the default values can be changed.

·Enable Symbol Server instructionStep enable or disable this server

The following three entries must be set to enable the OK button and define the symbol server.

doc-collapse-icon OK button not enabled? The OK button will only be enabled when the following entries have a valid value:

- Symbol Server DLL names a dll present in the Memory Validator install directory.
- Symbol Store Directory has been specified and exists.
- Symbol Server URL has been specified (this value will not be checked for correctness).

·Symbol Server instructionStep select a predefined public symbol server or enter the URL of the symbol server you wish to use - the Microsoft server is initially set as the default

·Symbol Store Directory instructionStep enter or Browse to set the directory that will contain local copies of the downloaded symbols

The Symbol Server DLL is set chosen from the VM Validator directory, and then overridden by any matching DLLs found in the most recent Visual Studio installation that can be identified.

Reset All - Resets all global settings, not just those on the current page. This includes removing any symbol servers added.

Reset - Resets the settings on the current page. This includes removing any symbol servers added.


Starting your target program

Navigation: The User Interface >

Starting your target program

 Return to chapter overview

VM Validator provides a choice of 2 methods to start a target program and have VM Validator collect data from the target program about the program's execution.

·You can start a program in a specified directory and with as many command line arguments as you want.

·You can monitor an already running program.


Launching the program

Navigation: The User Interface > Starting your target program >

Launching the program

 Return to chapter overview

To start your program choose Start Application... on the Launch menu,

or click on the launch icon on the session toolbar.

Keyboard shortcuts:

The launch program dialog will be displayed.

The picture shows some already launched programs shown in the scrollable list. You can relaunch these programs by double clicking their entry in the list. Depending on what you want to do with your program you have a choice of launching the program.

Detailed program start (1)

1) Type in the program name in the Application field, or click the Browse... button to use a file browser to choose the program to launch.

2) Type in the program arguments in the Arguments field.

3) Type in the program directory in the Startup Directory field, or click the Dir... button to use a directory browser to choose the directory.

4) Click on the Go! button to launch the program.

Detailed program start (2)

1) Click on the program shown in the scrolled list that you want to start. The details for the program will appear in the Application, Arguments and Startup Directory fields.

2) Modify any of the Application, Arguments and Startup Directory fields as appropriate.

3) Click on the Go! button to launch the program.

Repeat program start

Double click on the program shown in the scrolled list. The program will be launched automatically.

VM Validator will start the program and inject the stub into the program. A progress dialog will be displayed whilst the stub is being injected into the program. The progress dialog lets you know what task it is performing during the injection sequence. When the stub is correctly installed in the target program the stub will establish communications with VM Validator.

If at any point you would like the fields reset, click on the Reset button.


Re-Launching the program

Navigation: The User Interface > Starting your target program >

Re-Launching the program

 Return to chapter overview

To re-start your program choose Re-Start Application... on the Launch menu,

or click on the relaunch icon on the session toolbar.

Keyboard shortcuts:

The application that was most recently launched is started.


Injecting into a running program

Navigation: The User Interface > Starting your target program >

Injecting into a running program

 Return to chapter overview

To inject the stub into an already running program choose Inject... on the Launch menu,

or click on the inject icon on the session toolbar.

Keyboard shortcuts:

The inject program dialog will be displayed.

Injecting into running process

1) Select the process to attach to.

2) Click on the Attach... button.

VM Validator will start the program and inject the stub into the program. A progress dialog will be displayed whilst the stub is being injected into the program. The progress dialog lets you know what task it is performing during the injection sequence. When the stub is correctly installed in the target program the stub will establish communications with VM Validator.

You can choose if you want to view system and/or user processes. If you need to refresh the list of active processes, click the Refresh button.


Waiting for a program

Navigation: The User Interface > Starting your target program >

Waiting for a program

 Return to chapter overview

To start your program choose Wait For Application... on the Launch menu,

Keyboard shortcuts:

The Wait for process dialog allows you to specify a process that when it starts, VM Validator will attach to and start collecting debug events.

·Application Path Policy instructionStep specify if the application you're going to wait for exists on a specific path or it's going to be created dynamically (and the path will therefore be unknown)

·Application Executable instructionStep type or Browse to set the application name to wait for

·Full path instructionStep shows the full path to the process executable in the list

·Image Name instructionStep shows the short program name without path

·Reset instructionStep clears the list

·Wait for Process instructionStep start waiting for the process to start. When the process starts VM Validator will attach to it and start collecting debug events.

·Stop Waiting instructionStep stops waiting for the process to start


Stopping your target program

Navigation: The User Interface >

Stopping your target program

 Return to chapter overview

Sometimes you will start a run of your target program and realise that you made a mistake, forgot to do something or need a different option enabled and need to restart the test from the beginning. You can stop the target program using Task Manager, using the debugger, or using VM Validator.

VM Validator provides you with a simple way of stopping the target program. Choose Abandon Application on the Launch Menu,

or click on the large red X on the session toolbar.

The target program is terminated using TerminateProcess(). When VM Validator has ended the target program, there will be no data to display.

Using VM Validator to stop the target program is usually quicker than using Task Manager or the debugger because the session is thrown away for you, rather than you having to terminate the current session.

Please note that if you wish your program to end in a controlled manner you should close your program yourself and should no use the Abandon Application option in VM Validator.


Closing VM Validator

Navigation: The User Interface >

Closing VM Validator

 Return to chapter overview

To finish working with VM Validator, choose Exit on the File menu.


Software Updates

Navigation: The User Interface >

Software Updates

 Return to chapter overview

The Software Updates menu controls how often software updates are downloaded.

If you've been notified of a new software release to VM Validator or just want to see if there's a new version, this feature makes it easy to update.

menu Software Updates menu instructionStep Check for software updates instructionStep checks for updates and shows the software update dialog if any exist

An internet connection is needed to be able to make contact with our servers.

note Before updating the software, close the help manual, and end any active session by closing target programs.

If no updates are available, you'll just see this message:

Software Update dialog

If a software update is available for VM Validator you'll see the software update dialog.

·Download and install instructionStep downloads the update, showing progress

Once the update has downloaded, VM Validator will close, run the installer, and restart.

You can stop the download at any time, if necessary.

·Don't download... instructionStep Doesn't download, but you'll be prompted for it again next time you start VM Validator

·Skip this version... instructionStep Doesn't download the update and doesn't bother you again until there's an even newer update

·Software update options... instructionStep edit the software update schedule

Problems downloading or installing?

If for whatever reason, automatic download and installation fails to complete:

·Download the latest installer manually from the software verify website.

Make some checks for possible scenarios where files may be locked by VM Validator as follows:

·Ensure VM Validator and its help manual is also closed

·Ensure any error dialogs from the previous installation are closed

You should now be ready to run the new version.

Software update schedule

VM Validator can automatically check to see if a new version of VM Validator is available for downloading.

menu Software Updates menu instructionStep Configure software updates instructionStep shows the software update schedule dialog

The update options are:

·never check for updates

·check daily (the default)

·check weekly

·check monthly

The most recent check for updates is shown at the bottom.

Software update directory

It’s important to be able to specify where software updates are downloaded to because of potential security risks that may arise from allowing the TMP directory to be executable. For example, to counteract security threats it's possible that account ownership permissions or antivirus software blocks program execution directly from the TMP directory.

The TMP directory is the default location but if for whatever reason you're not comfortable with that, you can specify your preferred download directory. This allows you to set permissions for TMP to deny execute privileges if you wish.

menu Software Updates menu instructionStep Set software update directory instructionStep shows the Software update download directory dialog

An invalid directory will show the path in red and will not be accepted until a valid folder is entered.

Example reasons for invalid directories include:

·the directory doesn't exist

·the directory doesn't have write privilege (update can't be downloaded)

·the directory doesn't have execute privilege (downloaded update can't be run)

note When modifying the download directory, you should ensure the directory will continue to be valid. Updates may no longer occur if the download location is later invalidated.

·Reset instructionStep reverts the download location to the user's TMP directory

The default location is c:\users\[username]\AppData\Local\Temp


View Memory Dialog

Navigation: The User Interface >

View Memory Dialog

 Return to chapter overview

The Inspect Memory dialog is shown below.

Address instructionStep an address inside the application to start viewing memory

Size instructionStep how many bytes to view

Specify an address inside the application and the number of bytes to view.

If the memory is readable, the memory will be displayed.

If the memory is executable, a disassembly view is also availble.


Search Memory Dialog

Navigation: The User Interface >

Search Memory Dialog

 Return to chapter overview

The Search Memory dialog is shown below.

You can search for text strings or you can search for byte sequences.

Search for a text string instructionStep type the string you wish to search for into the text box

Match case instructionStep select the check box if the string match should be case sensitive

Unicode instructionStep select the check box if the string match should be Unicode. If the check box is not selected the string match is ANSI

Search for bytes instructionStep type the bytes you wish to search for into the text box. A byte should be specified as a two digit hex value. Separate bytes with spaces

Search instructionStep perform the search. The progress of the search is shown on the progress bar, any matching search results are shown in the list.

Clear instructionStep clear the search results

A context menu on the search results provides a single option:

Clicking View data... opens a memory inspection dialog, allowing you to view the search results memory as BYTEs, WORDs, DWORDs or QWORDs.


Help

Navigation: The User Interface >

Help

 Return to chapter overview

VM Validator provides a help system to help you get the most from VM Validator.


Tip of the day

Navigation: The User Interface > Help >

Tip of the day

 Return to chapter overview

The tip of the day dialog provides helpful tips on how to get the most from VM Validator.


About VM Validator

Navigation: The User Interface > Help >

About VM Validator

 Return to chapter overview

Information about this version of VM Validator, copyright notices and user information.


Help Topics

Navigation: The User Interface > Help >

Help Topics

 Return to chapter overview

Display the online help for VM Validator.

PDF Help

PDF versions of the help file are available from https://www.softwareverify.com/helpPDFs.html.


Command Line Interface

Navigation: »No topics above this level«

Command Line Interface

 Return to chapter overview

VM Validator can be used from the command line as well as with the GUI.

The command line options allow you to launch an application that VM Validator will monitor, or to monitor an already running process.

Use in your own debugging work

One usage scenario which we have at Software Verify is to launch VM Validator to monitor a worker process we've just launched.

The -process processId option is very useful for this.

Command Line Switches before V7.00

Prior to V7.00, all command lines switches started with '/', not '-'.

We made this breaking change when we upgraded the command processor to be the same as the main Validator tools.


Alphabetic Reference

Navigation: Command Line Interface >

Alphabetic Reference

 Return to chapter overview

-allArgs

Specifies the arguments passed to the process being started. All remaining arguments on the command line are consumed by this command.

-args arguments to pass to process.

Example: -allArgs weebles wobble but they don't fall down

-arg

Specifies an argument to be passed to the process being started

/arg argument to pass to process. Enclose in quotes if any whitespace.

Examples:

-arg webbles

-arg "webbles wobble"

-arg webbles -arg wobble -arg but -arg "they don't fall down"

-directory

Specifies the startup directory for the process being started

-dir directory. Enclose in quotes if any whitespace.

Examples:

-dir e:\om\c\

-dir "e:\om\c path with spaces\"

-process

Specifies the process that will be monitored

-process processId

Example: -process 1344

-minidump

Specifies the minidump that will be loaded

-minidump path-to-minidump. Enclose in quotes if any whitespace.

Examples:

-minidump e:\om\c\test\release\test.dmp

-minidump "e:\om\c\test path with spaces\release\test.dmp"

-program

Specifies the executable that will be started

-program path-to-executable. Enclose in quotes if any whitespace.

Examples:

-program e:\om\c\test\release\test.exe

-program "e:\om\c\test path with spaces\release\test.exe"

If you specify the file without a path then:

·If you used -directory to set a startup directory then the filename in that directory is used if it exists

·Otherwise, the directories in the PATH environment variable are used to look for the filename

-session

Specifies the saved session that will be loaded. The session file was previously saved using Save Session.

-session path-to-session-file. Enclose in quotes if any whitespace.

Examples:

-session e:\om\c\test\release\test.vvm

-session "e:\om\c\test path with spaces\release\test.vvm"

File extensions

32 bit session files have extension vvm.

64 bit session files have extension vvm_x64.


Usage Reference

Navigation: Command Line Interface >

Usage Reference

 Return to chapter overview

Launch Application

Launch an application that will be monitored by VM Validator.

-allArgs

Specifies the arguments passed to the process being started. All remaining arguments on the command line are consumed by this command.

-args arguments to pass to process.

Example: -allArgs weebles wobble but they don't fall down

-arg

Specifies an argument to be passed to the process being started

-arg argument to pass to process. Enclose in quotes if any whitespace.

Examples:

-arg webbles

-arg "webbles wobble"

-arg webbles -arg wobble -arg but -arg "they don't fall down"

-dir

Specifies the startup directory for the process being started

-dir directory. Enclose in quotes if any whitespace.

Examples:

-dir e:\om\c\

-dir "e:\om\c path with spaces\"

-program

Specifies the executable that will be started

-program path-to-executable. Enclose in quotes if any whitespace.

Examples:

-program e:\om\c\test\release\test.exe

-program "e:\om\c\test path with spaces\release\test.exe"

If you specify the file without a path then:

·If you used -directory to set a startup directory then the filename in that directory is used if it exists

·Otherwise, the directories in the PATH environment variable are used to look for the filename

Monitor Application

Monitor an application that is already running.

-process

Specifies the process that will be monitored

-process processId

Example: -process 1344

Load a saved session

Load a session saved by VM Validator.

-session

Specifies the saved session that will be loaded. The session file was previously saved using Save Session.

-session path-to-session-file. Enclose in quotes if any whitespace.

Examples:

-session e:\om\c\test\release\test.vvm

-session "e:\om\c\test path with spaces\release\test.vvm"

File extensions

32 bit session files have extension vvm.

64 bit session files have extension vvm_x64.

Load a minidump

Load a minidump saved by VM Validator, Exception Tracer, Task Manager, Visual Studio.

-minidump

Specifies the minidump that will be loaded

-minidump path-to-minidump. Enclose in quotes if any whitespace.

Examples:

-minidump e:\om\c\test\release\test.dmp

-minidump "e:\om\c\test path with spaces\release\test.dmp"


Command Line Examples

Navigation: Command Line Interface >

Command Line Examples

 Return to chapter overview

This section provides some example command lines. For each example we'll break it down, argument by argument so that you can see how the command line works.

In all these examples the executable to run is vmValidator.exe. You will need to provide the full path to vmValidator.exe, or add the path to vmValidator install directory to your $PATH.

32 bit application monitoring: vmValidator.exe

64 bit application monitoring: vmValidator_x64.exe

Example 1

vmValidator.exe -program e:\om\c\test\release\test.exe -dir e:\om\c\test\release -args "-add 3 4"

-program e:\om\c\test\release\test.exe

Start application e:\om\c\test\release\test.exe

-dir e:\om\c\test\release

Start the application in e:\om\c\test\release

-args "-add 3 4"

Pass the arguments -add 3 4 to the application being launched

Example 2

vmValidator.exe -process 1344

-process 1344

Attach to process 1344 and monitor that process.

Example 3

Launching VM Validator from your own code to monitor a process you've just started. The arguments are the same as for Example 2.

int attachVMValidatorToRunningProcess(DWORD processId, // process id to monitor
const TCHAR *dir) // startup dir, can be NULL
{
CString vmValidator;
int bRet;

vmValidator = getVMValidatorPath(dir);
if (GetFileAttributes(vmValidator) != INVALID_FILE_ATTRIBUTES)
{
// only try to launch if exception tracer is a valid filename

TCHAR commandLine[1000];
STARTUPINFO stStartInfo;
PROCESS_INFORMATION stProcessInfo;

memset(&stStartInfo, 0, sizeof(STARTUPINFO));
memset(&stProcessInfo, 0, sizeof(PROCESS_INFORMATION));

stStartInfo.cb = sizeof(STARTUPINFO);

_stprintf_s(commandLine, sizeof(commandLine) / sizeof(commandLine[0]), _T("%s -process %u"), (const TCHAR *)vmValidator, processId);

bRet = CreateProcess(NULL,
commandLine,
NULL,
NULL,
FALSE,
0,
NULL,
dir,
&stStartInfo,
&stProcessInfo);
if (bRet)
{
WaitForInputIdle(stProcessInfo.hProcess, 10 * 1000); // 10 seconds

CloseHandle(stProcessInfo.hProcess);
CloseHandle(stProcessInfo.hThread);
}
}
else
bRet = FALSE;

return bRet;
}

Example 4

vmValidator.exe -session e:\crashes\2022_10_05\osc1.vvm

-session e:\crashes\2022_10_05\osc1.vvm

Load session file e:\crashes\2022_10_05\osc1.vvm

Example 5

vmValidator.exe -minidump e:\crashes\2022_10_05\crash34.dmp

-minidump e:\crashes\2022_10_05\crash34.dmp

Load minidump e:\crashes\2022_10_05\crash34.dmp


Frequently Asked Questions

Navigation: »No topics above this level«

Frequently Asked Questions

 Return to chapter overview

This section lists the commonly asked questions about VM Validator.


I have an idea for a feature, can it be added to VM Validator?

Navigation: Frequently Asked Questions >

I have an idea for a feature, can it be added to VM Validator?

 Return to chapter overview

We have tried to add as many features to VM Validator that we thought would be useful to the potential users of VM Validator. In fact every feature in VM Validator has been used to solve problems and bugs on consulting work carried out for our customers and on internal projects at Software Verify Limited. We know the features we have put in the product are useful.

However it is possible we have overlooked a feature that you may find very useful. We will be pleased to consider all ideas for new features to VM Validator. Please contact us at the address provided on the contact page.

A Quake III mode, however much fun, is not useful in solving bugs. Sorry guys!


What file extensions does VM Validator use for itself?

Navigation: Frequently Asked Questions >

What file extensions does VM Validator use for itself?

 Return to chapter overview

VM Validator stores all of the configuration data it needs in the registry.

VM Validator does not use an specific file extensions.


What is Wasted Memory?

Navigation: Frequently Asked Questions >

What is Wasted Memory?

 Return to chapter overview

Wasted memory is a term we use to identify memory that is wasted when memory allocations are made with VirtualAlloc() that are smaller than the Windows operating system allocation granularity (which is typically 64KB).

This is best explained with an example;

ptr = VirtualAlloc(NULL, 24 * 1024, MEM_COMMIT, PAGE_READWRITE);

For example if you use VirtualAlloc() to commit 24KB of memory, VirtualAlloc() will set aside 64KB of memory, and then commit 24KB of that 64KB memory. There will be two chunks of memory as a result:

1 | 24KB | Committed | PAGE_READWRITE
2 | 40KB | Free | PAGE_NO_ACCESS

The first block is pointed to by the pointer returned from VirtualAlloc().

The second block isn't pointed to by anything. You can calculate where it is if you know about the allocation and the size of the allocation.

But in most cases, for this type of allocation, the second block is there implicitly - the caller probably doesn't realise they've used 64KB of memory to make that 24KB allocation.

How to prevent wasted memory?

The best way to prevent wasted memory is to use a different allocator (HeapAlloc, malloc, new, etc) to allocate the memory you need, and if you need to change the memory protection on that memory then call VirtualProtect() to change the memory protection on that memory (bear in mind this works on 4KB blocks at a minimum, aligned on 4KB page boundaries - for x86, x64 machines).

Alternatively you would write a simple memory allocator that uses VirtualAlloc() and VirtualFree() as it's backing store. You allocator would allocate when necessary using VirtualAlloc() and then subdivide those blocks to pass back suitable locations inside the larger blocks, thus avoiding the memory wastage.


Display Settings

Navigation: »No topics above this level«

Display Settings

 Return to chapter overview

VM Validator allows a fine degree of control of which data is displayed. This control is provided by some global settings which affect all displays on VM Validator. In addition to the global settings each of the main display windows has its own local controls. This section describes the global settings available from the display settings dialog.

To view the display settings dialog click on the toolbox icon on the session toolbar.

The settings dialog is displayed.

Colours

The Settings dialog allows you to specify the colours that will be used to represent each type of data item collected by VM Validator.

For each colour there are two ways of specifying the colour to use.

·Select a named colour from the combo box.

·Click on the button labeled ... to edit the colour using the standard Microsoft® colour choosing dialog.

The Reset button resets the colour selections and the check boxes to the default options.


Colours

Navigation: »No topics above this level«

Colours

 Return to chapter overview

The Colours tab lets you choose the colours used to display each type of data item collected by VM Validator.

The default colours are shown below:

Changing display colours

For each colour you can choose a predefined colour or make your own:

·Use the drop-down list colour-combo instructionStep pick one of 16 predefined colours below

·Click the colour-dotdotdot-button button instructionStep edit the colour using the standard colour dialog:

Reset All - Resets all global settings, not just those on the current page.

Reset - Resets the settings on the current page.