[Tinyos-2-commits] CVS: tinyos-2.x/tos/lib/mac/tkn154/interfaces/private EnergyDetection.nc, 1.1, 1.2 FrameTx.nc, 1.1, 1.2 FrameTxNow.nc, 1.1, 1.2 RadioOff.nc, 1.1, 1.2 RadioRx.nc, 1.1, 1.2 RadioTx.nc, 1.1, 1.2

[Jan-Hinrich Hauer]

Update of /cvsroot/tinyos/tinyos-2.x/tos/lib/mac/tkn154/interfaces/private
In directory ddv4jf1.ch3.sourceforge.com:/tmp/cvs-serv21632/tos/lib/mac/tkn154/interfaces/private

Modified Files:
	EnergyDetection.nc FrameTx.nc FrameTxNow.nc RadioOff.nc 
	RadioRx.nc RadioTx.nc 
Log Message:
+ modified radio driver (PHY) interfaces: CSMA-CA algorithm is now pushed to radio driver
+ adapted CC2420 driver
+ renamed CsmaP -> FrameDispatchP
+ provided workaround for a problem with virtualized alarms (sometimes they seem to fire 2s too late)
+ updated placeholder components
+ updated debug information

Index: EnergyDetection.nc
===================================================================
RCS file: /cvsroot/tinyos/tinyos-2.x/tos/lib/mac/tkn154/interfaces/private/EnergyDetection.nc,v
retrieving revision 1.1
retrieving revision 1.2
diff -C2 -d -r1.1 -r1.2
*** EnergyDetection.nc	16 Jun 2008 18:00:32 -0000	1.1
--- EnergyDetection.nc	25 Nov 2008 09:35:09 -0000	1.2
***************
*** 38,43 ****
    /**
     * Requests to measure the energy level on the current channel; the
!    * measurement should last for <code>duration<\code> symbols and the  
!    * maximum energy level is signalled through the <code>done<\code>
     * event.
     *
--- 38,43 ----
    /**
     * Requests to measure the energy level on the current channel; the
!    * measurement should last for <tt>duration</tt> symbols and the  
!    * maximum energy level is signalled through the <tt>done</tt>
     * event.
     *
***************
*** 45,59 ****
     * (in symbol time)
     * @return SUCCESS if the request was accepted and only then 
!    * the <code>done<\code> event will be signalled, FAIL otherwise
     **/
    command error_t start(uint32_t duration);
  
    /**
!    * Signalled in response to a call to <code>start<\code>;
     * returns the maximum energy measured on the channel over the
     * specified period of time.
     *
     * @param status SUCCESS if the measurement succeeded
!    * and only then <code>EnergyLevel<\code> is valid, FAIL 
     * otherwise
     * @param EnergyLevel The maximum energy on the channel
--- 45,59 ----
     * (in symbol time)
     * @return SUCCESS if the request was accepted and only then 
!    * the <tt>done</tt> event will be signalled, FAIL otherwise
     **/
    command error_t start(uint32_t duration);
  
    /**
!    * Signalled in response to a call to <tt>start<\tt>;
     * returns the maximum energy measured on the channel over the
     * specified period of time.
     *
     * @param status SUCCESS if the measurement succeeded
!    * and only then <tt>EnergyLevel<\tt> is valid, FAIL 
     * otherwise
     * @param EnergyLevel The maximum energy on the channel

Index: FrameTx.nc
===================================================================
RCS file: /cvsroot/tinyos/tinyos-2.x/tos/lib/mac/tkn154/interfaces/private/FrameTx.nc,v
retrieving revision 1.1
retrieving revision 1.2
diff -C2 -d -r1.1 -r1.2
*** FrameTx.nc	16 Jun 2008 18:00:33 -0000	1.1
--- FrameTx.nc	25 Nov 2008 09:35:09 -0000	1.2
***************
*** 39,43 ****
     * @param  txFrame    the frame to transmit
     * @return IEEE154_SUCCESS if the request was accepted and
!    * only then <code>transmitDone()</code> will be signalled
     */  
    command ieee154_status_t transmit(ieee154_txframe_t *txFrame); 
--- 39,43 ----
     * @param  txFrame    the frame to transmit
     * @return IEEE154_SUCCESS if the request was accepted and
!    * only then <tt>transmitDone()</tt> will be signalled
     */  
    command ieee154_status_t transmit(ieee154_txframe_t *txFrame); 

Index: FrameTxNow.nc
===================================================================
RCS file: /cvsroot/tinyos/tinyos-2.x/tos/lib/mac/tkn154/interfaces/private/FrameTxNow.nc,v
retrieving revision 1.1
retrieving revision 1.2
diff -C2 -d -r1.1 -r1.2
*** FrameTxNow.nc	16 Jun 2008 18:00:33 -0000	1.1
--- FrameTxNow.nc	25 Nov 2008 09:35:09 -0000	1.2
***************
*** 39,43 ****
     * @param  txFrame    the frame to transmit
     * @return IEEE154_SUCCESS if the request was accepted and
!    * only then <code>transmitDone()</code> will be signalled
     */  
    async command ieee154_status_t transmitNow(ieee154_txframe_t *frame); 
--- 39,43 ----
     * @param  txFrame    the frame to transmit
     * @return IEEE154_SUCCESS if the request was accepted and
!    * only then <tt>transmitDone()</tt> will be signalled
     */  
    async command ieee154_status_t transmitNow(ieee154_txframe_t *frame); 

Index: RadioOff.nc
===================================================================
RCS file: /cvsroot/tinyos/tinyos-2.x/tos/lib/mac/tkn154/interfaces/private/RadioOff.nc,v
retrieving revision 1.1
retrieving revision 1.2
diff -C2 -d -r1.1 -r1.2
*** RadioOff.nc	16 Jun 2008 18:00:33 -0000	1.1
--- RadioOff.nc	25 Nov 2008 09:35:09 -0000	1.2
***************
*** 38,49 ****
  
    /** 
!    * Switches the radio off and changes the radio state to RADIO_OFF. This
     * command will succeed only if the current state of the radio is either
     * TX_LOADED, RX_PREPARED or RECEIVING.
     *
!    * @return EALREADY if radio is already switched off <br> FAIL if radio the
!    * current radio state is neither TX_LOADED, RX_PREPARED nor RECEIVING <br>
!    * SUCCESS if the command was accepted and the <tt>offDone()</tt> event will
!    * be signalled.
     */
    async command error_t off();
--- 38,49 ----
  
    /** 
!    * Disables the transceiver and changes the radio state to RADIO_OFF. This
     * command will succeed only if the current state of the radio is either
     * TX_LOADED, RX_PREPARED or RECEIVING.
     *
!    * @return SUCCESS if the command was accepted and the <tt>offDone()</tt>
!    * event will be signalled; EALREADY if radio is already switched off; FAIL
!    * if the current radio state is neither TX_LOADED, RX_PREPARED nor
!    * RECEIVING.
     */
    async command error_t off();
***************
*** 55,59 ****
    async event void offDone();
  
!  /** @return TRUE if the radio is in the state RADIO_OFF, FALSE otherwise */
!   async command bool isOff();
  }
--- 55,62 ----
    async event void offDone();
  
!   /** 
!    * Tells whether the radio is in state RADIO_OFF.
!    * @return TRUE if the radio is in the state RADIO_OFF, FALSE otherwise 
!    */
!   async command bool isOff(); 
  }

Index: RadioRx.nc
===================================================================
RCS file: /cvsroot/tinyos/tinyos-2.x/tos/lib/mac/tkn154/interfaces/private/RadioRx.nc,v
retrieving revision 1.1
retrieving revision 1.2
diff -C2 -d -r1.1 -r1.2
*** RadioRx.nc	16 Jun 2008 18:00:33 -0000	1.1
--- RadioRx.nc	25 Nov 2008 09:35:09 -0000	1.2
***************
*** 36,40 ****
  interface RadioRx
  {
- 
    /** 
     * Prepares the radio for receive mode. This command will fail, if the radio
--- 36,39 ----
***************
*** 56,66 ****
    async event void prepareDone(); 
  
!   /** @return TRUE if the radio is in the state RX_PREPARED, FALSE otherwise */
    async command bool isPrepared();
  
    /** 
     * Switches the radio to receive mode at time <tt>t0 + dt</tt>.  If
!    * <tt>t0</tt> is NULL, then the callee interprets <tt>t0</tt> as the current
!    * time. 
     *
     * @param t0 Reference time for receive operation (NULL means now)  
--- 55,67 ----
    async event void prepareDone(); 
  
!   /** 
!    * Tells whether the radio is in state RX_PREPARED.
!    * @return TRUE if the radio is in the state RX_PREPARED, FALSE otherwise 
!    */
    async command bool isPrepared();
  
    /** 
     * Switches the radio to receive mode at time <tt>t0 + dt</tt>.  If
!    * <tt>t0</tt> is NULL, then the callee interprets <tt>t0</tt> as now. 
     *
     * @param t0 Reference time for receive operation (NULL means now)  
***************
*** 74,78 ****
    async command error_t receive(ieee154_reftime_t *t0, uint32_t dt); 
    
!   /** @return TRUE if the radio is in the state RECEIVING, FALSE otherwise */
    async command bool isReceiving();
  
--- 75,82 ----
    async command error_t receive(ieee154_reftime_t *t0, uint32_t dt); 
    
!   /**
!    * Tells whether the radio is in state RECEIVING.
!    * @return TRUE if the radio is in the state RECEIVING, FALSE otherwise 
!    */
    async command bool isReceiving();
  

Index: RadioTx.nc
===================================================================
RCS file: /cvsroot/tinyos/tinyos-2.x/tos/lib/mac/tkn154/interfaces/private/RadioTx.nc,v
retrieving revision 1.1
retrieving revision 1.2
diff -C2 -d -r1.1 -r1.2
*** RadioTx.nc	16 Jun 2008 18:00:33 -0000	1.1
--- RadioTx.nc	25 Nov 2008 09:35:09 -0000	1.2
***************
*** 50,54 ****
     * TX_LOADED) until either the transmission was successful, i.e.
     * <tt>transmitDone()</tt> was signalled with a status IEEE154_SUCCESS, or
!    * the radio is explicitly switched off through the <tt>RadioOff</tt>
     * interface. Until then the callee might have to reserve certain resources
     * (e.g. the bus connected to the radio), so the caller should keep the time
--- 50,54 ----
     * TX_LOADED) until either the transmission was successful, i.e.
     * <tt>transmitDone()</tt> was signalled with a status IEEE154_SUCCESS, or
!    * the radio is switched off through the <tt>RadioOff</tt>
     * interface. Until then the callee might have to reserve certain resources
     * (e.g. the bus connected to the radio), so the caller should keep the time
***************
*** 81,166 ****
    /** 
     * Transmits the frame whose transmission has previously been prepared
!    * through a call to <tt>load()</tt>. The actual time of transmission -- the
!    * point in time when the first symbol of the PPDU is transmitted -- is
!    * defined by: <tt>t0 + dt</tt>. The data type of the <tt>t0</tt> parameter
!    * is platform-specific (symbol precision or better) while <tt>dt</tt> is
!    * expressed in 802.15.4 symbols. If <tt>t0</tt> is NULL, then the callee
!    * interprets <tt>t0</tt> as the current time. The caller guarantees (through
     * platform-specific guard times and by calling <tt>transmit</tt> in an
!    * atomic block) that the callee can start the transmission on time, taking
!    * any prior clear channel assesment(s) into consideration. 
!    *
!    * A transmission may require 0, 1 or 2 prior clear channel assesments
!    * (<tt>numCCA</tt> parameter) to be performed 0, 20 or 40 symbols,
!    * respectively, before the actual transmission. If a CCA determines a busy
!    * channel, then the frame will not be transmitted. 
!    *
!    * A successful transmission may also require an acknowledgement from the
!    * destination (indicated through the <tt>ackRequest</tt> parameter); then,
!    * the callee has to perform the necessary steps for receiving that
!    * acknowledgement (switching the radio to Rx mode immediately after
!    * transmission, etc.; for details see IEEE 802.15.4-2006).
!    *
!    * The <tt>transmit()</tt> command will succeed iff the radio is in state
!    * TX_LOADED. The <tt>transmitDone()</tt> event will then signal the result
     * of the transmission.
     *
     * @param t0 Reference time for transmission (NULL means now)  
-    *
     * @param dt A positive offset relative to <tt>t0</tt>.  
     *
-    * @param numCCA Number of clear channel assesments.
-    *
-    * @param ackRequest TRUE means an acknowledgement is required, FALSE means
-    * no acknowledgement is not required
-    *
     * @return SUCCESS if the transmission was triggered successfully and only
     * then <tt>transmitDone()</tt> will be signalled; FAIL, if the transmission
     * was not triggered because no frame was loaded.
!    */  
!   async command error_t transmit(ieee154_reftime_t *t0, uint32_t dt, 
!       uint8_t numCCA, bool ackRequest);
  
    /**
!    * Signalled in response to a call to <tt>transmit()</tt>. Depending on the
!    * <tt>error</tt> parameter the radio is now in state RADIO_OFF
!    * (<tt>error</tt> == IEEE154_SUCCESS) or still in state TX_LOADED
!    * (<tt>error</tt> != IEEE154_SUCCESS).  If the transmission succeeded then
!    * the time of transmission -- the point in time when the first symbol of the
!    * PPDU was transmitted -- will be stored in the metadata field of the frame.
!    * In addition, the <tt>t0</tt> parameter will hold a platform-specific
!    * representation of the same point in time (possibly with higher precision)
!    * to be used as future reference time in a <tt>transmit()</tt> command. If
!    * the transmission did not succeed no timestamp will be stored in the
!    * metadata portion, but <tt>t0</tt> will still represent the hypothetical
!    * transmission time. 
     *
!    * If <tt>error</tt> has a value other than IEEE154_SUCCESS the frame will
!    * stay loaded and a subsequent call to <tt>transmit</tt> will (re-)transmit
!    * the same <tt>frame</tt> again. If <tt>error</tt> has a value of
!    * IEEE154_SUCCESS then the frame was automatically un-loaded and a new frame
!    * has to be loaded before the <tt>transmit()</tt> command will succeed.
     *
!    * When the <tt>transmit()</tt> command was called with an
!    * <tt>ackRequest</tt> parameter with value TRUE, and <tt>error</tt> has a
!    * value of IEEE154_SUCCESS, then this means that a corresponding
!    * acknowledgement was successfully received. In this case, the
!    * <tt>ackPendingFlag</tt> represents the "pending" flag in the header of the
!    * acknowledgement frame (TRUE means set, FALSE means reset).
     *
     * @param frame The frame that was transmitted.  
     *
!    * @param t0 The (hypothetical) transmission time; the pointer is only valid
!    * until the eventhandler returns.  
     *
     * @param ackPendingFlag TRUE if an acknowledgement was received and the
     * "pending" flag is set in the header of the ACK frame, FALSE otherwise
     *
!    * @param error SUCCESS if the transmission succeeded (including successful
!    * CCA and acknowledgement reception, if requested); EBUSY if CCA was
!    * unsuccessful (frame was not transmitted); ENOACK if frame was transmitted
!    * but no matching acknowledgement was received.
!    **/  
!   async event void transmitDone(ieee154_txframe_t *frame, ieee154_reftime_t *t0, 
!       bool ackPendingFlag, error_t error);   
  }
--- 81,216 ----
    /** 
     * Transmits the frame whose transmission has previously been prepared
!    * through a call to <tt>load()</tt> at time <tt>t0+dt</tt> or immediately if
!    * <tt>t0</tt> is NULL. In the first case the caller has to guarantee (through
     * platform-specific guard times and by calling <tt>transmit</tt> in an
!    * atomic block) that the callee can start the transmission on time.
!    * The frame is transmitted without carrier sense (without CCA).  
!    * The <tt>transmitDone()</tt> event will signal the result
     * of the transmission.
     *
     * @param t0 Reference time for transmission (NULL means now)  
     * @param dt A positive offset relative to <tt>t0</tt>.  
     *
     * @return SUCCESS if the transmission was triggered successfully and only
     * then <tt>transmitDone()</tt> will be signalled; FAIL, if the transmission
     * was not triggered because no frame was loaded.
!    */
!   async command error_t transmit(ieee154_reftime_t *t0, uint32_t dt);
  
    /**
!    * Signalled in response to a call to <tt>transmit()</tt> and completing the transmission. Depending on the
!    * <tt>error</tt> parameter the radio is now in the state RADIO_OFF
!    * (<tt>error == IEEE154_SUCCESS</tt>) or back in state TX_LOADED
!    * (<tt>error != IEEE154_SUCCESS</tt>). 
     *
!    * @param frame The frame that was transmitted.  
!    * @param txTime The time of transmission of the first symbol of the PPDU or NULL if the transmission failed.  
!    */
!   async event void transmitDone(ieee154_txframe_t *frame, ieee154_reftime_t *txTime);
! 
! 
!  /** 
!    * Transmits the frame whose transmission has previously been prepared
!    * through a call to <tt>load()</tt> using the unslotted CSMA-CA 
!    * algorithm as specified in the IEEE 802.15.4-2006 standard Sect. 7.5.1.4. The initial 
!    * CSMA-CA parameters are passed as a parameter, the algorithm should start immediately.
!    * The <tt>transmitUnslottedCsmaCaDone()</tt> event will signal the result
!    * of the transmission.
!    * A successful transmission may include an acknowledgement from the
!    * destination if the ACK_REQUESTED flag is set in the loaded frame's header; then,
!    * the callee also has to perform the necessary steps for receiving the
!    * acknowledgement (switching the radio to Rx mode immediately after
!    * transmission, etc., as specified in IEEE 802.15.4-2006 Sect. 7.5.6.4). 
!    * 
!    * @param csmaParameters parameters for the unslotted CSMA-CA algorithm. 
     *
!    * @return SUCCESS if the unslotted CSMA-CA was triggered successfully,
!    * FAIL otherwise.
!    */
!   async command error_t transmitUnslottedCsmaCa(ieee154_csma_t *csmaParameters);
! 
!   /**
!    * Signalled in response to a call to <tt>transmitUnslottedCsmaCa()</tt>. 
!    * Depending on the
!    * <tt>error</tt> parameter the radio is now in the state RADIO_OFF
!    * (<tt>error == IEEE154_SUCCESS</tt>) or still in state TX_LOADED
!    * (<tt>error != IEEE154_SUCCESS</tt>). If the transmission succeeded then
!    * the time of the transmission -- the point in time when the first symbol of the
!    * PPDU was transmitted -- will be stored in the metadata field of the frame. 
     *
     * @param frame The frame that was transmitted.  
+    * @param csmaParameters csmaParameters parameters for the unslotted CSMA-CA algorithm
+    * @param ackPendingFlag TRUE if an acknowledgement was received and the
+    * "pending" flag is set in the header of the ACK frame, FALSE otherwise
+    * @param result SUCCESS if the the frame was transmitted (and a matching
+    * acknowledgement was received, if requested); FAIL if the CSMA-CA algorithm failed
+    * because NB > macMaxCsmaBackoffs.  
     *
!    * unslotted CSMA-CA was triggered successfully,
!    * FAIL otherwiseThe time of transmission or NULL if the transmission failed.  
!    */
!   async event void transmitUnslottedCsmaCaDone(ieee154_txframe_t *frame,
!       bool ackPendingFlag, ieee154_csma_t *csmaParameters, error_t result);
! 
! 
!  /** 
!    * Transmits the frame whose transmission has previously been prepared
!    * through a call to <tt>load()</tt> using the slotted CSMA-CA 
!    * algorithm as specified in the IEEE 802.15.4-2006 standard Sect. 7.5.1.4. The initial 
!    * CSMA-CA parameters are passed as a parameter, the algorithm should start immediately,
!    * but the frame transmission should start no later than <tt>slot0Time+dtMax</tt>. The backoff slot boundaries
!    * are defined relative to <tt>slot0Time</tt>, if the <tt>resume</tt>
!    * then the initial backoff (in symbols) is passed as the <tt>initialBackoff</tt> parameter.
     *
+    * The <tt>transmitSlottedCsmaCaDone()</tt> event will signal the result
+    * of the transmission.
+    * A successful transmission may include an acknowledgement from the
+    * destination if the ACK_REQUESTED flag is set in the loaded frame's header; then,
+    * the callee also has to perform the necessary steps for receiving the
+    * acknowledgement (switching the radio to Rx mode immediately after
+    * transmission, etc., as specified in IEEE 802.15.4-2006 Sect. 7.5.6.4). 
+    * 
+    * @param slot0Time Reference time (last beacon)  
+    * @param dtMax <tt>slot0Time+dtMax</tt> is the last time the frame may be transmitted.
+    * @param resume TRUE means that the initial backoff is defined by the
+    * <tt>initialBackoff</tt> parameter, FALSE means the <tt>initialBackoff</tt>
+    * should be ignored.
+    * @param initialBackoff initial backoff.
+    * @param csmaParameters parameters for the slotted CSMA-CA algorithm. 
+    *
+    * @return SUCCESS if the slotted CSMA-CA was triggered successfully,
+    * FAIL otherwise.
+    */
+   async command error_t transmitSlottedCsmaCa(ieee154_reftime_t *slot0Time, uint32_t dtMax, 
+       bool resume, uint16_t initialBackoff, ieee154_csma_t *csmaParameters);
+ 
+   /**
+    * Signalled in response to a call to <tt>transmitSlottedCsmaCa()</tt>. 
+    * Depending on the
+    * <tt>error</tt> parameter the radio is now in the state RADIO_OFF
+    * (<tt>error == IEEE154_SUCCESS</tt>) or still in state TX_LOADED
+    * (<tt>error != IEEE154_SUCCESS</tt>). If the transmission succeeded then
+    * the time of the transmission -- the point in time when the first symbol of the
+    * PPDU was transmitted -- will be stored in the metadata field of the frame.
+    * It will also passed (possibly with higher precision) through the
+    * <tt>txTime</tt> parameter.
+    *
+    * @param frame The frame that was transmitted.  
+    * @param txTime The time of transmission of the first symbol of the PPDU or NULL if the transmission failed.  
     * @param ackPendingFlag TRUE if an acknowledgement was received and the
     * "pending" flag is set in the header of the ACK frame, FALSE otherwise
+    * @param remainingBackoff only valid if <tt>error == ERETRY</tt>, i.e.
+    * when the frame could not be transmitted because transmission would have
+    * started later than <tt>slot0Time+dtMax</tt>; then it 
+    * specifies the remaining offset (in symbols) relative to <tt>slot0Time+dtMax</tt>,
+    * when the frame would have been transmitted
+    * @param csmaParameters csmaParameters parameters for the unslotted CSMA-CA algorithm
     *
!    * @result result SUCCESS if the the frame was transmitted (and a matching
!    * acknowledgement was received, if requested); FAIL if the CSMA-CA algorithm failed
!    * because NB > macMaxCsmaBackoffs; ERETRY if the frame could not be transmitted because transmission would have
!    * started later than <tt>slot0Time+dtMax</tt>
!    */
!   async event void transmitSlottedCsmaCaDone(ieee154_txframe_t *frame, ieee154_reftime_t *txTime, 
!       bool ackPendingFlag, uint16_t remainingBackoff, ieee154_csma_t *csmaParameters, error_t result);
  }