tep131.txt

tinyos-2.x.rar

   {
     error_t ok;

     ok = call MeasureClock.init();
     ok = ecombine(ok, call MoteInit.init());
     return ok;
   }
 }

4.2.3 Init example: PlatformLedsC
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Below is an example from mica/PlatformLedsC.nc wiring to the platform
specific *MoteInit* interface.

:: 

  configuration PlatformLedsC {
    provides interface GeneralIO as Led0;
  ...
    uses interface Init;
  } implementation {
    components HplAtm128GeneralIOC as IO;
    components PlatformP;
  
    Init = PlatformP.MoteInit;
  ...  

3.3 Platform Specific Code
--------------------------------------------------------------------

In addition to PlatformP/PlatformC the platform directory contain
additional code that is specific to this platform. First this could be
code that ties platform independent resources to particular instances
on this platform, second it could be code that is only relevant on
this particular platform (e.g. the clock rate of this platform). For
example the LEDs are a an example of the first: most platform have a
few LEDs, and the particular pin on this platform is tied to the
platform independent implementation using PlatformLedsC.

TinyOS requires that the header ``hardware.h`` is present while other
component can be named freely.

4.3.1 Platform Headers
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

TinyOS relies on a few C-header files being present for each
platform. These headers are then automatically included from the
respective parts of the TinyOS system. TinyOS expects that the
following files are present and that certain properties are defined in
them.

hardware.h
**********************

The ``hardware.h`` header file is included by ``tos/system/MainC.nc``
and usually in turn includes a MCU specific header file, with a few
required macros (such as avr128hardware.h, see Section 5.1.1). The
header is documented in TinyOS 2 Tutorial Lesson 10[TUT10_]

In addition the hardware.h file can set flags that are not related to
the hardware in general, but to this platform (e.g. clock rate). Below
is a snippet from ``mica2/hardware.h``

::

  #ifndef MHZ
  /* Clock rate is ~8MHz except if specified by user 
     (this value must be a power of 2, see MicaTimer.h and MeasureClockC.nc) */
  #define MHZ 8
  #endif
  
  #include <atm128hardware.h>
   
  enum {
    PLATFORM_BAUDRATE = 57600L
  };
  ...

platform_message.h
**********************

As part of the TinyOS 2 message buffer abstraction[TEP111_], TinyOS
includes the header *platform_message.h* from the internal TinyOS
header *message.h*. This header is only strictly required for
platforms wishing to use the message_t abstraction - this is not
described further in this TEP, but is used widely throughout TinyOS
(See [TEP111_] for details). The is expected to define the structures:
*message_header_t*, *message_footer_t*, and *message_metadata_t* which
are used to fill out the generic *message_t* structure.

Below is an example from the ``mica2`` *platform_message.h*

::

  typedef union message_header {
    cc1000_header_t cc1k;
    serial_header_t serial;
  } message_header_t;

  typedef union message_footer {
    cc1000_footer_t cc1k;
  } message_footer_t;

  typedef union message_metadata {
    cc1000_metadata_t cc1k;
  } message_metadata_t;


4.3.2 Platform Specific Components
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The code for platform dependent features also resides in the platform
directory. If the code can be tied to a particular chip it can be
placed in a separate directory below the ``chips`` directory. As an
example the following section of
``micaz/chips/cc2420/HplCC2420PinsC.nc`` ties specific pins to general
names on the MicaZ platform.

::

  configuration HplCC2420PinsC {
    provides {
      interface GeneralIO as CCA;
      interface GeneralIO as CSN;
      interface GeneralIO as FIFO;
      interface GeneralIO as FIFOP;
      interface GeneralIO as RSTN;
      interface GeneralIO as SFD;
      interface GeneralIO as VREN;
    }
  }
  
  implementation {
  
    components HplAtm128GeneralIOC as IO;
    
    CCA    = IO.PortD6;
    CSN    = IO.PortB0;
    FIFO   = IO.PortB7;
    FIFOP  = IO.PortE6;
    RSTN   = IO.PortA6;
    SFD    = IO.PortD4;
    VREN   = IO.PortA5;
  
  }



5. The chips
====================================================================

The functionality of each chip is provided by a set of one or more
interfaces and one or more components, in traditional terms this makes
up a driver. Each chip is assigned a sub directory in the the
``tos/chips`` directory. All code that define the functionality of a
chip is located here regardless of the type of chip (MCU, radio,
etc.). In addition MCU's group the code related to separate sub
systems into further sub directories (e.g. ``tos/chips/atm128/timer``).

In this section we will go trough some of the peripherals commonly
built into MCUs, but we will not go trough other chips such as sensors
or radio.

5.1 MCU Internals
--------------------------------------------------------------------

Apart from the drivers for each of the peripheral units, a few
additional definitions are required for the internals of the MCU. This
includes i) atomic begin/end and ii) low power mode. The first is
defined in the header *hardware.h* and the latter component
*MCUSleepC*.

5.1.1 mcuXardware.h
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Each architecture defines a set of required and useful macros in a
header filed named after the architecture (for example
*atm128hardware.h* for ATMega128). This header is then in turn
included from *hardware.h* in the platform directory (See Section
4.3.1).

A few of the macros are required by nesC code generation. nesC will
output code using these macros and they must be defined in advance,
other useful macros such as interrupt handlers on this particular
platform can be defined here as well. The required macros are:

  * *__nesc_enable_interrupt* / *__nesc_disable_interrupt*
  * *__nesc_atomic_start* / *__nesc_atomic_end*

Below is a few examples from *atm128hardware.h*

::

  /* We need slightly different defs than SIGNAL, INTERRUPT */
  #define AVR_ATOMIC_HANDLER(signame) \
    void signame() __attribute__ ((signal)) @atomic_hwevent() @C()
  
  #define AVR_NONATOMIC_HANDLER(signame) \
    void signame() __attribute__ ((interrupt)) @hwevent() @C()
  
  ...
  
  inline void __nesc_enable_interrupt()  { sei(); }
  inline void __nesc_disable_interrupt() { cli(); }

  ...
  
  inline __nesc_atomic_t 
  __nesc_atomic_start(void) @spontaneous()  {
      __nesc_atomic_t result = SREG;
      __nesc_disable_interrupt();
      asm volatile("" : : : "memory");
      return result;
  }
  
  /* Restores interrupt mask to original state. */
  inline void 
  __nesc_atomic_end(__nesc_atomic_t original_SREG) @spontaneous() {
    asm volatile("" : : : "memory");
    SREG = original_SREG;
  }
  

5.1.2 MCUSleepC
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

TinyOS manages the power state of the MCU through a few
interfaces. These interfaces allow components to signal how and when
this platform should enter low power mode. Each new MCU in TinyOS must
implement the *MCUSleepC* component that provide the *McuSleep* and
*McuPowerState* interfaces.

The TinyOS scheduler calls *McuSleep.sleep()* when it runs out of
tasks to start. The purpose of this function is to make the MCU enter
the appropriate sleep mode. The call to *McuSleep.sleep()* is made
from within an atomic section making it essential that sleep() enables
interrupts before entering sleep mode!  If the interrupts not enabled
prior to entering sleep mode the MCU will not be able to power back up.

A dummy MCU sleep component that does not enter sleep mode, but merely
switches interrupts on and off is shown below. This ensures that the
platform will not lock up even without proper sleep support.

::

  #include "hardware.h"

  module McuSleepC {
    provides interface McuSleep;
    provides interface McuPowerState;
    uses  interface McuPowerOverride;
  } implementation {
    async command void McuSleep.sleep() {
      __nesc_enable_interrupt();
      // Enter sleep here
      __nesc_disable_interrupt();
    }
  
    async command void McuPowerState.update() { }
  }
  

5.2 GeneralIO 
--------------------------------------------------------------------

Virtually all micro controllers feature a set of input output (I/O)
pins.  The features of these pins is often configurable and often some
pins only support a subset of features. The HIL level interface for
TinyOS is described in [TEP117_] and uses two interface to describe
general purpose I/O pins common to many MCUs:

* **GeneralIO**: Digital input/output. The GeneralIO interface
  describes a digital pin with a state of either *clr* or *set*, the
  pin must be capable of both input and output. Some MCUs provide pins
  with different capabilities: more modes (e.g. an alternate
  peripheral mode), less modes (e.g. only input) or a third
  "tri-state" mode. Such chip specific additional features are not
  supported. Some chips group a set of pins into "ports" that can be
  read or written simultaneously, the HIL level interface does not
  support reading or setting an entire port.

* **GpioInterrupt**: Edge triggered interrupts. GpioInterrupt support
  a single pin providing an interrupt triggered on a rising or falling
  edge. Pins capable of triggering on an input level or only
  triggering on one edge is not supported.

While these interfaces are aimed at the HIL level some platforms use
the GeneralIO and GpioInterrupt interface to represent the HPL level
(atm128 for example) and others platforms define their own interface
to capture the entire functionality (msp430, pxa27x for example).

[TEP117_] states that each platform must provide the general IO pins of
that platform through the *GeneralIO* interface and should do this
though the component *GeneralIOC*. It is however not clear how the
entire set of pins should be provided - this could be in the form of a
list of pins, group of pins, a generic component, etc.

The pin implementations are usually found in the *pins* sub directory
for a particular MCU (e.g. *msp430/pins* for MSP430 pin
implementation).

5.2.1 Example MSP430
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The MSP430 implementation builds the platform independent pin
implementation as a stack of components starting with a platform
specific component for each pin.

::

               |  GeneralIO
    +---------------------+
    |      Msp430GpioC    |
    +---------------------+
               |  HplMsp430GeneralIO
    +---------------------+
    | HplMsp430GeneralIOC |
    +---------------------+
               |  HplMsp430GeneralIO
    +---------------------+
    | HplMsp430GeneralIOP |
    +---------------------+

At the bottom the component ``HplMsp430GeneralIOP`` provides a general
implementation of one Msp430 pin using the ``HplMsp430GeneralIO``