/* tsnClkLib.h - Wind River tsn clock library */

/*
 * Copyright (c) 2017 Wind River Systems, Inc.
 *
 * The right to copy, distribute, modify or otherwise make use
 * of this software may be licensed only pursuant to the terms
 * of an applicable Wind River license agreement.
 */
/*
modification history
--------------------
25jan17,xxy  Init version
*/

#ifndef __INCtsnClkLibh
#define __INCtsnClkLibh

/*
 ****************************************************************************
 * 1                    DESCRIPTION
 ****************************************************************************
 * Public header file of TSN clock.
 */

/*
DESCRIPTION
This library contains the APIs provided by the WindRiver TSN clock.
INCLUDE FILES: base/b_struct_timespec.h
*/

/*
 ****************************************************************************
 * 2                    CONFIGURATION
 ****************************************************************************
 */

/*
 ****************************************************************************
 * 3                    INCLUDE FILES
 ****************************************************************************
 */

/* typedef struct timespec */
#include <base/b_struct_timespec.h>


#ifdef __cplusplus
extern "C" {
#endif

/*
 ****************************************************************************
 * 4                    DEFINES
 ****************************************************************************
 */

/*
 *===========================================================================
 *                         release
 *===========================================================================
 */


#define BILLION         1000000000	/* 1000 million nanoseconds / second */


/*
 ****************************************************************************
 * 5                    TYPES
 ****************************************************************************
 */



/*******************************************************************************
*
* tsnClockIdGet - get a TSN 1588 timer device ID.
*
* This routine get a timer ID using the 1588 clock timer for a timing base.
* It returns a value in <pClockId> that identifies the timer in subsequent timer
* requests
*
* The <timerNo> argument, refer to the 1588 clock device unit,0 or 1
*  The timestamp device can be used independently to get the 1588 clock.
*
* Parameters:
* \is
* \i <pName>
* A pointer to the ethernet device name.
* \i <unit>
* Ethernet device index.
* \i <timerNo>
* 1588 clock timer number(0/1).
* \ie
*
* RETURNS:
* clock id, or 0 (ERROR)
*
* ERRNO:
*
* SEE ALSO: tsnTimerAllocate(), tsnClockConnect(), tsnClockDisable(),
*           tsnClockRateSet(), tsnClockEnable(), tsnTimerRelease()
*
* SYNOPSIS
* clockid_t  tsnClockIdGet
* (
*    char        *pName,
*    int         unit,
*    int         timerNo
* )
*
*
*/

clockid_t  tsnClockIdGet
(
    char        *pName,     /*eth device name */
    int         unit,      /*eth device index */
    int         timerNo       /* 1588 clock timer nuber */
);

/*******************************************************************************
*
* tsnClockTimeGet - get the current time of the tsn clock
*
* This routine is to get the current time of the tsn clock.
*
*
* Parameters:
* \is
* \i <clock_id>
* A value that identifies the timer ID of 1588 timer .
* \i <tp>
* A pointer to store current tsn clock time
* \ie
*
* RETURNS:
* 0 (OK), or -1 (ERROR)
*
* ERRNO:
*
*
* SYNOPSIS
* STATUS tsnClockTimeGet
*     (
*     clockid_t       clock_id,
*     struct timespec * tp
*     )
*
*/

STATUS tsnClockTimeGet
(
    clockid_t       clock_id,   /* clock ID */
    struct timespec    *tp      /* where to store current time */
);

/*******************************************************************************
*
* tsnTimerAllocate - Allocate a TSN 1588 timer.
*
* This routine allocate a timer using the 1588 clock for a timing base, and if 
* it is the first time to use the timer or the timer has been released by 
* tsnTimerRelease(), the timer has to be allocated first by tsnTimerAllocate() 
* before using the timer  
*
*
* Parameters:
* \is
* \i <clock_id>
* A value that identifies the timer ID of 1588 timer .
* \ie
*
* RETURNS:
* 0 (OK), or -1 (ERROR) if the timer has already been allocated or the unit
* number is invalid.
*
* ERRNO:
*
* SEE ALSO: tsnClockConnect(), tsnClockDisable(),tsnClockRateSet(), 
*           tsnClockEnable(), tsnTimerRelease()
*
* SYNOPSIS
* STATUS tsnTimerAllocate
*     (
*     clockid_t       clock_id
*     )
*
*/

STATUS tsnTimerAllocate
(
    clockid_t       clock_id   /* 1588 time clock ID */
);



/*******************************************************************************
*
* tsnTimerRelease - Release a TSN 1588 timer
*
* This routine Release a timer using the 1588 clock for a timing base.When a 
* a timer released, tsnTimerAllocate() need to be callled first before using
* the timer.
*
* Parameters:
* \is
* \i <clock_id>
* A value that identifies the timer ID of 1588 timer .
* \ie
*
* RETURNS:
* 0 (OK), or -1 (ERROR)
*
* ERRNO:
*
* SEE ALSO: tsnTimerAllocate(), tsnClockConnect(), tsnClockDisable(),
*           tsnClockRateSet(), tsnClockEnable()
*
* SYNOPSIS
* STATUS tsnTimerRelease
*     (
*     clockid_t       clock_id
*     )
*
*/


STATUS tsnTimerRelease
(
    clockid_t       clock_id   /* 1588 time clock ID */
);


/*******************************************************************************
*
* tsnClockConnect - connect a routine to the TSN 1588 clock cyclical(ticks)
* or one shot interrupt.
*
* This routine specifies the interrupt service routine to be called at
* each TSN 1588 clock cyclical(tick) or one shot interrupt. It does not 
* enable TSN 1588  clock interrupts. The timer should be first allocated before 
* doing the connection.
*
*
* Parameters:
* \is
* \i <clock_id>
* A value that identifies the timer ID of 1588 timer .
* \i <routine>
* A pointer for the interrupt service routine.
* \i <arg>
* A value for the parameter of interrupt service routine.
* \ie
*
* RETURNS:
* 0 (OK), or -1 (ERROR) 
*
* ERRNO:
*
*
* SYNOPSIS
* STATUS tsnClockConnect
*     (
*     clockid_t       clock_id,
*     FUNCPTR         routine,
*     _Vx_usr_arg_t   arg
*     )
*
*/

STATUS tsnClockConnect
(
    clockid_t       clock_id,   /* clock ID */
    FUNCPTR         routine,    /* routine called at each sys1588 clock interrupt    */
    _Vx_usr_arg_t   arg   /* argument to TSN 1588 clock interrupt routine */
);



/*******************************************************************************
*
* tsnClockDisable - turn off TSN 1588 clock cyclical(ticks) interrupts
*
* This routine disables TSN 1588 clock cyclical(ticks) interrupts.
*
*
* Parameters:
* \is
* \i <clock_id>
* A value that identifies the timer ID of 1588 timer .
* \ie
*
* RETURNS:
* 0 (OK), or -1 (ERROR) 
*
* ERRNO:
*
*
* SYNOPSIS
* STATUS tsnClockDisable
*     (
*     clockid_t       clock_id,
*     )
*
*/

STATUS tsnClockDisable
(
    clockid_t       clock_id   /* clock ID */
);


    
/*******************************************************************************
*
* tsnClockEnable - turn on TSN 1588 clock cyclical or one shot interrupts
*
* This routine enables TSN 1588 clock cyclical or one shot interrupts.
* If the clock rate is set to zero, it enable the one shot time interrupt, 
* otherwise enable cyclical interrupt.
*
* Parameters:
* \is
* \i <clock_id>
* A value that identifies the timer ID of 1588 timer .
* \i <launch>
* A pointer to the absolute time for start of the interrupt set by tsnClockConnect 
* if launch is NULL, start interrup at next second with zero ns
* \ie
*
* RETURNS:
* 0 (OK), or -1 (ERROR)
*
* ERRNO:
*
*
* SYNOPSIS
* STATUS tsnClockEnable
*     (
*     clockid_t       clock_id,
*     struct timespec * launch
*     )
*
*/

STATUS tsnClockEnable
(
    clockid_t       clock_id,   /* clock ID */
    struct timespec * launch   /* the absolute time for start of the interrupt */
);





/*******************************************************************************
*
* tsnClockRateGet - get the TSN 1588 cyclical(ticks) clock rate
*
* This routine returns the interrupt rate of the TSN 1588 cyclical(ticks) clock.
*
*
* Parameters:
* \is
* \i <clock_id>
* A value that identifies the timer ID of 1588 timer to be close.
* \ie
*
* RETURNS:
* ticks Per Second, or -1 (ERROR) 
*
* ERRNO:
*
*
* SYNOPSIS
* STATUS tsnClockRateGet
*     (
*     clockid_t       clock_id,
*     )
*
*/

STATUS tsnClockRateGet
(
    clockid_t       clock_id   /* clock ID */
);




/*******************************************************************************
*
* tsnClockRateSet - set the TSN 1588 cyclical(ticks) clock rate
*
* This routine sets the interrupt rate of the TSN 1588 cyclical clock,It does
* not enable TSN 1588 clock interrupts.If ticksPerSecond is set to be zero,one
* shot interrupt would be generated by calling tsnClockEnable().
*
*
* Parameters:
* \is
* \i <clock_id>
* A value that identifies the timer ID of 1588 timer 
* \i <ticksPerSecond>
* Number of ticks per second,to use one shot interrupt set to be zero
* \ie
*
* RETURNS:
* 0 (OK), or -1 (ERROR)
*
* ERRNO:
*
* SYNOPSIS
* STATUS tsnClockRateSet
*     (
*     clockid_t       clock_id,
*     UINT32 ticksPerSecond
*     )
*
*/

STATUS tsnClockRateSet
(
    clockid_t       clock_id,   /* clock ID */
    UINT32 ticksPerSecond          /* number of clock interrupts per second */
);



#ifdef __cplusplus
}
#endif

#endif

/*
 ****************************************************************************
 *                      END OF FILE
 ****************************************************************************
 */