envsys issues [was Re: envstat wrong: who's at fault?]

[der Mouse <mouse%Rodents-Montreal.ORG@localhost>]

[moved from port-i386]

[me]
>> In passing, would it be appropriate and/or useful to suggest
>> improvements to [the envsys(4)] API?  When I was writing code, I
>> found the envsys(4) ioctls to be deficient for my purposes.
[Paul Goyette]
> I'd be interested in knowing in which ways you found the current API
> lacking.  [...]

Well, some things are underdocumented.  For example, it seems that most
sensors are not in the units specified by envsys_tre_data_t.units, but
rather in 1e-6 of that unit - for example ENVSYS_SWATTHOUR sensors are
not in watthours but in microwatthours - and, as far as I've been able
to find, this factor of 1e6 is not documented anywhere but the source
to envstat(8).  Except for temperature, which is specifically said to
be in microKelvins.  But others are said to be in volts, amps, etc.  To
quote both the envsys(4) and <sys/envsys.h>,

                     union {                         /* all data is given */
                             uint32_t data_us;       /* in microKelvins, */
                             int32_t data_s;         /* rpms, volts, amps, */
                     } cur, min, max, avg;           /* ohms, watts, etc */
                                                     /* see units below */

If the "micro" is supposed to apply to all those units, not just
Kelvins, then (a) "rpms" needs to be removed from the list and (b) the
wording needs to be improved.

But the one piece I've found so far that isn't just a lack of
documentation (well, unless there are totally undocumented calls) is
that there's no way to fetch multiple sensors' values without potential
for skew between them..  For example, to quote from the code I've been
developing,

 prev_charging = -1;
 prev_discharging = -1;
 /*
  * This loop exists in an attempt to avoid getting confused by things
  *  changing in between fetching one variable and fetching the other.
  *  It can still get confused if multiple changes occur during that
  *  interval, but, without some kind of assist from the API, that's
  *  not fixable.  (My preferred assist would be a way to fetch
  *  multiple sensors' values atomically; failing that, some kind of
  *  change serial number.)
  */
 while (1)
  { charging = get_boolean(SENSOR_CHARGING);
    if (charging < 0) return(0);
    discharging = get_boolean(SENSOR_DISCHARGING);
    if (discharging < 0) return(0);
    if ((charging == prev_charging) && (discharging == prev_discharging)) break;
    prev_charging = charging;
    prev_discharging = discharging;
  }

(get_boolean returns 0 or 1, wrapping ENVSYS_GTREDATA, with checks that
the sensor being fetched is of type ENVSYS_INDICATOR and has
ENVSYS_FCURVALID set; the SENSOR_* defines are application-specific).

Or is this fundamentally unfixable because sensors' values are fetched
serially and individually from the hardware with the corresponding risk
at that level too?  Then I agree with the remark in the manpage that
some kind of event-stream interface is needed.

/~\ The ASCII                             Mouse
\ / Ribbon Campaign
 X  Against HTML                mouse%rodents-montreal.org@localhost
/ \ Email!           7D C8 61 52 5D E7 2D 39  4E F1 31 3E E8 B3 27 4B