IP Filter Configuration

When tracing the target software execution, the Intel® PT hardware records every event. To focus on information of your interest, you can use IP filtering. Using this feature, you can specify address ranges where the software execution is traced.

For example, to trace the execution of a specific function only, you can program the hardware with the address range containing the function. The execution trace is only recorded for instructions executed within that range. For instruction executions outside of that range, execution trace is not recorded.

IP filters facilitate working with the Intel® Debug Extensions for WinDbg* for Intel® Processor Trace, because the debug agent executes all the actions (for example, run-control like stepping, reading registers and memory) on behalf of WinDbg* on the target and communicates regularly with WinDbg*. Usually, tracing all those actions of the debug agent is not desired. Using IP filters, the Intel® PT hardware only records the code execution of interest.

The most basic form of installing an IP filter is to use the !setipfilter command to specify an address range where code execution is traced. For convenience, the extension also provides commands to set a filter based on a function name with !setipfilterfunction or a module name with !setipfiltermodule, where the extension automatically looks up the address range of that function or module.

Displaying the IP Filter Configuration

!showipfilters [/all] [/here]
  /all - Also show filters that are currently unused
  /here - Show IP filter configuration for the currently selected processor only

Setting / Adding a New IP Filter

Configure Intel(R) Processor Trace IP filtering using a memory range
!setipfilter [/stop] [/here] [/id <expr>] <start> <end>
  <start> - Start address of filter region
  <end> - End address of filter region
  /stop - Configure for trace-stop
  /id <expr> - ID of filter to overwrite
  /here - Set IP filter configuration on the currently selected processor only

Configure Intel(R) Processor Trace IP filtering using a function symbol
!setipfilterfunction [/stop] [/here] [/id <expr>] <name>
  <name> - Name of function to filter on
  /stop - Configure for trace-stop
  /id <expr> - ID of filter to overwrite
  /here - Set IP filter configuration on the currently selected processor only

Configure (R) Processor Trace IP filtering using a module name
!setipfiltermodule [/tracestop] [/here] [/id <expr>] <name>
  <name> - Name of module to filter on
  /stop - Configure for trace-stop
  /id <expr> - ID of filter to overwrite
  /here - Set IP filter configuration on the currently selected processor only

Deleting an IP Filter – Counterparts to Setipfilter* and Additionally Deleting by ID or Simply All IP Filters

Delete Intel(R) Processor Trace IP filter region based on an address range
!delipfilter [/here] <start> <end>
  <start> - Start address of filter region
  <end> - End address of filter region
  /here - Delete IP filter on the currently selected processor only

Delete Intel(R) Processor Trace IP filter region based on a function symbol
!delipfilterfunction [/here] <name>
  <name> - Name of function
  /here - Delete IP filter on the currently selected processor only

Delete Intel(R) Processor Trace IP filter region based on a module name
!delipfiltermodule [/here] <name>
  <name> - Name of module
  /here - Delete IP filter on the currently selected processor only

Delete Intel(R) Processor Trace IP filter region based on its ID
!delipfilterid [/here] <expr>
  <expr> - Number/ID of filter region to delete
  /here - Delete IP filter on the currently selected processor only

Delete all Intel(R) Processor Trace IP filter regions
!delipfilterall [/here]
  /here - Delete IP filter on the currently selected processor only

CR3 Filter Configuration

The Intel® PT hardware also provides CR3 filtering. CR3 filtering is based on address spaces. This means that the execution trace is only recorded if the CR3 register value matches the CR3 filter value. Since CR3 values can be considered as process identifiers, you use this feature to only record code executed in the context of a certain process.

Configure Intel® PT CR3 filtering as follows:

!setcr3filter [/here] <expr>

where

<expr>

- CR3 filtering value

/here

- Option to modify CR3 filter configuration on the currently selected processor only

Disable Intel® PT CR3 filtering as follows:

!delcr3filter [/here]

where

/here

- Option to disable CR3 filtering on the currently selected processor only

For more complete information about compiler optimizations, see our Optimization Notice.