A common grammar is used for an expression defining a filter and an expression used to compute a memory object index.
The grammar specifies an expression as a combination of operators and operands or keywords. For filters, if the expression evaluates to true, the packet is included; if the expression evaluates to false, the packet is excluded. For memory objects or index objects, the expression is evaluated to an index that defines the particular memory object or index object referenced in the packet.
Operands in an expression can be labels, constants, or fields within a data record, as listed with the describe command. The operands include THRID, LWPID, CPUID , USTACK, XSTACK, MSTACK, LEAF, VIRTPC, PHYSPC, VADDR, PADDR, DOBJ, TSTAMP, SAMPLE, EXPID, PID, or the name of a memory object. Operand names are case-insensitive.
USTACK, XSTACK, and MSTACK represent the function call stacks in user view, expert view, and machine view, respectively.
VIRTPC, PHYSPC, VADDR, and PADDR are non-zero only when “+” is specified for Hardware-counter-profiling or clock-profiling. Furthermore, VADDR is less than 256 when the real virtual address could not be determined. PADDR is zero if VADDR could not be determined, or if the virtual address could not be mapped to a physical address. Likewise, VIRTPC is zero if backtracking failed or was not requested, and PHYSPC is zero if either VIRTPC is zero, or the VIRTPC could not be mapped to a physical address.
Operators include the usual logical operators and arithmetic (including shift) operators, in C notation, with C precedence rules, and an operator for determining whether an element is in a set (IN) or whether any or all of a set of elements is contained in a set (SOME IN or IN, respectively). An additional operator ORDERED IN determines whether all elements from the left operand appear in the same sequence in the right operand. Note that the IN operator requires all elements from the left operand to appear in the right operand but does not enforce the order.
If-then-else constructs are specified as in C, with the ? and : operators. Use parentheses to ensure proper parsing of all expressions. On the er_print command lines, the expression cannot be split across lines. In scripts or on the command line, the expression must be inside double quotes if it contains blanks.
Filter expressions evaluate to a Boolean value, true if the packet should be included, and false if it should not be included. Thread, CPU, experiment-id, process-pid, and sample filtering are based on a relational expression between the appropriate keyword and an integer, or using the IN operator and a comma-separated list of integers.
Time-filtering is used by specifying one or more relational expressions between TSTAMP and a time, given in integer nanoseconds from the start of the experiment whose packets are being processed. Times for samples can be obtained using the overview command. Times in the overview command are given in seconds, and must be converted to nanoseconds for time-filtering. Times can also be obtained from the Timeline display in Performance Analyzer.
Function filtering can be based either on the leaf function, or on any function in the stack. Filtering by leaf function is specified by a relational expression between the LEAF keyword and an integer function ID, or using the IN operator and the construct FNAME("regexp"), where regexp is a regular expression as specified on the regexp(5) man page. The entire name of the function, as given by the current setting of name, must match.
Filtering based on any function in the call stack is specified by determining if any function in the construct FNAME("regexp") is in the array of functions represented by the keyword USTACK using the expression (FNAME("myfunc") SOME IN USTACK). FNAME can also be used to filter the machine view of the stack (MSTACK) and the expert view (XSTACK) in the same way.
Data object filtering is analogous to stack function filtering, using the DOBJ keyword and the construct DNAME("regexp") enclosed in parentheses.
Memory object filtering is specified using the name of the memory object, as shown in the mobj_list command, and the integer index of the object, or the indices of a set of objects. (The <Unknown> memory object has index -1.)
Index object filtering is specified using the name of the index object, as shown in the indxobj_list command, and the integer index of the object, or the indices of a set of objects. (The <Unknown> index object has index -1.)
Data object filtering and memory object filtering are meaningful only for hardware counter packets with dataspace data; all other packets are excluded under such filtering.
Direct filtering of virtual addresses or physical addresses is specified with a relational expression between VADDR or PADDR, and the address.
Memory object definitions (see mobj_define mobj-type index-exp) use an expression that evaluates to an integer index, using either the VADDR keyword or PADDR keyword. The definitions are applicable only to hardware counter packets for memory counters and dataspace data. The expression should return an integer, or -1 for the <Unknown> memory object.
Index object definitions (see indxobj_define indxobj-type index-exp) use an expression that evaluates to an integer index. The expression should return an integer, or -1 for the <Unknown> index object.
This section shows examples of filter expressions that can be used with the er_print -filters command, and in the Advanced Customer Filters dialog box.
With the er_print -filters command, the filter expression is enclosed in single quotes, similar to the following example:
er_print -filters 'FNAME("myfunc") SOME IN USTACK' -functions test.1.er
Example 4 Filter Functions by Name and Stack
To filter functions named myfunc from the user function stack:
FNAME("myfunc") SOME IN USTACK
Example 5 Filter Events by Thread and CPUTo see events from thread 1 when it was running on CPU 2 only:
THRID == 1 && CPUID == 2
Example 6 Filter Events by Index ObjectIf an index object, THRCPU, is defined as "CPUID<<16|THRID", the following filter is equivalent to the filter to see events from thread 1 when running on CPU 2:
THRCPU == 0x10002
Example 7 Filter Events Occurring in a Specified Time PeriodTo filter events from experiment 2 that occurred during the period between second 5 and second 9:
EXPID==2 && TSTAMP >= 5000000000 && TSTAMP < 9000000000
Example 8 Filter Events From a Particular Java ClassTo filter events that have any method from a particular Java class in the stack (in user view mode):
FNAME("myClass.*") SOME IN USTACK
Example 9 Filter Events by Internal Function ID and Call SequenceIf function IDs are known (as shown in Performance Analyzer), to filter events that contain a particular call sequence in the machine call stack:
(314,272) ORDERED IN MSTACK
Example 10 Filter Events by State or DurationIf the describe command lists the following properties for a clock profiling experiment:
MSTATE UINT32 Thread state NTICK UINT32 Duration
you can select events that are in a particular state using the following filter:
MSTATE == 1
Alternatively, you can use the following filter to select events that are in a particular state and whose duration is longer than 1 clock tick:
MSTATE == 1 && NTICK > 1