IP Filter Configuration

Intel® System Debugger User Guide

ID 648476

Date 06/13/2024

Version

Confidential

When tracing the target software execution, the Intel(R) Processor Trace (Intel(R) 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(R) Debug Extensions for WinDbg* for Intel(R) PT, 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(R) 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

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(R) Processor Trace (Intel(R) PT) hardware also provides CR3 filtering, which 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(R) 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(R) PT CR3 filtering as follows:

!delcr3filter [/here]

where:

/here: Option to disable CR3 filtering on the currently selected processor only