X-Git-Url: https://oss.titaniummirror.com/gitweb/?a=blobdiff_plain;f=tos%2Flib%2Fmac%2Ftkn154%2Finterfaces%2Fprivate%2FRadioTx.nc;h=37b8c0a98bdd8e0c39035736d841e2ec7283ed98;hb=e9bfab607e051bae6afb47b44892ce37541d1b44;hp=7229b1921f52e7bed12b6e60493c325b920ff698;hpb=adf1de6c009d13b7b52e68535c63b28f59c97400;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..37b8c0a9 100644
--- a/tos/lib/mac/tkn154/interfaces/private/RadioTx.nc
+++ b/tos/lib/mac/tkn154/interfaces/private/RadioTx.nc
@@ -33,134 +33,62 @@
* ========================================================================
*/
#include "TKN154_MAC.h"
-#include "TKN154_PHY.h"
+#include "TKN154_platform.h"
interface RadioTx
{
-
/**
- * Prepares the transmission of a frame. This command will fail, if the
- * radio is neither in state RADIO_OFF nor in state TX_LOADED. The actual
- * transmission will be triggered through a call to transmit(). Any
- * frame that was previously prepared for transmission ("loaded") will be
- * overwritten. The loadDone() event signals the completion of the
- * load() command.
- *
- * 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
- * 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.
- *
- * @param frame The frame to transmit.
+ * Transmits a frame at time t0 + dt or immediately if t0 +
+ * dt lies in the past. The frame is transmitted in any case (without
+ * prior CCA). Analogous to the Timer interface t0 is
+ * interpreted as a time in the past. If t0 is NULL or if
+ * dt is zero then the frame is transmitted immediately. This
+ * command will fail, if the radio is currently not in state RADIO_OFF.
+ *
+ * Iff the ACK_REQUESTED flag is set in the frame's header a successful
+ * transmission will include an acknowledgement from the destination; then,
+ * the callee will perform the necessary steps for receiving this
+ * acknowledgement following the specification in IEEE 802.15.4-2006 Sect.
+ * 7.5.6.4.
+ *
+ * @param frame The frame to transmit
+ *
+ * @param t0 Reference time for transmission, NULL means frame will be
+ * transmitted immediately
+ *
+ * @param dt A positive offset relative to t0, ignored
+ * if t0 is NULL
*
- * @return SUCCESS if the command was accepted and loadDone() will
- * be signalled; FAIL otherwise
- **/
- async command error_t load(ieee154_txframe_t *frame);
-
- /**
- * Signalled in response to a successful call to load(). This
- * event is completing the preparation of a transmission, the radio is
- * now in the state TX_LOADED. The actual transmission is triggered
- * through a call to transmit().
- **/
- async event void loadDone();
-
- /**
- * If the radio is in state TX_LOADED then this commands returns the
- * the frame that was loaded last; it returns NULL otherwise.
- *
- * @return last frame loaded if radio is in the state TX_LOADED,
- * NULL otherwise
- **/
- async command ieee154_txframe_t* getLoadedFrame();
-
- /**
- * 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
- * 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
- * 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);
+ * then transmitDone() will be signalled; FAIL, if the command was
+ * not accepted, because the radio is currently not in the state RADIO_OFF;
+ * EINVAL if frame or a pointer therein is invalid, or the length
+ * of the frame is invalid
+ */
+ async command error_t transmit(ieee154_txframe_t *frame, const ieee154_timestamp_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 of a frame. The radio is now back in state RADIO_OFF.
+ * The time of the transmission -- the point in time when the first bit of the
+ * PPDU was transmitted -- is given by timestamp. Since the
+ * frame was transmitted without CCA the transmission can only have
+ * failed if no acknowledgement was received although one was requested.
*
* @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);
+ * @param timestamp The point in time when the first bit of the PPDU
+ * was received or NULL if a timestamp is not available. The
+ * timestamp's data type is platform-specific, you can use the
+ * IEEE154Frame.getTimestamp() command to get a platform-
+ * independent variant (uint32_t) of the timestamp. This pointer
+ * is only valid while the event is signalled and no reference must
+ * be kept to it afterwards.
+ *
+ * @param result SUCCESS if the frame was transmitted (and a matching
+ * acknowledgement was received, if requested); ENOACK if the frame was
+ * transmitted, but no matching acknowledgement was received although one
+ * was requested
+ **/
+ async event void transmitDone(ieee154_txframe_t *frame, const ieee154_timestamp_t *timestamp, error_t result);
}