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_Kind = 0, /* Identifier of the probe */
Probe_Key_Name = 0, /* Old name of Probe_Key_Kind,
kept for compatibility */
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_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_KindThere can be many probes associated with the same kind, but they should all represent the same type of measured data.
The kind should be named so it is humanly possible to understand what you get back when you read it.
To avoid conflicts, the kind should be an hierarchical name where each level is separated with a dot. Probes falling into the same domain should have logical names according to this. Currently, there are some defined names on the first level that can be used to build the hierarchy. Among them are: cpu. that collects probes related to a CPU, dev. that collects probes for devices, cell. that collects probes related to cells, host. collects probes related to the host environment, and sim. that collects probes having to do with the overall simulation environment.
Some 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-kind, for similar probe values. The probe's unique identifier is a string containing the object name then a colon, followed by the probe-kind, 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_ScopeCell-aggregates are put under the available cell objects and will aggregate the probe which belongs to the respective cell object.
Probe_Key_Aggregate_FunctionFor probes of the fraction type, if any denominator contains a zero value (division by zero), the calculated value is undefined and [0, 0] is returned. This applies to all fraction aggregates except weighted-arith-mean, where the zero denominator can be handled.
summinmaxarith-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_Kind 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"