/** * @file clock.h * @brief Implements a PTP clock. * @note Copyright (C) 2011 Richard Cochran * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. */ #ifndef HAVE_CLOCK_H #define HAVE_CLOCK_H #include "ds.h" #include "servo.h" #include "tmv.h" #include "transport.h" #define MAX_PORTS 8 /** Defines a network interface, with PTP options. */ struct interface { char *name; enum transport_type transport; enum timestamp_type timestamping; }; /** Opaque type. */ struct clock; /** * Obtains a reference to the best foreign master of a clock. * @param c The clock instance. * @return A pointer to the data set of the foreign master, * or NULL if none has been yet discovered. */ struct dataset *clock_best_foreign(struct clock *c); /** * Obtains a reference to the port with the best foreign master. * @param c The clock instance. * @return A pointer to the port with the best foreign master, * or NULL if none has been yet discovered. */ struct port *clock_best_port(struct clock *c); /** * Obtain the clockClass attribute from a clock. * @param c The clock instance. * @return The value of the clock's class. */ UInteger8 clock_class(struct clock *c); /** * Create a clock instance. There can only be one clock in any system, * so subsequent calls will destroy the previous clock instance. * * @param phc PTP hardware clock device to use. * Pass NULL to select CLOCK_REALTIME. * @param interface An array of network interfaces. * @param count The number of elements in @a interfaces. * @param ds A pointer to a default data set for the clock. * @param pod A pointer to a default port data set for the clock. * @return A pointer to the single global clock instance. */ struct clock *clock_create(char *phc, struct interface *iface, int count, struct defaultDS *ds, struct port_defaults *pod); /** * Obtains a clock's default data set. * @param c The clock instance. * @return A pointer to the data set of the clock. */ struct dataset *clock_default_ds(struct clock *c); /** * Obtain the domain number from a clock's default data set. * @param c The clock instance. * @return The PTP domain number. */ UInteger8 clock_domain_number(struct clock *c); /** * Obtain a clock's identity from its default data set. * @param c The clock instance. * @return The clock's identity. */ struct ClockIdentity clock_identity(struct clock *c); /** * Install a port's file descriptor array into its controlling clock. * @param c The clock instance. * @param p The port installing the array. * @param fda The port's open file decriptors for its sockets and timers. */ void clock_install_fda(struct clock *c, struct port *p, struct fdarray fda); /** * Obtain a clock's parent data set. * @param c The clock instance. * @return A pointer to the parent data set of the clock. */ struct parentDS *clock_parent_ds(struct clock *c); /** * Obtain the parent port identity from a clock's parent data set. * @param c The clock instance. * @return The parent port identity. */ struct PortIdentity clock_parent_identity(struct clock *c); /** * Provide a data point to estimate the path delay. * @param c The clock instance. * @param req The transmission time of the delay request message. * @param rx The reception time of the delay request message, * as reported in the delay response message. * @param correction The correction field from the delay response message. */ void clock_path_delay(struct clock *c, struct timespec req, struct timestamp rx, Integer64 correction); /** * Provide the estimated peer delay from a slave port. * @param c The clock instance. * @param ppd The peer delay as measured on a slave port. */ void clock_peer_delay(struct clock *c, tmv_t ppd); /** * Poll for events and dispatch them. * @param c A pointer to a clock instance obtained with clock_create(). * @return Zero on success, non-zero otherwise. */ int clock_poll(struct clock *c); /** * Remove a port's file descriptor array from its controlling clock. * @param c The clock instance. * @param p The port removing the array. * @param fda The port's file decriptor array. */ void clock_remove_fda(struct clock *c, struct port *p, struct fdarray fda); /** * Obtain the slave-only flag from a clock's default data set. * @param c The clock instance. * @return The value of the clock's slave-only flag. */ int clock_slave_only(struct clock *c); /** * Obtain the steps removed field from a clock's current data set. * @param c The clock instance. * @return The value of the clock's steps removed field. */ UInteger16 clock_steps_removed(struct clock *c); /** * Provide a data point to synchronize the clock. * @param c The clock instance to synchronize. * @param ingress_ts The ingress time stamp on the sync message. * @param origin_ts The reported transmission time of the sync message. * @param correction1 The correction field of the sync message. * @param correction2 The correction field of the follow up message. * Pass zero in the case of one step operation. * @return The state of the clock's servo. */ enum servo_state clock_synchronize(struct clock *c, struct timespec ingress_ts, struct timestamp origin_ts, Integer64 correction1, Integer64 correction2); /** * Obtain a clock's time properties data set. * @param c The clock instance. * @return A pointer to the time properties data set of the clock. */ struct timePropertiesDS *clock_time_properties(struct clock *c); #endif