envsys, round two

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

Okay, I finally got the leisure to put together proplib-aware-enough
code to pick apart the dictionary returned by ENVSYS_GETDICTIONARY.
(Incidentally, for whoever it was that told me all the proplib types
are the same, I investigated, and it's not actually true.
prop_object_t is void *, but the rest are typedefs for various struct
types - _different_ struct types.  The documentation evidences other
confusion, too, such as one routine which is described as returning 8,
16, 32, 64, or NULL - and the description of its return value actually
could lead to any value from 0 up to some maximum not clearly defined
by the API as far as I can see.  Fortunately the implementation
actually returns 0 in the cases when the documentation says it returns
NULL.)

This is all talking about 5.2.  Perhaps the situation has improved
since then?

Now, I'm wondering if there's documentation on the available type
strings and what they mean.  So far, I've seen "Ampere hour", "Ampere",
"Battery capacity", "Battery charge", "Indicator", "Integer",
"Temperature", and "Voltage DC".  I've found no documentation on what
any of those mean, though as an anglophone I see them as having at
least a little implication of semantics embedded in the words.
However, most of them don't give any indication of units and even the
two that do ("Ampere hour" and "Ampere") are wrong; while I'm not sure,
I suspect they are actually microamps and microamp-hours.
sysmon_envsys, which is referred to, says (in a somewhat confusing
place) that "the user should convert the value returned by the driver
to the appropiate unit.  For example voltage sensors to mV, temperature
sensors to uK, Watts to mW, Ampere to mA, etc.".  That is not a
plausible match to what I see.  In the dictionary returned by
ENVSYS_GETDICTIONARY, the (sub)dictionary whose "description" is
"discharge rate" and whose "type" is "Ampere" has a "cur-value" of
3043000, which if taken as mA means it's drawing over three thousand
amperes, a completely ludicrous figure.  And this isn't just a driver
returning ridiculous results, because envstat(8) prints reasonable
values.

It's also not clear to what extent that text from sysmon_envsys (which
is in section 9) is supposed to be applicable to the dictionary which
crosses from kernel to userland (as opposed to the kernel-internal
interfaces it documents).

If this is going to be a people-are-supposed-to-write-code-to-this
published interface, it really needs clear and correct documentation
and a sanely constructed API.  The existing manpages are not clear, not
complete (unless I've missed something), and occasionally not even
correct, and the API is a confusing hybrid between OO and C.  And
that's not even going into all the underlying semantic issues.

So, where can I find the units of those type strings?  Do I have to
UTSL on envstat(8) and assume that it's doing it right?  Or did I miss
something somewhere?

/~\ 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