/* qav_qbv.h - Wind River 802.1Qav and 802.1Qbv library */

/*
 * Copyright (c) 2016-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
--------------------
05sep16,xxy  Init version.
*/

#ifndef __INCqav_qbvh
#define __INCqav_qbvh

/*
 ****************************************************************************
 * 1                    DESCRIPTION
 ****************************************************************************
 * Public header file for 802.1Qav and 802.1Qbv.
 */

/*
DESCRIPTION
This library contains the APIs provided by the Wind River implementation of
802.1Qav and 802.1Qbv.

INCLUDE FILES: qav_qbv.h
*/

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

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

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


#ifdef __cplusplus
extern "C" {
#endif

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

/*
 *===========================================================================
 *                         release
 *===========================================================================
 */
#define QAVQBV_RELEASE 70001

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

/*
 ****************************************************************************
 * 6                   PUBLIC FUNCTIONS
 ****************************************************************************
 */

/*******************************************************************************
*
* tsnQbvTimerCycleCreate - create a QBV timer cycle
*
* This function creates a QBV timer cycle bound to a specific Ethernet physical
* device.
*
*
* Parameters:
* \is
* \i <pName>
* A pointer to the Ethernet device name.
* \i <index>
* Ethernet device index.
* \i <cycleStart>
* A pointer to the absolute time (according to the 1588 clock) when the QBV cycle
* comes into effect. The 1588 clock time can be obtained by calling
* muxIoctl(ethCookie, EIOCG1588SYSTIM, (void *)&ts). If this parameter is
* zero, or less than the current time, the QBV cycle comes into effect
* immediately. If this parameter is a future time, tsnQbvMuxSend() has no effect
* until the cycle starts.
* \i <cycleLen>
* Length of time for the cycle. The units are us.
* \ie
*
* RETURNS: \is
* \i 'cycle ID'
* if successful.
* \i 'ERROR'
* if unsuccessful.
* \ie
*
* ERRNO:
*
*
* SYNOPSIS
* int tsnQbvTimerCycleCreate
*    (
*    char             *pName,
*    int               index,
*    struct timespec  *cycleStart,
*    size_t            cycleLen
*    )
*
*/

int tsnQbvTimerCycleCreate
(
    char * pName,
    int    index,
    struct timespec * cycleStart,
    size_t cycleLen
);

/*******************************************************************************
*
* tsnQbvTimeSlotAdd - add a time slot to the timer cycle of the QBV
*
* This function adds a time slot to the timer cycle of the QBV. cycleId is the
* return value of the tsnQbvTimerCycleCreate( ) function. slotId is a unique,
* user-assigned value.
*
* Parameters:
* \is
* \i <cycleId>
* ID for the cycle. This value is returned by tsnQbvTimerCycleCreate().
* \i <slotId>
* Time slot ID. This value is a unique, user-assigned value.
* \i <slotStart>
* Offset to the start boundary for each cycle. The unit for this offset is us.
* \i <slotLen>
* Length of the time slot. The unit for this length is us.
* \ie
*
* RETURNS: \is
* \i 'OK'
* if successful.
* \i 'ERROR'
* if unsuccessful.
* \ie
*
* ERRNO:
*
*
* SYNOPSIS
* STATUS tsnQbvTimeSlotAdd
*    (
*    int cycleId,
*    int slotId,
*    int slotStart,
*    size_t slotLen
*    )
*/

STATUS tsnQbvTimeSlotAdd
(
    int cycleId,
    int slotId,
    int slotStart,
    size_t slotLen
);

/*******************************************************************************
*
* tsnQbvTimeSlotDelete - delete a time slot from the timer cycle of the QBV
*
* This function deletes a time slot from the timer cycle of the QBV.
*
* Parameters:
* \is
* \i <cycleId>
* ID for the cycle. This value is returned by tsnQbvTimerCycleCreate().
* \i <slotId>
* Time slot ID. This value is the unique, user-assigned value that was passed
* to tsnQbvTimeSlotAdd.
* \ie
*
* RETURNS: \is
* \i 'OK'
* if successful.
* \i 'ERROR'
* if unsuccessful.
* \ie
*
* ERRNO:
*
* SYNOPSIS
* STATUS tsnQbvTimeSlotDelete
*    (
*    int cycleId,
*    int slotId
*    )
*
*/


STATUS tsnQbvTimeSlotDelete
(
    int  cycleId,
    int  slotId
);

/*******************************************************************************
*
* tsnQbvMuxSend - send an Ethernet packet by TSN QBV mux
*
* This function sends an Ethernet packet by TSN QBV mux. The cycleId is the
* return value of the tsnQbvTimerCycleCreate( ) function. The cycleOffset is
* the number of additional cycles to be added to the current running cycles.
* If the cycleOffset is zero, the TSN-scheduled send is launched in the next
* cycle adjacent to the current running cycle. The cycleOffset is used to
* ensure that the TSN-scheduled send is launched in a future time. Because
* it is limited by the NIC, the value of cycleOffset should not be a large
* value. For example, the Intel I210 chip can only hold launch time for a
* maximum of 0.5 seconds. Therefore, the value of cycleOffset is calculated
* as follows: (cycleOffset * cycleLen) < 500 ms. slotDelay is the time added
* to the start time of the slot. slotDelay is used to keep the order for
* multiple packets in the same slot. slotId is the parameter passed to
* tsnQbvTimeSlotAdd(). When calling tsnQbvMuxSend(), slotId must reuse the
* value that was previously passed to tsnQbvTimeSlotAdd().
*
*
* Parameters:
* \is
* \i <cycleId>
* ID for the cycle. This value is returned by tsnQbvTimerCycleCreate().
* \i <cycleOffset>
* The number of additional cycles to be added to the current running cycles.
* \i <slotId>
* Time slot ID. This value is the unique, user-assigned value that was passed
* to tsnQbvTimeSlotAdd.
* \i <slotDelay>
* The time added to the start time of the slot. slotDelay is used to keep the
* order for multiple packets in the same slot. The units are ns.
* \i <trafficType>
* trafficType :    0 Time-Aware(TSN-scheduled)
*                  1 Credit-based A(not TSN-scheduled)
*                  2 Credit-based B(not TSN-scheduled)
*                  3 Prioritized(not TSN-scheduled)
*                  4 Best-Effort(not TSN-scheduled)
* \i <buf>
* A pointer to the buffer to be sent.
* \i <len>
* Length of the buffer. The units are bytes.
* \ie
*
* RETURNS: \is
* \i 'OK'
* if successful.
* \i 'ERROR'
* if unsuccessful.
* \ie
*
* ERRNO:
*
* SYNOPSIS
* STATUS tsnQbvMuxSend
*    (
*    int      cycleId,
*    int      cycleOffset,
*    int      slotId,
*    int      slotDelay,
*    int      trafficType,
*    const void *buf,
*    size_t   len
*    )
*
*/


STATUS tsnQbvMuxSend
(
    int    cycleId,
    int    cycleOffset,
    int    slotId,
    int    slotDelay,
    int    trafficType,
    const void *buf,
    size_t len
);

#ifdef __cplusplus
}
#endif

#endif

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