Probes should be used for user observable values and are not intended for model to model communication.
The properties() method is typically called once for each tool
or use-case to get information about the probe. It should return a key/value
attr_value_t list, i.e., list of lists of two values, with
probe specific properties. The first value of the inner list represents the
property key as an Sim_Val_Integer using the enum probe_key_t
type, and the second value is a key specific data item described below. The
probe_key_t is defined as:
typedef enum {
Probe_Key_Name = 0, /* Identifier of the probe */
Probe_Key_Type = 1, /* string, any of: {
"int", "float, "fraction",
"histogram", "int128", "string"
} */
Probe_Key_Categories = 2, /* list of strings */
Probe_Key_Cause_Slowdown = 3, /* bool */
Probe_Key_Owner_Object = 4, /* object: owner object */
Probe_Key_Display_Name = 5, /* string: short narrow name */
Probe_Key_Description = 6, /* string */
Probe_Key_Float_Percent = 7,
Probe_Key_Float_Decimals = 8,
Probe_Key_Metric_Prefix = 9,
Probe_Key_Unit = 10,
Probe_Key_Binary_Prefix = 11,
Probe_Key_Time_Format = 12,
Probe_Key_Width = 13,
Probe_Key_Value_Notifier = 14,
Probe_Key_Global_Sum = 15, /* [list of properties] OBSOLETE */
Probe_Key_Cell_Sum = 16, /* [list of properties] OBSOLETE */
Probe_Key_Aggregates = 17, /* Defines new probes which aggregate
over this probe:
[list of [list properties]]
Invalid for Type: "string"
*/
Probe_Key_Aggregate_Scope = 18, /* Aggregate over all probes in the
cells or all probes in the system.
String and of ["global", "cell"] */
Probe_Key_Aggregate_Function = 19, /* How the aggregation should be
done:
"sum",
"weighted-arith-mean",
- only fractions
*/
Probe_Key_Definition = 20, /* string: how the probe is
calculated */
} probe_key_t;
The value() method should return the data for the probe as an
attr_value_t in accordance of how the property type has been
defined. This method is called each time a tool/user wants to read the latest
probe value.
The property keys are describes here as follows:
Probe_Key_NameSome examples, include: cpu.cycles, cpu.exec_mode.jit_steps, dev.io_access_count, cell.steps, host.swap.used, and sim.slowdown.
Several objects implementing this interface can use the same probe name, for similar probe values. The global identifier for a probe is a string containing the object name then a colon and then the probe name, e.g., "board.mb.cpu0.cpu[0][0]:cpu.cycles".
Probe_Key_Display_NameProbe_Key_Typeattr_value_t value that should be returned by
the value method for these types are as follows:
For the int type, an attr_value_t of type Sim_Val_Integer
should be returned.
For the float type, return a Sim_Val_Floating value.
The string type is returned by a Sim_Val_String value. The string typically represents some momentarily state. Due to nature of a string, a tool cannot do any calculation on the probe value, only show the current string content.
The fraction type should use a attr_value_t list of two
Sim_Val_Integer or Sim_Val_Floating values. This represent a mathematical
fraction value, where the first one is the numerator and and the second
value is the denominator value. Note however that a float value can be used
for both of them. To get the proper value for this probe the tool/user
should divide the numerator with the denominator. Using fraction makes it
possible for the tool to calculate a mean value for this probe between any
point in time where the probe was read, e.g., say you have a probe that
reads the frequency of a simulated processor that varies over time. Then
this probe can be defined as a fraction between the cycle count and the
elapsed virtual time (cycles/time = frequency). If the tool saves the cycle
difference and the time difference between to points in time, it can
calculate the mean frequency between those point by dividing the
differences.
For very large numbers the int128 type can be used, the type is represented as a attr_value_t list of two value; the high 64-bit number followed by the low 64-bit number.
The histogram type is represented by a attr_value_t list of
lists of two values. Where the inner list is used as a tuple of a named
group as a Sim_Val_String, and its corresponding value as a Sim_Val_Integer
or Sim_Val_Floating. A tool can then display an histogram of these groups
and/or calculate the difference between two histograms over time and display
that.
Probe_Key_CategoriesProbe_Key_Cause_SlowdownProbe_Key_Owner_ObjectProbe_Key_DescriptionProbe_Key_DefinitionProbe_Key_Float_DecimalsProbe_Key_Float_PercentProbe_Key_Metric_PrefixProbe_Key_Binary_PrefixProbe_Key_UnitProbe_Key_Time_FormatProbe_Key_WidthProbe_Key_Value_NotifierProbe_Key_Global_SumProbe_Key_Aggregates instead.Probe_Key_Cell_SumProbe_Key_Aggregates instead.Probe_Key_Aggregates
Only in the aggregate scope, the Probe_Key_Aggregate_Scope
and Probe_Key_Aggregate_Function key-value pairs are used to further
define how the aggregation is done.
Note that aggregates depend on the the type of the underlying probe.
Some probe types can only be aggregated with certain functions.
Probe_Key_Aggregate_ScopeProbe_Key_Aggregate_Functionsumminmaxarith-meanweighted-arith-meanUsing these weights implies that the weighted arithmetic mean can be calculated by adding all numerators and denominators, producing a new fraction of these sums.
For example, when calculating the mean instruction per cycles (IPC) on all processors (where the IPC per processor is represented as a fraction: instructions / cycles). With two processors having [20/30] and [40/50], the total IPC becomes [(20+40)/(30+50)] or [60/80] and the IPC value of 0.75.
medianobject-histogramclass-histogramAll key/value pairs except the Probe_Key_Name and Probe_Key_Type are optional.
SIM_INTERFACE(probe) {
attr_value_t (*value)(conf_object_t *obj);
attr_value_t (*properties)(conf_object_t *obj);
};
#define PROBE_INTERFACE "probe"