[Tinyos-2-commits] CVS: tinyos-2.x/doc/txt tep101.txt, 1.1.2.6, 1.1.2.7

Fri Jul 14 10:01:17 PDT 2006

Update of /cvsroot/tinyos/tinyos-2.x/doc/txt
In directory sc8-pr-cvs10.sourceforge.net:/tmp/cvs-serv13783/doc/txt

Modified Files:
      Tag: tinyos-2_0_devel-BRANCH
	tep101.txt 
Log Message:
Integrated the changes discussed during the last working group telephone conference:
- removed remarks about how the Resource interface must be used (instead included a reference to TEP108)
- made section 3 (HAL1 requirements) less restrictive (SHOULD => should, inserted a recommendation for the round robin arbiter)
- added missing link in Introduction to point to section 6 (Implementation)

Index: tep101.txt
===================================================================
RCS file: /cvsroot/tinyos/tinyos-2.x/doc/txt/tep101.txt,v
retrieving revision 1.1.2.6
retrieving revision 1.1.2.7
diff -C2 -d -r1.1.2.6 -r1.1.2.7
*** tep101.txt	14 Jun 2006 17:53:45 -0000	1.1.2.6
--- tep101.txt	14 Jul 2006 17:01:14 -0000	1.1.2.7
***************
*** 36,40 ****

  Analog-to-digital converters (ADCs) are devices that convert analog input
! signals to discrete digital output signals, typically voltage to a digital
  number.  The interested reader can refer to Appendix A for a brief overview of
  the ADC hardware on some current TinyOS platforms.  In earlier versions of
--- 36,40 ----

  Analog-to-digital converters (ADCs) are devices that convert analog input
! signals to discrete digital output signals, typically voltage to a binary
  number.  The interested reader can refer to Appendix A for a brief overview of
  the ADC hardware on some current TinyOS platforms.  In earlier versions of
***************
*** 88,95 ****
  * the set of platform-independent interfaces for the collection of ADC
    conversion results (`2. Interfaces`_)
! * guidelines on how an ADC's HAL SHOULD should be split into HAL1 and HAL2 and
!   how the HAL1 SHOULD expose chip-specific interfaces (`3. HAL1 guidelines`_)
  * what components an ADC's HAL2 MUST implement (`4. HAL2 requirements`_)
  * guidelines on how the HAL2 may be structured (`5. HAL2 implementation guidelines`_)

  This TEP ends with appendices documenting, as an example, the ADC
--- 88,97 ----
  * the set of platform-independent interfaces for the collection of ADC
    conversion results (`2. Interfaces`_)
! * guidelines on how an ADC's HAL should be split into HAL1 and HAL2 and
!   how the HAL1 should expose chip-specific interfaces (`3. HAL1 guidelines`_)
  * what components an ADC's HAL2 MUST implement (`4. HAL2 requirements`_)
  * guidelines on how the HAL2 may be structured (`5. HAL2 implementation guidelines`_)
+ * a section pointing to the current implementation (`6. Implementation`_)
+ 

  This TEP ends with appendices documenting, as an example, the ADC
***************
*** 132,138 ****
  channel immediately (the request is not buffered). Due to its timing
  constraints the ReadNow interface is always provided in conjunction with an
! instance of the Resource interface. A client MUST request access to the ADC
! via the Resource interface before it can call ReadNow.read() and it MUST
! release access via the Resource interface when it is finished (see [TEP108]_).

  ReadStream
--- 134,140 ----
  channel immediately (the request is not buffered). Due to its timing
  constraints the ReadNow interface is always provided in conjunction with an
! instance of the Resource interface. Refer to [TEP108]_ on how the 'Resource'
! interface should be used by a client component.
! 

  ReadStream
***************
*** 154,158 ****
  HAA [TEP2]_. Therefore only chip- and platform-dependent clients MAY wire to
  the HAL1. Although the HAL1 is chip-specific, both, in terms of implementation
! and representation, its design SHOULD follow the guidelines described below to
  facilitate the mapping to platform-independent interfaces on the level of
  HAL2. Appendix B shows the HAL1 specification for the TI MSP430 MCU.
--- 156,160 ----
  HAA [TEP2]_. Therefore only chip- and platform-dependent clients MAY wire to
  the HAL1. Although the HAL1 is chip-specific, both, in terms of implementation
! and representation, its design should follow the guidelines described below to
  facilitate the mapping to platform-independent interfaces on the level of
  HAL2. Appendix B shows the HAL1 specification for the TI MSP430 MCU.
***************
*** 163,193 ****
  As the ADC hardware is a shared resource that is multiplexed between several
  clients, it requires access arbitration. Therefore the HAL1 configuration
! component SHOULD provide a parameterized 'Resource' interface, instantiate a
  generic arbiter component and connect the 'Resource' interface to the arbiter
! as described in [TEP108]_. To provide a uniform arbitration service for all
! platforms on the level of HAL2 (see `4. HAL2 requirements`_), all ADCs should
! be arbitrated in round robin fashion, i.e. the HAL1 SHOULD instantiate the
! standard round robin arbiter. On the level of HAL1 a client MUST have
! successfully requested access to the ADC via the 'Resource' interface before
! it can configure / sample a channel. After use it MUST release the ADC via the
! 'Resource' interface (see [TEP108]_).

  Configuration and sampling
  --------------------------------------------------------------------

! As the ADC hardware is a shared resource the HAL1 SHOULD support hardware
  configuration and sampling on a per-client basis (although per-port
  configuration is possible, it is not recommended, because it forces all
! clients to use the same settings for a given port). Therefore an HAL1 SHOULD
! provide "sampling interfaces" parameterized by a client identifier. An HAL1
  client can use its instance of the sampling interface to configure the ADC
  hardware, start the sampling process and get conversion results. It wires to a
  sampling interface using a unique client identifier. All commands and events
! in the sampling interface SHOULD be 'async' to reflect the potential timing
! requirements of clients. An HAL1 MAY provide multiple different parameterized
  sampling interfaces, depending on the hardware capabilities.  This allows to
  differentiate/group ADC functionality, for example single vs.  repeated
  sampling, single channel vs. multiple channels or low-frequency vs.
! high-frequency sampling.  Every sampling interface SHOULD allow the client to
  individually configure the ADC hardware, for example by including the
  configuration data as parameters in the sampling commands.  However, if
--- 165,191 ----
  As the ADC hardware is a shared resource that is multiplexed between several
  clients, it requires access arbitration. Therefore the HAL1 configuration
! component should provide a parameterized 'Resource' interface, instantiate a
  generic arbiter component and connect the 'Resource' interface to the arbiter
! as described in [TEP108]_. To ensure fair and uniform arbitration on all
! platforms the standard round robin arbiter is recommended. Refer to [TEP108]_
! on how the 'Resource' interface is to be used by a client wiring to HAL1.

  Configuration and sampling
  --------------------------------------------------------------------

! As the ADC hardware is a shared resource the HAL1 should support hardware
  configuration and sampling on a per-client basis (although per-port
  configuration is possible, it is not recommended, because it forces all
! clients to use the same settings for a given port). Therefore an HAL1 should
! provide sampling interfaces parameterized by a client identifier. An HAL1
  client can use its instance of the sampling interface to configure the ADC
  hardware, start the sampling process and get conversion results. It wires to a
  sampling interface using a unique client identifier. All commands and events
! in the sampling interface should be 'async' to reflect the potential timing
! requirements of clients. An HAL1 may provide multiple different parameterized
  sampling interfaces, depending on the hardware capabilities.  This allows to
  differentiate/group ADC functionality, for example single vs.  repeated
  sampling, single channel vs. multiple channels or low-frequency vs.
! high-frequency sampling.  Every sampling interface should allow the client to
  individually configure the ADC hardware, for example by including the
  configuration data as parameters in the sampling commands.  However, if
***************
*** 200,204 ****

  In order to hide wiring complexities and/or export only a subset of all ADC
! functions generic ADC wrapper components MAY be provided on the level of HAL1
  to be instantiated by chip- and platform-dependent clients.

--- 198,202 ----

  In order to hide wiring complexities and/or export only a subset of all ADC
! functions generic ADC wrapper components may be provided on the level of HAL1
  to be instantiated by chip- and platform-dependent clients.