[Tinyos-beta-commits] CVS: tinyos-1.x/beta/ProgManual power.tex,
NONE, 1.1.2.1 Makefile, 1.2, 1.2.8.1 comm.tex, 1.1,
1.1.8.1 core.tex, 1.1, 1.1.8.1 intro.tex, 1.3, 1.3.8.1 pm.tex,
1.3, 1.3.8.1
Kristin Wright
kristinwright at users.sourceforge.net
Thu Nov 11 05:44:59 PST 2004
Update of /cvsroot/tinyos/tinyos-1.x/beta/ProgManual
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv8305/beta/ProgManual
Modified Files:
Tag: tos-1-1-8-candidate
Makefile comm.tex core.tex intro.tex pm.tex
Added Files:
Tag: tos-1-1-8-candidate
power.tex
Log Message:
merge with trunk using the tos-1-1-8-postbugfix trunk snapshot
--- NEW FILE: power.tex ---
The whole point of using HPLPowerManagement is that you don't actually *use*
it. You call HPLPowerManagement.enable() and then the mote will
automatically sleep when the following conditions are met:
* the radio is off
* all high speed clock output compare interrupts are disabled
* spi interrupt disabled
* task queue is empty
There is no code to "use" power management, instead each service (Timer,
Radio, SpiByteFifo, etc) calls HPLPowerManagement.adjustPower() when the
component has shut down to notify the PowerManagement component that it
should check the state of the above items again and reset the sleep
register. Thus applications need not worry about explicitly telling the
mote to go to sleep (THIS is the main difference between HPLPowerManagement
and the *deprecated* Snooze).
The main advantage of this approach is it allows services to clean up, save
state, and shut down before the cpu is halted. In snooze, the cpu is stolen
out from under running services without any notification to those services.
For HPLPowerManagement to work, an application must call
CC1000RadioC.StdControl.stop(). After this call, HPLPowerManagement takes
over (once the radio is done shutting down), and sets the appropriate
registers to put the mote to sleep after the task queue empties. Note that
if using a low power radio listening state (such as
CC1000RadioIntM.setListeningMode(i)), the CC1000 radio module will take care
of notifying HPLPowerManagement to say it is okay to halt the CPU.
The mote will wake up on the next 32kHz Timer interrupt.
The long winded answer to your question, Mark, is that *only* services need
to call adjustPower() when they have finished shutting down or starting up.
It is invalid semantics for an application to call adjustPower(), however
you are not penalized by it in the current implementation. Thus, your
application should call HPLPowerManagement.enable() in its
StdControl.init(). Power Management is disabled by default.
I believe HPLPowerManagement is documented somewhere in the TOS 1.1 release.
GDI and TASK/TinyDB both enable HPLPowerManagement. The GDI code is in
contrib/ucb/apps/TestLabApp. GDI uses low power radio sampling (part of the
default CC1000 radio stack) and achieves 30uA sleep state. TinyDB uses its
own TDMA scheme for low power communications and also achieves the same low
power state.
Index: Makefile
===================================================================
RCS file: /cvsroot/tinyos/tinyos-1.x/beta/ProgManual/Makefile,v
retrieving revision 1.2
retrieving revision 1.2.8.1
diff -C2 -d -r1.2 -r1.2.8.1
*** Makefile 6 Mar 2004 01:18:43 -0000 1.2
--- Makefile 11 Nov 2004 13:43:08 -0000 1.2.8.1
***************
*** 4,10 ****
#
! LATEX = pdflatex
PDF = pdflatex
! BIB = bibtex
pm.pdf: *.tex
--- 4,12 ----
#
! #LATEX = pdflatex
! #PDF = pdflatex
! LATEX = latex
PDF = pdflatex
! BIBTEX = bibtex
pm.pdf: *.tex
Index: comm.tex
===================================================================
RCS file: /cvsroot/tinyos/tinyos-1.x/beta/ProgManual/comm.tex,v
retrieving revision 1.1
retrieving revision 1.1.8.1
diff -C2 -d -r1.1 -r1.1.8.1
*** comm.tex 3 Mar 2004 21:52:42 -0000 1.1
--- comm.tex 11 Nov 2004 13:43:08 -0000 1.1.8.1
***************
*** 1,17 ****
!
\section{Communication}
\subsection{Communication Interfaces}
! \subsubsection{BareSendMsg}
\subsubsection{ReceiveMsg}
\subsubsection{RadioCoordinator}
\subsection{Communication Implementations}
\subsubsection{UART}
! \subsubsection{CC1000Radiol}
CC1000RadioControl
\subsubsection{CC2420 Radio}
--- 1,271 ----
! >
\section{Communication}
+ \subsection{Communication Model: Active Messages}
+
+ Active message model. Use IDs to dispatch messages to message handler
+ code. Refer to AM paper.
+
+ Active message model used regardless of the underlying communication
+ substrate: radio, UART (serial).
+
+ \subsubsection{Buffer model}
+
+ \emph{Sending.}
+ To avoid potentially expensive memory management schemes in the AM
+ layer but still allow concurrent operation, TinyOS Active Message
+ buffers follow a strict alternating ownership protocol. Provided that the
+ messaging layer returns SUCCESS from the send() call, the active
+ message layer 'owns' the send buffer provided by the higher-level
+ component until
+ the send is complete as indicated by the sendDone() event. That is,
+ the requesting component should not modify the buffer a between the
+ successful send() call and the corresponding sendDone() event.
+
+ The send-buffer management simplicity usually requires that the
+ application implement some buffer management. A common, simple mechanism is a
+ pending flag which keeps track of a single buffer's status. If the previous
+ message is still being sent, the application cannot modify the buffer
+ and must return FAIL for any send requests. If the flag indicates
+ that the send buffer is available, the application is free to fill the
+ buffer and send the message. Of course more complicated schemes can be
+ implemented where necessary.
+
+ \emph{Receiving.} AM memory management for incoming messages requires
+ that the receiving component return a pointer to a free message
+ buffer; the buffer can be the same buffer recieved in that call or a
+ different buffer. A message arrives and fills a buffer, and then the Active
+ Message layer dispatches the message based on the handler type. The buffer
+ is handed to the application component (through the
+ ReceiveMsg.receive() event), and the application
+ component must return a pointer to a free buffer upon completion.
+
+ If the application is done with the buffer, it can return a pointer to
+ that buffer. If your component needs to save the message contents for
+ later use, it needs to copy the message to a new buffer, or return a
+ new (free) message buffer for use by the network stack.
+
+ \subsection{Packet definition}
+
+ TOS_Msg defined in AM.h, but some platforms redefine TOS_Msg to make,
+ for example, address handling or byte-order conversion more easy. In
+ this case the definition is in tos/platforms/<platform>/AM.h, but the
+ definitions remain very similar.
+
+ Put definition in a nice box.
+
+ typedef struct TOS_Msg
+ {
+ /* The following fields are transmitted/received on the radio. */
+ uint16_t addr;
+ uint8_t type;
+ uint8_t group;
+ uint8_t length;
+ int8_t data[TOSH_DATA_LENGTH];
+ uint16_t crc;
+
+ /* The following fields are not actually transmitted or received
+ * on the radio! They are used for internal accounting only.
+ * The reason they are in this structure is that the AM interface
+ * requires them to be part of the TOS_Msg that is passed to
+ * send/receive operations.
+ */
+ uint16_t strength;
+ uint8_t ack;
+ uint16_t time;
+ uint8_t sendSecurityMode;
+ uint8_t receiveSecurityMode;
+ } TOS_Msg;
+
+ Slightly different fields for TinySec packets. See TinySec section.
+
+ TOSMsg fields (table).
+ Columns would be field/semantics/when set and by whom
+ addr
+ type
+
+ TOSH_DATA_LENGTH. TOSH_DATA_LENGTH is a constant that defines the
+ \emph{maximum} length of the data payload in the messages. When
+ message buffers are allocated, the are generally done so by declaring
+ a TOS_Msg structure. Rather than introduce potentially complicated
+ code that can handle data packets of arbitrary length, the TOS_Msg
+ structure allocates space for the data using the TOSH_DATA_LENGTH
+ constant.
+
+ The actual length of
+ the data payload is in the length field of the TOSMsg structure. The
+ communications components can handle transmission/receipt of the
+ actual data using the length field.
+
+ There are hooks in the TinyOS make system (tools/make) that allow
+ you can to set the value of TOS_DATA_LENGTH in your application by
+ defining MSG_SIZE to the size you'd like in your application's makefile
+ where MSG_SIZE is the value you want to use for TOSH_DATA_LENGH.
+ For example, 'MSG_SIZE=40' would effectively change TOSH_DATA_LENGTH to
+ 40 bytes.
+
+
\subsection{Communication Interfaces}
! \subsubsection{SendMsg}
\subsubsection{ReceiveMsg}
+
+ \subsubsection{Mac-layer Control, Reliability & Error Detection}
+
+ Always call radio control (SetRFPower(), MacControl.enableAck(), etc.)
+ functions in StdControl.start() rather than StdControl.init(). The
+ order of init() calls in TinyOS cannot be predetermined, so the radio's init()
+ function may be called after the application's init() fucntion and
+ reset any previously set settings.
+
+ CRCs.
+
+ interface MacBackoff
+ {
+ async event int16_t initialBackoff(TOS_MsgPtr m);
+ async event int16_t congestionBackoff(TOS_MsgPtr m);
+ }
+
+ Acks (CC1000 & CC2420 below, RFM?)
+
+ interface MacControl
+ {
+ async command void enableAck();
+ async command void disableAck();
+ }
+
+ Acks are disabled by default. MacControl.enableAck() must be called
+ before message is sent. If on, hardware will automatically send an
+ acknowledgement. If acknowledgements are enabled, the radio stack
+ will wait for an ack or timeout before signaling the sendDone event.
+ If an ack is received, the TOSMsg.ack field will be set to 1, it will
+ be set to 0 otherwise.
+
+ Note: cc1000 requires 250us to switch radio's mode from rcv to xmit,
+ then 10-15 bytes to sync sending radio with receiver radio, and only
+ then can you send the ACK. The effective throughput cut by
+ 1/3. Nevertheless, ACKs can be sent on CC1000 (Is this still true?)
+
+ \subsection{Achievable Bandwidth}
+
+ \subsection{Communication Components}
+
+ \subsection{GenericComm}
+
+ SendMsg, ReceiveMsg, StdControl.
+
+ \subsubsection{Low-level}
\subsubsection{RadioCoordinator}
+ \subsubsection{BareSendMsg}
\subsection{Communication Implementations}
\subsubsection{UART}
! \subsubsection{CC1000Radio}
CC1000RadioControl
+ \subsubsubsection{PowerManagement}
+
+ App needs to call radio component's StdControl.stop() function. For
+ example: CC2420RadioC.StdControl.stop()
+
\subsubsection{CC2420 Radio}
+ High-level overview
+ Design goals.
+
+ High-level use by applications:
+ CC2420RadioC
+ - BareSendMsg
+ - ReceiveMsg
+ - CC2420Control
+ - MacControl
+ - MacBackoff
+
+ (wired to CC2420RadioM, CC2420RadioControlM)
+
+ Mention that the sendDone and receive signals are signaled from
+ the stack rather than from the radio interrupt contexts. Semantics
+ could be important (i.e., task that signals sendDone behind other
+ long-running tasks).
+
+ \subsubsubsection{CC2420 Implementation}
+
+ A note about the mapping between spec, CC2420Const.h, and usage in
+ HPL* files. Current parameters stored in a current parameter (CP)
+ array.
+
+ {\bf Initialization.} Done in split-phase.
+ Question: How deprecated is stdcontrol? That is, are we actively
+ porting all the StdControl() interfaces to SplitControl()? Or is this
+ isolated to radio stack?
+
+ SplitControl used because some of the init/start/stop calls
+ require delays. For example,
+
+ SplitControl and CC2420Control interfaces implemented by CC2420ControlM.
+
+ {\bf Buffering.}: two receive buffers, one send buffer.
+ Question: In receive, the implementation checks for a valid
+ returned buffer (that is, a non-null pointer) and only sets
+ bPacketReceiving to FALSE if it's non-null. If it is null, doesn't
+ that completely screw up receiving? That is, isn't there not another
+ way to give a receive buffer back to the stack?
+
+ State machines:
+ timer
+ radio
+ DISABLED_STATE = 0, (stopped, as in app called CC2420RadioM.StdControl.stop())
+ IDLE_STATE,
+ TX_STATE, (attempting to transmitting (possibly must wait for radio
+ to switch to xmit or for SFD pin to go high)
+ TX_WAIT,
+ PRE_TX_STATE, (if we're backed-off in a congestion timer)
+ POST_TX_STATE,
+ POST_TX_ACK_STATE,
+ RX_STATE,
+ POWER_DOWN_STATE,
+ WARMUP_STATE, (just called start)
+
+ TIMER_INITIAL = 0,
+ TIMER_BACKOFF,
+ TIMER_ACK
+
+ Send: if the radio is in a state where it can transmit, wait for SFD
+ (Start of Frame Delimeter) to go high. When the pin goes high, set
+ state to TX_STATE . Will retry up to 8 times; reasons for not
+ being able to send include:
+
+ sfd.captured:
+ - could be one of several states:
+ -
+
+ Send failed situation: if a send fails, sendDone is signaled w/ FAIL,
+ pointer to txbuffer (duh).
+
+ uses {
+ interface SplitControl as CC2420SplitControl;
+ interface CC2420Control;
+ interface HPLCC2420 as HPLChipcon;
+ interface HPLCC2420FIFO as HPLChipconFIFO;
+ interface HPLCC2420Interrupt as FIFOP;
+ interface HPLCC2420Capture as SFD;
+ interface StdControl as TimerControl;
+ interface TimerJiffyAsync as BackoffTimerJiffy;
+ interface Random;
+ interface Leds;
+ }
+ }
+
+ \subsubsection{Hardware Resources}
+
+ Timer1.
+
+ Timer2.
+
+ \subsubsubsection{PowerManagement}
+
+
+
+
+
Index: core.tex
===================================================================
RCS file: /cvsroot/tinyos/tinyos-1.x/beta/ProgManual/core.tex,v
retrieving revision 1.1
retrieving revision 1.1.8.1
diff -C2 -d -r1.1 -r1.1.8.1
*** core.tex 6 Mar 2004 01:18:43 -0000 1.1
--- core.tex 11 Nov 2004 13:43:25 -0000 1.1.8.1
***************
*** 2,7 ****
Before one can understand how to customize components or place
! components together to form an application, some concepts central to
! TinyOS must first be explained.\footnote{The
information found in this section is covered in detail in \cite{jhill-thesis}.}
--- 2,7 ----
Before one can understand how to customize components or place
! components together to form an application, some central TinyOS concepts
! must first be explained.\footnote{The
information found in this section is covered in detail in \cite{jhill-thesis}.}
***************
*** 28,31 ****
--- 28,33 ----
\subsubsection{\nesc support for the execution model}
+ async / sync
+
\subsection{The Component Model}
Index: intro.tex
===================================================================
RCS file: /cvsroot/tinyos/tinyos-1.x/beta/ProgManual/intro.tex,v
retrieving revision 1.3
retrieving revision 1.3.8.1
diff -C2 -d -r1.3 -r1.3.8.1
*** intro.tex 6 Mar 2004 01:18:43 -0000 1.3
--- intro.tex 11 Nov 2004 13:43:25 -0000 1.3.8.1
***************
*** 51,55 ****
read before continuing beyond this introduction.
!
--- 51,56 ----
read before continuing beyond this introduction.
! {\bf Programming conventions.}
! enum.
Index: pm.tex
===================================================================
RCS file: /cvsroot/tinyos/tinyos-1.x/beta/ProgManual/pm.tex,v
retrieving revision 1.3
retrieving revision 1.3.8.1
diff -C2 -d -r1.3 -r1.3.8.1
*** pm.tex 6 Mar 2004 01:18:43 -0000 1.3
--- pm.tex 11 Nov 2004 13:43:25 -0000 1.3.8.1
***************
*** 1,3 ****
! \documentclass[11pt,letterpaper]{article}
\usepackage{verbatim}
--- 1,3 ----
! \documentclass[10pt]{article}
\usepackage{verbatim}
***************
*** 17,22 ****
\title{TinyOS Programmer's Manual}
! \author{Kristin Wright}
! \date{May 2003}
\maketitle
--- 17,22 ----
\title{TinyOS Programmer's Manual}
! \author{Kristin Wright and the TinyOS Team}
! \date{October 2004}
\maketitle
***************
*** 25,32 ****
\input{core}
%\input{env}
! %\input{comm}
%\input{timers}
%\input{memory}
! %\input{power}
%\input{sensors}
%\input{misc}
--- 25,32 ----
\input{core}
%\input{env}
! \input{comm}
%\input{timers}
%\input{memory}
! \input{power}
%\input{sensors}
%\input{misc}
More information about the Tinyos-beta-commits
mailing list