[Tinyos-beta-commits] CVS: tinyos-1.x/beta/ProgManual comm.tex, 1.2, 1.3 intro.tex, 1.3, 1.4

[Kristin Wright]

Update of /cvsroot/tinyos/tinyos-1.x/beta/ProgManual
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv13260

Modified Files:
	comm.tex intro.tex 
Log Message:
more comm stuff

Index: comm.tex
===================================================================
RCS file: /cvsroot/tinyos/tinyos-1.x/beta/ProgManual/comm.tex,v
retrieving revision 1.2
retrieving revision 1.3
diff -C2 -d -r1.2 -r1.3
*** comm.tex	15 Oct 2004 22:37:28 -0000	1.2
--- comm.tex	25 Oct 2004 19:59:08 -0000	1.3
***************
*** 1,34 ****
! 
  \section{Communication}
  
  \subsection{Communication Model: Active Messages}
  
! Active message model. Use IDs to dispatch messages to message handler code. Refer to AM paper. 
  
! Buffer model. 
  
! Sending:
! TinyOS Active Message buffers follow a strict alternating
! ownership protocol to avoid expensive memory management, while still
! allowing concurrent operation. If the message layer accepts the send()
! command, it owns the send buffer and the requesting component should
! not modify the buffer until the send is complete (as indicated by the
! sendDone() event).
  
! The simplicity of the send-buffer management in the underlying
! communication layers usually requires that the application implement
! some buffer management. A common mechanism is a pending flag which
! keeps track of the buffer's status. If the previous messages is still
! being sent, the application cannot modify the buffer and 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.
  
! Receiving: Memory management for incoming messages is inherently
! dynamic. A message arrives and fills a buffer, and the Active Message
! layer decodes the handler type and dispatches it. The buffer is handed
! to the application component (through the ReceiveMsg.receive() event),
! but, critically, 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
--- 1,43 ----
! >
  \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
***************
*** 39,47 ****
  \subsection{Packet definition}
  
! TOSMsg.
  
  TOSH_DATA_LENGTH. TOSH_DATA_LENGTH is a constant that defines the 
! maximum length of the data payload in the messages. The actual length of
! the data payload is in the length field of the TOSMsg structure. 
  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 
--- 48,101 ----
  \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 
***************
*** 49,53 ****
  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}
--- 103,108 ----
  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}
***************
*** 79,87 ****
  }
  
! Protocol: 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,
--- 134,143 ----
  }
  
! 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,
***************
*** 90,93 ****
--- 146,151 ----
  1/3. Nevertheless, ACKs can be sent on CC1000 (Is this still true?)
  
+ \subsection{Achievable Bandwidth}
+ 
  \subsection{Communication Components}
  
***************
*** 109,114 ****
  \subsubsubsection{PowerManagement}
  
! App needs to call radio component's StdControl.stop() function. For example:
!   CC2420RadioC.StdControl.stop()
  
  \subsubsection{CC2420 Radio}
--- 167,172 ----
  \subsubsubsection{PowerManagement}
  
! App needs to call radio component's StdControl.stop() function. For
!   example: CC2420RadioC.StdControl.stop()
  
  \subsubsection{CC2420 Radio}
***************
*** 117,121 ****
  Design goals.
  
! High-level use:
  CC2420RadioC 
    - BareSendMsg
--- 175,179 ----
  Design goals.
  
! High-level use by applications:
  CC2420RadioC 
    - BareSendMsg
***************
*** 127,130 ****
--- 185,267 ----
  (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: intro.tex
===================================================================
RCS file: /cvsroot/tinyos/tinyos-1.x/beta/ProgManual/intro.tex,v
retrieving revision 1.3
retrieving revision 1.4
diff -C2 -d -r1.3 -r1.4
*** intro.tex	6 Mar 2004 01:18:43 -0000	1.3
--- intro.tex	25 Oct 2004 19:59:08 -0000	1.4
***************
*** 51,55 ****
  read before continuing beyond this introduction.
  
! 
  
  
--- 51,56 ----
  read before continuing beyond this introduction.
  
! {\bf Programming conventions.} 
! enum.