From 9a086f1df425c84ed113454bcbb523db1450c35a Mon Sep 17 00:00:00 2001 From: sallai Date: Thu, 29 May 2008 15:43:11 +0000 Subject: [PATCH] move tep 132/133 interfaces to tos/interfaces --- tos/interfaces/PacketTimeStamp.nc | 60 +++++++++++++++++ tos/interfaces/TimeSyncAMSend.nc | 104 ++++++++++++++++++++++++++++++ tos/interfaces/TimeSyncPacket.nc | 46 +++++++++++++ 3 files changed, 210 insertions(+) create mode 100644 tos/interfaces/PacketTimeStamp.nc create mode 100644 tos/interfaces/TimeSyncAMSend.nc create mode 100644 tos/interfaces/TimeSyncPacket.nc diff --git a/tos/interfaces/PacketTimeStamp.nc b/tos/interfaces/PacketTimeStamp.nc new file mode 100644 index 00000000..1380d8de --- /dev/null +++ b/tos/interfaces/PacketTimeStamp.nc @@ -0,0 +1,60 @@ +/* + * Copyright (c) 2007, Vanderbilt University + * All rights reserved. + * + * Permission to use, copy, modify, and distribute this software and its + * documentation for any purpose, without fee, and without written agreement is + * hereby granted, provided that the above copyright notice, the following + * two paragraphs and the author appear in all copies of this software. + * + * IN NO EVENT SHALL THE VANDERBILT UNIVERSITY BE LIABLE TO ANY PARTY FOR + * DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT + * OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF THE VANDERBILT + * UNIVERSITY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + * + * THE VANDERBILT UNIVERSITY SPECIFICALLY DISCLAIMS ANY WARRANTIES, + * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY + * AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS + * ON AN "AS IS" BASIS, AND THE VANDERBILT UNIVERSITY HAS NO OBLIGATION TO + * PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS. + * + * Author: Miklos Maroti + */ + +interface PacketTimeStamp +{ + /** + * Returns TRUE if the time stamp of the message is valid. Under special + * circumstances the radio chip might not be able to correctly assign a + * precise time value to an incoming packet (e.g. under very heavy traffic + * multiple interrupts can occur before they could be serviced, and even + * if capture registers are used, it is not possible to get the time stamp + * for the first or last unserviced event), in which case the time stamp + * value should not be used. It is recommended that the isValid command be + * called from the receive or sendDone event handler. + */ + async command bool isValid(message_t* msg); + + /** + * Return the time stamp for the given message. Please check with the + * isValid command if this value can be relied upon. If this command is + * called after transmission, then the transmit time of the packet + * is returned (the time when the frame synchronization byte was + * transmitted). If this command is called after the message is received, + * the tne receive time of the message is returned. It is recommended that + * the timestamp command be called only from the receive or sendDone event + * handler. + */ + async command size_type timestamp(message_t* msg); + + /** + * Sets the isValid flag to FALSE. + */ + async command void clear(message_t* msg); + + /** + * Sets the isValid flag to TRUE and the time stamp value to the + * specified value. + */ + async command void set(message_t* msg, size_type value); +} diff --git a/tos/interfaces/TimeSyncAMSend.nc b/tos/interfaces/TimeSyncAMSend.nc new file mode 100644 index 00000000..eb862776 --- /dev/null +++ b/tos/interfaces/TimeSyncAMSend.nc @@ -0,0 +1,104 @@ +/* + * Copyright (c) 2007, Vanderbilt University + * All rights reserved. + * + * Permission to use, copy, modify, and distribute this software and its + * documentation for any purpose, without fee, and without written agreement is + * hereby granted, provided that the above copyright notice, the following + * two paragraphs and the author appear in all copies of this software. + * + * IN NO EVENT SHALL THE VANDERBILT UNIVERSITY BE LIABLE TO ANY PARTY FOR + * DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT + * OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF THE VANDERBILT + * UNIVERSITY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + * + * THE VANDERBILT UNIVERSITY SPECIFICALLY DISCLAIMS ANY WARRANTIES, + * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY + * AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS + * ON AN "AS IS" BASIS, AND THE VANDERBILT UNIVERSITY HAS NO OBLIGATION TO + * PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS. + */ + +/** + * @author Philip Levis + * @author Miklos Maroti + * + * @see TimeSyncPacket + */ + +#include +#include +#include + +interface TimeSyncAMSend +{ + /** + * This command sends a regular message just like AMSend.send, but + * it also performs sender-receiver time synchronization. The event_time + * parameter holds the time of some event as expressed in the local clock of + * the sender. The receiver can obtain the time of this event (expressed in its + * own local time) via the TimeSyncPacket interface. + * + * @param addr address to which to send the packet + * @param msg the packet + * @param len the length of the data in the packet payload + * @param event_time the synchronization point to be transfered with the message + * @return SUCCESS if the request to send succeeded and a + * sendDone will be signaled later, EBUSY if the + * abstraction cannot send now but will be able to + * later, or FAIL if the communication layer is not + * in a state that can send (e.g., off). + * @see sendDone + */ + command error_t send(am_addr_t addr, message_t* msg, uint8_t len, size_type event_time); + + /** + * Cancel a requested transmission. Returns SUCCESS if the + * transmission was canceled properly (not sent in its + * entirety). Note that the component may not know + * if the send was successfully canceled, if the radio is + * handling much of the logic; in this case, a component + * should be conservative and return an appropriate error code. + * A successful call to cancel must always result in a + * sendFailed event, and never a sendSucceeded event. + * + * @param msg the packet whose transmission should be cancelled. + * @return SUCCESS if the transmission was cancelled, FAIL otherwise. + * @see sendDone + */ + command error_t cancel(message_t* msg); + + /** + * Signaled in response to an accepted send request. msg is + * the message buffer sent, and error indicates whether + * the send was successful. + * + * @param msg the packet which was submitted as a send request + * @param error SUCCESS if it was sent successfully, FAIL if it was not, + * ECANCEL if it was cancelled + * @see send + * @see cancel + */ + event void sendDone(message_t* msg, error_t error); + + /** + * Return the maximum payload length that this communication layer + * can provide. This command behaves identically to + * Packet.maxPayloadLength and is included in this + * interface as a convenience. + * + * @return the maximum payload length + */ + command uint8_t maxPayloadLength(); + + /** + * Return a pointer to a protocol's payload region in a packet. + * This command behaves identically to Packet.getPayload + * (minus the length parameter) and is included in this interface + * as a convenience. + * + * @param msg the packet + * @return the payload of the packet + */ + command void* getPayload(message_t* msg, uint8_t len); +} diff --git a/tos/interfaces/TimeSyncPacket.nc b/tos/interfaces/TimeSyncPacket.nc new file mode 100644 index 00000000..027a8048 --- /dev/null +++ b/tos/interfaces/TimeSyncPacket.nc @@ -0,0 +1,46 @@ +/* + * Copyright (c) 2007, Vanderbilt University + * All rights reserved. + * + * Permission to use, copy, modify, and distribute this software and its + * documentation for any purpose, without fee, and without written agreement is + * hereby granted, provided that the above copyright notice, the following + * two paragraphs and the author appear in all copies of this software. + * + * IN NO EVENT SHALL THE VANDERBILT UNIVERSITY BE LIABLE TO ANY PARTY FOR + * DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT + * OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF THE VANDERBILT + * UNIVERSITY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + * + * THE VANDERBILT UNIVERSITY SPECIFICALLY DISCLAIMS ANY WARRANTIES, + * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY + * AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS + * ON AN "AS IS" BASIS, AND THE VANDERBILT UNIVERSITY HAS NO OBLIGATION TO + * PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS. + * + * Author: Miklos Maroti + */ + +interface TimeSyncPacket +{ + /** + * Returns TRUE if the value returned by getTime can be trusted. + * Under certain circumstances the received message cannot be properly + * time stamped, so the sender-receiver synchronization cannot be finished + * on the receiver side. In this case, this command returns FALSE. + * This command MUST BE called only on the receiver side and only for + * messages transmitted via the TimeSyncSend interface. It is recommended + * that this command be called from the receive event handler. + */ + async command bool isValid(message_t* msg); + + /** + * This command should be called by the receiver of a message. The time + * of the synchronization event is returned as expressed in the local + * clock of the caller. This command MUST BE called only on the receiver + * side and only for messages transmitted via the TimeSyncSend interface. + * It is recommended that this command be called from the receive event + * handler. + */ + async command size_type eventTime(message_t* msg); +} -- 2.39.2