331 lines
11 KiB
C
331 lines
11 KiB
C
/**
|
|
* @file port.h
|
|
* @note Copyright (C) 2011 Richard Cochran <richardcochran@gmail.com>
|
|
*
|
|
* 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_PORT_H
|
|
#define HAVE_PORT_H
|
|
|
|
#include "dm.h"
|
|
#include "fd.h"
|
|
#include "foreign.h"
|
|
#include "fsm.h"
|
|
#include "notification.h"
|
|
#include "transport.h"
|
|
|
|
/* forward declarations */
|
|
struct interface;
|
|
struct clock;
|
|
|
|
/** Opaque type. */
|
|
struct port;
|
|
|
|
/**
|
|
* Returns the dataset from a port's best foreign clock record, if any
|
|
* has yet been discovered. This function does not bring the returned
|
|
* dataset up to date, so the caller should invoke port_compute_best()
|
|
* beforehand.
|
|
*
|
|
* @param port A pointer previously obtained via port_open().
|
|
* @return A pointer to a dataset, or NULL.
|
|
*/
|
|
struct dataset *port_best_foreign(struct port *port);
|
|
|
|
/**
|
|
* Close a port and free its associated resources. After this call
|
|
* returns, @a port is no longer a valid port instance.
|
|
*
|
|
* @param port A pointer previously obtained via port_open().
|
|
*/
|
|
void port_close(struct port *port);
|
|
|
|
/**
|
|
* Computes the 'best' foreign master discovered on a port. This has
|
|
* the side effect of updating the 'dataset' field of the returned
|
|
* foreign master.
|
|
*
|
|
* @param port A pointer previously obtained via port_open().
|
|
* @return A pointer to the port's best foreign master, or NULL.
|
|
*/
|
|
struct foreign_clock *port_compute_best(struct port *port);
|
|
|
|
/**
|
|
* Dispatch a port event. This may cause a state transition on the
|
|
* port, with the associated side effect.
|
|
*
|
|
* @param port A pointer previously obtained via port_open().
|
|
* @param event One of the @a fsm_event codes.
|
|
* @param mdiff Whether a new master has been selected.
|
|
*/
|
|
void port_dispatch(struct port *p, enum fsm_event event, int mdiff);
|
|
|
|
/**
|
|
* Generates state machine events based on activity on a port's file
|
|
* descriptors.
|
|
*
|
|
* @param port A pointer previously obtained via port_open().
|
|
* @param fd_index The index of the active file descriptor.
|
|
* @return One of the @a fsm_event codes.
|
|
*/
|
|
enum fsm_event port_event(struct port *port, int fd_index);
|
|
|
|
/**
|
|
* Forward a message on a given port.
|
|
* @param port A pointer previously obtained via port_open().
|
|
* @param msg The message to send. Must be in network byte order.
|
|
* @return Zero on success, non-zero otherwise.
|
|
*/
|
|
int port_forward(struct port *p, struct ptp_message *msg);
|
|
|
|
/**
|
|
* Forward a message on a given port to the address stored in the message.
|
|
* @param port A pointer previously obtained via port_open().
|
|
* @param msg The message to send. Must be in network byte order.
|
|
* @return Zero on success, non-zero otherwise.
|
|
*/
|
|
int port_forward_to(struct port *p, struct ptp_message *msg);
|
|
|
|
/**
|
|
* Prepare message for transmission and send it to a given port. Note that
|
|
* a single message cannot be sent several times using this function, that
|
|
* would lead to corrupted data being sent. Use msg_pre_send and
|
|
* port_forward if you need to send single message to several ports.
|
|
* @param p A pointer previously obtained via port_open().
|
|
* @param msg The message to send.
|
|
* @param event One of the @ref transport_event enumeration values.
|
|
*/
|
|
int port_prepare_and_send(struct port *p, struct ptp_message *msg,
|
|
enum transport_event event);
|
|
|
|
/**
|
|
* Obtain a port's identity.
|
|
* @param p A pointer previously obtained via port_open().
|
|
* @return The port identity of 'p'.
|
|
*/
|
|
struct PortIdentity port_identity(struct port *p);
|
|
|
|
/**
|
|
* Obtain a port number.
|
|
* @param p A port instance.
|
|
* @return The port number of 'p'.
|
|
*/
|
|
int port_number(struct port *p);
|
|
|
|
/**
|
|
* Obtain the link status of a port.
|
|
* @param p A port instance.
|
|
* @return One (1) if the link is up, zero otherwise.
|
|
*/
|
|
int port_link_status_get(struct port *p);
|
|
|
|
/**
|
|
* Manage a port according to a given message.
|
|
* @param p A pointer previously obtained via port_open().
|
|
* @param ingress The port on which 'msg' was received.
|
|
* @param msg A management message.
|
|
* @return 1 if the message was responded to, 0 if it did not apply
|
|
* to the port, -1 if it was invalid.
|
|
*/
|
|
int port_manage(struct port *p, struct port *ingress, struct ptp_message *msg);
|
|
|
|
/**
|
|
* Send a management error status message.
|
|
* @param pid The id of the responding port.
|
|
* @param ingress Port on which the 'req' was received.
|
|
* @param req The management message which triggered the error.
|
|
* @param error_id One of the management error ID values.
|
|
* @return Zero on success, non-zero otherwise.
|
|
*/
|
|
int port_management_error(struct PortIdentity pid, struct port *ingress,
|
|
struct ptp_message *req, Enumeration16 error_id);
|
|
|
|
/**
|
|
* Allocate a reply to a management message.
|
|
*
|
|
* Messages are reference counted, and newly allocated messages have a
|
|
* reference count of one. Allocated messages are freed using the
|
|
* function @ref msg_put().
|
|
*
|
|
* @param pid The id of the responding port.
|
|
* @param ingress The port on which 'req' was received.
|
|
* @param req A management message.
|
|
* @return Pointer to a message on success, NULL otherwise.
|
|
*/
|
|
struct ptp_message *port_management_reply(struct PortIdentity pid,
|
|
struct port *ingress,
|
|
struct ptp_message *req);
|
|
|
|
/**
|
|
* Allocate a standalone reply management message.
|
|
*
|
|
* See note in @ref port_management_reply description about freeing the
|
|
* message. Also note that the constructed message does not have
|
|
* targetPortIdentity and sequenceId filled.
|
|
*
|
|
* @param pid The id of the responding port.
|
|
* @param port The port to which the message will be sent.
|
|
* @return Pointer to a message on success, NULL otherwise.
|
|
*/
|
|
struct ptp_message *port_management_notify(struct PortIdentity pid,
|
|
struct port *port);
|
|
|
|
/**
|
|
* Construct and send notification to subscribers about an event that
|
|
* occured on the port.
|
|
* @param p The port.
|
|
* @param event The identification of the event.
|
|
*/
|
|
void port_notify_event(struct port *p, enum notification event);
|
|
|
|
/**
|
|
* Open a network port.
|
|
* @param phc_index The PHC device index for the network device.
|
|
* @param timestamping The timestamping mode for this port.
|
|
* @param number An arbitrary number assigned to this port.
|
|
* @param interface The interface data
|
|
* @param clock A pointer to the system PTP clock.
|
|
* @return A pointer to an open port on success, or NULL otherwise.
|
|
*/
|
|
struct port *port_open(int phc_index,
|
|
enum timestamp_type timestamping,
|
|
int number,
|
|
struct interface *interface,
|
|
struct clock *clock);
|
|
|
|
/**
|
|
* Returns a port's current state.
|
|
* @param port A port instance.
|
|
* @return One of the @ref port_state values.
|
|
*/
|
|
enum port_state port_state(struct port *port);
|
|
|
|
/**
|
|
* Update a port's current state based on a given event.
|
|
* @param p A pointer previously obtained via port_open().
|
|
* @param event One of the @a fsm_event codes.
|
|
* @param mdiff Whether a new master has been selected.
|
|
* @return One (1) if the port state has changed, zero otherwise.
|
|
*/
|
|
int port_state_update(struct port *p, enum fsm_event event, int mdiff);
|
|
|
|
/**
|
|
* Return array of file descriptors for this port. The fault fd is not
|
|
* included.
|
|
* @param port A port instance
|
|
* @return Array of file descriptors. Unused descriptors are guranteed
|
|
* to be set to -1.
|
|
*/
|
|
struct fdarray *port_fda(struct port *port);
|
|
|
|
/**
|
|
* Return file descriptor of the port.
|
|
* @param port A port instance.
|
|
* @return File descriptor or -1 if not applicable.
|
|
*/
|
|
int port_fault_fd(struct port *port);
|
|
|
|
/**
|
|
* Utility function for setting or resetting a file descriptor timer.
|
|
*
|
|
* This function sets the timer 'fd' to the value M(2^N), where M is
|
|
* the value of the 'scale' parameter and N in the value of the
|
|
* 'log_seconds' parameter.
|
|
*
|
|
* Passing both 'scale' and 'log_seconds' as zero disables the timer.
|
|
*
|
|
* @param fd A file descriptor previously opened with timerfd_create(2).
|
|
* @param scale The multiplicative factor for the timer.
|
|
* @param log_seconds The exponential factor for the timer.
|
|
* @return Zero on success, non-zero otherwise.
|
|
*/
|
|
int set_tmo_log(int fd, unsigned int scale, int log_seconds);
|
|
|
|
/**
|
|
* Utility function for setting a file descriptor timer.
|
|
*
|
|
* This function sets the timer 'fd' to a random value between M * 2^N and
|
|
* (M + S) * 2^N, where M is the value of the 'min' parameter, S is the value
|
|
* of the 'span' parameter, and N in the value of the 'log_seconds' parameter.
|
|
*
|
|
* @param fd A file descriptor previously opened with timerfd_create(2).
|
|
* @param min The minimum value for the timer.
|
|
* @param span The span value for the timer. Must be a positive value.
|
|
* @param log_seconds The exponential factor for the timer.
|
|
* @return Zero on success, non-zero otherwise.
|
|
*/
|
|
int set_tmo_random(int fd, int min, int span, int log_seconds);
|
|
|
|
/**
|
|
* Utility function for setting or resetting a file descriptor timer.
|
|
*
|
|
* This function sets the timer 'fd' to the value of the 'seconds' parameter.
|
|
*
|
|
* Passing 'seconds' as zero disables the timer.
|
|
*
|
|
* @param fd A file descriptor previously opened with timerfd_create(2).
|
|
* @param seconds The timeout value for the timer.
|
|
* @return Zero on success, non-zero otherwise.
|
|
*/
|
|
int set_tmo_lin(int fd, int seconds);
|
|
|
|
/**
|
|
* Sets port's fault file descriptor timer.
|
|
* Passing both 'scale' and 'log_seconds' as zero disables the timer.
|
|
*
|
|
* @param fd A port instance.
|
|
* @param scale The multiplicative factor for the timer.
|
|
* @param log_seconds The exponential factor for the timer.
|
|
* @return Zero on success, non-zero otherwise.
|
|
*/
|
|
int port_set_fault_timer_log(struct port *port,
|
|
unsigned int scale, int log_seconds);
|
|
|
|
/**
|
|
* Sets port's fault file descriptor timer.
|
|
* Passing 'seconds' as zero disables the timer.
|
|
*
|
|
* @param fd A port instance.
|
|
* @param seconds The timeout value for the timer.
|
|
* @return Zero on success, non-zero otherwise.
|
|
*/
|
|
int port_set_fault_timer_lin(struct port *port, int seconds);
|
|
|
|
/**
|
|
* Returns a port's last fault type.
|
|
*
|
|
* @param port A port instance.
|
|
* @return One of the @ref fault_type values.
|
|
*/
|
|
enum fault_type last_fault_type(struct port *port);
|
|
|
|
/**
|
|
* Fills passed in struct fault_interval with the value associated to a
|
|
* port and fault type.
|
|
*
|
|
* @param port A port instance.
|
|
* @param ft Fault type.
|
|
* @param i Pointer to the struct which will be filled in.
|
|
*/
|
|
void fault_interval(struct port *port, enum fault_type ft,
|
|
struct fault_interval *i);
|
|
|
|
/**
|
|
* Release all of the memory in the TC transmit descriptor cache.
|
|
*/
|
|
void tc_cleanup(void);
|
|
|
|
#endif
|