VSInstr

  • Article

VSInstr tool is used to instrument binaries. It is invoked by using the following syntax:

VSInstr [/U] filename [/options]

The following table describes VSInstr tool options:

Options Description

HELP or ?

Displays help.

@filename

Response file should have one command option per line. Do not use quotes.

OUTPUTPATH:path

Destination directory for the instrumented image. If an output path is not specified, the original binary is renamed by appending "Orig" to the file name in the same directory, and a copy of the binary is instrumented.

CONTROL:{THREAD|PROCESS|GLOBAL}

CONTROL option is used to specify the profiling level of the following data collection control functions:

StartProfile

StopProfile

SuspendProfile

ResumeProfile

THREAD - specifies thread-level data collection control functions. Profiling is started or stopped only for the current thread. The profiling state of other threads is not affected. The default is thread.

PROCESS - specifies process-level profiling data collection control functions. Profiling starts or stops for all threads in the current process. The profiling state of other processes is not affected.

GLOBAL - specifies global-level (cross-process) data collection control functions.

An error occurs if you do not specify the profiling level.

START:{INSIDE|OUTSIDE},funcname

The START option is used to limit data collection to the target function and child functions called by that function.

INSIDE - Inserts the StartProfile function immediately after the entry to the target function. Inserts the StopProfile function immediately before each return in the target function.

OUTSIDE - Inserts the StartProfile function immediately before each call to the target function. Inserts the StopProfile function immediately after each call to the target function.

funcname - the name of the target function.

SUSPEND:{INSIDE|OUTSIDE},funcname

The SUSPEND option is used to exclude data collection for the target function and child functions called by the function.

INSIDE - Inserts the SuspendProfile function immediately after the entry to the target function. Inserts the ResumeProfile function immediately before each return in the target function.

OUTSIDE - Inserts the SuspendProfile function immediately before the entry to the target function. Inserts the ResumeProfile function immediately after the exit from the target function.

funcname - name of the target function.

If the target function contains a StartProfile function, the SuspendProfile function is inserted before it. If the target function contains a StopProfile function, the ResumeProfile function is inserted after it.

STARTONLY:{BEFORE|AFTER|TOP|BOTTOM},funcname

The STARTONLY option is used to begin data collection during a profiling run. It inserts the StartProfile API function at the specified location.

BEFORE - immediately before the target function entry.

AFTER - immediately after the target function exit.

TOP - immediately after the target function entry.

BOTTOM - immediately before each return in the target function.

funcname - name of the target function.

STOPONLY:{BEFORE|AFTER|TOP|BOTTOM},funcname

The STOPONLY option is used to halt data collection during a profiling run. It inserts the StopProfile function at the specified location.

BEFORE - immediately before the target function entry.

AFTER - immediately after the target function exit.

TOP - immediately after the target function entry.

BOTTOM - immediately before each return in the target function.

funcname - name of the target function.

SUSPENDONLY:{BEFORE|AFTER|TOP|BOTTOM},funcname

The SUSPENDONLY option is used to halt data collection during a profiling run. It inserts the SuspendProfile API at the specified location.

BEFORE - immediately before the target function entry.

AFTER - immediately after the target function exit.

TOP - immediately after the target function entry.

BOTTOM - immediately before each return in the target function.

funcname - name of the target function.

If the target function contains a StartProfile function, the SuspendProfile function is inserted before it.

RESUMEONLY:{BEFORE|AFTER|TOP|BOTTOM},funcname

The RESUMEONLY option is used to begin or resume data collection during a profiling run.

It is usually used to start profiling after a SUSPENDONLY option has stopped profiling. It inserts a ResumeProfile API at the specified location.

BEFORE - immediately before the target function entry.

AFTER - immediately after the target function exit.

TOP - immediately after the target function entry.

BOTTOM - immediately before each return in the target function.

funcname - name of the target function.

If the target function contains a StopProfile function, the ResumeProfile function is inserted after it.

EXCLUDE:funcspec

The EXCLUDE option specifies a function specification to exclude from instrumentation by probes. It is useful when profiling probe insertion in a function causes unpredictable or unwanted results.

Do not use EXCLUDE and INCLUDE options that refer to functions in the same binary.

You can specify multiple function specification with separate EXCLUDE options.

funcspec is a defined as:

[namespace<separator1>] [class<separator2>]function

<separator1> is :: for native code, and . for managed code.

<separator2> is always ::

EXCLUDE option is supported with code coverage.

To exclude all functions in a namespace use the wildcard character:

MyNamespace::*

INCLUDE:funcspec

The INCLUDE option specifies a function specification in a binary to instrument with probes. All other functions in the binaries are not instrumented.

You can specify multiple function specifications with separate INCLUDE options.

Do not use INCLUDE and EXCLUDE options that refer to functions in the same binary.

INCLUDE option is not supported with code coverage.

funcspec is a defined as:

[namespace<separator1>] [class<separator2>]function

<separator1> is :: for native code, and . for managed code.

<separator2> is always ::

MARK:{BEFORE|AFTER|TOP|BOTTOM},funcname,markid

The MARK option inserts a MarkProfile API function at the entry to or the exit from the target function. The MarkProfile API inserts a profile mark (an identifier used to delimit the data in reports) that you can use to identify the start or end of a data range in the .vsp report file.

BEFORE - Immediately before the target function entry.

AFTER - Immediately after the target function exit.

TOP - Immediately after the target function entry.

BOTTOM - Immediately before each return in the target function.

funcname - Name of the target function

Markid - A positive integer (long) to use as the identifier of the profile mark.

COVERAGE

The COVERAGE option performs coverage instrumentation. It can be combined with the OUTPUTPATH option.

VERBOSE

The VERBOSE option is used to view detailed information about the instrumentation process.

NOWARN[:[Message Number[;Message Number]]]

The NOWARN option is used to suppress all or specific warnings.

Message Number - the warning number. If Message Number is omitted, all warnings are suppressed.

For more information, see VSInstr warnings in the See Also section.

DUMPFUNCS

The DUMPFUNCS option displays the functions within the specified image - no instrumentation is performed.

U

The U option writes the redirected console output as Unicode - must be first option specified.

See Also

Reference

VSPerfMon
VSPerfCmd
VSPerfReport
VSInstr Warnings
Performance Report Column Definition