ixtimesyncacc.h

Uboot源码,非常通用的bootloader.适用于各种平台的Linux系统引导.

/**
 * @file IxTimeSyncAcc.h
 *
 * @author Intel Corporation
 * @date 07 May 2004
 *
 * @brief  Header file for IXP400 Access Layer to IEEE 1588(TM) Precision
 * Clock Synchronisation Protocol Hardware Assist
 *
 * @version 1
 *
 * @par
 * IXP400 SW Release version 2.0
 * 
 * -- Copyright Notice --
 * 
 * @par
 * Copyright 2001-2005, Intel Corporation.
 * All rights reserved.
 * 
 * @par
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 * 3. Neither the name of the Intel Corporation nor the names of its contributors
 *    may be used to endorse or promote products derived from this software
 *    without specific prior written permission.
 * 
 * @par
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS''
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 * SUCH DAMAGE.
 * 
 * @par
 * -- End of Copyright Notice --
 */

/**
 * @defgroup IxTimeSyncAcc IXP400 Time Sync Access Component API 
 *
 * @brief Public API for IxTimeSyncAcc
 *
 * @{
 */
#ifndef IXTIMESYNCACC_H
#define IXTIMESYNCACC_H

#ifdef  __ixp46X

#include "IxOsal.h"

/**
 * Section for enum
 */

/**
 * @ingroup IxTimeSyncAcc
 * 
 * @enum IxTimeSyncAccStatus
 *
 * @brief The status as returned from the API
 */
typedef enum /**< IxTimeSyncAccStatus */
{
    IX_TIMESYNCACC_SUCCESS = IX_SUCCESS,    /**< Requested operation successful */
    IX_TIMESYNCACC_INVALIDPARAM,            /**< An invalid parameter was passed */
    IX_TIMESYNCACC_NOTIMESTAMP,             /**< While polling no time stamp available */
    IX_TIMESYNCACC_INTERRUPTMODEINUSE,      /**< Polling not allowed while operating in interrupt mode */
    IX_TIMESYNCACC_FAILED                   /**< Internal error occurred */
}IxTimeSyncAccStatus;

/**
 * @ingroup IxTimeSyncAcc
 * 
 * @enum IxTimeSyncAccAuxMode
 *
 * @brief Master or Slave Auxiliary Time Stamp (Snap Shot)
 */
typedef enum /**< IxTimeSyncAccAuxMode */
{
    IX_TIMESYNCACC_AUXMODE_MASTER,          /**< Auxiliary Master Mode */
    IX_TIMESYNCACC_AUXMODE_SLAVE,           /**< Auxiliary Slave Mode */
    IX_TIMESYNCACC_AUXMODE_INVALID          /**< Invalid Auxiliary Mode */
}IxTimeSyncAccAuxMode;

/**
 * @ingroup IxTimeSyncAcc
 * 
 * @enum IxTimeSyncAcc1588PTPPort
 *
 * @brief IEEE 1588 PTP Communication Port(Channel)
 */
typedef enum /**< IxTimeSyncAcc1588PTPPort */
{
    IX_TIMESYNCACC_NPE_A_1588PTP_PORT,      /**< PTP Communication Port on NPE-A */
    IX_TIMESYNCACC_NPE_B_1588PTP_PORT,      /**< PTP Communication Port on NPE-B */
    IX_TIMESYNCACC_NPE_C_1588PTP_PORT,      /**< PTP Communication Port on NPE-C */
    IX_TIMESYNCACC_NPE_1588PORT_INVALID     /**< Invalid PTP Communication Port */
} IxTimeSyncAcc1588PTPPort;

/**
 * @ingroup IxTimeSyncAcc
 * 
 * @enum IxTimeSyncAcc1588PTPPortMode
 *
 * @brief Master or Slave mode for IEEE 1588 PTP Communication Port
 */
typedef enum  /**< IxTimeSyncAcc1588PTPPortMode */
{
    IX_TIMESYNCACC_1588PTP_PORT_MASTER,       /**< PTP Communication Port in Master Mode */
    IX_TIMESYNCACC_1588PTP_PORT_SLAVE,        /**< PTP Communication Port in Slave Mode */
    IX_TIMESYNCACC_1588PTP_PORT_ANYMODE,      /**< PTP Communication Port in ANY Mode
                                                  allows time stamping of all messages
                                                  including non-1588 PTP */
    IX_TIMESYNCACC_1588PTP_PORT_MODE_INVALID  /**< Invalid PTP Port Mode */
}IxTimeSyncAcc1588PTPPortMode;

/**
 * @ingroup IxTimeSyncAcc
 * 
 * @enum IxTimeSyncAcc1588PTPMsgType
 *
 * @brief 1588 PTP Messages types that can be detected on communication port
 *
 * Note that client code can determine this based on master/slave mode in which
 * it is already operating in and this information is made available for the sake
 * of convenience only.
 */
typedef enum  /**< IxTimeSyncAcc1588PTPMsgType */
{
    IX_TIMESYNCACC_1588PTP_MSGTYPE_SYNC,     /**< PTP Sync message sent by Master or received by Slave */
    IX_TIMESYNCACC_1588PTP_MSGTYPE_DELAYREQ, /**< PTP Delay_Req message sent by Slave or received by Master */
    IX_TIMESYNCACC_1588PTP_MSGTYPE_UNKNOWN   /**< Other PTP and non-PTP message sent or received by both
                                                Master and/or Slave */
} IxTimeSyncAcc1588PTPMsgType;

/**
 * Section for struct
 */

/**
 * @ingroup IxTimeSyncAcc
 *
 * @struct IxTimeSyncAccTimeValue
 *
 * @brief Struct to hold 64 bit SystemTime and TimeStamp values
 */
typedef struct  /**< IxTimeSyncAccTimeValue */
{
    UINT32 timeValueLowWord;               /**< Lower 32 bits of the time value */
    UINT32 timeValueHighWord;              /**< Upper 32 bits of the time value */  
} IxTimeSyncAccTimeValue;

/**
 * @ingroup IxTimeSyncAcc
 *
 * @struct IxTimeSyncAccUuid
 *
 * @brief Struct to hold 48 bit UUID values captured in Sync or Delay_Req messages
 */
typedef struct  /**< IxTimeSyncAccUuid */
{
    UINT32 uuidValueLowWord;               /**<The lower 32 bits of the UUID */
    UINT16 uuidValueHighHalfword;          /**<The upper 16 bits of the UUID */  
} IxTimeSyncAccUuid;

/**
 * @ingroup IxTimeSyncAcc
 *
 * @struct IxTimeSyncAccPtpMsgData
 *
 * @brief Struct for data from the PTP message returned when TimeStamp available
 */
typedef struct  /**< IxTimeSyncAccPtpMsgData */
{
    IxTimeSyncAcc1588PTPMsgType ptpMsgType; /**< PTP Messages type */
    IxTimeSyncAccTimeValue ptpTimeStamp;    /**< 64 bit TimeStamp value from PTP Message */
    IxTimeSyncAccUuid ptpUuid;              /**< 48 bit UUID value from the PTP Message */
    UINT16 ptpSequenceNumber;               /**< 16 bit Sequence Number from PTP Message */
} IxTimeSyncAccPtpMsgData;

/**
 * @ingroup IxTimeSyncAcc
 *
 * @struct IxTimeSyncAccStats
 *
 * @brief Statistics for the PTP messages
 */
typedef struct  /**< IxTimeSyncAccStats */
{
    UINT32 rxMsgs; /**< Count of timestamps for received PTP Messages */
    UINT32 txMsgs; /**< Count of timestamps for transmitted PTP Messages */
} IxTimeSyncAccStats;

/**
 * @ingroup IxTimeSyncAcc
 *
 * @typedef IxTimeSyncAccTargetTimeCallback
 *
 * @brief Callback for use by target time stamp interrupt
 */
typedef void (*IxTimeSyncAccTargetTimeCallback)(IxTimeSyncAccTimeValue targetTime);

/**
 * @ingroup IxTimeSyncAcc
 *
 * @typedef IxTimeSyncAccAuxTimeCallback
 *
 * @brief Callback for use by auxiliary time interrupts
 */
typedef void (*IxTimeSyncAccAuxTimeCallback)(IxTimeSyncAccAuxMode auxMode,
             IxTimeSyncAccTimeValue auxTime);

/*
 * Section for prototypes interface functions
 */

/**
 * @ingroup IxTimeSyncAcc
 * 
 * @fn IxTimeSyncAccStatus ixTimeSyncAccPTPPortConfigSet(
                               IxTimeSyncAcc1588PTPPort ptpPort,
                               IxTimeSyncAcc1588PTPPortMode ptpPortMode)
 *
 * @brief Configures the IEEE 1588 message detect on particular PTP port.
 *
 * @param ptpPort [in] - PTP port to config
 * @param ptpPortMode [in]- Port to operate in Master or Slave mode
 *
 * This API will enable the time stamping on a particular PTP port.
 *          
 * @li Re-entrant   : No
 * @li ISR Callable : No
 * 
 * @return @li IX_TIMESYNCACC_SUCCESS - Operation is successful
 *         @li IX_TIMESYNCACC_INVALIDPARAM - Invalid parameters passed
 *         @li IX_TIMESYNCACC_FAILED - Internal error occurred
 */
PUBLIC IxTimeSyncAccStatus
ixTimeSyncAccPTPPortConfigSet(IxTimeSyncAcc1588PTPPort ptpPort,
       IxTimeSyncAcc1588PTPPortMode ptpPortMode);

/**
 * @ingroup IxTimeSyncAcc
 * 
 * @fn IxTimeSyncAccStatus ixTimeSyncAccPTPPortConfigGet(
                               IxTimeSyncAcc1588PTPPort ptpPort,
                               IxTimeSyncAcc1588PTPPortMode *ptpPortMode)
 *
 * @brief Retrieves IEEE 1588 PTP operation mode on particular PTP port.
 *
 * @param ptpPort [in] - PTP port
 * @param ptpPortMode [in]- Mode of operation of PTP port (Master or Slave)
 *
 * This API will identify the time stamping capability of a PTP port by means
 * of obtaining its mode of operation.
 *          
 * @li Re-entrant   : No
 * @li ISR Callable : No
 * 
 * @return @li IX_TIMESYNCACC_SUCCESS - Operation is successful
 *         @li IX_TIMESYNCACC_INVALIDPARAM - Invalid parameters passed
 *         @li IX_TIMESYNCACC_FAILED - Internal error occurred
 */
PUBLIC IxTimeSyncAccStatus
ixTimeSyncAccPTPPortConfigGet(IxTimeSyncAcc1588PTPPort ptpPort,
    IxTimeSyncAcc1588PTPPortMode *ptpPortMode);

/**
 * @ingroup IxTimeSyncAcc
 * 
 * @fn IxTimeSyncAccStatus ixTimeSyncAccPTPRxPoll(
                               IxTimeSyncAcc1588PTPPort ptpPort,
                               IxTimeSyncAccPtpMsgData  *ptpMsgData)
 *
 * @brief Polls the IEEE 1588 message/time stamp detect status on a particular 
 * PTP Port on the Receive side.
 *
 * @param ptpPort [in] - PTP port to poll
 * @param ptpMsgData [out] - Current TimeStamp and other Data
 *
 * This API will poll for the availability of a time stamp on the received Sync 
 * (Slave) or Delay_Req (Master) messages.
 * The client application will provide the buffer.
 *              
 * @li Re-entrant   : No
 * @li ISR Callable : No
 * 
 * @return @li IX_TIMESYNCACC_SUCCESS - Operation is successful
 *         @li IX_TIMESYNCACC_INVALIDPARAM - Invalid parameters passed
 *         @li IX_TIMESYNCACC_NOTIMESTAMP - No time stamp available
 *         @li IX_TIMESYNCACC_FAILED - Internal error occurred
 */
PUBLIC IxTimeSyncAccStatus
ixTimeSyncAccPTPRxPoll(IxTimeSyncAcc1588PTPPort ptpPort,
    IxTimeSyncAccPtpMsgData  *ptpMsgData);

/**
 * @ingroup IxTimeSyncAcc
 * 
 * @fn IxTimeSyncAccStatus ixTimeSyncAccPTPTxPoll(
                               IxTimeSyncAcc1588PTPPort ptpPort,
                               IxTimeSyncAccPtpMsgData  *ptpMsgData)
 *
 *
 * @brief Polls the IEEE 1588 message/time stamp detect status on a particular 
 * PTP Port on the Transmit side.
 *
 * @param ptpPort [in] - PTP port to poll
 * @param ptpMsgData [out] - Current TimeStamp and other Data
 *                        
 * This API will poll for the availability of a time stamp on the transmitted
 * Sync (Master) or Delay_Req (Slave) messages.
 * The client application will provide the buffer.
 *              
 * @li Re-entrant   : No
 * @li ISR Callable : No
 * 
 * @return @li IX_TIMESYNCACC_SUCCESS - Operation is successful
 *         @li IX_TIMESYNCACC_INVALIDPARAM - Invalid parameters passed
 *         @li IX_TIMESYNCACC_NOTIMESTAMP - No time stamp available
 *         @li IX_TIMESYNCACC_FAILED - Internal error occurred
 */
PUBLIC IxTimeSyncAccStatus
ixTimeSyncAccPTPTxPoll(IxTimeSyncAcc1588PTPPort ptpPort,
    IxTimeSyncAccPtpMsgData  *ptpMsgData);

/**
 * @ingroup IxTimeSyncAcc
 * 
 * @fn IxTimeSyncAccStatus ixTimeSyncAccSystemTimeSet(
                               IxTimeSyncAccTimeValue systemTime)
 *
 * @brief Sets the System Time in the IEEE 1588 hardware assist block
 *
 * @param systemTime [in] - Value to set System Time
 *                        
 * This API will set the SystemTime to given value.
 *              
 * @li Re-entrant   : yes
 * @li ISR Callable : no
 * 
 * @return @li IX_TIMESYNCACC_SUCCESS - Operation is successful
 *         @li IX_TIMESYNCACC_FAILED - Internal error occurred
 */
PUBLIC IxTimeSyncAccStatus
ixTimeSyncAccSystemTimeSet(IxTimeSyncAccTimeValue systemTime);

/**
 * @ingroup IxTimeSyncAcc
 * 
 * @fn IxTimeSyncAccStatus ixTimeSyncAccSystemTimeGet(
                               IxTimeSyncAccTimeValue *systemTime)
 *
 * @brief Gets the System Time from the IEEE 1588 hardware assist block
 *
 * @param systemTime [out] - Copy the current System Time into the client 
 * application provided buffer
 *
 * This API will get the SystemTime from IEEE1588 block and return to client
 *      
 * @li Re-entrant   : no
 * @li ISR Callable : no
 * 
 * @return @li IX_TIMESYNCACC_SUCCESS - Operation is successful
 *         @li IX_TIMESYNCACC_INVALIDPARAM - Invalid parameters passed
 *         @li IX_TIMESYNCACC_FAILED - Internal error occurred
 */
PUBLIC IxTimeSyncAccStatus
ixTimeSyncAccSystemTimeGet(IxTimeSyncAccTimeValue *systemTime);

/**
 * @ingroup IxTimeSyncAcc
 * 
 * @fn IxTimeSyncAccStatus ixTimeSyncAccTickRateSet(
                               UINT32 tickRate)
 *
 * @brief Sets the Tick Rate (Frequency Scaling Value) in the IEEE 1588
 * hardware assist block