X-Git-Url: https://oss.titaniummirror.com/gitweb/?a=blobdiff_plain;f=tos%2Flib%2Fmac%2Ftkn154%2Finterfaces%2Fprivate%2FRadioTx.nc;h=f5d45c8904b29ad0833a3b96516f9c510d3f3638;hb=82c215ff867ea7ef4fa748fb72b686c32ffb25e1;hp=7229b1921f52e7bed12b6e60493c325b920ff698;hpb=afb6da3df34fdebb6843598761ef4de5eb0186f6;p=tinyos-2.x.git
diff --git a/tos/lib/mac/tkn154/interfaces/private/RadioTx.nc b/tos/lib/mac/tkn154/interfaces/private/RadioTx.nc
index 7229b192..f5d45c89 100644
--- a/tos/lib/mac/tkn154/interfaces/private/RadioTx.nc
+++ b/tos/lib/mac/tkn154/interfaces/private/RadioTx.nc
@@ -49,7 +49,7 @@ interface RadioTx
* The frame will be loaded (and the radio will stay in the state
* TX_LOADED) until either the transmission was successful, i.e.
* transmitDone() was signalled with a status IEEE154_SUCCESS, or
- * the radio is explicitly switched off through the RadioOff
+ * the radio is switched off through the RadioOff
* 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
* while a frame is loaded as short as possible.
@@ -80,87 +80,137 @@ interface RadioTx
/**
* Transmits the frame whose transmission has previously been prepared
- * through a call to load(). The actual time of transmission -- the
- * point in time when the first symbol of the PPDU is transmitted -- is
- * defined by: t0 + dt. The data type of the t0 parameter
- * is platform-specific (symbol precision or better) while dt is
- * expressed in 802.15.4 symbols. If t0 is NULL, then the callee
- * interprets t0 as the current time. The caller guarantees (through
+ * through a call to load() at time t0+dt or immediately if
+ * t0 is NULL. In the first case the caller has to guarantee (through
* platform-specific guard times and by calling transmit 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
- * (numCCA 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 ackRequest 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 transmit() command will succeed iff the radio is in state
- * TX_LOADED. The transmitDone() event will then signal the result
+ * atomic block) that the callee can start the transmission on time.
+ * The frame is transmitted without carrier sense (without CCA).
+ * The transmitDone() event will signal the result
* of the transmission.
*
* @param t0 Reference time for transmission (NULL means now)
- *
* @param dt A positive offset relative to t0.
*
- * @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 transmitDone() 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);
+ */
+ async command error_t transmit(ieee154_reftime_t *t0, uint32_t dt);
/**
- * Signalled in response to a call to transmit(). Depending on the
- * error parameter the radio is now in state RADIO_OFF
- * (error == IEEE154_SUCCESS) or still in state TX_LOADED
- * (error != 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 t0 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 transmit() command. If
- * the transmission did not succeed no timestamp will be stored in the
- * metadata portion, but t0 will still represent the hypothetical
- * transmission time.
- *
- * If error has a value other than IEEE154_SUCCESS the frame will
- * stay loaded and a subsequent call to transmit will (re-)transmit
- * the same frame again. If error has a value of
- * IEEE154_SUCCESS then the frame was automatically un-loaded and a new frame
- * has to be loaded before the transmit() command will succeed.
- *
- * When the transmit() command was called with an
- * ackRequest parameter with value TRUE, and error has a
- * value of IEEE154_SUCCESS, then this means that a corresponding
- * acknowledgement was successfully received. In this case, the
- * ackPendingFlag represents the "pending" flag in the header of the
- * acknowledgement frame (TRUE means set, FALSE means reset).
+ * Signalled in response to a call to transmit() and completing the transmission. Depending on the
+ * error parameter the radio is now in the state RADIO_OFF
+ * (error == IEEE154_SUCCESS) or back in state TX_LOADED
+ * (error != IEEE154_SUCCESS).
*
* @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 load() 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 transmitUnslottedCsmaCaDone() 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.
*
- * @param t0 The (hypothetical) transmission time; the pointer is only valid
- * until the eventhandler returns.
+ * @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 transmitUnslottedCsmaCa().
+ * Depending on the
+ * error parameter the radio is now in the state RADIO_OFF
+ * (error == IEEE154_SUCCESS) or still in state TX_LOADED
+ * (error != IEEE154_SUCCESS). 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 load() 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 slot0Time+dtMax. The backoff slot boundaries
+ * are defined relative to slot0Time, if the resume
+ * then the initial backoff (in symbols) is passed as the initialBackoff parameter.
+ *
+ * The transmitSlottedCsmaCaDone() 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 slot0Time+dtMax is the last time the frame may be transmitted.
+ * @param resume TRUE means that the initial backoff is defined by the
+ * initialBackoff parameter, FALSE means the initialBackoff
+ * 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 transmitSlottedCsmaCa().
+ * Depending on the
+ * error parameter the radio is now in the state RADIO_OFF
+ * (error == IEEE154_SUCCESS) or still in state TX_LOADED
+ * (error != IEEE154_SUCCESS). 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
+ * txTime parameter.
*
- * @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);
+ * @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 error == ERETRY, i.e.
+ * when the frame could not be transmitted because transmission would have
+ * started later than slot0Time+dtMax; then it
+ * specifies the remaining offset (in symbols) relative to slot0Time+dtMax,
+ * 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 slot0Time+dtMax
+ */
+ async event void transmitSlottedCsmaCaDone(ieee154_txframe_t *frame, ieee154_reftime_t *txTime,
+ bool ackPendingFlag, uint16_t remainingBackoff, ieee154_csma_t *csmaParameters, error_t result);
}