3.2 Using Context Queries

Simics implements a query-based system to specify subsets of contexts. The queries specify context properties and what values they must have in order to match. In addition, a query can filter based on a context's ancestors in the context hierarchy.

3.2.1 About Context Queries

A query consists of a sequence of parts separated by a slash character (/). This sequence specifies a path through the context tree.

A context matches the query if the last part of the query matches the properties of the context, and the parent of the context matches the query excluding the last part. The properties of a context match a part if each property specified in the part matches the property of the same name in the context, or if the name of the context matches the string specified in the part.

The contexts are assumed to be placed in a tree. Each context has zero or one parent. If it has zero parents it is a child of the root of the tree.

There are also two wild cards. The part * matches any context. The part ** matches any sequence of contexts. If the query starts with a /, the first part of the query must match a child of the root of the context tree.

3.2.2 Context Query Syntax

query = [ "/" ], { part, "/" }, part ;
    part = string | "*" | "**" | properties ;
    properties = property, { ",", property } ;
    property = string, "=", value ;
    value = string | number | boolean ;
    string = quoted string | symbol ;
    quoted string = '"', {any-character - ('"' | '\')
                                 | ('\', ('"' | '\'))}, '"' ;
    symbol = letter, { letter | digit } ;
    number = digit, { digit } ;
    boolean = "true" | "false" ;
    letter = ? A-Z, a-z or _ ? ;
    digit = ? 0-9 ? ;
    any-character = ? any character ? ;

3.2.3 Examples

This section illustrates the syntax with some examples, and what a user might mean when providing such a query:

• httpd: matches all contexts named "httpd".
• pid=4711: matches any context with a property pid, which has the value 4711.
• /server/**: matches all contexts that are descendants of the top level context named "server".
• "Linux 2.6.14"/Kernel/*: matches all kernel processes in operating systems named "Linux 2.6.14".
• pid=4711/*: matches all threads in processes with the pid 4711.
• /client/**/"rule30.elf": matches the context for program rule30.elf running on the machine called client.
• /server/**/HasState=true: matches all threads that are descendants of the context "server". Contexts with no state, typically container, do not match the query.

3.2.4 Context Queries in the Command Line Interface

The Simics debugger is built on top of the target connection framework (TCF) technology, which introduces the context query concept. The above text describes the standard TCF syntax for context queries. It is very similar in principle to the process trackers node path concept.

To make context queries work better with the CLI syntax, and look closer to node paths, the syntax of TCF context queries in the command line has been modified. The difference is minor, as it impacts only the double quote character (") used to quote a string with non-alpha-numeric characters. In the command line you must either escape this character or use the single quote character (') instead.

Originally the context query to match a context named rule30.elf is written name="rule30.elf". The corresponding node path is name='rule30.elf'. So for instance in the command line you will use:

simics> add-symbol-file context-query = "name='rule30.elf'"
or
simics> add-symbol-file context-query = "name=\"rule30.elf\""

Another example for selecting a cpu context named cpu[0], in Simics command line, the query is written:

simics> break-location 0xfff00000 context-query = "'cpu[0]'"
or
simics> break-location 0xfff00000 context-query = "\"cpu[0]\""