add extra units to pmUnits

man/man1/pmie.1

@@ -620,6 +620,9 @@ A
 .B pmie
 specification is a sequence of semicolon terminated expressions.
 .PP
+The sequence ``//'' introduces a comment and all text from here
+to the end of the current input line will be ignored.
+.PP
 Basic operators are modeled on the arithmetic, relational and Boolean
 operators of the C programming language.
 Precedence rules are as expected, although the use of parentheses
@@ -670,6 +673,8 @@ and the time interval between these samples.
 All numeric expressions are evaluated in double precision, and where
 appropriate, automatically
 scaled into canonical units of ``bytes'', ``seconds'' and ``counts''.
+Note that metrics defined over extra units like ``temperature'' or ``voltage''
+are not scaled into canonical units.
 .PP
 A
 .B rule
@@ -1046,6 +1051,17 @@ Simple scale factors are constructed from the keywords:
 \f(CBbyte\fR, \f(CBKbyte\fR, \f(CBMbyte\fR, \f(CBGbyte\fR, \f(CBTbyte\f1,
 \f(CBcount\fR, \f(CBKcount\fR and \f(CBMcount\fR,
 and the operator \f(CR/\fR, for example ``\f(CBKbytes / hour\f1''.
+.PP
+Metrics defined over extra units like ``temperature'' or ``voltage''
+may have a very wide variety of possible scales, but there is no support
+in
+.B pmie
+for keywords to effect scaling, so expressions must use explicit scaling,
+e.g.
+.br
+.ti +0.5i
+\f(CBthis.temp.celsius\fR >= (\f(CBother.temp.fahrenheit\fR - 32) * 5 / 9
+.br
 .SH MACROS
 Macros are defined using expressions of the form:
 .PP

man/man1/pminfo.1

@@ -18,7 +18,7 @@
 \f3pminfo\f1 \- display information about performance metrics
 .SH SYNOPSIS
 \fBpminfo\fR
-[\fB\-dfFIlLmMstTvVxz?\fR]
+[\fB\-defFIlLmMstTvVxz?\fR]
 [\fB\-a\fR \fIarchive\fR]
 [\fB\-b\fR \fIbatchsize\fR]
 [\fB\-c\fR \fIdmfile\fR]
@@ -134,6 +134,12 @@ to be queried.
 Metric descriptions detailing the PMID, data type, data semantics, units,
 scale and associated instance domain.
 .TP
+\fB\-e\fR, \fB\-\-metadata-errors\fR
+Same as
+.B \-v
+but do not report metrics that return no values, so any metrics reported
+are ones that have either persistent errors or inconsistent metadata.
+.TP
 \fB\-f\fR, \fB\-\-fetch\fR
 Fetch and print values for all instances.
 When fetching from a set of archives, only those instances present in the

man/man1/pmlogrewrite.1

@@ -200,7 +200,9 @@ the
 .KW RESCALE
 option for the
 .KW UNITS
-clause of the metric rewriting rule described below.
+and
+.KW EXTRAUNITS
+clauses of the metric rewriting rule described below.
 .TP
 \fB\-v\fR, \fB\-\-verbose\fR
 Enable verbose mode.
@@ -1118,6 +1120,51 @@ may be used to chose value rescaling as per the
 command line option, but applied to just this metric.
 .RE
 
+.PP
+.KW EXTRAUNITS
+.KW ->
+.I newextraunits
+[
+.KW RESCALE
+]
+.RS +4n
+.PP
+Same semantics as the
+.KW UNITS
+clause, except
+.I newextraunits
+is eight values separated by commas.
+The first six values are exactly the same as for
+.I newunits
+in the
+.KW UNITS
+clause.
+The seventh value identifies one of the ``extra'' units and
+should be 0 (if there is none),
+else the
+the XXX part of the name of one of the
+.B PM_UNIT_XXX
+macros, e.g.
+.KW TEMPERATURE
+for
+.BR PM_UNIT_TEMPERATURE .
+The eigth value identifies the scale of the ``extra'' unit and
+should be 0 (if there is none),
+else the XXX part of the name of one of the associated
+.BI PM_ <unit> _XXX
+macros, e.g.
+.KW C
+for
+.BR PM_TEMPERATURE_C
+(the value is a temperature in degrees Celsius).
+.PP
+The optional keyword
+.KW RESCALE
+has the same meaning as for the
+.KW UNITS
+clause.
+.RE
+
 .PP
 .KW VALUE
 .KW REPLACE

man/man3/pmapi.3

@@ -240,6 +240,11 @@ service time is Time/Count.
 In each dimension there are a number
 of common scale values that may be used to better encode ranges that might
 otherwise exhaust the precision of a 32-bit value.
+.PP
+Orthogonally, extra ``units'' information is also supported for values
+that represent physical and electrical measurements, e.g. temperature,
+voltage, current, power, etc.
+.PP
 This information is encoded
 in the
 .CR pmUnits

man/man3/pmconvscale.3

@@ -74,7 +74,17 @@ The scaling takes place from the units defined by
 .I iunit
 into the units defined by
 .IR ounit .
-Both input and output units must have the same dimensionality.
+Both input and output units must have the same dimensionality, i.e. each
+of the fields
+.IR dimSpace ,
+.IR dimTime ,
+.IR dimCount
+and
+.I extraUnit
+must have the same value in both
+.I iunit
+and
+.IR ounit .
 .PP
 The performance metric type for both input and output values is determined by
 .IR type ,

man/man3/pmiaddmetric.3

@@ -128,8 +128,10 @@ The semantics of the metric (counter, instantaneous value, etc.) is
 specified by the
 .I sem
 argument which would normally be the result of a call to the
-convenience constructor method
-.BR pmiUnits (3).
+convenience constructor methods
+.BR pmiUnits (3)
+or
+.BR pmiExtraUnits (3)
 .SH DIAGNOSTICS
 .B pmiAddMetric
 returns zero on success else a negative value that can be turned into an
@@ -138,12 +140,14 @@ error message by calling
 .SH SEE ALSO
 .BR PCPIntro (1),
 .BR LOGIMPORT (3),
+.BR PMAPI (3),
+.BR pmLookupDesc (3),
 .BR pmiErrStr (3),
+.BR pmiExtraUnits (3),
+.BR pmiPutLabel (3),
 .BR pmiPutResult (3),
-.BR pmiPutValue (3),
-.BR pmiPutValueHandle (3),
 .BR pmiPutText (3),
-.BR pmiPutLabel (3),
-.BR pmiUnits (3)
+.BR pmiPutValue (3),
+.BR pmiPutValueHandle (3)
 and
-.BR pmLookupDesc (3).
+.BR pmiUnits (3).

man/man3/pmiunits.3

@@ -17,6 +17,7 @@
 .TH PMIUNITS 3 "PCP" "Performance Co-Pilot"
 .SH NAME
 \f3pmiUnits\f1,
+\f3pmiExtraUnits\f1,
 \f3pmiID\f1,
 \f3pmiInDom\f1 \- construct core metric data structures
 .SH "C SYNOPSIS"
@@ -35,9 +36,20 @@ pmUnits pmiUnits(int \fIdimSpace\fP,
 'in +\w'pmUnits pmiUnits('u
 int\ \fIdimTime\fP,
 int\ \fIdimCount\fP,
-int\ \fIscaleSpace\fP,
-int\ \fIscaleTime\fP,
-int\ \fIscaleCount\fP);
+unsigned\ int\ \fIscaleSpace\fP,
+unsigned\ int\ \fIscaleTime\fP,
+unsigned\ int\ \fIscaleCount\fP);
+.in
+.br
+pmUnits pmiExtraUnits(int \fIdimSpace\fP,
+'in +\w'pmExtraUnits pmiUnits('u
+int\ \fIdimTime\fP,
+int\ \fIdimCount\fP,
+unsigned\ int\ \fIscaleSpace\fP,
+unsigned\ int\ \fIscaleTime\fP,
+unsigned\ int\ \fIscaleCount\fP,
+int \fIextraUnit\fP,
+unsigned\ int\ \fIextraScale\fP);
 .in
 .sp
 cc ... \-lpcp_import \-lpcp
@@ -62,6 +74,17 @@ $\fIscaleSpace\fP,
 $\fIscaleTime\fP,
 $\fIscaleCount\fP);
 .in
+.br
+$units = pmiExtraUnits($\fIdimSpace\fP,
+'in +\w'$units = pmiExtraUnits('u
+$\fIdimTime\fP,
+$\fIdimCount\fP,
+$\fIscaleSpace\fP,
+$\fIscaleTime\fP,
+$\fIscaleCount\fP,
+$\fIextraUnit\fP,
+$\fIextraScale\fP);
+.in
 .hy
 .ad
 .ft 1
@@ -85,7 +108,9 @@ for a complete description of the values and semantics of the
 components of a
 .B pmUnits
 structure, and hence the valid argument values for
-.BR pmiUnits .
+.B pmiUnits
+and
+.BR pmiExtraUnits .
 .SH SEE ALSO
 .BR LOGIMPORT (3),
 .BR pmiAddMetric (3),

man/man3/pmlookupdesc.3

@@ -157,6 +157,8 @@ encoding as follows.
 The dimensionality is defined by a power, or index, in
 each of 3 orthogonal dimensions, namely Space, Time and Count
 (or Events, which are dimensionless).
+Additional ``extra'' units are also available as descibed below.
+.PP
 For example I/O throughput might be represented as
 .ti 1i
 .CR "\0\0\0\0\0\0\0\0\0\0-1"
@@ -193,10 +195,12 @@ structure.
  * for Performance Metric Values
  *
  * For example, a pmUnits struct of
- *      { 1, \-1, 0, PM_SPACE_MBYTE, PM_TIME_SEC, 0 }
+ *      { 1, \-1, 0, PM_SPACE_MBYTE, PM_TIME_SEC, 0, 0, 0 }
  * represents Mbytes/sec, while
- *      { 0, 1, \-1, 0, PM_TIME_HOUR, 6 }
- * represents hours/million-events
+ *      { 0, 1, \-1, 0, PM_TIME_HOUR, 6, 0, 0 }
+ * represents hours/million-events, and
+ *      { 0, 0, 0, 0, 0, 0, PM_UNIT_VOLTAGE, PM_VOLTAGE_mV }
+ * represents voltage in units of mV
  */
 typedef struct {
     int dimSpace:4;             /* space dimension */
@@ -205,6 +209,8 @@ typedef struct {
     unsigned int scaleSpace:4;  /* one of PM_SPACE_* below */
     unsigned int scaleTime:4;   /* one of PM_TIME_* below */
     int scaleCount:4;           /* one of PM_COUNT_* below */
+    int extraUnit:5;            /* code for extra unit from PM_UNIT_* below */
+    int extraScale:3;           /* scale for extra unit */
 } pmUnits;                      /* dimensional units and scale of value */
 
 /* pmUnits.scaleSpace */
@@ -230,6 +236,31 @@ typedef struct {
  * e.g. 6 for 10^6, or \-3 for 10^\-3
  */
 #define PM_COUNT_ONE    0       /* 1 */
+/*
+ * the extra unit types are mutually exclusive so at most one one of
+ * the following extraUnit values may be used for each metric
+ */
+#define PM_UNIT_TEMPERATURE    1
+#define PM_UNIT_VOLTAGE        2
+#define PM_UNIT_CURRENT        3
+#define PM_UNIT_POWER          4
+/*
+ * scale factors for extra units ... must be > 0 and <= 7 and
+ * unique for each extra unit type
+ */
+#define PM_TEMPERATURE_C        1       /* celsius */
+#define PM_TEMPERATURE_F        2       /* fahrenheit */
+#define PM_TEMPERATURE_K        3       /* kelvin */
+#define PM_VOLTAGE_V            1       /* Volt */
+#define PM_VOLTAGE_mV           2       /* milli Volt */
+#define PM_VOLTAGE_uV           3       /* micro Volt */
+#define PM_CURRENT_A            1       /* Ampere */
+#define PM_CURRENT_mA           2       /* milli Ampere */
+#define PM_CURRENT_uA           3       /* micro Ampere */
+#define PM_POWER_kW             1       /* kilo Watt */
+#define PM_POWER_W              2       /* Watt */
+#define PM_POWER_mW             3       /* milli Watt */
+#define PM_POWER_uW             4       /* micro Watt */
 .in
 .fi
 .ft 1

man/man3/pmregisterderived.3

@@ -700,6 +700,17 @@ multiplication or division are allowed, or if the left operand is
 not a counter and the right operand is a counter, then only multiplication
 is allowed.
 .PP
+Metrics with extra units, like temperature or voltage, are subject
+to some additional constraints, specifically no automatic scale
+conversion (although the
+.ft CR
+rescale
+.ft R
+function works as expected),
+extra units cannot be used for both operands in 
+multiplication (``*'') and extra units are only allowed for
+both operands of division (``/'') if the units and scale are identical.
+.PP
 Because relational expressions use the current value only and produce
 a result that is not a counter, either or both operands of a relational expression
 may be counters.