[Tinyos-beta-commits] CVS: tinyos-1.x/beta/teps/txt tep101.txt, 1.8, 1.9 tep3.txt, 1.9, 1.10

Mon Jun 6 14:28:23 PDT 2005

Update of /cvsroot/tinyos/tinyos-1.x/beta/teps/txt
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv24481

Modified Files:
	tep101.txt tep3.txt 
Log Message:
Removed a formatting error in tep3.txt.

Edited tep101 to more closely represent document tone and intent. Added
an additional MUST: the presence of a HAL2. Otherwise, it's hard to
say what being tep101 compliant is...

Index: tep101.txt
===================================================================
RCS file: /cvsroot/tinyos/tinyos-1.x/beta/teps/txt/tep101.txt,v
retrieving revision 1.8
retrieving revision 1.9
diff -C2 -d -r1.8 -r1.9
*** tep101.txt	31 May 2005 01:14:31 -0000	1.8
--- tep101.txt	6 Jun 2005 21:28:19 -0000	1.9
***************
*** 38,53 ****
  Analog-to-digital converters (ADCs) are devices that convert analog
  input signals to discrete digital output signals, typically voltage to
! a digital number. The ADCs used in TinyOS differ in many respects (see
! `Hardware differences between the current platforms`_). This makes it
! difficult to find a chip independent representation for ADCs. Even if
! there were such a representation, the configuration details of an ADC
! still depend on the actual device (sensor) producing the input
! signal. Neither a platform independent application nor the ADC
! hardware stack itself has access to this information, which can only
! be determined on a platform or sensorboard level. For example,
! determining which ADC port a certain sensor is attached to and how a
! conversion result needs to be interpreted is a platform specific
! determination. Thus ADCs themselves are not well suited to a platform
! independent (HIL) representation.

  Although ADCs are very platform specific, there are commonalities
--- 38,67 ----
  Analog-to-digital converters (ADCs) are devices that convert analog
  input signals to discrete digital output signals, typically voltage to
! a digital number. In earlier versions of TinyOS, the distinction
! between a sensor and an ADC were blurred: this led components that had
! nothing to do with an ADC to still resemble one programatically, even
! though the semantics and forms of operation were completely
! different. This led non-ADC sensors to introduce new interfaces, such
! as ADCError, that were tightly bound to sensor acquisition but
! separate in wiring. The separation between the ADC and ADCError
! interface is bug prone and problematic, as is the equation of a sensor
! and an ADC. TinyOS 2.x separates the structure and interfaces of an
! ADC from those of sensors (which may be on top of an ADC, but this is
! hidden from higher level components). This TEP presents how TinyOS 2.x
! decomposes and structures ADC software. TEP 109 (Sensorboards) presents how a
! platform can present actual named sensors [tep109]_.
! 
! TinyOS platforms are based on many different hardware chips, whose
! ADCs differ in many respects (see `Hardware differences between the
! current platforms`_).  This makes it difficult to find a chip
! independent representation for ADCs. Even if there were such a
! representation, the configuration details of an ADC still depend on
! the actual device (sensor) producing the input signal. Neither a
! platform independent application nor the ADC hardware stack itself has
! access to this information, which can only be determined on a platform
! or sensorboard level. For example, determining which ADC port a
! certain sensor is attached to and how a conversion result needs to be
! interpreted is a platform specific determination. Thus ADCs themselves
! are not well suited to a platform independent (HIL) representation.

  Although ADCs are very platform specific, there are commonalities
***************
*** 78,111 ****
  The highest layer of abstraction, the HIL, is composed of named sensor
  components that provide interfaces only for acquiring the
! corresponding data (TEP 109). However, many sensors sit on top of a
! shared hardware ADC.

! As the ADC hardware can be multiplexed between several client
! applications, it requires access arbitration.  The ADC stack uses a
! library of standard TinyOS resource management modules, such as
! AcquireDataRoundRobinM, to arbitrate access. These generic arbitration
! modules use parameterized AcquireData[Now] (and Resource) interfaces.
! An ADC hardware stack that supports arbitration of its input channels
! therefore incorporates a layer providing these interfaces for standard
! arbiter components to use. The parameter to such a parameterized
! interface defines the sensor or, more precisely, the ADC input
! channel. An input channel is the most natural representation on this
! level of abstraction, because a common denominator of all ADCs is that
! they sample an input channel and produce conversion results. Thus one
! level of abstraction of the ADC is a parameterized AcquireData
! interface, where the parameter defines the ADC input channel to be
! sampled. This level of abstraction, however, is not a HIL
  representation, because choosing an input channel is a platform or
  sensorboard specific decision (as a platform independent application
! would not know which channel to choose).  Instead, this layer provides
! a platform dependent HAL interface. It is important to note that the
! implementation of this HAL is, however, chip dependent and platform
! independent, while the instantiation is performed on a platform level
! (for an example, see below).

  There is also need for an HAL in the 'traditional' sense of the
! Hardware Abstraction Architecture (HAA): An HAL that offers access to
! all the chip specific capabilities via a chip specific interface.
! Below this HAL the lowest layer is, as usual, composed of the HPL. 

  An example for a component stack of a platform independent application
--- 92,132 ----
  The highest layer of abstraction, the HIL, is composed of named sensor
  components that provide interfaces only for acquiring the
! corresponding data [tep109]_.

! Many sensors sit on top of a shared hardware ADC, however. As the ADC
! hardware is a shared resource that is multiplexed between several
! clients, it requires access arbitration.  The Service layer provides
! this level of ADC abstraction. The Service layer uses a library of
! standard TinyOS resource management modules, such as
! AcquireDataRoundRobinM (found in tos/lib/adc), to arbitrate access to
! underlying ADC abstractions. These generic arbitration modules use
! parameterized intefaces, where the parameterization follows the
! Service Instance pattern to represent arbitration
! clients [sipattern]_.
! 
! The highest level of actual ADC abstraction -- HAL2, which sensors
! interact with -- is composed of three parameterized interfaces:
! AcquireData, AcquireDataNow, and Resource.  An ADC hardware stack that
! supports arbitration of its input channels therefore MUST incorporate
! a layer providing these interfaces for standard arbiter components to
! use. The parameter to these parameterized interface defines the sensor
! or, more precisely, the ADC input channel. An input channel is the
! most natural representation on this level of abstraction, because a
! common denominator of all ADCs is that they sample an input channel
! and produce conversion results.
! 
! Although HAL2 is common across many ADCs, it is *not* a HIL
  representation, because choosing an input channel is a platform or
  sensorboard specific decision (as a platform independent application
! would not know which channel to choose).  Instead, this layer is a
! platform dependent HAL interface. The implementation HAL2 is chip
! dependent and platform independent, and instantiation is performed on
! a platform level (for an example, see below).

  There is also need for an HAL in the 'traditional' sense of the
! Hardware Abstraction Architecture (HAA): a HAL that offers access to
! all the chip specific capabilities via a chip specific interface. This
! HAL is called HAL1. HAL1 resembles a standard HAL in the HAA; the HPL
! lies below it.

  An example for a component stack of a platform independent application
***************
*** 174,180 ****
  ====================================================================

! Currently two different on-chip ADCs are in use for TinyOS, the ADC of
! the Atmel ATmega 128 and the ADC12 of TI MSP430.  Their
! characteristics are compared in the following table:

  +----------------------+----------------------+---------------------+
--- 195,204 ----
  ====================================================================

! The TI MSP430 and the Atmel ATmega 128 are two common microcontrollers
! used in TinyOS platforms. They both have integrated ADCs, but have
! very different functionality and capabilities. These distinctions
! illustrate the complexities that prevent ADCs from having a truly
! hardware independent abstraction. The following table comparse the
! characteristics of the two microcontrollers:

  +----------------------+----------------------+---------------------+
***************
*** 256,260 ****
  As explained in the `Overview`_ the HAL consists of two sublayers.  To
  differentiate the two Hardware Adaptation 'sub'Layers they are called
! HAL2 (for the HAL providing a parameterized AcquireData[Now]
  interface) and HAL1 (for the 'traditional' HAL). In the hardware stack
  for the ADC the HAL1 resides below HAL2, i.e. HAL2 uses the primitives
--- 280,284 ----
  As explained in the `Overview`_ the HAL consists of two sublayers.  To
  differentiate the two Hardware Adaptation 'sub'Layers they are called
! HAL2 (for the HAL providing a parameterized AcquireData and AcquireData
  interface) and HAL1 (for the 'traditional' HAL). In the hardware stack
  for the ADC the HAL1 resides below HAL2, i.e. HAL2 uses the primitives
***************
*** 308,314 ****
         for all other requests, therefore an application SHOULD
         minimize this reservation period. Every application MUST
!        conform to this policy. The HAL1 will NOT check at runtime
!        whether a data request maps to the application that has
!        reserved the ADC. 

         ii. The MSP430ADC12SingleChannel interface includes four
--- 332,338 ----
         for all other requests, therefore an application SHOULD
         minimize this reservation period. Every application MUST
!        conform to this policy. The HAL1 MAY check at runtime whether a
!        data request maps to the application that has reserved the ADC, but
!        a caller MUST NOT assume it does.

         ii. The MSP430ADC12SingleChannel interface includes four
***************
*** 342,356 ****

         An application needs to implement an event handler for the
!        MSP430ADC12SingleChannel.getConfigurationData() event. This event 
!        handler MUST return the configuration data for the channel
!        the application wants to sample. The event MAY be signalled
!        multiple times by HAL1 and the application MUST always return  
!        the same configuration data. 
!        This approach (in contrast to a command) has the
!        advantage that HAL1 does not need to maintain a table 
!        of configuration data in RAM. Instead configuration data is 
!        retrieved from the application at runtime whenever needed.
!        The application SHOULD keep configuration data in program
!        memory (flash), not in RAM. 

         The *getData* commands use the four different conversion modes
--- 366,380 ----

         An application needs to implement an event handler for the
!        MSP430ADC12SingleChannel.getConfigurationData() event. This
!        event handler MUST return the configuration data for the
!        channel the application wants to sample. The event MAY be
!        signalled multiple times by HAL1 and the application MUST
!        return the same configuration data for each of these
!        events. This approach (in contrast to a command) has the
!        advantage that HAL1 does not need to maintain a table of
!        configuration data in RAM. Instead configuration data is
!        retrieved from the application at runtime whenever needed.  The
!        application SHOULD keep configuration data in program memory
!        (flash), not in RAM.

         The *getData* commands use the four different conversion modes
***************
*** 520,524 ****
  mentioned in the `Introduction`_. Instead named sensor wrappers
  provide platform independent access to the ADC which is covered in TEP
! 109 (Sensorboards).  

  Implementation
--- 544,548 ----
  mentioned in the `Introduction`_. Instead named sensor wrappers
  provide platform independent access to the ADC which is covered in TEP
! 109 [tep109]_.  

  Implementation
***************
*** 561,562 ****
--- 585,592 ----

+ 5. Citations
+ ====================================================================
+ 
+ .. [sipattern] The Service Instance Pattern. In *Software Design Patterns for TinyOS.* David Gay, Philip Levis, and David Culler. Published in Proceedings of the ACM SIGPLAN/SIGBED 2005 Conference on Languages, Compilers, and Tools for Embedded Systems (LCTES'05).
+ 
+ .. [tep109] TEP 109: Sensorboards. David Gay, Wei Hong, Philip Levis, and Joe Polastre.

Index: tep3.txt
===================================================================
RCS file: /cvsroot/tinyos/tinyos-1.x/beta/teps/txt/tep3.txt,v
retrieving revision 1.9
retrieving revision 1.10
diff -C2 -d -r1.9 -r1.10
*** tep3.txt	24 Mar 2005 21:39:21 -0000	1.9
--- tep3.txt	6 Jun 2005 21:28:19 -0000	1.10
***************
*** 229,236 ****
    - Functions should be lower case, words separated by underscores,
      prefixed by package.
!   - Function macros (`#define`s) should be all upper case, words separated
      by underscores, prefixed by package.

!     - Use of function macros is discouraged: use `inline` functions.
    - Constants should be all upper case, words separated by underscores,
      prefixed by package.
--- 229,237 ----
    - Functions should be lower case, words separated by underscores,
      prefixed by package.
!   - Function macros (`#define` ) should be all upper case, words separated
      by underscores, prefixed by package.

!     - Using function macros is discouraged: use `inline` functions.
! 
    - Constants should be all upper case, words separated by underscores,
      prefixed by package.