[Tinyos-2-commits] CVS: tinyos-2.x/doc/html tep101.html, 1.1.2.12,
1.1.2.13
Jan-Hinrich Hauer
janhauer at users.sourceforge.net
Thu Oct 12 10:02:39 PDT 2006
Update of /cvsroot/tinyos/tinyos-2.x/doc/html
In directory sc8-pr-cvs10.sourceforge.net:/tmp/cvs-serv31095/doc/html
Modified Files:
Tag: tinyos-2_0_devel-BRANCH
tep101.html
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.html
===================================================================
RCS file: /cvsroot/tinyos/tinyos-2.x/doc/html/tep101.html,v
retrieving revision 1.1.2.12
retrieving revision 1.1.2.13
diff -C2 -d -r1.1.2.12 -r1.1.2.13
*** tep101.html 9 Oct 2006 11:05:59 -0000 1.1.2.12
--- tep101.html 12 Oct 2006 17:02:37 -0000 1.1.2.13
***************
*** 344,363 ****
software. TEP 109 (Sensor Boards) shows how a platform can present actual named
sensors <a class="citation-reference" href="#tep109" id="id2" name="id2">[TEP109]</a>.</p>
! <p>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 <tt class="docutils literal"><span class="pre">message_t</span></tt> is declared per link layer (see
! <a class="citation-reference" href="#tep111" id="id3" name="id3">[TEP111]</a>), an ADC configuration abstraction can be declared per ADC chip and
! still be passed between components using standard TinyOS interfaces. This TEP
! proposes the <tt class="docutils literal"><span class="pre">AdcConfigure</span></tt> 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 <strong>platform</strong> is responsible to
! define the configuration for every sensor attached to the ADC.</p>
<p>In spite of their hardware differences, one aspect represents a common
denominator of all ADCs: they produce conversion results. To facilitate sensor
--- 344,368 ----
software. TEP 109 (Sensor Boards) shows how a platform can present actual named
sensors <a class="citation-reference" href="#tep109" id="id2" name="id2">[TEP109]</a>.</p>
! <p>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 <strong>hardware independent
! interfaces</strong>: in a similar way as the <tt class="docutils literal"><span class="pre">Read</span></tt> interface definition does not
! predefine the type or semantics of the exchanged data (see <a class="citation-reference" href="#tep114" id="id3" name="id3">[TEP114]</a>), 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 <tt class="docutils literal"><span class="pre">Read<uint8_t></span></tt> or <tt class="docutils literal"><span class="pre">Read<uint16_t></span></tt> interface
! depending on the data it can offer, a component can also use a
! <tt class="docutils literal"><span class="pre">AdcConfigure<atm128_adc_config_t></span></tt> or
! <tt class="docutils literal"><span class="pre">AdcConfigure<msp430adc12_channel_config_t></span></tt> interface depending on what ADC
! it represents. This TEP proposes the (typed) <tt class="docutils literal"><span class="pre">AdcConfigure</span></tt> interface as the
! standard interface for configuring an ADC in TinyOS 2.x.</p>
<p>In spite of their hardware differences, one aspect represents a common
denominator of all ADCs: they produce conversion results. To facilitate sensor
***************
*** 375,424 ****
<tt class="docutils literal"><span class="pre">ReadStream</span></tt> and uses the <tt class="docutils literal"><span class="pre">AdcConfigure</span></tt> interface for hardware
configuration (why it <strong>uses</strong> and does not <strong>provide</strong> <tt class="docutils literal"><span class="pre">AdcConfigure</span></tt> is
! explained below).</p>
! <p>Following the principles of the HAA <a class="citation-reference" href="#tep2" id="id5" name="id5">[TEP2]</a> the Hardware Adaptation Layer (HAL,
which resides below the HIL) of an ADC should expose all the chip-specific
capabilities of the chip. For example, the ADC12 on the MSP430 MCU supports a
"Repeat-Sequence-of-Channels Mode" and therefore this function should be
accessible on the HAL of the <strong>MSP430 ADC12</strong> 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 <tt class="docutils literal"><span class="pre">ReadStream</span></tt>
command can be emulated by multiple single conversion commands. Below the HAL
resides the Hardware Presentation Layer (HPL), a stateless component that
! provides access to the hardware registers (see <a class="citation-reference" href="#tep2" id="id6" name="id6">[TEP2]</a>). The general structure
(without virtualization) of the ADC hardware stack is as follows</p>
<pre class="literal-block">
! ^ |
! | |
! | Read,
! AdcConfigure ReadNow (+ Resource),
! | ReadStream
! | |
! | V
! +----------------------------------+
! | Hardware Interface Layer (HIL) |
! | (chip-specific implementation) |
! +----------------------------------+
! |
! |
! chip-specific interface(s) + Resource
! (e.g. Msp430Adc12SingleChannel)
! |
! V
! +----------------------------------+
! | Hardware Adaptation Layer (HAL) |
! | (chip-specific implementation) |
! +----------------------------------+
! |
! |
! chip-specific interface(s)
! (e.g. HplAdc12)
! |
! V
! +----------------------------------+
! | Hardware Presentation Layer (HPL)|
! | (chip-specific implementation) |
! +----------------------------------+
</pre>
<p>The rest of this TEP specifies:</p>
--- 380,431 ----
<tt class="docutils literal"><span class="pre">ReadStream</span></tt> and uses the <tt class="docutils literal"><span class="pre">AdcConfigure</span></tt> interface for hardware
configuration (why it <strong>uses</strong> and does not <strong>provide</strong> <tt class="docutils literal"><span class="pre">AdcConfigure</span></tt> 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 <a class="citation-reference" href="#tep2" id="id5" name="id5">[TEP2]</a>).</p>
! <p>Following the principles of the HAA <a class="citation-reference" href="#tep2" id="id6" name="id6">[TEP2]</a> the Hardware Adaptation Layer (HAL,
which resides below the HIL) of an ADC should expose all the chip-specific
capabilities of the chip. For example, the ADC12 on the MSP430 MCU supports a
"Repeat-Sequence-of-Channels Mode" and therefore this function should be
accessible on the HAL of the <strong>MSP430 ADC12</strong> 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 <tt class="docutils literal"><span class="pre">ReadStream</span></tt>
command can be emulated by multiple single conversion commands. Below the HAL
resides the Hardware Presentation Layer (HPL), a stateless component that
! provides access to the hardware registers (see <a class="citation-reference" href="#tep2" id="id7" name="id7">[TEP2]</a>). The general structure
(without virtualization) of the ADC hardware stack is as follows</p>
<pre class="literal-block">
! ^ |
! | |
! | Read,
! AdcConfigure ReadNow (+ Resource),
! | ReadStream
! | |
! | V
! +----------------------------------+
! | Hardware Interface Layer (HIL) |
! | (chip-specific implementation) |
! +----------------------------------+
! |
! |
! chip-specific interface(s) + Resource
! (e.g. Msp430Adc12SingleChannel + Resource)
! |
! V
! +----------------------------------+
! | Hardware Adaptation Layer (HAL) |
! | (chip-specific implementation) |
! +----------------------------------+
! |
! |
! chip-specific interface(s)
! (e.g. HplAdc12)
! |
! V
! +----------------------------------+
! | Hardware Presentation Layer (HPL)|
! | (chip-specific implementation) |
! +----------------------------------+
</pre>
<p>The rest of this TEP specifies:</p>
***************
*** 441,468 ****
and the <tt class="docutils literal"><span class="pre">Read</span></tt>, <tt class="docutils literal"><span class="pre">ReadNow</span></tt> and <tt class="docutils literal"><span class="pre">ReadStream</span></tt> interfaces to acquire
conversion results. A <tt class="docutils literal"><span class="pre">Read[Now|Stream]</span></tt> interface is always provided in
! conjunction with an <tt class="docutils literal"><span class="pre">AdcConfigure</span></tt> interface.</p>
<div class="section">
<h2><a id="interface-for-configuring-the-adc-hardware" name="interface-for-configuring-the-adc-hardware">Interface for configuring the ADC hardware</a></h2>
<p>The <tt class="docutils literal"><span class="pre">AdcConfigure</span></tt> interface is defined as follows:</p>
<pre class="literal-block">
! interface AdcConfigure<adc_config_t>
{
! async command adc_config_t getConfiguration();
}
</pre>
! <p>This interface is used by the ADC implementation to retrieve the desired
! hardware configuration of an ADC client. <tt class="docutils literal"><span class="pre">adc_config_t</span></tt> 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 <tt class="docutils literal"><span class="pre">AdcConfigure</span></tt> interface will be instantiated with the
! <tt class="docutils literal"><span class="pre">msp430adc12_channel_config_t</span></tt> structure. A client MUST always return the
! same configuration through an <tt class="docutils literal"><span class="pre">AdcConfigure</span></tt> interface. If a client wants to
! use the ADC with different configurations it must provide multiple instances of
! the <tt class="docutils literal"><span class="pre">AdcConfigure</span></tt> interface.</p>
</div>
<div class="section">
<h2><a id="interfaces-for-acquiring-conversion-results" name="interfaces-for-acquiring-conversion-results">Interfaces for acquiring conversion results</a></h2>
<p>This TEP proposes to adopt the following three generic, source-independent data
! collection interfaces from <a class="citation-reference" href="#tep114" id="id7" name="id7">[TEP114]</a> for the collection of ADC conversion
results on the level of HIL:</p>
<pre class="literal-block">
--- 448,477 ----
and the <tt class="docutils literal"><span class="pre">Read</span></tt>, <tt class="docutils literal"><span class="pre">ReadNow</span></tt> and <tt class="docutils literal"><span class="pre">ReadStream</span></tt> interfaces to acquire
conversion results. A <tt class="docutils literal"><span class="pre">Read[Now|Stream]</span></tt> interface is always provided in
! conjunction with a <tt class="docutils literal"><span class="pre">AdcConfigure</span></tt> interface.</p>
<div class="section">
<h2><a id="interface-for-configuring-the-adc-hardware" name="interface-for-configuring-the-adc-hardware">Interface for configuring the ADC hardware</a></h2>
<p>The <tt class="docutils literal"><span class="pre">AdcConfigure</span></tt> interface is defined as follows:</p>
<pre class="literal-block">
! interface AdcConfigure< config_type >
{
! async command config_type getConfiguration();
}
</pre>
! <p>This interface is used by the ADC implementation to retrieve the hardware
! configuration of an ADC client. <tt class="docutils literal"><span class="pre">config_type</span></tt> 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
! <tt class="docutils literal"><span class="pre">AdcConfigure</span></tt> interface will be instantiated with the <tt class="docutils literal"><span class="pre">const</span>
! <span class="pre">msp430adc12_channel_config_t*</span></tt> data type. A client MUST always return the same
! configuration through a <tt class="docutils literal"><span class="pre">AdcConfigure</span></tt> interface and, if configuration data
! is passed as a pointer, the HIL component (see <a class="reference" href="#hil-requirements">4. HIL requirements</a>) MUST NOT
! reference it after the return of the <tt class="docutils literal"><span class="pre">getConfiguration()</span></tt> command. If a
! client wants to use the ADC with different configurations it must provide
! multiple instances of the <tt class="docutils literal"><span class="pre">AdcConfigure</span></tt> interface.</p>
</div>
<div class="section">
<h2><a id="interfaces-for-acquiring-conversion-results" name="interfaces-for-acquiring-conversion-results">Interfaces for acquiring conversion results</a></h2>
<p>This TEP proposes to adopt the following three generic, source-independent data
! collection interfaces from <a class="citation-reference" href="#tep114" id="id8" name="id8">[TEP114]</a> for the collection of ADC conversion
results on the level of HIL:</p>
<pre class="literal-block">
***************
*** 471,486 ****
interface ReadStream< size_type >
</pre>
! <p>Every data collection interface is associated with an <tt class="docutils literal"><span class="pre">AdcConfigure</span></tt> interface
! (how this association is realized is explained in Section <a class="reference" href="#hil-requirements">4. HIL
requirements</a>). As the resolution of conversion results is chip-specific, the
! <tt class="docutils literal"><span class="pre">size_type</span></tt> 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 <a class="citation-reference" href="#tep114" id="id8" name="id8">[TEP114]</a>, in the
! following their usage is explained with respect to ADCs.</p>
<div class="section">
<h3><a id="read" name="read">Read</a></h3>
<p>The <tt class="docutils literal"><span class="pre">Read</span></tt> interface can be used to sample an ADC channel and return a single
conversion result as an uninterpreted value. The meaning of the <tt class="docutils literal"><span class="pre">Read</span></tt>
! interface is explained in <a class="citation-reference" href="#tep114" id="id9" name="id9">[TEP114]</a>.</p>
</div>
<div class="section">
--- 480,495 ----
interface ReadStream< size_type >
</pre>
! <p>Every data collection interface is associated with an <tt class="docutils literal"><span class="pre">AdcConfigure</span></tt>
! interface (how this association is realized is explained in Section <a class="reference" href="#hil-requirements">4. HIL
requirements</a>). As the resolution of conversion results is chip-specific, the
! <tt class="docutils literal"><span class="pre">size_type</span></tt> 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
! <a class="citation-reference" href="#tep114" id="id9" name="id9">[TEP114]</a>, in the following their usage is explained with respect to ADCs.</p>
<div class="section">
<h3><a id="read" name="read">Read</a></h3>
<p>The <tt class="docutils literal"><span class="pre">Read</span></tt> interface can be used to sample an ADC channel and return a single
conversion result as an uninterpreted value. The meaning of the <tt class="docutils literal"><span class="pre">Read</span></tt>
! interface is explained in <a class="citation-reference" href="#tep114" id="id10" name="id10">[TEP114]</a>.</p>
</div>
<div class="section">
***************
*** 488,496 ****
<p>The <tt class="docutils literal"><span class="pre">ReadNow</span></tt> interface is similar to the <tt class="docutils literal"><span class="pre">Read</span></tt> interface. The difference
is that if a call to <tt class="docutils literal"><span class="pre">ReadNow.read()</span></tt> succeeds, the ADC starts to sample the
! channel immediately (more precisely: when <tt class="docutils literal"><span class="pre">SUCCESS</span></tt> is returned the hardware
! has started the sampling process). Due to its timing constraints the <tt class="docutils literal"><span class="pre">ReadNow</span></tt>
! interface is always provided in conjunction with an instance of the <tt class="docutils literal"><span class="pre">Resource</span></tt>
! interface (a client must reserve the ADC before the client may call
! <tt class="docutils literal"><span class="pre">ReadNow.read()</span></tt>). Please refer to <a class="citation-reference" href="#tep108" id="id10" name="id10">[TEP108]</a> on how the <tt class="docutils literal"><span class="pre">Resource</span></tt>
interface should be used by a client component.</p>
</div>
--- 497,505 ----
<p>The <tt class="docutils literal"><span class="pre">ReadNow</span></tt> interface is similar to the <tt class="docutils literal"><span class="pre">Read</span></tt> interface. The difference
is that if a call to <tt class="docutils literal"><span class="pre">ReadNow.read()</span></tt> succeeds, the ADC starts to sample the
! channel immediately (precisely: when <tt class="docutils literal"><span class="pre">SUCCESS</span></tt> is returned the hardware has
! started the sampling process). Due to its timing constraints the <tt class="docutils literal"><span class="pre">ReadNow</span></tt>
! interface is always provided in conjunction with an instance of the
! <tt class="docutils literal"><span class="pre">Resource</span></tt> interface (a client must reserve the ADC before the client may
! call <tt class="docutils literal"><span class="pre">ReadNow.read()</span></tt>). Please refer to <a class="citation-reference" href="#tep108" id="id11" name="id11">[TEP108]</a> on how the <tt class="docutils literal"><span class="pre">Resource</span></tt>
interface should be used by a client component.</p>
</div>
***************
*** 499,503 ****
<p>The <tt class="docutils literal"><span class="pre">ReadStream</span></tt> interface can be used to sample an ADC channel multiple times
with a specified sampling period. The meaning of the <tt class="docutils literal"><span class="pre">ReadStream</span></tt> interface
! is explained in <a class="citation-reference" href="#tep114" id="id11" name="id11">[TEP114]</a> .</p>
</div>
</div>
--- 508,512 ----
<p>The <tt class="docutils literal"><span class="pre">ReadStream</span></tt> interface can be used to sample an ADC channel multiple times
with a specified sampling period. The meaning of the <tt class="docutils literal"><span class="pre">ReadStream</span></tt> interface
! is explained in <a class="citation-reference" href="#tep114" id="id12" name="id12">[TEP114]</a> .</p>
</div>
</div>
***************
*** 515,523 ****
<p>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 <tt class="docutils literal"><span class="pre">Resource</span></tt> interface, instantiate a standard
! arbiter component and connect the <tt class="docutils literal"><span class="pre">Resource</span></tt> interface to the arbiter as
! described in <a class="citation-reference" href="#tep108" id="id12" name="id12">[TEP108]</a>. To ensure fair and uniform arbitration on all platforms
! the standard round robin arbiter is recommended. The meaning of resource
! arbiters and the <tt class="docutils literal"><span class="pre">Resource</span></tt> interface is the topic of <a class="citation-reference" href="#tep108" id="id13" name="id13">[TEP108]</a>.</p>
</div>
<div class="section">
--- 524,532 ----
<p>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 <tt class="docutils literal"><span class="pre">Resource</span></tt> interface, instantiate a
! standard arbiter component and connect the <tt class="docutils literal"><span class="pre">Resource</span></tt> interface to the
! arbiter as described in <a class="citation-reference" href="#tep108" id="id13" name="id13">[TEP108]</a>. To ensure fair and uniform arbitration on
! all platforms the standard round robin arbiter is recommended. Resource
! arbiters and the <tt class="docutils literal"><span class="pre">Resource</span></tt> interface are the topic of <a class="citation-reference" href="#tep108" id="id14" name="id14">[TEP108]</a>.</p>
</div>
<div class="section">
***************
*** 527,531 ****
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
--- 536,540 ----
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
***************
*** 533,537 ****
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
--- 542,546 ----
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
***************
*** 558,574 ****
ADC:</p>
<pre class="literal-block">
! AdcReadClient
! AdcReadNowClient
! AdcReadStreamClient
</pre>
<p>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
! <a class="reference" href="#interfaces">2. Interfaces</a>. An ADC client may instantiate multiple such components. The
! following paragraphs describe their signatures. Appendix C shows the
! <tt class="docutils literal"><span class="pre">AdcReadClient</span></tt> for the MSP430.</p>
<div class="section">
! <h2><a id="adcreadclient" name="adcreadclient">AdcReadClient</a></h2>
<pre class="literal-block">
! generic configuration AdcReadClient() {
provides {
interface Read< size_type >;
--- 567,586 ----
ADC:</p>
<pre class="literal-block">
! AdcReadClientC
! AdcReadNowClientC
! AdcReadStreamClientC
</pre>
<p>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 <a class="reference" href="#interfaces">2. Interfaces</a>. 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 <tt class="docutils literal"><span class="pre">AdcReadClientC</span></tt> for
! the MSP430.</p>
<div class="section">
! <h2><a id="adcreadclientc" name="adcreadclientc">AdcReadClientC</a></h2>
<pre class="literal-block">
! generic configuration AdcReadClientC() {
provides {
interface Read< size_type >;
***************
*** 579,583 ****
}
</pre>
! <p>The <tt class="docutils literal"><span class="pre">AdcReadClient</span></tt> component provides a <tt class="docutils literal"><span class="pre">Read</span></tt> interface for acquiring
single conversion results. The associated ADC channel (port) and further
configuration details are returned by the <tt class="docutils literal"><span class="pre">AdcConfigure.getConfiguration()</span></tt>
--- 591,595 ----
}
</pre>
! <p>The <tt class="docutils literal"><span class="pre">AdcReadClientC</span></tt> component provides a <tt class="docutils literal"><span class="pre">Read</span></tt> interface for acquiring
single conversion results. The associated ADC channel (port) and further
configuration details are returned by the <tt class="docutils literal"><span class="pre">AdcConfigure.getConfiguration()</span></tt>
***************
*** 588,597 ****
command. Note that both, <tt class="docutils literal"><span class="pre">size_type</span></tt> and <tt class="docutils literal"><span class="pre">config_type</span></tt>, are only
placeholders and will be instantiated by the respective HIL implementation (for
! an example, see the AdcReadClient for the MSP430 in Appendix C).</p>
</div>
<div class="section">
! <h2><a id="adcreadnowclient" name="adcreadnowclient">AdcReadNowClient</a></h2>
<pre class="literal-block">
! generic configuration AdcReadNowClient() {
provides {
interface Resource;
--- 600,609 ----
command. Note that both, <tt class="docutils literal"><span class="pre">size_type</span></tt> and <tt class="docutils literal"><span class="pre">config_type</span></tt>, are only
placeholders and will be instantiated by the respective HIL implementation (for
! an example, see the AdcReadClientC for the MSP430 in Appendix C).</p>
</div>
<div class="section">
! <h2><a id="adcreadnowclientc" name="adcreadnowclientc">AdcReadNowClientC</a></h2>
<pre class="literal-block">
! generic configuration AdcReadNowClientC() {
provides {
interface Resource;
***************
*** 603,615 ****
}
</pre>
! <p>The <tt class="docutils literal"><span class="pre">AdcReadNowClient</span></tt> component provides a <tt class="docutils literal"><span class="pre">ReadNow</span></tt> interface for
acquiring single conversion results. In contrast to <tt class="docutils literal"><span class="pre">Read.read()</span></tt> when a call
to <tt class="docutils literal"><span class="pre">ReadNow.read()</span></tt> succeeds, the ADC starts to sample the channel
immediately (a successful <tt class="docutils literal"><span class="pre">Read.read()</span></tt> command may not have this
! implication, see <a class="citation-reference" href="#tep114" id="id14" name="id14">[TEP114]</a> and <a class="reference" href="#interfaces">2. Interfaces</a>). A client MUST reserve the ADC
through the <tt class="docutils literal"><span class="pre">Resource</span></tt> interface before the client may call
<tt class="docutils literal"><span class="pre">ReadNow.read()</span></tt> and it must release the ADC through the <tt class="docutils literal"><span class="pre">Resource</span></tt>
interface when it no longer needs to access it (for more details on the
! <tt class="docutils literal"><span class="pre">Resource</span></tt> interface please refer to <a class="citation-reference" href="#tep108" id="id15" name="id15">[TEP108]</a>). The associated ADC channel
(port) and further configuration details are returned by the
<tt class="docutils literal"><span class="pre">AdcConfigure.getConfiguration()</span></tt> command. It is the task of the client to
--- 615,627 ----
}
</pre>
! <p>The <tt class="docutils literal"><span class="pre">AdcReadNowClientC</span></tt> component provides a <tt class="docutils literal"><span class="pre">ReadNow</span></tt> interface for
acquiring single conversion results. In contrast to <tt class="docutils literal"><span class="pre">Read.read()</span></tt> when a call
to <tt class="docutils literal"><span class="pre">ReadNow.read()</span></tt> succeeds, the ADC starts to sample the channel
immediately (a successful <tt class="docutils literal"><span class="pre">Read.read()</span></tt> command may not have this
! implication, see <a class="citation-reference" href="#tep114" id="id15" name="id15">[TEP114]</a> and <a class="reference" href="#interfaces">2. Interfaces</a>). A client MUST reserve the ADC
through the <tt class="docutils literal"><span class="pre">Resource</span></tt> interface before the client may call
<tt class="docutils literal"><span class="pre">ReadNow.read()</span></tt> and it must release the ADC through the <tt class="docutils literal"><span class="pre">Resource</span></tt>
interface when it no longer needs to access it (for more details on the
! <tt class="docutils literal"><span class="pre">Resource</span></tt> interface please refer to <a class="citation-reference" href="#tep108" id="id16" name="id16">[TEP108]</a>). The associated ADC channel
(port) and further configuration details are returned by the
<tt class="docutils literal"><span class="pre">AdcConfigure.getConfiguration()</span></tt> command. It is the task of the client to
***************
*** 620,629 ****
<tt class="docutils literal"><span class="pre">size_type</span></tt> and <tt class="docutils literal"><span class="pre">config_type</span></tt>, 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).</p>
</div>
<div class="section">
! <h2><a id="adcreadstreamclient" name="adcreadstreamclient">AdcReadStreamClient</a></h2>
<pre class="literal-block">
! generic configuration AdcReadStreamClient() {
provides {
interface ReadStream< size_type >;
--- 632,641 ----
<tt class="docutils literal"><span class="pre">size_type</span></tt> and <tt class="docutils literal"><span class="pre">config_type</span></tt>, 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).</p>
</div>
<div class="section">
! <h2><a id="adcreadstreamclientc" name="adcreadstreamclientc">AdcReadStreamClientC</a></h2>
<pre class="literal-block">
! generic configuration AdcReadStreamClientC() {
provides {
interface ReadStream< size_type >;
***************
*** 634,644 ****
}
</pre>
! <p>The <tt class="docutils literal"><span class="pre">AdcReadStreamClient</span></tt> component provides a <tt class="docutils literal"><span class="pre">ReadStream</span></tt> interface for
acquiring multiple conversion results at once. The <tt class="docutils literal"><span class="pre">ReadStream</span></tt> interface is
! explained in <a class="citation-reference" href="#tep114" id="id16" name="id16">[TEP114]</a> and <a class="reference" href="#interfaces">2. Interfaces</a>. The <tt class="docutils literal"><span class="pre">AdcConfigure</span></tt> interface is
! used in the same way as described in the section on the <tt class="docutils literal"><span class="pre">AdcReadClient</span></tt>.
Note that both, <tt class="docutils literal"><span class="pre">size_type</span></tt> and <tt class="docutils literal"><span class="pre">config_type</span></tt>, 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).</p>
</div>
</div>
--- 646,656 ----
}
</pre>
! <p>The <tt class="docutils literal"><span class="pre">AdcReadStreamClientC</span></tt> component provides a <tt class="docutils literal"><span class="pre">ReadStream</span></tt> interface for
acquiring multiple conversion results at once. The <tt class="docutils literal"><span class="pre">ReadStream</span></tt> interface is
! explained in <a class="citation-reference" href="#tep114" id="id17" name="id17">[TEP114]</a> and <a class="reference" href="#interfaces">2. Interfaces</a>. The <tt class="docutils literal"><span class="pre">AdcConfigure</span></tt> interface is
! used in the same way as described in the section on the <tt class="docutils literal"><span class="pre">AdcReadClientC</span></tt>.
Note that both, <tt class="docutils literal"><span class="pre">size_type</span></tt> and <tt class="docutils literal"><span class="pre">config_type</span></tt>, 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).</p>
</div>
</div>
***************
*** 648,663 ****
<tt class="docutils literal"><span class="pre">Read</span></tt>, <tt class="docutils literal"><span class="pre">ReadNow</span></tt> or <tt class="docutils literal"><span class="pre">ReadStream</span></tt> request to a chip-specific HAL sampling
command and it abstracts from the <tt class="docutils literal"><span class="pre">Resource</span></tt> interface (the latter only for
! the <tt class="docutils literal"><span class="pre">AdcReadClient</span></tt> and <tt class="docutils literal"><span class="pre">AdcReadStreamClient</span></tt>). The first task is solved
with the help of the <tt class="docutils literal"><span class="pre">AdcConfigure</span></tt> 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: <tt class="docutils literal"><span class="pre">ArbitratedReadC</span></tt>, and
<tt class="docutils literal"><span class="pre">ArbitratedReadStreamC</span></tt> (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 <tt class="docutils literal"><span class="pre">ReadNow</span></tt> interface is always provided in
conjunction with a <tt class="docutils literal"><span class="pre">Resource</span></tt> interface the HIL implementation does not have
! to perform the ADC resource reservation for an <tt class="docutils literal"><span class="pre">AdcReadNowClient`,</span> <span class="pre">but</span> <span class="pre">may</span>
! <span class="pre">simply</span> <span class="pre">forward</span> <span class="pre">an</span> <span class="pre">instance</span> <span class="pre">of</span> <span class="pre">the</span> <span class="pre">``Resource</span></tt> interface from the HAL to the
! <tt class="docutils literal"><span class="pre">AdcReadNowClient</span></tt>.</p>
! <p>The typical sequence of events is as follows: When a client requests data
through the <tt class="docutils literal"><span class="pre">Read</span></tt> or <tt class="docutils literal"><span class="pre">ReadStream</span></tt> interface the HIL will request access to
the HAL using the <tt class="docutils literal"><span class="pre">Resource</span></tt> interface. After the HIL has been granted
--- 660,675 ----
<tt class="docutils literal"><span class="pre">Read</span></tt>, <tt class="docutils literal"><span class="pre">ReadNow</span></tt> or <tt class="docutils literal"><span class="pre">ReadStream</span></tt> request to a chip-specific HAL sampling
command and it abstracts from the <tt class="docutils literal"><span class="pre">Resource</span></tt> interface (the latter only for
! the <tt class="docutils literal"><span class="pre">AdcReadClientC</span></tt> and <tt class="docutils literal"><span class="pre">AdcReadStreamClientC</span></tt>). The first task is solved
with the help of the <tt class="docutils literal"><span class="pre">AdcConfigure</span></tt> 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: <tt class="docutils literal"><span class="pre">ArbitratedReadC</span></tt>, and
<tt class="docutils literal"><span class="pre">ArbitratedReadStreamC</span></tt> (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 <tt class="docutils literal"><span class="pre">ReadNow</span></tt> interface is always provided in
conjunction with a <tt class="docutils literal"><span class="pre">Resource</span></tt> interface the HIL implementation does not have
! to perform the ADC resource reservation for an <tt class="docutils literal"><span class="pre">AdcReadNowClientC</span></tt>, but may
! simply forward an instance of the <tt class="docutils literal"><span class="pre">Resource</span></tt> interface from the HAL to the
! <tt class="docutils literal"><span class="pre">AdcReadNowClientC</span></tt>.</p>
! <p>The typical sequence of events is as follows: when a client requests data
through the <tt class="docutils literal"><span class="pre">Read</span></tt> or <tt class="docutils literal"><span class="pre">ReadStream</span></tt> interface the HIL will request access to
the HAL using the <tt class="docutils literal"><span class="pre">Resource</span></tt> interface. After the HIL has been granted
***************
*** 685,689 ****
<li><tt class="docutils literal"><span class="pre">AdcReadClientC.nc</span></tt>, <tt class="docutils literal"><span class="pre">AdcReadNowClientC.nc</span></tt> and
<tt class="docutils literal"><span class="pre">AdcReadStreamClientC.nc</span></tt> provide virtualized access to the HIL</li>
! <li>Please refer to the <tt class="docutils literal"><span class="pre">README.txt</span></tt> to</li>
</ul>
</blockquote>
--- 697,702 ----
<li><tt class="docutils literal"><span class="pre">AdcReadClientC.nc</span></tt>, <tt class="docutils literal"><span class="pre">AdcReadNowClientC.nc</span></tt> and
<tt class="docutils literal"><span class="pre">AdcReadStreamClientC.nc</span></tt> provide virtualized access to the HIL</li>
! <li>the use of DMA or the reference voltage generator and the
! HAL virtualization components are explained in <tt class="docutils literal"><span class="pre">README.txt</span></tt></li>
</ul>
</blockquote>
***************
*** 699,706 ****
the HAL</li>
<li><tt class="docutils literal"><span class="pre">AdcReadClientC.nc</span></tt>, <tt class="docutils literal"><span class="pre">AdcReadNowClientC.nc</span></tt> and
! <tt class="docutils literal"><span class="pre">AdcReadStreamClientC.nc</span></tt> 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 <tt class="docutils literal"><span class="pre">Atm128AdcConfig.nc</span></tt></li>
</ul>
</blockquote>
--- 712,716 ----
the HAL</li>
<li><tt class="docutils literal"><span class="pre">AdcReadClientC.nc</span></tt>, <tt class="docutils literal"><span class="pre">AdcReadNowClientC.nc</span></tt> and
! <tt class="docutils literal"><span class="pre">AdcReadStreamClientC.nc</span></tt> provide virtualized access to the HIL</li>
</ul>
</blockquote>
***************
*** 837,844 ****
</div>
<div class="section">
! <h1><a id="appendix-b-an-hal-representation-msp430-adc12" name="appendix-b-an-hal-representation-msp430-adc12">Appendix B: an HAL representation: MSP430 ADC12</a></h1>
! <p>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
--- 847,854 ----
</div>
<div class="section">
! <h1><a id="appendix-b-a-hal-representation-msp430-adc12" name="appendix-b-a-hal-representation-msp430-adc12">Appendix B: a HAL representation: MSP430 ADC12</a></h1>
! <p>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
***************
*** 846,850 ****
interrupt after multiple samples and thus enable high-frequency sampling. The
<tt class="docutils literal"><span class="pre">DMAExtension</span></tt> interface is used to reset the state machine when the DMA is
! responsible for data transfer:</p>
<pre class="literal-block">
configuration Msp430Adc12P
--- 856,860 ----
interrupt after multiple samples and thus enable high-frequency sampling. The
<tt class="docutils literal"><span class="pre">DMAExtension</span></tt> interface is used to reset the state machine when the DMA is
! responsible for data transfer (managed in an exterior component):</p>
<pre class="literal-block">
configuration Msp430Adc12P
***************
*** 867,874 ****
async event uint16_t* multipleDataReady(uint16_t buffer[], uint16_t numSamples);
}
</pre>
</div>
<div class="section">
! <h1><a id="appendix-c-an-hil-representation-msp430-adc12" name="appendix-c-an-hil-representation-msp430-adc12">Appendix C: an HIL representation: MSP430 ADC12</a></h1>
<p>The signature of the AdcReadClientC component for the MSP430 ADC12 is as
follows:</p>
--- 877,895 ----
async event uint16_t* multipleDataReady(uint16_t buffer[], uint16_t numSamples);
}
+
+ 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;
</pre>
</div>
<div class="section">
! <h1><a id="appendix-c-a-hil-representation-msp430-adc12" name="appendix-c-a-hil-representation-msp430-adc12">Appendix C: a HIL representation: MSP430 ADC12</a></h1>
<p>The signature of the AdcReadClientC component for the MSP430 ADC12 is as
follows:</p>
***************
*** 888,892 ****
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
! <tr><td class="label"><a name="tep2">[TEP2]</a></td><td><em>(<a class="fn-backref" href="#id5">1</a>, <a class="fn-backref" href="#id6">2</a>)</em> TEP 2: Hardware Abstraction Architecture.</td></tr>
</tbody>
</table>
--- 909,913 ----
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
! <tr><td class="label"><a name="tep2">[TEP2]</a></td><td><em>(<a class="fn-backref" href="#id5">1</a>, <a class="fn-backref" href="#id6">2</a>, <a class="fn-backref" href="#id7">3</a>)</em> TEP 2: Hardware Abstraction Architecture.</td></tr>
</tbody>
</table>
***************
*** 894,898 ****
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
! <tr><td class="label"><a name="tep108">[TEP108]</a></td><td><em>(<a class="fn-backref" href="#id10">1</a>, <a class="fn-backref" href="#id12">2</a>, <a class="fn-backref" href="#id13">3</a>, <a class="fn-backref" href="#id15">4</a>)</em> TEP 108: Resource Arbitration.</td></tr>
</tbody>
</table>
--- 915,919 ----
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
! <tr><td class="label"><a name="tep108">[TEP108]</a></td><td><em>(<a class="fn-backref" href="#id11">1</a>, <a class="fn-backref" href="#id13">2</a>, <a class="fn-backref" href="#id14">3</a>, <a class="fn-backref" href="#id16">4</a>)</em> TEP 108: Resource Arbitration.</td></tr>
</tbody>
</table>
***************
*** 903,916 ****
</tbody>
</table>
- <table class="docutils citation" frame="void" id="tep111" rules="none">
- <colgroup><col class="label" /><col /></colgroup>
- <tbody valign="top">
- <tr><td class="label"><a class="fn-backref" href="#id3" name="tep111">[TEP111]</a></td><td>TEP 111: message_t</td></tr>
- </tbody>
- </table>
<table class="docutils citation" frame="void" id="tep114" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
! <tr><td class="label"><a name="tep114">[TEP114]</a></td><td><em>(<a class="fn-backref" href="#id4">1</a>, <a class="fn-backref" href="#id7">2</a>, <a class="fn-backref" href="#id8">3</a>, <a class="fn-backref" href="#id9">4</a>, <a class="fn-backref" href="#id11">5</a>, <a class="fn-backref" href="#id14">6</a>, <a class="fn-backref" href="#id16">7</a>)</em> TEP 114: SIDs: Source and Sink Independent Drivers.</td></tr>
</tbody>
</table>
--- 924,931 ----
</tbody>
</table>
<table class="docutils citation" frame="void" id="tep114" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
! <tr><td class="label"><a name="tep114">[TEP114]</a></td><td><em>(<a class="fn-backref" href="#id3">1</a>, <a class="fn-backref" href="#id4">2</a>, <a class="fn-backref" href="#id8">3</a>, <a class="fn-backref" href="#id9">4</a>, <a class="fn-backref" href="#id10">5</a>, <a class="fn-backref" href="#id12">6</a>, <a class="fn-backref" href="#id15">7</a>, <a class="fn-backref" href="#id17">8</a>)</em> TEP 114: SIDs: Source and Sink Independent Drivers.</td></tr>
</tbody>
</table>
More information about the Tinyos-2-commits
mailing list