msg.h

   1 /**
   2  * @file msg.h
   3  * @brief Implements the various PTP message types.
   4  * @note Copyright (C) 2011 Richard Cochran <richardcochran@gmail.com>
   5  *
   6  * This program is free software; you can redistribute it and/or modify
   7  * it under the terms of the GNU General Public License as published by
   8  * the Free Software Foundation; either version 2 of the License, or
   9  * (at your option) any later version.
  10  *
  11  * This program is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14  * GNU General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU General Public License along
  17  * with this program; if not, write to the Free Software Foundation, Inc.,
  18  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  19  */
  20 #ifndef HAVE_MSG_H
  21 #define HAVE_MSG_H
  22
  23 #include <stdio.h>
  24 #include <sys/queue.h>
  25 #include <time.h>
  26
  27 #include "address.h"
  28 #include "ddt.h"
  29 #include "tlv.h"
  30
  31 #define PTP_VERSION 2
  32
  33 /* Values for the messageType field */
  34 #define SYNC                  0x0
  35 #define DELAY_REQ             0x1
  36 #define PDELAY_REQ            0x2
  37 #define PDELAY_RESP           0x3
  38 #define FOLLOW_UP             0x8
  39 #define DELAY_RESP            0x9
  40 #define PDELAY_RESP_FOLLOW_UP 0xA
  41 #define ANNOUNCE              0xB
  42 #define SIGNALING             0xC
  43 #define MANAGEMENT            0xD
  44
  45 /* Bits for flagField[0] */
  46 #define ALT_MASTER     (1<<0)
  47 #define TWO_STEP       (1<<1)
  48 #define UNICAST        (1<<2)
  49
  50 /* Bits for flagField[1] */
  51 #define LEAP_61        (1<<0)
  52 #define LEAP_59        (1<<1)
  53 #define UTC_OFF_VALID  (1<<2)
  54 #define PTP_TIMESCALE  (1<<3)
  55 #define TIME_TRACEABLE (1<<4)
  56 #define FREQ_TRACEABLE (1<<5)
  57
  58 enum timestamp_type {
  59         TS_SOFTWARE,
  60         TS_HARDWARE,
  61         TS_LEGACY_HW,
  62         TS_ONESTEP,
  63 };
  64
  65 struct hw_timestamp {
  66         enum timestamp_type type;
  67         struct timespec ts;
  68         struct timespec sw;
  69 };
  70
  71 enum controlField {
  72         CTL_SYNC,
  73         CTL_DELAY_REQ,
  74         CTL_FOLLOW_UP,
  75         CTL_DELAY_RESP,
  76         CTL_MANAGEMENT,
  77         CTL_OTHER,
  78 };
  79
  80 struct ptp_header {
  81         uint8_t             tsmt; /* transportSpecific | messageType */
  82         uint8_t             ver;  /* reserved          | versionPTP  */
  83         UInteger16          messageLength;
  84         UInteger8           domainNumber;
  85         Octet               reserved1;
  86         Octet               flagField[2];
  87         Integer64           correction;
  88         UInteger32          reserved2;
  89         struct PortIdentity sourcePortIdentity;
  90         UInteger16          sequenceId;
  91         UInteger8           control;
  92         Integer8            logMessageInterval;
  93 } PACKED;
  94
  95 struct announce_msg {
  96         struct ptp_header    hdr;
  97         struct Timestamp     originTimestamp;
  98         Integer16            currentUtcOffset;
  99         Octet                reserved;
 100         UInteger8            grandmasterPriority1;
 101         struct ClockQuality  grandmasterClockQuality;
 102         UInteger8            grandmasterPriority2;
 103         struct ClockIdentity grandmasterIdentity;
 104         UInteger16           stepsRemoved;
 105         Enumeration8         timeSource;
 106         uint8_t              suffix[0];
 107 } PACKED;
 108
 109 struct sync_msg {
 110         struct ptp_header   hdr;
 111         struct Timestamp    originTimestamp;
 112 } PACKED;
 113
 114 struct delay_req_msg {
 115         struct ptp_header   hdr;
 116         struct Timestamp    originTimestamp;
 117 } PACKED;
 118
 119 struct follow_up_msg {
 120         struct ptp_header   hdr;
 121         struct Timestamp    preciseOriginTimestamp;
 122         uint8_t             suffix[0];
 123 } PACKED;
 124
 125 struct delay_resp_msg {
 126         struct ptp_header   hdr;
 127         struct Timestamp    receiveTimestamp;
 128         struct PortIdentity requestingPortIdentity;
 129         uint8_t             suffix[0];
 130 } PACKED;
 131
 132 struct pdelay_req_msg {
 133         struct ptp_header   hdr;
 134         struct Timestamp    originTimestamp;
 135         struct PortIdentity reserved;
 136 } PACKED;
 137
 138 struct pdelay_resp_msg {
 139         struct ptp_header   hdr;
 140         struct Timestamp    requestReceiptTimestamp;
 141         struct PortIdentity requestingPortIdentity;
 142 } PACKED;
 143
 144 struct pdelay_resp_fup_msg {
 145         struct ptp_header   hdr;
 146         struct Timestamp    responseOriginTimestamp;
 147         struct PortIdentity requestingPortIdentity;
 148         uint8_t             suffix[0];
 149 } PACKED;
 150
 151 struct signaling_msg {
 152         struct ptp_header   hdr;
 153         struct PortIdentity targetPortIdentity;
 154         uint8_t             suffix[0];
 155 } PACKED;
 156
 157 struct management_msg {
 158         struct ptp_header   hdr;
 159         struct PortIdentity targetPortIdentity;
 160         UInteger8           startingBoundaryHops;
 161         UInteger8           boundaryHops;
 162         uint8_t             flags; /* reserved | actionField */
 163         uint8_t             reserved;
 164         uint8_t             suffix[0];
 165 } PACKED;
 166
 167 struct message_data {
 168         uint8_t buffer[1500];
 169 } PACKED;
 170
 171 struct ptp_message {
 172         union {
 173                 struct ptp_header          header;
 174                 struct announce_msg        announce;
 175                 struct sync_msg            sync;
 176                 struct delay_req_msg       delay_req;
 177                 struct follow_up_msg       follow_up;
 178                 struct delay_resp_msg      delay_resp;
 179                 struct pdelay_req_msg      pdelay_req;
 180                 struct pdelay_resp_msg     pdelay_resp;
 181                 struct pdelay_resp_fup_msg pdelay_resp_fup;
 182                 struct signaling_msg       signaling;
 183                 struct management_msg      management;
 184                 struct message_data        data;
 185         } PACKED;
 186         /**/
 187         int tail_room;
 188         int refcnt;
 189         TAILQ_ENTRY(ptp_message) list;
 190         struct {
 191                 /**
 192                  * Contains the time stamp from the packet data in a
 193                  * native binary format for the host machine. The
 194                  * exact source of the time stamp's value depends on
 195                  * the message type:
 196                  *
 197                  * - announce    originTimestamp
 198                  * - follow_up   preciseOriginTimestamp
 199                  * - sync        originTimestamp
 200                  * - delay_req   originTimestamp
 201                  * - pdelay_resp     requestReceiptTimestamp
 202                  * - pdelay_resp_fup responseOriginTimestamp
 203                  */
 204                 struct timestamp pdu;
 205                 /**
 206                  * Approximate ingress time stamp using the relative
 207                  * CLOCK_MONOTONIC. Used to determine when announce
 208                  * messages have expired.
 209                  */
 210                 struct timespec host;
 211         } ts;
 212         /**
 213          * Contains the ingress time stamp obtained by the
 214          * SO_TIMESTAMPING socket option.
 215          */
 216         struct hw_timestamp hwts;
 217         /**
 218          * Contains the address this message was received from or should be
 219          * sent to.
 220          */
 221         struct address address;
 222         /**
 223          * Contains the number of TLVs in the suffix.
 224          */
 225         int tlv_count;
 226         /**
 227          * Used to hold the data of the last TLV in the message when
 228          * the layout of the TLV makes it difficult to access the data
 229          * directly from the message's buffer.
 230          */
 231         struct tlv_extra last_tlv;
 232 };
 233
 234 /**
 235  * Obtain the action field from a management message.
 236  * @param m  A management message.
 237  * @return   The value of the action field.
 238  */
 239 static inline uint8_t management_action(struct ptp_message *m)
 240 {
 241         return m->management.flags & 0x0f;
 242 }
 243
 244 /**
 245  * Test a given bit in a message's flag field.
 246  * @param m      Message to test.
 247  * @param index  Index into flag field, either 0 or 1.
 248  * @param bit    Bit mask of one bit to test.
 249  * @return       One if bit is set, zero otherwise.
 250  */
 251 static inline Boolean field_is_set(struct ptp_message *m, int index, Octet bit)
 252 {
 253         return m->header.flagField[index] & bit ? TRUE : FALSE;
 254 }
 255
 256 /**
 257  * Obtain the transportSpecific field from a message.
 258  * @param m  Message to test.
 259  * @return   The value of the transportSpecific field. Note that the
 260  *           value is returned unshifted, in the upper nibble.
 261  */
 262 static inline UInteger8 msg_transport_specific(struct ptp_message *m)
 263 {
 264         return m->header.tsmt & 0xf0;
 265 }
 266
 267 /**
 268  * Obtain the message type.
 269  * @param m  Message to test.
 270  * @return   The value of the messageType field.
 271  */
 272 static inline int msg_type(struct ptp_message *m)
 273 {
 274         return m->header.tsmt & 0x0f;
 275 }
 276
 277 /**
 278  * Allocate a new message instance.
 279  *
 280  * Messages are reference counted, and newly allocated messages have a
 281  * reference count of one. Allocated messages are freed using the
 282  * function @ref msg_put().
 283  *
 284  * @return Pointer to a message on success, NULL otherwise.
 285  */
 286 struct ptp_message *msg_allocate(void);
 287
 288 /**
 289  * Release all of the memory in the message cache.
 290  */
 291 void msg_cleanup(void);
 292
 293 /**
 294  * Obtain a reference to a message, increasing its reference count by one.
 295  * @param m A message obtained using @ref msg_allocate().
 296  */
 297 void msg_get(struct ptp_message *m);
 298
 299 /**
 300  * Process messages after reception.
 301  * @param m    A message obtained using @ref msg_allocate().
 302  * @param cnt  The size of 'm' in bytes.
 303  * @return   Zero on success, non-zero if the message is invalid.
 304  */
 305 int msg_post_recv(struct ptp_message *m, int cnt);
 306
 307 /**
 308  * Prepare messages for transmission.
 309  * @param m  A message obtained using @ref msg_allocate().
 310  * @return   Zero on success, non-zero if the message is invalid.
 311  */
 312 int msg_pre_send(struct ptp_message *m);
 313
 314 /**
 315  * Print messages for debugging purposes.
 316  * @param type  Value of the messageType field as returned by @ref msg_type().
 317  * @return      String describing the message type.
 318  */
 319 const char *msg_type_string(int type);
 320
 321 /**
 322  * Print messages for debugging purposes.
 323  * @param m   A message obtained using @ref msg_allocate().
 324  * @param fp  An open file pointer.
 325  */
 326 void msg_print(struct ptp_message *m, FILE *fp);
 327
 328 /**
 329  * Release a reference to a message, decreasing its reference count by one.
 330  * @param m A message obtained using @ref msg_allocate().
 331  */
 332 void msg_put(struct ptp_message *m);
 333
 334 /**
 335  * Test whether an event message received a valid SO_TIMESTAMPING time stamp.
 336  * @param m  Message to test.
 337  * @return   One if the message is an event without a time stamp, zero otherwise.
 338  */
 339 int msg_sots_missing(struct ptp_message *m);
 340
 341 /**
 342  * Test whether a message has a valid SO_TIMESTAMPING time stamp.
 343  * @param m  Message to test.
 344  * @return   One if the message has a valid time stamp, zero otherwise.
 345  */
 346 static inline int msg_sots_valid(struct ptp_message *m)
 347 {
 348         return (m->hwts.ts.tv_sec || m->hwts.ts.tv_nsec) ? 1 : 0;
 349 }
 350
 351 /**
 352  * Work around buggy 802.1AS switches.
 353  */
 354 extern int assume_two_step;
 355
 356 /**
 357  * Test whether a message is one-step message.
 358  * @param m  Message to test.
 359  * @return   One if the message is a one-step, zero otherwise.
 360  */
 361 static inline Boolean one_step(struct ptp_message *m)
 362 {
 363         if (assume_two_step)
 364                 return 0;
 365         return !field_is_set(m, 0, TWO_STEP);
 366 }
 367
 368 /**
 369  * Convert a 64 bit word into network byte order.
 370  */
 371 int64_t host2net64(int64_t val);
 372
 373 /**
 374  * Convert a 64 bit word into host byte order.
 375  */
 376 int64_t net2host64(int64_t val);
 377
 378 #endif