[Tinyos Core WG] time sync interfaces

[Miklos Maroti]

Dear All,

I put together a proposal for the time sync interface for T2.
Actually, I propose two interfaces, one from receiver-receiver time
synchronization (the time stamp does not need to be embedded into the
message), and sender-receiver time synchronization. Both interfaces
take a precision tag and size parameter. I am very strongly for 16-bit
time synch implementation inside the radio drivers so we do not have
to juggle with 32-bit numbers for backoff and stuff and can have a
single notion of time inside the driver. Both interfaces are designed
so that it is trivial to implement 16->32 bit extensions, and the
precision could also be changed without much difficulties. I think the
two interfaces should not be merged into a single one because they are
fundamentally different. Here are the interfaces:

interface PacketTimeStamp<precision_tag, size_type>
{
  /**
   * Returns TRUE if the time stamp stored in 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.
   */
  async command bool isSet(message_t* msg);

  /**
   * Return the time stamp for the given message. Please check with the
   * isSet 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.
   */
  async command size_type get(message_t* msg);

  /**
   * Sets the isSet flag to FALSE.
   */
  async command void clear(message_t* msg);

  /**
   * Sets the isSet false to TRUE and the time stamp value to the
   * specified value.
   */
  async command void set(message_t* msg, size_type value);
}

interface PacketTimeSynch<precision_tag, size_type>
{
  /**
   * This command should be called by the sender on packets used for sender-
   * receiver time synchronization. The eventTime parameter should be as
   * close to the current time as possible (precision and size of the stamp
   * permitting) to avoid large time synchronization errors resulting from
   * the time skew between the clocks of the sender and receiver. The
   * time difference between the sending time and eventTime is stored in
   * the message just before it is transmitted over the air.
   */
  async command void set(message_t* msg, size_type eventTime);

  /**
   * The recveive should call this method to ensure that the received time
   * stamp is correct (for the same reason as for PacketTimeStamp.isSet).
   * If this method returns TRUE, then the eventTime returned by the get
   * command is correct.
   */
  async command bool isSet(message_t* msg);

  /**
   * This command should be called by the receiver. The time stamp of the
   * received message is added to the embedded time difference to get the
   * eventTime as measured by the clock of the receiver. The caller should
   * call the isSet command before to make sure that the returned time is
   * correct.
   */
  async command size_type get(message_t* msg);
}

One remaining issue is where to store the embedded time stamp.
Probably it should go into the footer, but then we might need another
Send/Receive interface for time stamped messages? What do you think
about this? Also, I am happy to forward this to the devel list, as I
think many people would have some say in it.

Best,
Miklos