[Tinyos-beta-commits]
CVS: tinyos-1.x/beta/teps/txt tep101.txt, 1.5, 1.6
Jan-Hinrich Hauer
janhauer at users.sourceforge.net
Tue May 24 19:46:55 PDT 2005
Update of /cvsroot/tinyos/tinyos-1.x/beta/teps/txt
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv19270/beta/teps/txt
Modified Files:
tep101.txt
Log Message:
TEP 101 (ADC) basically rewritten.
Index: tep101.txt
===================================================================
RCS file: /cvsroot/tinyos/tinyos-1.x/beta/teps/txt/tep101.txt,v
retrieving revision 1.5
retrieving revision 1.6
diff -C2 -d -r1.5 -r1.6
*** tep101.txt 14 Feb 2005 20:28:17 -0000 1.5
--- tep101.txt 25 May 2005 02:46:52 -0000 1.6
***************
*** 8,12 ****
:Status: Draft
:TinyOS-Version: 2.x
! :Author: Jan-Hinrich Hauer, Vlado Handziski, Joe Polastre, Lama Nachman
:Draft-Created: 20-Dec-2004
--- 8,12 ----
:Status: Draft
:TinyOS-Version: 2.x
! :Author: Jan-Hinrich Hauer, Philip Levis, Vlado Handziski, David Gay
:Draft-Created: 20-Dec-2004
***************
*** 27,54 ****
This TEP proposes a new hardware abstraction for the analog-to-digital
! converters (ADCs) in TinyOS 1.2. It focuses on aligning the ADC
abstraction with the three-layer Hardware Abstraction Architecture
! (HAA).
! 1. Introduction
====================================================================
! Internal ADCs
! -------------
! There are two different internal ADCs in use for the TinyOS platforms:
! The internal ADC of the Atmel Atmega 128 and the ADC12 of TI MSP430.
! Their characteristics are compared in the following table:
+----------------------+----------------------+---------------------+
| | Atmel Atmega 128 | TI MSP430 ADC12 |
+======================+======================+=====================+
! |Resolution | 10-bit | 12-bit |
+----------------------+----------------------+---------------------+
! |channels |- 8 multiplexed |- 8 individually |
! | | external channels | configurable |
! | |- 16 differential | external channels |
! | | voltage input |- internal channels |
! | | combinations | (AVcc, temperature,|
| |- 2 differential | reference voltages)|
| | inputs with gain | |
--- 27,188 ----
This TEP proposes a new hardware abstraction for the analog-to-digital
! converters (ADCs) in TinyOS 2.x. It focuses on aligning the ADC
abstraction with the three-layer Hardware Abstraction Architecture
! (HAA) described in TEP 2. The ADC abstraction itself does not include
! an HIL, but the platform independent representation is discussed in
! TEP 109 (Sensorboards).
! Introduction
====================================================================
! 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 was such a representation, the configuration details of an ADC
! would 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. It can only be
! determined on a platform or sensorboard level, e.g. which ADC port a
! certain sensor is attached to and how a conversion result needs to be
! interpreted. Thus there is no platform independent (HIL)
! representation of an ADC in TinyOS.
! Instead, on top of the ADC hardware abstraction a further abstraction
! concept is required to use ADCs in a platform independent way. This
! concept is described in TEP 109 (Sensorboards): Named sensor
! components, called sensor wrappers, provide platform independent
! access to sensors by providing standard TinyOS interfaces.
!
! In order to facilitate the writing of sensor wrappers and allow them
! to incorporate certain services (e.g. access to the ADC on a round
! robin basis), the ADC hardware stack will include as its top layer a
! second, chip independent (but still platform dependent) HAL. The
! following section gives an overview of the involved components.
! Afterwards each layer is discussed in detail.
!
! Overview
! ====================================================================
!
! The ADC hardware abstraction ends with a platform dependent HAL. But
! it is designed with regard to the sensor abstraction in TEP 109, which
! covers the definition and implementation of HIL sensor components.
! This overview shows how they match up by describing the integrated
! component graph in a top-down fashion.
!
! The highest layer of abstraction, the HIL, will be composed of named
! sensor components (sensor wrappers) that provide interfaces only for
! acquiring the corresponding data. TEP 109 covers the definition and
! implementation of these HIL sensor components. However, many sensors
! sit on top of a shared hardware ADC.
!
! As the ADC hardware will usually be multiplexed between several client
! applications, access to it needs to be arbitrated. The ADC stack uses
! 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
! wiring to a sensor wrapper on the 'eyes' platform (using the MSP430)
! is shown in the following figure.::
!
!
! +-------------+
! | Platform |
! APPLICATION: | independent | location: e.g. tinyos-2.x/apps/TestADC
! | Application |
! +-------------+
! ^
! |
! AcquireData
! |
! +----------------+
! | DemoSensorRRC |
! HIL: | (instantiating | location: tinyos-2.x/tos/platforms/eyes
! | ADCChannelC) |
! +----------------+
! ^
! |
! AcquireData[]
! |
! +----------------------------+
! | ADCChannelArbiterC |
! Service: | (instantiating | location: tinyos-2.x/tos/lib/adc
! | AcquireDataNowRoundRobinM) |
! +----------------------------+
! ^
! |
! AcquireData[]
! |
! +---------------------+
! | ADCC |
! HAL2: | (MSP430 specific | location: tinyos-2.x/tos/chips/msp430
! | implementation and |
! | representation) |
! +---------------------+
! ^
! |
! MSP430ADC12SingleChannel[]
! |
! +---------------------+
! | MSP430ADC12C |
! HAL1: | (MSP430 specific | location: tinyos-2.x/tos/chips/msp430
! | implementation and |
! | representation) |
! +---------------------+
! ^
! |
! MSP430ADC12HPL
! |
! +---------------------+
! | MSP430ADC12HPLC |
! HPL: | (MSP430 specific | location: tinyos-2.x/tos/chips/msp430
! | implementation and |
! | representation) |
! +---------------------+
!
!
!
!
! Hardware differences between the current platforms
! ====================================================================
!
! 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:
+----------------------+----------------------+---------------------+
| | Atmel Atmega 128 | TI MSP430 ADC12 |
+======================+======================+=====================+
! |Resolution | 10-bit | 12-bit |
+----------------------+----------------------+---------------------+
! |channels |- 8 multiplexed |- 8 individually |
! | | external channels | configurable |
! | |- 16 differential | external channels |
! | | voltage input |- internal channels |
! | | combinations | (AVcc, temperature,|
| |- 2 differential | reference voltages)|
| | inputs with gain | |
***************
*** 100,384 ****
+----------------------+----------------------+---------------------+
-
- External ADCs
- -------------
-
- In addition to the above internal ADCs, some of the TinyOS platforms
- use dedicated ADCs like ADS1242, ADS7828, ADS1251, ADS8345, ADS8325,
- ADS1100 (all by TI). They differ in resolution (12-bit to 24 -bit),
- interfaces (SPI, I2C), channel numbers (1 to 8), reference voltages
- and conversion rates. Implementation of the three layers of the HAA
- will be considerably different from internal ADCs, as issues like bus
- arbitration or communication errors have to be taken into
- consideration. Although the particular implementation will vary
- according to chip and platform, each HIL (`Hardware Interface Layer
- (HIL)`_) will export the standard *ADCSingle* and *ADCMultiple*
- interface, providing a uniform application-level OS service. External
- ADCs will influence the HIL interfaces and the layering in the
- following ways:
-
- - An additional command *reserveADC* will be included in the
- HIL interfaces. This command will guarantee a minimum
- delay between the next invocation of *getData* and the actual
- sampling of the channel.
- - The HIL will provide a mechanism to signal an error that
- occurred during the sampling process.
- - A more general architectural issue is how to structure the
- communication between the HPL of the external ADC and the HPL
- of the particular bus implementation.
- We propose to deal with bus arbitration and related tasks
- on the level of the HALs. I.e. the HAL\_ADC module will wire to
- e.g. HAL\_SPI module to perform bus arbitration while HPL\_ADC
- will wire to HPL\_SPI. HPL\_ADC is unaware of bus arbitration
- and will always assume to be owner of the bus. This ensures
- that
-
- - The HPL can be kept stateless.
- - The HAL is capable of deciding how long to maintain a certain
- state in bus arbitration. If there is, for example, a request
- for a continuous or sequence conversion the HAL could refrain
- from releasing the bus after each single conversion.
-
-
- 2. Architecture
- ====================================================================
-
- The proposed architecture aligns with the three-layer Hardware
- Abstraction Architecture (HAA).
-
Hardware Presentation Layer (HPL)
! ---------------------------------
!
! a. Implementation: chip/platform dependent
! b. Presentation: chip dependent
! c. Stateless
! d. General structure:
! i. StdControl (init, start, stop) for power management to work
! ii. get/set commands for the registers that control the hardware
! iii. additional commands for the frequently used operations
! iv. commands for enabling/disabling of interrupts
! v. service routines for the ADC interrupt
! e. The HPL for an external ADC SHOULD follow the general structure
! described above by wiring to the respective hardware module's HPL
! to access the bus and relevant pins (see `External ADCs`_).
Hardware Adaptation Layer (HAL)
! -------------------------------
!
! For the HAL presentation, the idea of binding an interface to ADC
! settings is extended. This mechanism was introduced in the
! ``ADCControl`` interface, but was only applied to channels. Instead of
! only binding to a channel, all settings supported by the interface
! SHOULD be passed to a ``bind`` commandhandler once at initialization.
! For all subsequent calls on the interface instance these settings are
! then valid.
!
! a. Implementation: chip/platform dependent
! b. Presentation: chip dependent
! c. MSP430:
! To offload the interfaces, the four supported conversion modes of the
! MSP430 are separated into two separate interfaces: *MSP430ADC12Single* and
! *MSP430ADC12Multiple*, for single and multiple conversions,
! respectively. Both interfaces provide two commands which allow the
! conversion(s) to be performed once or repeatedly. One
! characteristic of the MSP430 ADC12 is the ability to define the
! time interval between subsequent conversions. This is reflected by
! an additional parameter *jiffies* in the relevant commands of the
! HAL interfaces.
!
! A new return datatype ``msp430ADCresult_t`` is introduced, which
! not only includes MSP430ADC12_FAIL and MSP430ADC12_SUCCESS but
! also MSP430ADC12_QUEUED to queue commands.
! This is necessary to deal with a possible 17ms delay when
! starting the internal reference voltage generator.
! HAL-configuration, interfaces and datatypes are as follows (see
! `3. Implementation`_ for where to find commented versions).::
! configuration MSP430ADC12C
! {
! provides interface StdControl;
! provides interface MSP430ADC12Single[uint8_t id];
! provides interface MSP430ADC12Multiple[uint8_t id];
! }
! interface MSP430ADC12Single
! {
! command result_t bind(MSP430ADC12Settings_t settings);
! async command msp430ADCresult_t getData();
! async command msp430ADCresult_t getDataRepeat(uint16_t jiffies);
! async command result_t reserve();
! async command result_t reserveRepeat(uint16_t jiffies);
! async command result_t unreserve();
! async event result_t dataReady(uint16_t data);
! }
! interface MSP430ADC12Multiple
! {
! command result_t bind( MSP430ADC12Settings_t settings);
! async command msp430ADCresult_t getData(uint16_t *buf, uint16_t length,
! uint16_t jiffies);
! async command msp430ADCresult_t getDataRepeat(uint16_t *buf, uint8_t length,
! uint16_t jiffies);
! async command result_t reserve(uint16_t *buf, uint16_t length, uint16_t jiffies);
! async command result_t reserveRepeat(uint16_t *buf, uint8_t length, uint16_t jiffies);
! async command result_t unreserve();
! async event uint16_t* dataReady(uint16_t *buf, uint16_t length);
! }
! typedef struct
! {
! unsigned int refVolt2_5: 1; // reference voltage level
! unsigned int clockSourceSHT: 2; // clock source sample-hold-time
! unsigned int clockSourceSAMPCON: 2; // clock source sampcon signal
! unsigned int clockDivSAMPCON: 2; // clock divider sampcon
! unsigned int referenceVoltage: 3; // reference voltage
! unsigned int clockDivSHT: 3; // clock divider sample-hold-time
! unsigned int inputChannel: 4; // input channel
! unsigned int sampleHoldTime: 4; // sample-hold-time
! } MSP430ADC12Settings_t;
!
! typedef union
! {
! uint32_t i;
! MSP430ADC12Settings_t s;
! } MSP430ADC12Settings_ut;
- typedef enum
- {
- MSP430ADC12_FAIL = 0,
- MSP430ADC12_SUCCESS = 1,
- MSP430ADC12_QUEUED = 2
- } msp430ADCresult_t;
! d. Atmega 128:
! To maintain compatibility with the existing code the
! original ADC interface will be provided with one extension,
! a *reserveADC* command.
! i. interface Atmega128ADC::
! interface Atmega128ADC
! {
! async command result_t getData();
! async command result_t getContinuousData();
! async command result_t reserveADC();
! async event result_t dataReady(uint16_t data);
! }
!
!
! ii. interface ADCControl::
! /* the original ADCControl interface from tos/interfaces/ */
! command result_t init();
! command result_t setSamplingRate(uint8_t rate);
! command result_t bindPort(uint8_t port, uint8_t adcPort);
! e. External ADCs:
! The HALs of external ADCs are chip and platform dependent. Their
! interfaces SHOULD be defined with regard to the HIL
! interfaces specified below. As stated above (`External ADCs`_),
! HALs for external ADCs might also have to deal with bus arbitration
! and related tasks.
!
! Hardware Interface Layer (HIL)
! ------------------------------
! An HIL provides application-level OS services via platform independent
! interfaces. The ADC's HIL interface should abstract from platform
! dependent settings as a platform independent application is not in a
! position to deal with platform dependent settings such as a channel
! number or sample-hold-time. In HIL a translation from a platform
! independent representation of a sensor to platform dependent settings
! for a HAL's *bind* needs to be performed. Also, the HIL is responsible
! for translating an application request to HAL primitives.
! The current practice of having wrappers represent sensors is
! maintained: A wrapper configuration will provide a *StdControl*, the
! *ADCSingle* and the *ADCMultiple* interface. A wrapper thus
! represents the HIL in the ADC's hardware abstraction, i.e. it sits on
! top of the native HAL component. Its task is to bind to HAL with the
! appropriate settings (typically done in StdControl.init) and to
! forward commands, possibly adding slight changes to translate them to
! the HAL interface. Since an HAL interface is designed with the HIL
! interfaces in mind wrappers will typically be fairly lightweight. An
! example configuration for a temperature sensor wrapper on the msp430
! platform would look like this::
- StdControl
- | ADCSingle
- | | ADCMultiple
- | | |
- +------|----|----|------------------------------------------+
- | | | | Temperature |
- | v v v |
- | +--------------------+ MSP430ADC12Single +------------+ |
- | | TemperatureM |-------------------->|MSP430ADC12C| |
- | | | MSP430ADC12Multiple | | |
- | | |-------------------->| | |
- | +--------------------+ +------------+ |
- +-----------------------------------------------------------+
! On the level of HIL two interfaces MUST be provided: ADCSingle and
! ADCMultiple. ADCSingle is used for single conversions (once or
! repeated) and ADCMultiple is used for multiple conversions (once or
! repeated).
! Both interfaces must take into account that some (e.g. external ADCs)
! may face errors during the sampling process which can lead to invalid
! results. Therefore events in the ADCSingle and ADCMultiple interfaces
! not only return the conversion result(s) but also additional error
! information contained in a new datatype adcresult_t.
! The returned conversion results are uninterpreted 16-bit values. Note
! that still multiple results can be combined by an application to
! create a mean or median.
! a. Implementation: platform dependent
! b. Presentation: application-level OS service (see
! `3. Implementation`_ for where to find the commented version).::
!
! interface ADCSingle
! {
! async command adcresult_t getData();
! async command adcresult_t getDataContinuous();
! async command adcresult_t reserve();
! async command adcresult_t reserveContinuous();
! async command adcresult_t unreserve();
! async event result_t dataReady(adcresult result, uint16_t data);
! }
!
! interface ADCMultiple
! {
! async command adcresult_t getData(uint16_t *buf, uint16_t length);
! async command adcresult_t getDataContinuous(uint16_t *buf, uint16_t length);
! async command adcresult_t reserve(uint16_t *buf, uint16_t length);
! async command adcresult_t reserveContinuous(uint16_t *buf, uint16_t length);
! async command adcresult_t unreserve();
! async event uint16_t* dataReady(adcresult result, uint16_t *buf, uint16_t length);
! }
!
! 3. Implementation
====================================================================
! The ADCSingle and ADCMultiple interfaces and ADCHIL.h (containing the
! definition of adcresult_t) can be found in tos/interfaces. Interfaces
! relating to msp430 are in tos/platform/msp430. The HAL implementation
! of the msp430 as well as wrappers (HIL) for internal temperature and
! internal voltage of the msp430 can also be found in
! tos/platform/msp430. A test application for the msp430 platform is
! tinyos-1.x/contrib/eyes/apps/TestADC.
4. Author's Address
====================================================================
! | Jan Hauer <hauer at tkn.tu-berlin.de>,
! | Vlado Handziski <handzisk at tkn.tu-berlin.de>,
! | Joe Polastre <polastre at cs.berkeley.edu>,
! | Lama Nachman <lama.nachman at intel.com>
--- 234,562 ----
+----------------------+----------------------+---------------------+
Hardware Presentation Layer (HPL)
! ====================================================================
! a. Implementation: Chip dependent
! b. Presentation: Chip dependent
! c. Stateless
! d. General structure:
! i. provides StdControl interface if necessary for power management
! ii. get/set commands for the registers that control the hardware
! iii. additional commands for frequently used operations
! iv. commands for enabling/disabling of interrupts
! v. service routines for the ADC interrupt
Hardware Adaptation Layer (HAL)
! ====================================================================
! 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
! of HAL1. Only chip dependent application may wire to HAL1 or HAL2 i.e.
! platform independent applications MUST NOT wire to HAL1 or HAL2.
!
! Hardware Adaptation SubLayer1 (HAL1)
! --------------------------------------------------------------------
!
! a. Implementation: Chip dependent
! b. Presentation: Chip dependent
! c. Async
! d. ADC12 on MSP430
!
! The core configuration of the HAL1 on MSP430 is
! the MSP430ADC12C configuration.::
!
! configuration MSP430ADC12C
! {
! //provides interface Init;
! //provides interface StdControl;
! provides interface Resource[uint8_t client];
! provides interface MSP430ADC12SingleChannel as SingleChannel[uint8_t id];
! provides interface MSP430ADC12SingleChannel as SingleChannelADCC[uint8_t id];
! }
! MSP430ADC12C provides two parameterized
! MSP430ADC12SingleChannel interfaces. "SingleChannel" is
! provided to chip dependent applications, "SingleChannelADCC" is
! reserved for the ADCC component (see 'Hardware Adaptation
! SubLayer2 (HAL2)'_). An application SHOULD NOT directly wire
! to the MSP430ADC12C, but to an instantiation of the following
! generic configuration.::
!
! generic configuration MSP430ADC12Client()
! {
! provides interface Resource;
! provides interface MSP430ADC12SingleChannel;
! } implementation {
! components MSP430ADC12C;
!
! Resource = MSP430ADC12C.Resource[unique(ADC_RESOURCE)];
! MSP430ADC12SingleChannel = MSP430ADC12C.MSP430ADC12SingleChannel[unique(MSP430ADC12_CLIENT)];
! }
! i. The Resource interface is specified in TEP 108. Before a
! call to any command of the MSP430ADC12SingleChannel interface
! can succeed, the ADC12 MUST be reserved via the Resource
! interface. After an application has performed all desired
! operations on the ADC12, it then MUST release the ADC12 via the
! Resource interface. In the meantime the ADC12 will be blocked
! 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
! *getData* commands, two events signalling data back and a
! *getConfigurationData* event.::
! interface MSP430ADC12SingleChannel
! {
! async event msp430adc12_channel_config_t getConfigurationData();
! async command msp430adc12_result_t getDataSingle();
! async command msp430adc12_result_t getDataSingleRepeat(uint16_t jiffies);
! async command msp430adc12_result_t getDataMultiple(uint16_t *buf,
! uint16_t length, uint16_t jiffies);
! async command msp430adc12_result_t getDataMultipleRepeat(uint16_t *buf,
! uint8_t length, uint16_t jiffies);
! async event result_t dataSingleReady(uint16_t data);
! async event uint16_t* dataMultipleReady(uint16_t *buf, uint16_t length);
! }
! typedef struct
! {
! unsigned int refVolt2_5: 1; // reference voltage level
! unsigned int clockSourceSHT: 2; // clock source sample-hold-time
! unsigned int clockSourceSAMPCON: 2; // clock source sampcon signal
! unsigned int clockDivSAMPCON: 2; // clock divider sampcon
! unsigned int referenceVoltage: 3; // reference voltage
! unsigned int clockDivSHT: 3; // clock divider sample-hold-time
! unsigned int inputChannel: 4; // input channel
! unsigned int sampleHoldTime: 4; // sample-hold-time
! } msp430adc12_channel_config_t;
!
! 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
! of the ADC12: A single channel converted once or repeatedly or
! a sequence of channels converted once or repeatedly. The
! sequence-of-channel mode is used to perform high-frequency
! sampling of around 70kSPS (kilo samples per second) on a single
! channel. The MSP430 ADC12 allows to define a sampling period
! for subsequent conversions. This is reflected by an additional
! parameter *jiffies* in the relevant commands. A datatype
! ``msp430adc12_result_t`` is used, which not only includes
! MSP430ADC12_SUCCESS but also MSP430ADC12_QUEUED to queue
! commands. This is necessary to deal with a possible 17ms delay
! when starting the internal reference voltage generator.
!
!
! e. The ADC on ATmega128:
!
! In the current implementation on the Atmel an ADC channel is
! exhaustively defined by the port numer, i.e. there is no bind
! mechanism (e.g. like for the MSP430)::
!
! configuration HALADCC
! {
! provides {
! interface Init;
! interface StdControl;
! interface Resource[uint8_t client];
! interface ATm128ADC[uint8_t port];
! }
! }
!
! interface ATm128ADC
! {
! async command error_t getData();
! async command error_t getContinuousData();
! async event error_t dataReady(uint16_t data);
! }
!
! The Resource interface is specified in TEP 108. Before any call
! on the ATm128ADC interface can succeed, the ADC MUST be
! reserved via the Resource interface. After an application has
! performed all desired operations on the ADC, it then MUST
! release the ADC via the Resource interface. In the meantime
! the ADC will be blocked for all other request, therefore an
! application SHOULD minimize this reservation period.
! Hardware Adaptation SubLayer2 (HAL2)
! --------------------------------------------------------------------
! a. Presentation: Chip independent, platform dependent
! The common denominator of all ADCs is that they sample an input
! channel and produce conversion results. An abstraction of the
! ADC that satisfies both, is a parameterized AcquireData
! interface, where the parameter defines the ADC channel (i.e. port)
! to be sampled. An HAL2 MUST provide the following
! interfaces.::
!
! configuration ADCC {
! provides {
! interface Init;
! interface StdControl;
! interface Resource[uint8_t client];
! interface AcquireData[uint8_t port];
! interface AcquireDataNow[uint8_t port];
! interface AcquireDataBuffered[uint8_t port];
! }
! } implementation {
! // chip dependent
! }
!
! The name of a HAL2 configuration is chip specific (it can be,
! but doesn't have to be "ADCC"). An HAL2 module will perform a
! mapping of the chip specific HAL1 interfaces to the above shown
! standard TinyOS interfaces. Note that, although the provided
! interfaces are standard TinyOS interfaces, the fact that they
! are parameterized by a port identifier makes the HAL2
! representation platform dependent. Platform independent
! applications SHOULD NOT wire to HAL2.
!
! b. Implementation: Chip dependent
! The HAL2 representation allows access to an ADC on a port
! basis. For ADCs that require more detailed configuration
! information than the port number an additional
! mechanism is required for the HAL2 implementation to
! determine what the actual chip-specific settings for a given
! ADC port are. For example, the HAL2 module of the
! ADC12 on MSP430 needs to know the exact configuration settings
! ADC channel (port) in order to successfully call the
! for a given MSP430ADC12SingleChannel.bind() command. What these
! settings are can only be determined on a platform or sensorboard
! level and not within the ADC hardware stack itself. The mapping of
! a channel number to its settings must be well-defined for all
! relevant ADCs.
! i. MSP430
! Each platform or sensorboard that allows access to the
! ADC12 via ADCC MUST provide a module
! "MSP430ADC12ChannelConfigM.nc", because in its implementation
! ADCC wires to MSP430ADC12ChannelConfigM::
! /* HAL2 component for ADC12 of MSP430 */
! configuration ADCC {
! provides {
! interface Init;
! interface StdControl;
! interface Resource[uint8_t client];
! interface AcquireData[uint8_t port];
! interface AcquireDataNow[uint8_t port];
! interface AcquireDataBuffered[uint8_t port];
! }
! }
! }
! implementation {
! components ADCM, MSP430ADC12ChannelConfigM, MSP430ADC12C;
!
! Init = MSP430ADC12C;
! StdControl = MSP430ADC12C;
! Resource = MSP430ADC12C;
! AcquireData = ADCM;
! AcquireDataNow = ADCM;
! AcquireDataBuffered = ADCM;
!
! ADCM.SingleChannel -> MSP430ADC12C.SingleChannelADCC;
! ADCM.MSP430ADC12ChannelConfig -> MSP430ADC12ChannelConfigM;
! }
!
! The MSP430ADC12ChannelConfigM module SHOULD be placed in the
! according platform or sensorboard directory and it MUST
! implement the interface "MSP430ADC12ChannelConfig".::
!
! interface MSP430ADC12ChannelConfig {
! async event msp430adc12_channel_config_t getConfigurationData(uint8_t channel);
! }
!
! ADCM MAY signal the *getConfigurationData()* event for channels
! 0-7 and MSP430ADC12ChannelConfigM MUST return the corresponding
! configuration data for the platform or sensorboard. The event
! MAY be signalled multiple times and MSP430ADC12ChannelConfigM
! MUST always return the same configuration data.
! ii. For the ADC on the ATmega128 in the current implementation
! a port number exhaustively defines all relevant settings.
! Services
! ====================================================================
! As the ADC hardware will usually be multiplexed between several client
! applications, access to it needs to be arbitrated. Arbitration of the
! HAL2 is performed by channel arbiter components, e.g.
! ADCChannelArbiterC or ADCNowChannelArbiterC, located in
! tinyos-2.x/tos/lib/adc. These arbiters SHOULD NOT be wired to
! directly. Instead generic wrapper components, e.g. ADCChannelC or
! ADCNowChannelC, SHOULD be used. This guarantees correct wiring between
! arbiters and HAL2. The generic wrapper components will be instantiated
! by sensor wrapper components, i.e. per platform. Platform independent
! applications SHOULD NOT instantiate these themselves.
!
! Hardware Interface Layer (HIL)
! ====================================================================
! The ADC hardware stack itself does not include an HIL for reasons
! mentioned in the `Introduction`_. Instead named sensor wrappers
! provide platform independent access to the ADC which is covered in TEP
! 109 (Sensorboards).
! Implementation
====================================================================
! See the tinyos-2.x/tos/ tree. Interfaces are in interfaces/ and HPL,
! HAL1 and HAL2 components in chips/. Arbitration service components are
! in lib/adc.
4. Author's Address
====================================================================
! | Jan Hauer / Vlado Handziski
! | Sekr FT5
! | Einsteinufer 25
! | 10587 Berlin
! | GERMANY
! |
! | email - hauer at tkn.tu-berlin.de, handzisk at tkn.tu-berlin.de
! |
! |
! | Philip Levis
! | 467 Soda Hall
! | UC Berkeley
! | Berkeley, CA 94720
! |
! | phone - +1 510 290 5283
! |
! | email - pal at cs.berkeley.edu
! |
! |
! | David Gay
! | 2150 Shattuck Ave, Suite 1300
! | Intel Research
! | Berkeley, CA 94704
! |
! | phone - +1 510 495 3055
! |
! | email - david.e.gay at intel.com
More information about the Tinyos-beta-commits
mailing list