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); }