tep107.txt

tinyos-2.x.rar

============================
TinyOS 2.x Boot Sequence
============================

:TEP: 107
:Group: Core Working Group 
:Type: Documentary
:Status: Final
:TinyOS-Version: 2.x
:Author: Philip Levis 

.. Note::

   This memo documents a part of TinyOS for the TinyOS Community, and
   requests discussion and suggestions for improvements.  Distribution
   of this memo is unlimited. This memo is in full compliance with
   TEP 1.

Abstract
====================================================================

This memo documents the structure and implementation of the mote
boot sequence in TinyOS 2.x.


1. Introduction
====================================================================

TinyOS has a set of calling conventions and semantics in its boot
sequence. Earlier versions of TinyOS used an interface named
"StdControl" to take care of system initialization and starting
required software systems. Experience with several hardware platforms
showed StdControl to be insufficient, as it provided only a
synchronous interface. Additionally, StdControl bundled the notion of
initialization, which happens only at boot, with power management and
service control. TinyOS 2.x solves these problems by separating what
was once StdControl into three separate interfaces: one for
initialization, one for starting and stopping components, and one for
notification that the mote has booted. This memo describes the TinyOS
boot sequence and reasons for its semantics.

2. TinyOS 1.x Boot Sequence
====================================================================

The TinyOS 1.x boot sequence is uniform across most mote platforms
(TOSSIM has a very different boot sequence, as it is a PC
program). The module RealMain implements main(), and has the following
signature::

  module RealMain {
    uses {
      command result_t hardwareInit();
      interface StdControl;
      interface Pot;
    }
  }


The mote main() function uses a mix of nesC and C::

  int main() __attribute__ ((C, spontaneous)) {
    call hardwareInit();
    call Pot.init(10);
    TOSH_sched_init();
         
    call StdControl.init();
    call StdControl.start();
    __nesc_enable_interrupt();
     
    while(1) {
      TOSH_run_task();
    }
  }


Several problems exist. Some of these calls are artifacts of old
platforms: the Pot component refers to the mica variable potentiometer
for controlling radio transmission power, and for other platforms is a
stub component Some of the calls -- TOSH_sched_init and TOSH_run_task
-- are C functions that are implemented in other, automatically
included files. Separation from the nesC component model makes
changing what lies behind these functions more difficult than normal
in TinyOS.

More importantly, the initialization sequence has several
limitations. The component HPLInit implements the hardwareInit command
(wired by the component Main): hardware initialization may not be part
of a pure HPL layer. The scheduler is initialized after hardware,
which means that no hardware initialization can post a task if it
needs one. The StdControl interface combines component initialization
(init()) and activation (start()/stop()); if a component needs to be
initialized by RealMain, it must also be started. Separating these two
leads to more flexible power management, and distinguishes required
low-level components that must always be running (such as a Timer)
from high level components that can be power managed (such as an
application). Finally, some components that need to often need to be
started by main, such as a radio, do not follow a synchronous
start/stop model. In this case, some components can't operate properly
until the radio starts, but main has no mechanism for waiting for the
radio start completion event.


3. TinyOS 2.x Boot Interfaces
====================================================================

The TinyOS 2.x boot sequence uses three interfaces:

  * Init, for initializing component/hardware state
  * Scheduler, for initializing and running tasks
  * Boot, for signalling that the system has successfully booted

The Init interface has a single command, init()::

  interface Init {
    command error_t init();
  }

Init provides a synchronous interface, enabling initialization
ordering. Unlike normal execution, in which operations from a wide
range of components need to be interleaved effectively, initialization
is a sequential, synchronous operation: no component can be started
until initialization is complete. If a particular component's
initialization requires waiting for interrupts or other asynchronous
events, then it must explicitly wait for them (e.g., 
with a spin loop), MUST NOT return until complete. Otherwise the system
may start before initialization is complete.

The Scheduler interface is for initializing and controlling task
execution. It is detailed in TEP 106 [1]_.

The Boot interface has a single event, booted(), which the boot
sequence signals when it has completed::

  interface Boot {
    event void booted();
  }


4. TinyOS 2.x Boot Sequence
====================================================================

The module RealMainP implements the standard TinyOS 2.x boot sequence.
The configuration MainC wires some of RealMainP's interfaces to
components that implement standard abstractions and exports the others
that are application specific. Code above the Hardware Independent
Layer (TEP 2) SHOULD wire to MainC and not RealMainP::

 
  module RealMainP {
    provides interface Booted;
    uses {
      interface Scheduler;
      interface Init as PlatformInit;
      interface Init as SoftwareInit;
    }
  }
  implementation {
    int main() __attribute__ ((C, spontaneous)) {
      atomic {
        platform_bootstrap();
        call Scheduler.init();
        call PlatformInit.init();
        while (call Scheduler.runNextTask());
        call SoftwareInit.init();
        while (call Scheduler.runNextTask());
      }
      __nesc_enable_interrupt();
      signal Boot.booted();
      call Scheduler.taskLoop();
      return -1;
    }
    default command error_t PlatformInit.init() { return SUCCESS; }
    default command error_t SoftwareInit.init() { return SUCCESS; }
    default event void Boot.booted() { }
  }

4.1 Initialization
--------------------------------------------------------------------

The first step in the boot sequence is initializing the system::

  atomic {
    platform_bootstrap();
    call Scheduler.init();
    call PlatformInit.init();
    while (call Scheduler.runNextTask());
    call SoftwareInit.init();
    while (call Scheduler.runNextTask());
  }

The first call, platform_bootstrap(), is a minimalist function that
places the system into an executable state. This function MUST NOT include
operations besides those which are absolutely necessary for further code,
such as scheduler initialization, to execute.
Examples of platform_bootstrap() operations are configuring the memory
system and setting the processor mode. Generally, platform_bootstrap() 
is an empty function. TinyOS's top-level include file, ``tos.h``, includes
a default implementation of this function which does nothing. If a platform
needs to replace the default, it SHOULD put it in a platform's
``platform.h`` file as a #define. The implementation of ``tos.h``