Add SharedSplitControlC, for N clients needing shared access to something.

[tinyos-2.x.git] / doc / txt / tep107.txt

diff --git a/doc/txt/tep107.txt b/doc/txt/tep107.txt
index 3ea5ec68667f8738bf77c2bb3826b5e61e4af8bd..18465422927bf61197593ea1d222638e682c6809 100644 (file)
--- a/doc/txt/tep107.txt
+++ b/doc/txt/tep107.txt
@@ -5,15 +5,10 @@ TinyOS 2.x Boot Sequence
 :TEP: 107
 :Group: Core Working Group 
 :Type: Documentary
-:Status: Draft
+:Status: Final
 :TinyOS-Version: 2.x
 :Author: Philip Levis 
 
-:Draft-Created: 10-Dec-2004
-:Draft-Version: $Revision$
-:Draft-Modified: $Date$
-:Draft-Discuss: TinyOS Developer List <tinyos-devel at mail.millennium.berkeley.edu>
-
 .. Note::
 
    This memo documents a part of TinyOS for the TinyOS Community, and
@@ -162,6 +157,7 @@ Layer (TEP 2) SHOULD wire to MainC and not RealMainP::
   implementation {
     int main() __attribute__ ((C, spontaneous)) {
       atomic {
+        platform_bootstrap();
         call Scheduler.init();
         call PlatformInit.init();
         while (call Scheduler.runNextTask());
@@ -198,8 +194,18 @@ 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. The platform_bootstrap() function SHOULD be
-specified in a platform's ``hardware.h`` file. 
+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`` 
+supports this::
+
+  /* This platform_bootstrap macro exists in accordance with TEP
+     107. A platform may override this through a platform.h file. */
+  #include <platform.h>
+  #ifndef platform_bootstrap
+  #define platform_bootstrap() {}
+  #endif
 
 The boot sequence has three separate initializations: Scheduler,
 PlatformInit, and SoftwareInit. The boot configuration (MainC) wires
@@ -237,12 +243,9 @@ hardware, the sequence is platform-specific. A port of TinyOS to a
 new plaform MUST include a component PlatformC which provides
 one and only one instance of the Init interface.
 
-Generally, component intialization occurs through SoftwareInit.
-PlatformInit is for a small subset of initializations whose properties
-requires that they be performed separately. Initializations invoked
+Initializations invoked
 through PlatformC meet some or all of the following criteria:
 
-
 1. The initialization requires configuring hardware resources. This implies that the code is platform-specific. 
 
 2. The initialization should always be performed.
@@ -260,6 +263,15 @@ nominally meets all three criteria, the most important one is the third:
 as LEDs are often needed during SoftwareInit initialization, they must
 be set up before it is invoked.
 
+Note that not all code which meets some of these criteria is wired through 
+PlatformC. In particular, criterion 1 is typically necessary but not 
+sufficient to require PlatformC. For example, a timer system that
+configures overflow and capture settings or  a UART stack that sets the
+baud rate and transmission options can often be wired to SoftwareInit.
+They are encapsulated abstractions which will not be invoked or
+started until the boot event, and only need to be configured if the 
+system includes their functionality.
+
 Components whose initialization does not directly depend on hardware
 resources SHOULD wire to MainC.SoftwareInit. If a component requires a
 specific initialization ordering, then it is responsible for