tep131.txt

tinyos-2.x.rar

interface. The generic component ``HplMsp430GeneralIOP`` is then
instantiated for each pin by ``HplMsp430GeneralIOC``.

::
  
  interface HplMsp430GeneralIO {
    async command void set();
    async command void clr();
    async command void toggle();
    async command uint8_t getRaw();
    async command bool get();
    async command void makeInput();
    async command bool isInput();
    async command void makeOutput();
    async command bool isOutput();
    async command void selectModuleFunc();
    async command bool isModuleFunc();
    async command void selectIOFunc();
    async command bool isIOFunc();
  }

This interface is implemented in the generic component
HplMsp430GeneralIOP (abbreviated):

::

  generic module HplMsp430GeneralIOP(uint8_t port_in_addr, ...)  {
    provides interface HplMsp430GeneralIO as IO;
  } implementation  {
    #define PORTx (*(volatile TYPE_PORT_OUT*)port_out_addr)
  
    async command void IO.set() { atomic PORTx |= (0x01 << pin); }
    async command void IO.clr() { atomic PORTx &= ~(0x01 << pin); }
    async command void IO.toggle() { atomic PORTx ^= (0x01 << pin); }

 ...

These are then instantiated from HplMsp430GeneralIOC (abbreviated):

::

  configuration HplMsp430GeneralIOC {
    provides interface HplMsp430GeneralIO as Port10;
    provides interface HplMsp430GeneralIO as Port11;
  ...
  } implementation {
    components 
      new HplMsp430GeneralIOP(P1IN_, P1OUT_, P1DIR_, P1SEL_, 0) as P10,
      new HplMsp430GeneralIOP(P1IN_, P1OUT_, P1DIR_, P1SEL_, 1) as P11,
  ...
    Port10 = P10;
    Port11 = P11;
  ...


And finally these are transformed from the interface
HplMsp430GeneralIO to the platform independent GeneralIO using the
generic component Msp430GpioC (abbreviated):

::

  generic module Msp430GpioC() {
    provides interface GeneralIO;
    uses interface HplMsp430GeneralIO as HplGeneralIO;
  } implementation {
    async command void GeneralIO.set() { call HplGeneralIO.set(); }
    async command void GeneralIO.clr() { call HplGeneralIO.clr(); }
    async command void GeneralIO.toggle() { call HplGeneralIO.toggle(); }
  ...


5.3 LEDs
--------------------------------------------------------------------

Having a few leds on a platform is quite common and TinyOS supports
three leds in a platform independent manner. Three leds are provided
through the *LedsC* component regardless of the amount of leds
available on the platform. The LED implementation is not covered by a
TEP at the time of writing, but the general consensus between most
platforms seems to be to provide access to 3 LEDs through the
component *PlatformLedsC*. This component is then used by *LedC* and
*LedP* (from ``tos/system``) to provide a platform independent Led
interface.

The PlatformLedsC implementation is found in the platform directory of
each platform (e.g. *tos/platforms/mica2* for mica2). The consensus is
as follows:

* Each platform provides the component PlatformLedsC

* PlatformLedsC provides Led0, Led1, Led2 using the GeneralIO
  interface. If the platform has less than 3 Leds these are wired to
  the component NoPinC

* PlatformLedsC *uses* the Init interface and usually it wired back to
  an initialization in PlatformP - this way when LedC is included in
  an application it will be initialized when PlatformP call this
  interface

5.3.1 Example Mica2dot
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

::

  configuration PlatformLedsC
  {
    provides interface GeneralIO as Led0;
    provides interface GeneralIO as Led1;
    provides interface GeneralIO as Led2;
    uses interface Init;
  }
  implementation  {
    components HplAtm128GeneralIOC as IO;
    components new NoPinC();
    components PlatformP;
  
    Init = PlatformP.MoteInit;
  
    Led0 = IO.PortA2;  // Pin A2 = Red LED
    Led1 = NoPinC;
    Led2 = NoPinC;
  }
  



5.3.2 LEDs implementation discussion
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The Led interface described above is not specified in a TEP, though at
the time of writing most platforms seem to follow this pattern. Not
being covered by a TEP leads to a few uncertainties:

* *PlatformLedsC* exports leds using the *GeneralIO* interface. The
  intention is of course that a led is connected to a pin and this pin
  is used to turn the led on. *LedC* uses this assumption to calls the
  appropriate *makeOutput* and *set*/*clr* calls. However this might
  not be the case - a led could be connected differently making the
  semantics of, say *makeOutput* unclear. Furthermore it is assumed
  that the set call turns the led on, while the actual pin might have
  to be cleared (active low). And what is the semantics of *makeInput*
  on a LED? Abstracting these differences into on/off, enable/disable
  semantics would clear up the uncertainties.

* Initializing the Leds is important - the Leds can consume power even
  when turned off, if the corresponding pins are configured
  inappropriately. Including the LedsC component initializes the Leds
  as output when this component is used, if not they must be
  initialized elsewhere (e.g. PlatformP). It would seem elegant to
  group related code (e.g. one Leds component).

* The interface does not provide a uniform way of accessing any
  additional LEDs other than the 3 found on the Mica motes. While this
  is inherently platform specific, having a common consensus would be
  useful, say for example exporting an array of Led. In this way a
  program requiring say 4 leds could be compiled if 4 leds are available.


5.4 Timers
--------------------------------------------------------------------

The timer subsystem in TinyOS 2 is described in [TEP102_] the TEP
specifies interfaces at HAL and HIL levels that a platform must adhere
to. The timer does not cover the possible design choices at the HPL
level. The timers defined in this TEP are described in terms of
*width* of the underlying counters (e.g. 8, 16, 32 bit) and in the
tick period or frequency denoted *precision* (e.g. 10 kHz, 1 ms, 1
us). The timer subsystem is provided through a set of hardware
independent interfaces and a set of recommended configuration modules.
As such some features of a particular device may not be available in a
device independent manner.

The functionality commonly seen in MCU timer units is often split in 3
parts: control, timer/counter, capture/compare(trigger). Timer control
in is inherently platform specific and is not covered by a TEP. The
timer [TEP102_] covers timer/counter while capture/compare is covered
by [TEP117_]. From the TEPs it is not clear how capture/compare and
timer/counter relate to each other even though they are likely to
refer to the same time base. The calibration of the system clock is
often connected with the timer system and lives in the timer
directory, but it is not covered in [TEP102_].

The timer implementation for a given MCU is placed in the *timer* sub
directory of the directory for a given MCU
(e.g. *tos/chips/avr/timer*). Often clock initialization components
are placed in the same directory, but these are not covered by the
TEPs.

5.4.1 Timer Layers
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

TEP117_ follows the 3 layer architecture and separates the platform
dependent and independent abstractions. It poses not restrictions on
the HPL layer, but provides a suggested HAL layer and requirements at
the HIL level. It defines a set of interfaces and precisions that are
used at the HAL and HIL levels.

The common features of a timer are separated into a set of interfaces,
corresponding roughly to common features in MCU timer units. The
interfaces covered by the [TEP102_] are (capture from [TEP117_]):

* **BusyWait<precision_tag,size_type>** Short synchronous delays
* **Counter<precision_tag, size_type>** Current time, and overflow events
* **Alarm<precision_tag,size_type>** Extend Counter with at a given time
* **Timer<precision_tag>** 32 bit current time, one shot and periodic events
* **LocalTime<precision_tag>** 32 bit current time without overflow
* **GpioCapture** 16 bit time value on an external event (precision unspecified)

The precisions defined in [TEP117_] are defined as "binary" meaning
1024 parts of a second. Platforms must provide these precisions (if
possible) regardless of the underlying system frequency (i.e. this
could be a power of 10).

* **TMilli** 1024 Hz (period 0.98 ms)
* **TMicro** 1048576 Hz (period 0.95 us)
* **T32khz** 32.768 kHz (period 30.5 us)

HPL
********
The features of the underlying hardware timers are generally exposed
using one or more hardware specific interfaces. Many MCU provide a
rich a set of different timer units varying in timer width, frequency
and features. 

Many MCUs provides features that are quite close to the features
described by the interfaces above. The HPL layer exposes these
features and the layers above utilize the available hardware and
virtualize the features if necessary.

Consider for example generating events at a specific time. Often a
timer unit has a single counter and a few compare registers that
generate interrupts. The counter and compare registers often translate
relative straightforward to Counter and Alarm interfaces.

HAL
********

Each platform should expose a hardware timer of precision P and width W
as Counter${P}${W}C, Alarm${P}${W}C(). For example an 8 bit, 32.768 kHz
timer should be exposed as Counter32khz8C and Alarm32khz8C

Alarm/Counters come in pairs and refer to a particular hardware unit,
while there is only one counter there is commonly multiple compare
registers. Alarm is a generic component and each instantiation must
provide an independent alarm allocating more Alarm components than
available compare register should provide a compile time error.

HIL
*********

Each platform must expose the following components that provide
specific width and precision that are guaranteed to exist on TEP
compliant platforms.

 * **HilTimerMilliC** A 32 bit Timer interface of TMilli precision
 * **BusyWaitMicroC** A BusyWait interface of  TMicro precision


5.4.2 Timer Implementation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Implementing the timers for TinyOS in short consists of utilizing the
available HW timer features to provide TinyOS style timers
interfaces. In general the approach taken by existing platforms is to
create a set of HPL level timer and control interfaces that export the
available hardware features and adapt these to specific precisions and
widths at the HAL level. However the specific HPL level design choices
differ from platform to platform.

For example one could export all timers as a simple list, a component
for each timer, a parameterised interface, etc. Similarly for the
control features this could be provided with the timer interfaces or
kept as a separate interface. In the following we will go through a
few examples and point out their differences.


5.4.3 Example: ATMega128l
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The ATMega128l implementation (atm128) exports the system timers one
component each. Each component provide 4 interfaces - one for each of
the functions of the unit: timer, capture, compare and control. The
timer, capture, and compare interfaces are generic based on the width
(either 8 or 16 bit) while two separate control interfaces are
provided.

Depicted below is a diagram of how ``HplAtm128Timer1C`` could be stacked
to provide platform independent interfaces (not shown are
``HplAtm128Timer0Async``, ``HplAtm128Timer2``, ``HplAtm128Timer3``):

::

            +------------------------------------------------+
            |              HplAtm128Timer1C                  |
            +-----+-------------------+-----------------+----+
  HplAtm128Capture|     HplAtm128Timer| HplAtm128Compare|
                  |                   |                 |
       +----------+---------+         |                 |
       | Atm128GpioCaptureC |         |                 |
       +----------+---------+         |                 |
                  |                 +-+-----------------+--+
       GpioCapture|                 |      Atm128AlarmC    |
                  |                 +----------+-----------+
                  |                       Alarm|


The hardware features is exported using 3 interfaces:
``HplAtm128Timer``, ``HplAtm128Compare`` and ``HplAtm128Capture``.

::

 interface HplAtm128Timer<timer_size>
 {
   async command timer_size get();
   async command void       set( timer_size t );
   async event void overflow();
   async command void reset();
   async command void start();
 ...
 
 interface HplAtm128Compare<size_type>
 {
   async command size_type get();
   async command void set(size_type t);
   async event void fired();           //<! Signalled on compare interrupt