The optional probe argument specifies a specific probe to read. When this is used, only one probe is read, displayed and returned. In all other cases a table is shown and a list of values is being returned, even if there is only one probe actually read.
Without any arguments or switches, all probes in the system are being read and shown.
Filtering.
To reduce the number of probes shown, there are a large number of command arguments/switches that filters out the non-matching probes. Many filters can be used in the same command invocation.
The probe-kind filter specifies which probe-kinds to include. This can be the full name of a specific probe kind, or the string can be a partial kind, for example specifying cpu.exec_modes. would include all probe-kinds starting with this string.
The substr argument filter allows only probes which has a specific string in the probe name to be displayed.
To find probes in a particular object the object argument can be used, only showing the probes on that specific object.
In combination with the object argument the -recursive switch can be used to look at the probes that exists beneath the specified object, in the object hierarchy. This allows zooming in on the probes within a particular subsystem of the entire target system.
Each probe might be assigned with a number of categories represented as strings that describe some property of what they measure. The categories filter can be used to only include the probes which have all of the requested categories included.
Probes can returned different types when read. The probe-types argument allows only certain types to be shown.
Some probes requires subscription before they can return any value. The -active switch automatically discards the probes that cannot currently be read. For these to be shown the <probes>.subscribe command should be used first.
Controlling value output format.
By default, the value displayed, and returned, is formatted as a string, according to how the probe's suggested human-readable format.
To get the actual (non-formatted) values, the -values switch can be used.
If -raw-values is given the raw representation of the probe will be printed, i.e., for fraction probes the numerator and the denominator will be printed separately and for histogram probes the list of keys together with the corresponding value will printed. If the command is used in an expression these values will also be returned in CLI lists. Below are the generic table arguments. The max argument selects how many rows that should be printed, default is 40. Use max = 0 to get the entire table.
The max-table-width argument specifies how many characters the table width is allowed to be. Default is zero, which means that Simics will get the current width of the terminal where the command is executed. Tables which initially become wider than this, will be shrunk down by splitting cells to multiple lines.
The sort-on-column argument allows the table to be sorted on certain column names, not all columns are allowed to be sorted on. If sort-on-column is not specified, the table may be sorted on a the column it finds most interesting or present the table unsorted.
The sort-order argument allows the sort-order to be changed, so either high values are listed first ('descending') or low values are listed first ('ascending'). If not selected, the default order is selected by the column which is being sorted upon.
The float-decimals argument can be used to print out more or less number of decimals on the floating point numbers in the table.
The border-style argument specifies how the borders for the table should look like. Possible values are borderless, ascii, thin and thick. Default is 'thin'.
The -show-all-columns flag possibly displays some hidden columns. Some autogenerated columns associated with another column are normally only displayed if that column is used for sorting. This flag enables all columns to be showed in the same table.
The -ignore-column-widths flag formats the table columns to be the max widths of the contents in the displayed rows. Consequently ignoring any explicitly set widths set in the columns.
The -verbose flag displays additional information of the table such as a description on what each column represents.
By default, an additional 'row' column is added to the far left, displaying each row's number. This can be suppressed with the -no-row-column flag. Note that footers uses the row column for the footer-names. Consequently, if the row column is removed, and footers are printed, another empty column is created instead.
Any columns have data which should be calculated and displayed in the footer, this will be printed by default. The footer can be suppressed with the -no-footers flag.