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