[Tinyos-2-commits] CVS: tinyos-2.x/doc/txt tep102.txt, 1.1.2.5,
1.1.2.6
Cory Sharp
cssharp at users.sourceforge.net
Tue Oct 17 13:00:44 PDT 2006
Update of /cvsroot/tinyos/tinyos-2.x/doc/txt
In directory sc8-pr-cvs10.sourceforge.net:/tmp/cvs-serv15207
Modified Files:
Tag: tinyos-2_0_devel-BRANCH
tep102.txt
Log Message:
Addressed almost all current issues in the TEP 102 Discussion. One outstanding
issue is if we want to address the potentially confusing naming convention of
TMilli being a *binary* millisecond.
Issues addressed:
* Clarified Counter.isOverflowPending by discussing the overflow flag
* Changed a capitalized Compare to lowercase
* Expounded on Alarm.getAlarm to briefly discuss its use in creating a periodic
alarm
* Describe when in general to BusyWait vs Alarm, and explain that there is no
explicit upper bound on the wait time.
* Significantly clarify "3. HAL guidelines". Removed most of the platform
specific description from this section, instead keeping the discussion platform
independent. Use ${P} and ${W} in the component naming patterns. Soften up
the (implicit?) assertion that new alarms always map to independent hardware
timers.
* Remove the #define TIMERMILLIC_SERVICE ... line, change TIMERMILLIC_SERVICE
to UQ_TIMER_MILLI and explain that it is defined in Timer.h.
* Explain that TransformAlarmC imposes no consistency checks.
* Added "Section 6. Implementation". Briefly overview the components in
tos/lib/timer/ and tos/chips/msp430/timer/. Someone needs to fill this in for
the mica/atmel etc.
* Bump "Author's Address" to section 7, add my phone number.
Index: tep102.txt
===================================================================
RCS file: /cvsroot/tinyos/tinyos-2.x/doc/txt/tep102.txt,v
retrieving revision 1.1.2.5
retrieving revision 1.1.2.6
diff -C2 -d -r1.1.2.5 -r1.1.2.6
*** tep102.txt 21 Sep 2006 01:38:09 -0000 1.1.2.5
--- tep102.txt 17 Oct 2006 20:00:40 -0000 1.1.2.6
***************
*** 160,168 ****
isOverflowPending()
! return TRUE if an overflow interrupt will occur after the outermost
! atomic block is exits. FALSE otherwise.
clearOverflow()
! cancel the pending overflow interrupt.
overflow()
--- 160,173 ----
isOverflowPending()
!
! return TRUE if the overflow flag is set for this counter. That
! is, if an overflow interrupt will occur after the outermost atomic
! block is exits. Return FALSE otherwise. This command only
! returns the state of the overflow flag and causes no side effect.
! It is expected that the underlying hardware platforms sets
! overflow flag when appropriate.
clearOverflow()
! cancel the pending overflow interrupt clearing the overflow flag.
overflow()
***************
*** 175,179 ****
Alarm components are extensions of Counters that signal an event
! when their Compare register detects the alarm time has been hit.
All commands and events of the Alarm interface are asynchronous (or
in "interrupt context"). The Alarm interface provides a set of
--- 180,184 ----
Alarm components are extensions of Counters that signal an event
! when their compare register detects the alarm time has been hit.
All commands and events of the Alarm interface are asynchronous (or
in "interrupt context"). The Alarm interface provides a set of
***************
*** 211,220 ****
startAt(t0,dt)
cancel any previously running alarm and set to fire at time t1 =
t0+dt. This form allows a delay to be anchored to some time t0
! taken before the invocation of start. This is also the form used
! internally in the timer subsystem to allow the use of the full width
! of an alarm while being able to detect if the alarm time for a short
! alarm prematurely elapsed.
getNow()
--- 216,226 ----
startAt(t0,dt)
+
cancel any previously running alarm and set to fire at time t1 =
t0+dt. This form allows a delay to be anchored to some time t0
! taken before the invocation of startAt. This is also the form
! used internally in the timer subsystem to allow the use of the
! full width of an alarm while being detecting if the alarm time for
! a short alarm prematurely elapsed.
getNow()
***************
*** 223,227 ****
getAlarm()
return the time the currently running alarm will fire or the time
! that the previously running alarm was set to fire.
--- 229,236 ----
getAlarm()
return the time the currently running alarm will fire or the time
! that the previously running alarm was set to fire. getAlarm can
! be used with startAt to set an alarm from the previous alarm time,
! as in startAt(getAlarm(),dt). This pattern is used within the
! fired() event to construct periodic alarms.
***************
*** 229,234 ****
--------------------------------------------------------------------
! The BusyWait interface replaces the TOSH_uwait macro from TinyOS
! 1.x. ::
interface BusyWait<precision_tag,size_type>
--- 238,251 ----
--------------------------------------------------------------------
! The BusyWait interface allows for very short synchronous delays.
! BusyWait should be used sparingly and when an Alarm would not be
! reasonably efficient or accurate. The BusyWait interface replaces
! the TOSH_uwait macro from TinyOS 1.x.
!
! BusyWait blocks for no less than the specified amount of time. No
! explicit upper bound is imposed on the enacted delay, though it is
! expected the underlying implementation spins in a busy loop until
! the specified amount of time has elapsed.
! ::
interface BusyWait<precision_tag,size_type>
***************
*** 238,242 ****
wait(dt)
! block for no less than the specified amount of time.
LocalTime
--- 255,259 ----
wait(dt)
! block until at least dt time units have elapsed
LocalTime
***************
*** 331,375 ****
====================================================================
! Platforms typically select a clocking option for each of their
! hardware counters, based on their hardware design (e.g., the mica
! family of motes all run their hardware timer 0 at 32kHz, and the micaz
! mote runs its timer 1 at cpu frequency/256). Platforms SHOULD expose
! the timing functionality of these timers using the Alarm and Counter
! interfaces, in the fashion described below. Platforms MAY expose the
! same hardware timer with different frequencies - use of conflicting
! frequences in the same program SHOULD produce compile-time
! errors.
! A hardware timer with precision *P* and width *W* SHOULD be exposed as
! several components::
! configuration CounterPWC {
! provides interface Counter<TP, uintW_t>;
! } ...
! generic configuration AlarmPWC {
! provides interface Alarm<TP,uintW_t>;
! } ...
! and, except if *W* is 32::
! configuration CounterP32C {
! provides interface Counter<TP, uint32_t>;
! } ...
! generic configuration AlarmP32C {
! provides interface Alarm<TP,uint32_t>;
! } ...
! Instantiating the Alarm... components provides a new Alarm independent
! of all prior instantiations. Instantiating such a component "consumes"
! a compare register from the corresponding hardware timer; when no more
! compare registers are available, instantiation SHOULD produce a
! compile-time error (see Appendix B for an example of how to achieve
! this).
! For example, the micaz platform includes an AlarmMilli8C and
! AlarmMilli32C components for timer 0 (one instantiation allowed), and
! Alarm32kHz16C and Alarm32kHz32C for timer 1 (three instantiations
! allowed).
4. HIL requirements
--- 348,396 ----
====================================================================
! Platforms SHOULD expose their relevant timing capabilities using
! standard Alarm and Counter interfaces. The design pattern presented
! here defines a component naming convention to allow platform
! independent access to particular Alarms and Counters if they exist
! and to cause compile errors if they do not.
+ A platform specific hardware timer with precision ${P} and width
+ ${W} SHOULD be exposed as these two conventional Counter and Alarm
+ components::
! configuration Counter${P}${W}C
! {
! provides interface Counter< T${P}, uint${W}_t >;
! }
! generic configuration Alarm${P}${W}C
! {
! provides interface Alarm< T${P}, uint${W}_t >;
! }
! Instantiating a Alarm${P}${W}C component provides a new and
! independent Alarm. If the platform presents a limited number of
! Alarm resources, then allocating more Alarms in an application than
! are available for the platform SHOULD produce a compile-time error.
! See Appendix B for an example of how to make allocatable Alarms that
! are each implemented on independent hardware timers.
! For example, if a platform has an 8-bit 32kHz counter and three
! 8-bit 32kHz alarms, then the Counter and Alarm interfaces for
! ${P}=32khz and ${W}=16 are::
! configuration Counter32khz8C
! {
! provides interface Counter< T32khz, uint8_t >;
! }
! generic configuration Alarm32khz8C
! {
! provides interface Alarm< T32khz, uint8_t >;
! }
!
! This pattern MAY be used to defined components for the platform that
! are mutually incompatible in single application. Incompatible
! components SHOULD produce compile-time errors when compiled
! together.
4. HIL requirements
***************
*** 385,389 ****
::
- #define TIMERMILLIC_SERVICE ...
configuration TimerMilliC
{
--- 406,409 ----
***************
*** 393,399 ****
}
! A timer is allocated using unique(TIMERMILLIC_SERVICE) to obtain a new
! unique timer number. This timer number is used to index the TimerMilli
! parameterised interface.
BusyWaitMicroC
--- 413,420 ----
}
! A new timer is allocated using unique(UQ_TIMER_MILLI) to obtain a
! new unique timer number. This timer number is used to index the
! TimerMilli parameterised interface. UQ_TIMER_MILLI is defined in
! Timer.h.
BusyWaitMicroC
***************
*** 496,499 ****
--- 517,525 ----
new TransformAlarmC( TMilli, uint32_t, T32khz, uint16_t, 5 )
+ It is the exclusive responsibility of the developer using
+ TransformAlarmC to ensure that all five of its arguments are self
+ consistent. No compile errors are generated if the parameters
+ passed to TransformAlarmC are inconsistent.
+
TransformCounterC
***************
*** 544,548 ****
}
! 6. Author's Address
====================================================================
| Cory Sharp
--- 570,637 ----
}
! 6. Implementation
! ====================================================================
!
! The definition of the HIL interfaces are found in ``tinyos-2.x/tos/lib/timer``:
!
! * ``Alarm.nc``
! * ``BusyWait.nc``
! * ``Counter.nc``
! * ``LocalTime.nc``
! * ``Timer.h`` defines precision tags and strings for unique()
! * ``Timer.nc``
!
! The implementation of the utility components are also found in
! ``tinyos-2.x/tos/lib/timer``:
!
! * ``AlarmToTimerC.nc``
! * ``BusyWaitCounterC.nc``
! * ``CounterToLocalTimeC.nc``
! * ``TransformAlarmC.nc``
! * ``TransformAlarmCounterC.nc``
! * ``TransformCounterC.nc``
! * ``VirtualizeAlarmC.nc``
! * ``VirtualizeTimerC.nc``
!
! The implementation of Timers for the MSP430 is in
! ``tinyos-2.x/tos/chips/msp430/timer``:
!
! * ``Alarm32khzC.nc`` is generic and provides a new ``Alarm<T32khz,uint16_t>``
! and ``Alarm<T32khz,uint32_t>``
! * ``AlarmMilliC.nc`` is generic and provides a new ``Alarm<TMilli,uint32_t>``
! * ``BusyWait32khzC.nc`` provides ``BusyWait<T32khz,uint16_t>``
! * ``BusyWaitMicroC.nc`` provides ``BusyWait<TMicro,uint16_t>``
! * ``Counter32khzC.nc`` provides ``Counter<T32khz,uint16_t>``,
! ``Counter<T32khz,uint32_t>``, and ``LocalTime<T32khz>``
! * ``CounterMilliC.nc`` provides ``Counter<TMilli,uint32_t>`` and ``LocalTime<TMilli>``
! * ``GpioCaptureC.nc``
! * ``HilTimerMilliC.nc`` provides ``Timer<TMilli> as TimerMilli[uint8_t num]``
! * ``Msp430AlarmC.nc`` is generic and converts an MSP430 timer to a 16-bit Alarm
! * ``Msp430Capture.nc`` HPL interface definition for MSP430 timer captures
! * ``Msp430ClockC.nc`` exposes MSP430 hardware clock initialization
! * ``Msp430ClockInit.nc`` HPL interface definition for hardware clock initialization
! * ``Msp430ClockP.nc`` implements MSP430 hardware clock initialization and
! calibration and startup
! * ``Msp430Compare.nc`` HPL interface definition for MSP430 timer compares
! * ``Msp430Counter32khzC.nc`` provides ``Counter<T32khz,uint16_t>`` based on
! MSP430 TimerB
! * ``Msp430CounterC.nc`` is generic and converts an Msp430Timer to a Counter
! * ``Msp430CounterMicroC.nc`` provides ``Counter<TMicro,uint16_t>`` based on
! MSP430 TimerA
! * ``Msp430Timer.h`` defines additional MSP430 timer bitmasks and structs
! * ``Msp430Timer.nc`` HPL interface definition
! * ``Msp430Timer32khzC.nc`` is generic and allocates a new 32khz hardware timer
! * ``Msp430Timer32khzMapC.nc`` exposes the MSP430 hardware timers as a
! parameterized interface allocatable using Msp430Timer32khzC
! * ``Msp430TimerC.nc`` exposes the MSP430 hardware timers
! * ``Msp430TimerCapComP.nc`` is generic and implements the HPL for MSP430
! capture/compare special function registers
! * ``Msp430TimerCommonP.nc`` maps the MSP430 timer interrupts to Msp430TimerEvents
! * ``Msp430TimerControl.nc`` HPL interface definition
! * ``Msp430TimerEvent.nc`` HPL interface definition
! * ``Msp430TimerP.nc`` is generic and implements the HPL for MSP430 timer
! special function registers
!
! 7. Author's Address
====================================================================
| Cory Sharp
***************
*** 551,554 ****
--- 640,644 ----
| San Francisco, CA 94105
|
+ | phone - +1 415 692 0963
| email - cory at moteiv.com
|
More information about the Tinyos-2-commits
mailing list