[Tinyos-2-commits] CVS: tinyos-2.x/doc/txt tep101.txt, 1.1.2.8,
1.1.2.9
Jan-Hinrich Hauer
janhauer at users.sourceforge.net
Thu Oct 12 10:02:39 PDT 2006
Update of /cvsroot/tinyos/tinyos-2.x/doc/txt
In directory sc8-pr-cvs10.sourceforge.net:/tmp/cvs-serv31095/doc/txt
Modified Files:
Tag: tinyos-2_0_devel-BRANCH
tep101.txt
Log Message:
Updated as agreed on last telephone conference:
* configuration is done with the AdcConfigure (not Configure) interface
* added a sentence about pointer-passing semantics in AdcConfigure (don't dereference after return)
* integrated the (cosmetic) fixes proposed by David G.
Index: tep101.txt
===================================================================
RCS file: /cvsroot/tinyos/tinyos-2.x/doc/txt/tep101.txt,v
retrieving revision 1.1.2.8
retrieving revision 1.1.2.9
diff -C2 -d -r1.1.2.8 -r1.1.2.9
*** tep101.txt 9 Oct 2006 11:05:59 -0000 1.1.2.8
--- tep101.txt 12 Oct 2006 17:02:37 -0000 1.1.2.9
***************
*** 51,70 ****
sensors [TEP109]_.
! As can be seen in Appendix A the ADC hardware used on TinyOS platforms differ in
! many respects, which makes it difficult to find a chip independent
representation for an ADC. Even if there were such a representation, the
configuration details of an ADC would still depend on the actual device
! producing the input signal (sensor). Neither a platform independent application
! nor the ADC hardware stack itself has access to this information, as it can only
! be determined on a platform or sensorboard level. For example, determining which
! ADC port a sensor is attached to and how a conversion result is to be
! interpreted is a platform-specific determination. However, in a similar way as
! the message buffer abstraction ``message_t`` is declared per link layer (see
! [TEP111]_), an ADC configuration abstraction can be declared per ADC chip and
! still be passed between components using standard TinyOS interfaces. This TEP
! proposes the ``AdcConfigure`` interface as the standard interface for
! configuring an ADC in TinyOS 2.x. It describes how an ADC configuration
! structure is declared per ADC chip and that a **platform** is responsible to
! define the configuration for every sensor attached to the ADC.
In spite of their hardware differences, one aspect represents a common
--- 51,75 ----
sensors [TEP109]_.
! As can be seen in Appendix A the ADC hardware used on TinyOS platforms differ
! in many respects, which makes it difficult to find a chip independent
representation for an ADC. Even if there were such a representation, the
configuration details of an ADC would still depend on the actual device
! producing the input signal (sensor). Neither a platform independent
! application nor the ADC hardware stack itself has access to this information,
! as it can only be determined on a platform or sensorboard level. For example,
! determining which ADC port a sensor is attached to and how conversion results
! need to be interpreted is a platform specific determination. Although the
! actual configuration details may be different the procedure of configuring an
! ADC can be unified on all ADCs with the help of **hardware independent
! interfaces**: in a similar way as the ``Read`` interface definition does not
! predefine the type or semantics of the exchanged data (see [TEP114]_), a
! configuration interface definition can abstract from the data type and
! semantics of the involved configuration settings. For example, like a
! component can provide a ``Read<uint8_t>`` or ``Read<uint16_t>`` interface
! depending on the data it can offer, a component can also use a
! ``AdcConfigure<atm128_adc_config_t>`` or
! ``AdcConfigure<msp430adc12_channel_config_t>`` interface depending on what ADC
! it represents. This TEP proposes the (typed) ``AdcConfigure`` interface as the
! standard interface for configuring an ADC in TinyOS 2.x.
In spite of their hardware differences, one aspect represents a common
***************
*** 84,88 ****
``ReadStream`` and uses the ``AdcConfigure`` interface for hardware
configuration (why it **uses** and does not **provide** ``AdcConfigure`` is
! explained below).
Following the principles of the HAA [TEP2]_ the Hardware Adaptation Layer (HAL,
--- 89,95 ----
``ReadStream`` and uses the ``AdcConfigure`` interface for hardware
configuration (why it **uses** and does not **provide** ``AdcConfigure`` is
! explained below). Since the type and semantics of the parameters passed
! through these interfaces is dependent on the actual ADC implementation, it is
! only a "weak" HIL (see [TEP2]_).
Following the principles of the HAA [TEP2]_ the Hardware Adaptation Layer (HAL,
***************
*** 91,97 ****
"Repeat-Sequence-of-Channels Mode" and therefore this function should be
accessible on the HAL of the **MSP430 ADC12** hardware abstraction. Other ADCs
! might not exhibit such functionality and might therefore - on the level of HAL -
! provide only an interface to perform single conversions. Since all ADCs have the
! same HIL representation it may thus be necessary to perform some degree of
software emulation in the HIL implementation. For example, a ``ReadStream``
command can be emulated by multiple single conversion commands. Below the HAL
--- 98,104 ----
"Repeat-Sequence-of-Channels Mode" and therefore this function should be
accessible on the HAL of the **MSP430 ADC12** hardware abstraction. Other ADCs
! might not exhibit such functionality and might therefore - on the level of HAL
! - provide only an interface to perform single conversions. Since all ADCs have
! the same HIL representation it may thus be necessary to perform some degree of
software emulation in the HIL implementation. For example, a ``ReadStream``
command can be emulated by multiple single conversion commands. Below the HAL
***************
*** 104,108 ****
| |
| Read,
! AdcConfigure ReadNow (+ Resource),
| ReadStream
| |
--- 111,115 ----
| |
| Read,
! AdcConfigure ReadNow (+ Resource),
| ReadStream
| |
***************
*** 114,119 ****
|
|
! chip-specific interface(s) + Resource
! (e.g. Msp430Adc12SingleChannel)
|
V
--- 121,126 ----
|
|
! chip-specific interface(s) + Resource
! (e.g. Msp430Adc12SingleChannel + Resource)
|
V
***************
*** 155,159 ****
and the ``Read``, ``ReadNow`` and ``ReadStream`` interfaces to acquire
conversion results. A ``Read[Now|Stream]`` interface is always provided in
! conjunction with an ``AdcConfigure`` interface.
Interface for configuring the ADC hardware
--- 162,166 ----
and the ``Read``, ``ReadNow`` and ``ReadStream`` interfaces to acquire
conversion results. A ``Read[Now|Stream]`` interface is always provided in
! conjunction with a ``AdcConfigure`` interface.
Interface for configuring the ADC hardware
***************
*** 162,179 ****
The ``AdcConfigure`` interface is defined as follows::
! interface AdcConfigure<adc_config_t>
{
! async command adc_config_t getConfiguration();
}
! This interface is used by the ADC implementation to retrieve the desired
! hardware configuration of an ADC client. ``adc_config_t`` is a chip-specific
! data type (simple or structured) that contains all information necessary to
! configure the respective ADC hardware. For example, on the ADC12 of the MSP430
! the ``AdcConfigure`` interface will be instantiated with the
! ``msp430adc12_channel_config_t`` structure. A client MUST always return the
! same configuration through an ``AdcConfigure`` interface. If a client wants to
! use the ADC with different configurations it must provide multiple instances of
! the ``AdcConfigure`` interface.
--- 169,188 ----
The ``AdcConfigure`` interface is defined as follows::
! interface AdcConfigure< config_type >
{
! async command config_type getConfiguration();
}
! This interface is used by the ADC implementation to retrieve the hardware
! configuration of an ADC client. ``config_type`` is a chip-specific data type
! (simple or structured) that contains all information necessary to configure the
! respective ADC hardware. For example, on the ADC12 of the MSP430 the
! ``AdcConfigure`` interface will be instantiated with the ``const
! msp430adc12_channel_config_t*`` data type. A client MUST always return the same
! configuration through a ``AdcConfigure`` interface and, if configuration data
! is passed as a pointer, the HIL component (see `4. HIL requirements`_) MUST NOT
! reference it after the return of the ``getConfiguration()`` command. If a
! client wants to use the ADC with different configurations it must provide
! multiple instances of the ``AdcConfigure`` interface.
***************
*** 189,199 ****
interface ReadStream< 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). The above interfaces are specified in [TEP114]_, in the
! following their usage is explained with respect to ADCs.
Read
--- 198,208 ----
interface ReadStream< 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). The above interfaces are specified in
! [TEP114]_, in the following their usage is explained with respect to ADCs.
Read
***************
*** 209,217 ****
The ``ReadNow`` interface is similar to the ``Read`` interface. The difference
is that if a call to ``ReadNow.read()`` succeeds, the ADC starts to sample the
! channel immediately (more precisely: when ``SUCCESS`` is returned the hardware
! has started the sampling process). Due to its timing constraints the ``ReadNow``
! interface is always provided in conjunction with an instance of the ``Resource``
! interface (a client must reserve the ADC before the client may call
! ``ReadNow.read()``). Please refer to [TEP108]_ on how the ``Resource``
interface should be used by a client component.
--- 218,226 ----
The ``ReadNow`` interface is similar to the ``Read`` interface. The difference
is that if a call to ``ReadNow.read()`` succeeds, the ADC starts to sample the
! channel immediately (precisely: when ``SUCCESS`` is returned the hardware has
! started the sampling process). Due to its timing constraints the ``ReadNow``
! interface is always provided in conjunction with an instance of the
! ``Resource`` interface (a client must reserve the ADC before the client may
! call ``ReadNow.read()``). Please refer to [TEP108]_ on how the ``Resource``
interface should be used by a client component.
***************
*** 239,247 ****
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. The meaning of resource
! arbiters and the ``Resource`` interface is the topic of [TEP108]_.
Configuration and sampling
--- 248,256 ----
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
***************
*** 252,256 ****
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. An 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
--- 261,265 ----
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
***************
*** 258,262 ****
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. An 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
--- 267,271 ----
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
***************
*** 285,303 ****
ADC::
! AdcReadClient
! AdcReadNowClient
! AdcReadStreamClient
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
! `2. Interfaces`_. An ADC client may instantiate multiple such components. The
! following paragraphs describe their signatures. Appendix C shows the
! ``AdcReadClient`` for the MSP430.
! AdcReadClient
--------------------------------------------------------------------
::
! generic configuration AdcReadClient() {
provides {
interface Read< size_type >;
--- 294,316 ----
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 >;
***************
*** 308,312 ****
}
! The ``AdcReadClient`` 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()``
--- 321,325 ----
}
! 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()``
***************
*** 317,327 ****
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 AdcReadClient for the MSP430 in Appendix C).
! AdcReadNowClient
--------------------------------------------------------------------
::
! generic configuration AdcReadNowClient() {
provides {
interface Resource;
--- 330,340 ----
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;
***************
*** 333,337 ****
}
! The ``AdcReadNowClient`` 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
--- 346,350 ----
}
! 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
***************
*** 350,360 ****
``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 AdcReadClient see Appendix C).
! AdcReadStreamClient
--------------------------------------------------------------------
::
! generic configuration AdcReadStreamClient() {
provides {
interface ReadStream< size_type >;
--- 363,373 ----
``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 >;
***************
*** 365,375 ****
}
! The ``AdcReadStreamClient`` 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 ``AdcReadClient``.
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 AdcReadClient see Appendix C).
5. HIL guidelines
--- 378,388 ----
}
! 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).
5. HIL guidelines
***************
*** 379,395 ****
``Read``, ``ReadNow`` or ``ReadStream`` request to a chip-specific HAL sampling
command and it abstracts from the ``Resource`` interface (the latter only for
! the ``AdcReadClient`` and ``AdcReadStreamClient``). The first task is solved
with the help of the ``AdcConfigure`` interface which is used by the HIL
implementation to retrieve a client's ADC configuration. The second task MAY
be performed by the following library components: ``ArbitratedReadC``, and
``ArbitratedReadStreamC`` (in tinyos-2.x/tos/system) - please refer to the
! Atmel Atmega 128 HAL implementation (in tinyos-2.x/tos/chips/atm128/adc), for
! an example. Note that since the ``ReadNow`` interface is always provided in
conjunction with a ``Resource`` interface the HIL implementation does not have
! to perform the ADC resource reservation for an ``AdcReadNowClient`, but may
simply forward an instance of the ``Resource`` interface from the HAL to the
! ``AdcReadNowClient``.
! The typical sequence of events is as follows: When a client requests data
through the ``Read`` or ``ReadStream`` interface the HIL will request access to
the HAL using the ``Resource`` interface. After the HIL has been granted
--- 392,408 ----
``Read``, ``ReadNow`` or ``ReadStream`` request to a chip-specific HAL sampling
command and it abstracts from the ``Resource`` interface (the latter only for
! the ``AdcReadClientC`` and ``AdcReadStreamClientC``). The first task is solved
with the help of the ``AdcConfigure`` interface which is used by the HIL
implementation to retrieve a client's ADC configuration. The second task MAY
be performed by the following library components: ``ArbitratedReadC``, and
``ArbitratedReadStreamC`` (in tinyos-2.x/tos/system) - please refer to the
! Atmel Atmega 128 HAL implementation (in tinyos-2.x/tos/chips/atm128/adc) for an
! example. Note that since the ``ReadNow`` interface is always provided in
conjunction with a ``Resource`` interface the HIL implementation does not have
! to perform the ADC resource reservation for an ``AdcReadNowClientC``, but may
simply forward an instance of the ``Resource`` interface from the HAL to the
! ``AdcReadNowClientC``.
! The typical sequence of events is as follows: when a client requests data
through the ``Read`` or ``ReadStream`` interface the HIL will request access to
the HAL using the ``Resource`` interface. After the HIL has been granted
***************
*** 417,421 ****
* ``AdcReadClientC.nc``, ``AdcReadNowClientC.nc`` and
``AdcReadStreamClientC.nc`` provide virtualized access to the HIL
! * Please refer to the ``README.txt`` to
The Atmel Atmega 128 ADC implementation can be found in
--- 430,435 ----
* ``AdcReadClientC.nc``, ``AdcReadNowClientC.nc`` and
``AdcReadStreamClientC.nc`` provide virtualized access to the HIL
! * the use of DMA or the reference voltage generator and the
! HAL virtualization components are explained in ``README.txt``
The Atmel Atmega 128 ADC implementation can be found in
***************
*** 429,436 ****
the HAL
* ``AdcReadClientC.nc``, ``AdcReadNowClientC.nc`` and
! ``AdcReadStreamClientC.nc`` provide access to the ADC on a per-client
! basis via the platform-independent interfaces 'Read', 'ReadNow' and
! 'ReadStream', respectively, and the atmega-specific ADC configuration
! interface ``Atm128AdcConfig.nc``
--- 443,447 ----
the HAL
* ``AdcReadClientC.nc``, ``AdcReadNowClientC.nc`` and
! ``AdcReadStreamClientC.nc`` provide virtualized access to the HIL
***************
*** 501,510 ****
! Appendix B: an HAL representation: MSP430 ADC12
====================================================================
! The following section shows the HAL signature for the ADC12 of the TI MSP430
! MCU. It reflects the four MSP430 ADC12 conversion modes as it lets a client
! sample an ADC channel once ("Single-channel-single-conversion") or repeatedly
("Repeat-single-channel"), multiple times ("Sequence-of-channels") or multiple
times repeatedly ("Repeat-sequence-of-channels"). In contrast to the single
--- 512,521 ----
! Appendix B: a HAL representation: MSP430 ADC12
====================================================================
! This section shows the HAL signature for the ADC12 of the TI MSP430 MCU. It
! reflects the four MSP430 ADC12 conversion modes as it lets a client sample an
! ADC channel once ("Single-channel-single-conversion") or repeatedly
("Repeat-single-channel"), multiple times ("Sequence-of-channels") or multiple
times repeatedly ("Repeat-sequence-of-channels"). In contrast to the single
***************
*** 512,516 ****
interrupt after multiple samples and thus enable high-frequency sampling. The
``DMAExtension`` interface is used to reset the state machine when the DMA is
! responsible for data transfer::
configuration Msp430Adc12P
--- 523,527 ----
interrupt after multiple samples and thus enable high-frequency sampling. The
``DMAExtension`` interface is used to reset the state machine when the DMA is
! responsible for data transfer (managed in an exterior component)::
configuration Msp430Adc12P
***************
*** 534,539 ****
}
! Appendix C: an HIL representation: MSP430 ADC12
====================================================================
--- 545,561 ----
}
+ typedef struct {
+ unsigned int inch: 4; // input channel
+ unsigned int sref: 3; // reference voltage
+ unsigned int ref2_5v: 1; // reference voltage level
+ unsigned int adc12ssel: 2; // clock source sample-hold-time
+ unsigned int adc12div: 3; // clock divider sample-hold-time
+ unsigned int sht: 4; // sample-hold-time
+ unsigned int sampcon_ssel: 2; // clock source sampcon signal
+ unsigned int sampcon_id: 2; // clock divider sampcon signal
+ } msp430adc12_channel_config_t;
+
! Appendix C: a HIL representation: MSP430 ADC12
====================================================================
***************
*** 550,553 ****
.. [TEP108] TEP 108: Resource Arbitration.
.. [TEP109] TEP 109: Sensor Boards.
- .. [TEP111] TEP 111: message_t
.. [TEP114] TEP 114: SIDs: Source and Sink Independent Drivers.
--- 572,574 ----
More information about the Tinyos-2-commits
mailing list