tep101.txt

tinyos-2.x.rar

  interface ReadNow< size_type >
  
Every data collection interface is associated with an ``AdcConfigure``
interface (how this association is realized is explained in Section `4.  HIL
requirements`_).  As the resolution of conversion results is chip-specific, the
``size_type`` parameter reflects an upper bound for the chip-specific
resolution of the conversion results - the actual resolution may be smaller
(e.g.  uint16_t for a 12-bit ADC).

Read
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The ``Read`` interface can be used to sample an ADC channel once and return a
single conversion result as an uninterpreted value. The ``Read`` interface is
documented in [TEP114]_.

ReadStream
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The ``ReadStream`` interface can be used to sample an ADC channel multiple
times with a specified sampling period. The ``ReadStream`` interface is
documented in [TEP114]_ .

ReadNow
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The ``ReadNow`` interface is intended for split-phase low-latency
reading of small values::

  interface ReadNow<val_t> 
  {
    async command error_t read();
    async event void readDone( error_t result, val_t val );
  }

This interface is similar to the ``Read`` interface, but works in asynchronous
context. A successful call to ``ReadNow.read()`` means that the ADC hardware
has started the sampling process and that ``ReadNow.readDone()`` will be
signalled once it has finished (note that the asynchronous
``ReadNow.readDone()`` might be signalled even before the call to
``ReadNow.read()`` has returned).  Due to its timing constraints the
``ReadNow`` interface is always provided in conjunction with an instance of the
``Resource`` interface and a client must reserve the ADC through the
``Resource`` interface before the client may call ``ReadNow.read()``.  Please
refer to [TEP108]_ on how the ``Resource`` interface should be used by a client
component.


3. HAL guidelines
====================================================================

As explained in `1. Introduction`_ the HAL exposes the full capabilities of the
ADC hardware. Therefore only chip- and platform-dependent clients can wire to
the HAL. Although the HAL is chip-specific, both, in terms of implementation
and representation, its design should follow the guidelines described in this
section to facilitate the mapping to the HIL representation. Appendix B shows
the signature of the HAL for the MSP430.

Resource reservation
--------------------------------------------------------------------

As the ADC hardware is a shared resource that is usually multiplexed between
several clients some form of access arbitration is necessary.  The HAL should
therefore provide a parameterized ``Resource`` interface, instantiate a
standard 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. Resource
arbiters and the ``Resource`` interface are the topic of [TEP108]_.

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

As the ADC hardware is a shared resource the HAL should support hardware
configuration and sampling per client (although per-port configuration is
possible, it is not recommended, because it forces all clients to use the same
configuration for a given port).  Therefore the HAL should provide sampling
interfaces parameterized by a client identifier. A HAL client can use its
instance of the sampling interface to configure the ADC hardware, start the
sampling process and acquire conversion results. It wires to a sampling
interface using a unique client identifier (this may be hidden by a
virtualization component). All commands and events in the sampling interface
should be 'async' to reflect the potential timing requirements of clients on
the level of HAL. A HAL 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
configuration data is passed as a pointer, the HAL component MUST NOT reference
it after the return of the respective command.  Appendix B shows the HAL
interfaces for the MSP430.

HAL virtualization
--------------------------------------------------------------------

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 HAL.
Such components can also be used to ensure that a sampling interface is always
provided with a ``Resource`` interface and both are instantiated with the same
client ID if this is required by the HAL implementation.


4. HIL requirements
====================================================================

The following generic components MUST be provided on all platforms that have an
ADC::

  AdcReadClientC 
  AdcReadNowClientC 
  AdcReadStreamClientC 

These components provide virtualized access to the HIL of an ADC. They are
instantiated by an ADC client and provide/use the four interfaces described in
Section `2.  Interfaces`_. An ADC client may instantiate multiple such
components. The following paragraphs describe their signatures. Note that this
TEP does not address the issue of how to deal with multiple ADCs on the same
platform (the question of how to deal with multiple devices of the same class
is a general one in TinyOS 2.x). Appendix C shows the ``AdcReadClientC`` for
the MSP430.


AdcReadClientC
--------------------------------------------------------------------
::

  generic configuration AdcReadClientC() {
    provides {
      interface Read< size_type >;
    }
    uses {
      interface AdcConfigure< config_type >;
    }
  }

The ``AdcReadClientC`` component provides a ``Read`` interface for acquiring
single conversion results. The associated ADC channel (port) and further
configuration details are returned by the ``AdcConfigure.getConfiguration()``
command. It is the task of the client to wire this interface to a component
that provides the client's ADC configuration. The HIL implementation will use
the ``AdcConfigure`` interface to dynamically "pull" the client's ADC settings
when it translates the ``Read.read()`` command to a chip-specific sampling
command.  Note that both, ``size_type`` and ``config_type``, are only
placeholders and will be instantiated by the respective HIL implementation (for
an example, see the AdcReadClientC for the MSP430 in Appendix C).

AdcReadNowClientC
--------------------------------------------------------------------
::

  generic configuration AdcReadNowClientC() {
    provides {
      interface Resource;
      interface ReadNow< size_type >;
    }
    uses {
      interface AdcConfigure< config_type >;
    }
  }

The ``AdcReadNowClientC`` component provides a ``ReadNow`` interface for
acquiring single conversion results. In contrast to ``Read.read()`` when a call
to ``ReadNow.read()`` succeeds, the ADC starts to sample the channel
immediately (a successful ``Read.read()`` command may not have this
implication, see [TEP114]_ and `2. Interfaces`_). A client MUST reserve the ADC
through the ``Resource`` interface before the client may call
``ReadNow.read()`` and it MUST release the ADC through the ``Resource``
interface when it no longer needs to access it (for more details on how to use
the ``Resource`` interface please refer to [TEP108]_).  The associated ADC
channel (port) and further configuration details are returned by the
``AdcConfigure.getConfiguration()`` command. It is the task of the client to
wire this interface to a component that provides the client's ADC
configuration.  The HIL implementation will use the ``AdcConfigure`` interface
to dynamically "pull" the client's ADC settings when it translates the
``ReadNow.read()`` command to a chip-specific sampling command. Note that both,
``size_type`` and ``config_type``, are only placeholders and will be
instantiated by the respective HIL implementation (for an example how this is
done for the AdcReadClientC see Appendix C).

AdcReadStreamClientC
--------------------------------------------------------------------
::

  generic configuration AdcReadStreamClientC() {
    provides {
      interface ReadStream< size_type >;
    }
    uses {
      interface AdcConfigure< config_type>;
    }
  }

The ``AdcReadStreamClientC`` component provides a ``ReadStream`` interface for
acquiring multiple conversion results at once. The ``ReadStream`` interface is
explained in [TEP114]_ and `2. Interfaces`_. The ``AdcConfigure`` interface is
used in the same way as described in the section on the ``AdcReadClientC``.
Note that both, ``size_type`` and ``config_type``, are only placeholders and
will be instantiated by the respective HIL implementation (for an example how
this is done for the AdcReadClientC see Appendix C).