[Tinyos Core WG] Angels and Pins (ok, it's late/early)

[David Gay]

I can't sleep, so here's some thoughts on angels and pin heads ;-) All
names picked out of a hat.

A quick couple of definitions first:
- platform-defined X: X is defined on all platforms, but the
definition may be different
- platform-specfic X: X is defined on just one platform

* "Strong HILs", defined as "Code using these can reasonably be
expected to behave the same on all implementations". Examples include
TimerMilliC, LedsC, AM (if not using any radio metadata at least),
DemoSensorC, storage, the net2 group's abstractions.
Strong HILs may use platform-defined types if they also provide
operations to manipulate them (i.e., they are platform-defined
abstract data types). So message_t is fine (see the XXXPacket
interfaces) but current rssi fields are not (no way to create or
interpret rssi values)

* "Weak HILs", defined as "You can write portable code over these
abstractions. But any use of them involves platform-specific
behaviour.". Examples are:
- things whose use is inherently platform specific, like the ADC or an
I2C bus (what you're talking to is clearly platform specific)
- use or return values that are platform specific (ADC configurations,
radio metadata) - I'm not sure this is so logically different from the
previous characteristic though (the platform-specificity of the
contents of an I2C packet are not logically very different from that
of an ADC configuration)
Weak HILs may use platform-defined types (as in adc_config_t);
obtaining or manipulating these values may be a mysterious (aka
platform specific) process.

* "Hardware Independent interfaces" (HII?), which is just an interface
definition intended for use across multiple platforms. Examples
include the SID interfaces, the pin interfaces from TEP 117, the
Alarm/Counter/etc interfaces from TEP 102.

* "Utility components": these are pieces of clearly portable code
(typically generic components), but which aren't exposing a
self-contained service. Examples include the components in
tos/lib/timer, the ArbitratedRead* components. These provide and use
HIIs.

The benefit you get from weak HILs are at least:
- you can write portable utility code, e.g., a repeated sampling thing
for an ADC
- while code using these abstractions may not be portable, it's still
easier to port than code using HALs
- we provide some guidelines on how to expose some functionality,
which should help programmers when switching between platforms, and
provide guidance to platform developers

The benefit you get from using HIIs in HAL-level things are similar to
those from weak HILs:
- you can write useful utility components (but connecting these
utility components to the HAL-level thing is platform-specific, unlike
in the weak HIL case)
- while code using these abstractions may not be portable, it's still
easier to port than code using HALs (but probably a little more work
than with weak HILs)
- similar, though weaker, guideline benefits to weak HILs


Finally, there's some proposals of things below weak HILs:
* "weaker HILs", which are like weak HILs but use platform-defined
interfaces as well (my proposal for AdcC, where AdcConfig is
platform-defined)
* "HAL2s", where a component has a platform-independent name, and a
partially platform-independent specification. GeneralIOC (for pins)
from TEP117, the HAL guidelines from the timer TEP seem to fall here.

And really finally, it's worth noting that like all categorisations,
the one above is somewhat broken: is AM a strong HIL (you can send
packets everywhere) or a weak HIL (that pesky RSSI field)? It really
depends on the application ;-)

David