[Tinyos-2-commits] CVS: tinyos-2.x/doc/html tep101.html,1.6,1.7
Jan-Hinrich Hauer
janhauer at users.sourceforge.net
Fri Dec 29 07:48:55 PST 2006
Update of /cvsroot/tinyos/tinyos-2.x/doc/html
In directory sc8-pr-cvs10.sourceforge.net:/tmp/cvs-serv9531/doc/html
Modified Files:
tep101.html
Log Message:
Updated the ADC TEP once more:
1) integrated last suggested by reviewer (J.Stankovic):
- added a subsection in the "Implementation" section to reference the "TestAdc" implementation
- added a section that better describes how the "AdcConfigure" interface pulls the client's settings
- "sensors" -> "sensor drivers" in the introduction section
2) documented the ReadNow interface - as agreed during the last confcall it will not be documented in the SIDs TEP
3) minor (cosmetic) changes
Index: tep101.html
===================================================================
RCS file: /cvsroot/tinyos/tinyos-2.x/doc/html/tep101.html,v
retrieving revision 1.6
retrieving revision 1.7
diff -C2 -d -r1.6 -r1.7
*** tep101.html 12 Dec 2006 18:22:53 -0000 1.6
--- tep101.html 29 Dec 2006 15:48:52 -0000 1.7
***************
*** 4,8 ****
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
! <meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
<title>Analog-to-Digital Converters (ADCs)</title>
<meta name="author" content="Jan-Hinrich Hauer, Philip Levis, Vlado Handziski, David Gay" />
--- 4,8 ----
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
! <meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
<title>Analog-to-Digital Converters (ADCs)</title>
<meta name="author" content="Jan-Hinrich Hauer, Philip Levis, Vlado Handziski, David Gay" />
***************
*** 304,310 ****
<tr class="field"><th class="docinfo-name">Draft-Created:</th><td class="field-body">20-Dec-2004</td>
</tr>
! <tr class="field"><th class="docinfo-name">Draft-Version:</th><td class="field-body">1.1.2.9</td>
</tr>
! <tr class="field"><th class="docinfo-name">Draft-Modified:</th><td class="field-body">2006-10-12</td>
</tr>
<tr class="field"><th class="docinfo-name">Draft-Discuss:</th><td class="field-body">TinyOS Developer List <tinyos-devel at mail.millennium.berkeley.edu></td>
--- 304,310 ----
<tr class="field"><th class="docinfo-name">Draft-Created:</th><td class="field-body">20-Dec-2004</td>
</tr>
! <tr class="field"><th class="docinfo-name">Draft-Version:</th><td class="field-body">1.1.2.10</td>
</tr>
! <tr class="field"><th class="docinfo-name">Draft-Modified:</th><td class="field-body">2006-11-07</td>
</tr>
<tr class="field"><th class="docinfo-name">Draft-Discuss:</th><td class="field-body">TinyOS Developer List <tinyos-devel at mail.millennium.berkeley.edu></td>
***************
*** 323,327 ****
<p>This TEP proposes a hardware abstraction for analog-to-digital converters (ADCs)
in TinyOS 2.x, which is aligned to the three-layer Hardware Abstraction
! Architecture (HAA) specified in [TEP2]. It describes some design principles and
documents the set of hardware-independent interfaces to an ADC.</p>
</div>
--- 323,327 ----
<p>This TEP proposes a hardware abstraction for analog-to-digital converters (ADCs)
in TinyOS 2.x, which is aligned to the three-layer Hardware Abstraction
! Architecture (HAA) specified in <a class="citation-reference" href="#tep2" id="id2" name="id2">[TEP2]</a>. It describes some design principles and
documents the set of hardware-independent interfaces to an ADC.</p>
</div>
***************
*** 337,347 ****
completely different. To compensate for the difference non-ADC sensors
introduced additional interfaces, such as <tt class="docutils literal"><span class="pre">ADCError</span></tt>, that were tightly bound
! to sensor acquisition but separate in wiring. The separation between the ADC and
! <tt class="docutils literal"><span class="pre">ADCError</span></tt> interface is bug prone and problematic, as is the equation of a
! sensor and an ADC. TinyOS 2.x separates the structure and interfaces of an ADC
! from those of sensors (which may be on top of an ADC, but this fact is hidden
! from higher level components). This TEP presents how TinyOS 2.x structures ADC
! 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
--- 337,347 ----
completely different. To compensate for the difference non-ADC sensors
introduced additional interfaces, such as <tt class="docutils literal"><span class="pre">ADCError</span></tt>, that were tightly bound
! to sensor acquisition but separate in wiring. The separation between the ADC
! and <tt class="docutils literal"><span class="pre">ADCError</span></tt> interface is bug prone and problematic, as is the equation of
! a sensor and an ADC. TinyOS 2.x separates the structure and interfaces of an
! ADC from those of sensor drivers (which may be on top of an ADC stack, but
! this fact is hidden from higher level components). This TEP presents how TinyOS
! 2.x structures ADC software. <a class="citation-reference" href="#tep109" id="id3" name="id3">[TEP109]</a> (Sensor Boards) shows how a platform can
! present actual named sensors.</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
***************
*** 356,399 ****
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
! software development conversion results are returned by the ADC hardware stack
! using the standard TinyOS interfaces <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>
! (see <a class="reference" href="#interfaces">2. Interfaces</a> and <a class="citation-reference" href="#tep114" id="id4" name="id4">[TEP114]</a>). Conversion results are returned as
! uninterpreted values and translating them to engineering units can only be done
! with the configuration knowledge of the respective platform, for example, the
! reference voltage or the resistance of a reference resistor in ratiometric
! measurements. Translating uninterpreted values to engineering units is
! performed by components located on top of the ADC hardware stack and out of the
! scope of this TEP.</p>
<p>The top layer of abstraction of an ADC - the Hardware Interface Layer (HIL) -
! thus provides the standard TinyOS interfaces <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> 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">
^ |
--- 356,396 ----
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="id4" name="id4">[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, it
! can also provide 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 ADCs: they all produce conversion results. To facilitate sensor
! software development conversion results are returned by the ADC stack through
! the interfaces <tt class="docutils literal"><span class="pre">Read</span></tt>, <tt class="docutils literal"><span class="pre">ReadStream</span></tt> and <tt class="docutils literal"><span class="pre">ReadNow</span></tt> (see <a class="reference" href="#interfaces">2. Interfaces</a>
! and <a class="citation-reference" href="#tep114" id="id5" name="id5">[TEP114]</a>). Conversion results are returned as uninterpreted values and
! translating them to engineering units can only be done with the configuration
! knowledge of the respective platform, for example, the reference voltage or the
! resistance of a reference resistor in ratiometric measurements. Translating
! uninterpreted values to engineering units may be performed by components
! located on top of the ADC stack and is out of the scope of this TEP.</p>
<p>The top layer of abstraction of an ADC - the Hardware Interface Layer (HIL) -
! thus provides the interfaces <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> 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="id6" name="id6">[TEP2]</a>).</p>
! <p>Following the principles of the HAA <a class="citation-reference" href="#tep2" id="id7" name="id7">[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 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 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="id8" name="id8">[TEP2]</a>). The general structure
! (without virtualization) of the ADC stack is as follows</p>
<pre class="literal-block">
^ |
***************
*** 446,452 ****
<h1><a id="interfaces" name="interfaces">2. Interfaces</a></h1>
<p>This TEP proposes the <tt class="docutils literal"><span class="pre">AdcConfigure</span></tt> interface for ADC hardware configuration
! 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>
--- 443,451 ----
<h1><a id="interfaces" name="interfaces">2. Interfaces</a></h1>
<p>This TEP proposes the <tt class="docutils literal"><span class="pre">AdcConfigure</span></tt> interface for ADC hardware configuration
! and the <tt class="docutils literal"><span class="pre">Read</span></tt>, <tt class="docutils literal"><span class="pre">ReadStream</span></tt> and <tt class="docutils literal"><span class="pre">ReadNow</span></tt> interfaces to acquire
! conversion results. The <tt class="docutils literal"><span class="pre">Read</span></tt> and <tt class="docutils literal"><span class="pre">ReadStream</span></tt> interfaces are documented
! in <a class="citation-reference" href="#tep114" id="id9" name="id9">[TEP114]</a> and the <tt class="docutils literal"><span class="pre">ReadNow</span></tt> interface is documented in this TEP. 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>
***************
*** 458,483 ****
}
</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">
interface Read< size_type >
- interface ReadNow< size_type >
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
--- 457,494 ----
}
</pre>
! <p>This interface is used by the ADC stack to retrieve the hardware configuration
! of an ADC HIL 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>
! <p>Note that the <tt class="docutils literal"><span class="pre">AdcConfigure</span></tt> interface is <strong>provided</strong> by an ADC HIL client
! and it is <strong>used</strong> by the ADC HIL implementation. Therefore an ADC HIL client
! cannot initiate the configuration of the ADC hardware itself. Instead it is the
! ADC HIL implementation that can "pull" the client's ADC configuration just
! before it initates a conversion based on the respective client's configuration.
! The rationale is that the ADC HIL implementation does not have to store an ADC
! configuration per client - instead the ADC client can, for example, store its
! configuration in program memory.</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 two source-independent data
! collection interfaces from <a class="citation-reference" href="#tep114" id="id10" name="id10">[TEP114]</a> for the collection of ADC conversion
results on the level of HIL:</p>
<pre class="literal-block">
interface Read< size_type >
interface ReadStream< size_type >
</pre>
+ <p>In addition it proposes the following data collection interface for low-latency
+ reading of conversion results:</p>
+ <pre class="literal-block">
+ interface ReadNow< 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
***************
*** 485,512 ****
<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">
! <h3><a id="readnow" name="readnow">ReadNow</a></h3>
! <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>
<div class="section">
! <h3><a id="readstream" name="readstream">ReadStream</a></h3>
! <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>
--- 496,534 ----
<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).</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 once and return a
! single conversion result as an uninterpreted value. The <tt class="docutils literal"><span class="pre">Read</span></tt> interface is
! documented in <a class="citation-reference" href="#tep114" id="id11" name="id11">[TEP114]</a>.</p>
</div>
<div class="section">
! <h3><a id="readstream" name="readstream">ReadStream</a></h3>
! <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 <tt class="docutils literal"><span class="pre">ReadStream</span></tt> interface is
! documented in <a class="citation-reference" href="#tep114" id="id12" name="id12">[TEP114]</a> .</p>
</div>
<div class="section">
! <h3><a id="readnow" name="readnow">ReadNow</a></h3>
! <p>The <tt class="docutils literal"><span class="pre">ReadNow</span></tt> interface is intended for split-phase low-latency
! reading of small values:</p>
! <pre class="literal-block">
! interface ReadNow<val_t>
! {
! async command error_t read();
! async event void readDone( error_t result, val_t val );
! }
! </pre>
! <p>This interface is similar to the <tt class="docutils literal"><span class="pre">Read</span></tt> interface, but works in asynchronous
! context. A successful call to <tt class="docutils literal"><span class="pre">ReadNow.read()</span></tt> means that the ADC hardware
! has started the sampling process and that <tt class="docutils literal"><span class="pre">ReadNow.readDone()</span></tt> will be
! signalled once it has finished (note that the asynchronous
! <tt class="docutils literal"><span class="pre">ReadNow.readDone()</span></tt> might be signalled even before the call to
! <tt class="docutils literal"><span class="pre">ReadNow.read()</span></tt> has returned). 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 and 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>. Please
! refer to <a class="citation-reference" href="#tep108" id="id13" name="id13">[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>
</div>
***************
*** 517,523 ****
ADC hardware. Therefore only chip- and platform-dependent clients can wire to
the HAL. Although the HAL is chip-specific, both, in terms of implementation
! and representation, its design should follow the guidelines described below to
! facilitate the mapping to the HIL representation. Appendix B shows the
! signature of the HAL for the MSP430.</p>
<div class="section">
<h2><a id="resource-reservation" name="resource-reservation">Resource reservation</a></h2>
--- 539,545 ----
ADC hardware. Therefore only chip- and platform-dependent clients can wire to
the HAL. Although the HAL is chip-specific, both, in terms of implementation
! and representation, its design should follow the guidelines described in this
! section to facilitate the mapping to the HIL representation. Appendix B shows
! the signature of the HAL for the MSP430.</p>
<div class="section">
<h2><a id="resource-reservation" name="resource-reservation">Resource reservation</a></h2>
***************
*** 526,532 ****
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">
--- 548,554 ----
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="id14" name="id14">[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="id15" name="id15">[TEP108]</a>.</p>
</div>
<div class="section">
***************
*** 619,628 ****
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
wire this interface to a component that provides the client's ADC
--- 641,650 ----
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="id16" name="id16">[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 how to use
! the <tt class="docutils literal"><span class="pre">Resource</span></tt> interface please refer to <a class="citation-reference" href="#tep108" id="id17" name="id17">[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
wire this interface to a component that provides the client's ADC
***************
*** 648,652 ****
<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
--- 670,674 ----
<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="id18" name="id18">[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
***************
*** 688,691 ****
--- 710,723 ----
<div class="section">
<h1><a id="implementation" name="implementation">6. Implementation</a></h1>
+ <div class="section">
+ <h2><a id="testadc-application" name="testadc-application">TestAdc application</a></h2>
+ <p>An ADC HIL test application can be found in <tt class="docutils literal"><span class="pre">tinyos-2.x/apps/tests/TestAdc</span></tt>.
+ Note that this application instantiates generic DemoSensorC, DemoSensorStreamC
+ and DemoSensorNowC components (see <a class="citation-reference" href="#tep114" id="id19" name="id19">[TEP114]</a>) and assumes that these components
+ are actually wired to an ADC HIL. Please refer to
+ <tt class="docutils literal"><span class="pre">tinyos-2.x/apps/tests/TestAdc/README.txt</span></tt> for more information.</p>
+ </div>
+ <div class="section">
+ <h2><a id="haa-on-the-msp430-and-atmega-128" name="haa-on-the-msp430-and-atmega-128">HAA on the MSP430 and Atmega 128</a></h2>
<p>The implementation of the ADC12 stack on the MSP430 can be found in
<tt class="docutils literal"><span class="pre">tinyos-2.x/tos/chips/msp430/adc12</span></tt>:</p>
***************
*** 707,714 ****
<li><tt class="docutils literal"><span class="pre">HplAtm128AdcC.nc</span></tt> is the HPL implementation</li>
<li><tt class="docutils literal"><span class="pre">Atm128AdcP.nc</span></tt> is the HAL implementation</li>
! <li><tt class="docutils literal"><span class="pre">WireAdcP.nc</span></tt> and the library components for arbitrating 'Read',
! 'ReadNow' and 'ReadStream', <tt class="docutils literal"><span class="pre">ArbitratedReadC</span></tt> and
<tt class="docutils literal"><span class="pre">ArbitratedReadStreamC</span></tt> (in <tt class="docutils literal"><span class="pre">tinyos-2.x/tos/system</span></tt>), realize
! 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>
--- 739,746 ----
<li><tt class="docutils literal"><span class="pre">HplAtm128AdcC.nc</span></tt> is the HPL implementation</li>
<li><tt class="docutils literal"><span class="pre">Atm128AdcP.nc</span></tt> is the HAL implementation</li>
! <li><tt class="docutils literal"><span class="pre">AdcP.nc</span></tt>, <tt class="docutils literal"><span class="pre">WireAdcP.nc</span></tt> and the library components for arbitrating
! 'Read', 'ReadNow' and 'ReadStream', <tt class="docutils literal"><span class="pre">ArbitratedReadC</span></tt> and
<tt class="docutils literal"><span class="pre">ArbitratedReadStreamC</span></tt> (in <tt class="docutils literal"><span class="pre">tinyos-2.x/tos/system</span></tt>), realize
! the HIL</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>
***************
*** 716,719 ****
--- 748,752 ----
</blockquote>
</div>
+ </div>
<div class="section">
<h1><a id="appendix-a-hardware-differences-between-platforms" name="appendix-a-hardware-differences-between-platforms">Appendix A: Hardware differences between platforms</a></h1>
***************
*** 878,882 ****
}
! typedef struct {
unsigned int inch: 4; // input channel
unsigned int sref: 3; // reference voltage
--- 911,916 ----
}
! typedef struct
! {
unsigned int inch: 4; // input channel
unsigned int sref: 3; // reference voltage
***************
*** 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>
--- 943,947 ----
<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="#id2">1</a>, <a class="fn-backref" href="#id6">2</a>, <a class="fn-backref" href="#id7">3</a>, <a class="fn-backref" href="#id8">4</a>)</em> TEP 2: Hardware Abstraction Architecture.</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>
--- 949,953 ----
<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="#id13">1</a>, <a class="fn-backref" href="#id14">2</a>, <a class="fn-backref" href="#id15">3</a>, <a class="fn-backref" href="#id17">4</a>)</em> TEP 108: Resource Arbitration.</td></tr>
</tbody>
</table>
***************
*** 921,925 ****
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
! <tr><td class="label"><a class="fn-backref" href="#id2" name="tep109">[TEP109]</a></td><td>TEP 109: Sensor Boards.</td></tr>
</tbody>
</table>
--- 955,959 ----
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
! <tr><td class="label"><a class="fn-backref" href="#id3" name="tep109">[TEP109]</a></td><td>TEP 109: Sensor Boards.</td></tr>
</tbody>
</table>
***************
*** 927,931 ****
<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>
--- 961,965 ----
<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="#id5">2</a>, <a class="fn-backref" href="#id9">3</a>, <a class="fn-backref" href="#id10">4</a>, <a class="fn-backref" href="#id11">5</a>, <a class="fn-backref" href="#id12">6</a>, <a class="fn-backref" href="#id16">7</a>, <a class="fn-backref" href="#id18">8</a>, <a class="fn-backref" href="#id19">9</a>)</em> TEP 114: SIDs: Source and Sink Independent Drivers.</td></tr>
</tbody>
</table>
More information about the Tinyos-2-commits
mailing list