A structure containing breakpoint filter parameters.
uint16_t MatchFlags
MatchFlags is a bitmask whose individual bits represent specific breakpoint parameters. When a breakpoint occurs, its parameters are checked against the bitmask. If the relevant bit is set and the corresponding parameter matches, the breakpoint stops target execution. The currently defined values are:
| PS_FILTER_FLAG_MATCH_PAGE_TABLE0x0001 | Stop target execution if the breakpoint is hit while the current CR3 value equals to the PageTableAddress filter field. This is useful when you need to break only in a specific process. Typically, OS processes have isolated address spaces. An address space is uniquely defined by its page-table root in the CR3 register. |
| PS_FILTER_FLAG_MATCH_LINEAR_ADDRESS0x0002 | Stop target execution if a breakpoint was hit when the current RIP value equals the Address filter field. This is useful when a module is mapped at several locations in the linear address space. |
| PS_FILTER_FLAG_MATCH_FS_BASE0x0004 | Stop target execution if a breakpoint was hit when the current FS segment base value quals the FsBase filter field. This is useful when you need to break in a specific execution thread. Typically, operating systems use the FS or GS segment base as a thread-local storage base. |
| PS_FILTER_FLAG_MATCH_GS_BASE0x0008 | Stop target execution if a breakpoint was hit when the current GS segment base value quals the GsBase filter field. Useful if we need to break into a specific execution thread. Typically OSes use FS or GS segment base as a thread local storage base. |
| PS_FILTER_FLAG_MATCH_SELECTOR0x0010 | Stop target execution if a breakpoint was hit when the current CS segment selector value quals the Selector filter field. This is useful for 16-bit operating systems that use segmentation with aliasing. |
uint16_t SkipFlags
SkipFlags is a bitmask whose individual bits represent specific breakpoint parameters. When a breakpoint occurs, its parameters are checked against this bitmask. If the relevant bit is set and the corresponding parameter matches, the breakpoint does not stop target execution. The currently defined values are:
| PS_FILTER_FLAG_SKIP_PAGE_TABLE0x0001 | Continue target execution if the breakpoint is hit while the current CR3 value equals to the PageTableAddress filter field. This is useful when you need to break only in a specific process. Typically, OS processes have isolated address spaces. An address space is uniquely defined by its page-table root in the CR3 register. |
| PS_FILTER_FLAG_SKIP_LINEAR_ADDRESS0x0002 | Continue target execution if a breakpoint was hit when the current RIP value equals the Address filter field. This is useful when a module is mapped at several locations in the linear address space. |
| PS_FILTER_FLAG_SKIP_FS_BASE0x0004 | Continue target execution if a breakpoint was hit when the current FS segment base value quals the FsBase filter field. This is useful when you need to break in a specific execution thread. Typically, operating systems use the FS or GS segment base as a thread-local storage base. |
| PS_FILTER_FLAG_SKIP_GS_BASE0x0008 | Continue target execution if a breakpoint was hit when the current GS segment base value quals the GsBase filter field. This is useful when you need to break in a specific execution thread. Typically, operating systems use the FS or GS segment base as a thread-local storage base. |
| PS_FILTER_FLAG_SKIP_SELECTOR0x0010 | Continue target execution if a breakpoint was hit when the current CS segment selector value quals the Selector filter field. This is useful for 16-bit operating systems that use segmentation with aliasing. |
uint16_t Selector
Specifies the CS segment selector value used for filtering.
uint64_t PageTableAddress
Specifies the page-table root value used for filtering.
uint64_t Address
Specifies the logical address value used for filtering.
uint64_t FsBase
Specifies the FS segment base value used for filtering.
uint64_t GsBase
Specifies the GS segment base value used for filtering.
The PulseDbg host sets breakpoints using guest physical addresses. Because of that, shared executable modules trigger breakpoints in every process, regardless of the current address space. To make breakpoints more flexible, a set of filters may be attached to a breakpoint. For example, to make a breakpoint trigger only in a specific process, we can set the MatchFlags to PS_FILTER_FLAG_MATCH_PAGE_TABLE and PageTableAddress to its page-table root address derived from the CR3 value associated with that process’s virtual address space. After doing so, the breakpoint will only be triggered if the current CR3 register matches the the corresponding filter value. Other triggers for the same breakpoint will not stop the execution of the target - they will be effectively filtered out.
SkipFlags uses the inverse logic for breakpoint filtering. It ignores breakpoint hits that match the specified flags and their corresponding filter values. The breakpoint stops target execution for all other hits.