xref: /freebsd-11.0-release/sys/contrib/ncsw/inc/Peripherals/fm_rtc_ext.h

/* Copyright (c) 2008-2011 Freescale Semiconductor, Inc.
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *     * Redistributions of source code must retain the above copyright
 *       notice, this list of conditions and the following disclaimer.
 *     * 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.
 *     * Neither the name of Freescale Semiconductor nor the
 *       names of its contributors may be used to endorse or promote products
 *       derived from this software without specific prior written permission.
 *
 *
 * ALTERNATIVELY, this software may be distributed under the terms of the
 * GNU General Public License ("GPL") as published by the Free Software
 * Foundation, either version 2 of that License or (at your option) any
 * later version.
 *
 * THIS SOFTWARE IS PROVIDED BY Freescale Semiconductor ``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 Freescale Semiconductor 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.
 */

/**************************************************************************//**
 @File          fm_rtc_ext.h

 @Description   External definitions and API for FM RTC IEEE1588 Timer Module.

 @Cautions      None.
*//***************************************************************************/

#ifndef __FM_RTC_EXT_H__
#define __FM_RTC_EXT_H__


#include "error_ext.h"
#include "std_ext.h"


/**************************************************************************//**

 @Group         FM_grp Frame Manager API

 @Description   FM API functions, definitions and enums

 @{
*//***************************************************************************/

/**************************************************************************//**
 @Group         fm_rtc_grp FM RTC

 @Description   FM RTC functions, definitions and enums.

 @{
*//***************************************************************************/

/**************************************************************************//**
 @Group         fm_rtc_init_grp FM RTC Initialization Unit

 @Description   FM RTC initialization API.

 @{
*//***************************************************************************/

/**************************************************************************//**
 @Description   FM RTC Alarm Polarity Options.
*//***************************************************************************/
typedef enum e_FmRtcAlarmPolarity
{
    e_FM_RTC_ALARM_POLARITY_ACTIVE_HIGH,    /**< Active-high output polarity */
    e_FM_RTC_ALARM_POLARITY_ACTIVE_LOW      /**< Active-low output polarity */
} e_FmRtcAlarmPolarity;

/**************************************************************************//**
 @Description   FM RTC Trigger Polarity Options.
*//***************************************************************************/
typedef enum e_FmRtcTriggerPolarity
{
    e_FM_RTC_TRIGGER_ON_RISING_EDGE,    /**< Trigger on rising edge */
    e_FM_RTC_TRIGGER_ON_FALLING_EDGE    /**< Trigger on falling edge */
} e_FmRtcTriggerPolarity;

/**************************************************************************//**
 @Description   IEEE1588 Timer Module FM RTC Optional Clock Sources.
*//***************************************************************************/
typedef enum e_FmSrcClock
{
    e_FM_RTC_SOURCE_CLOCK_EXTERNAL,  /**< external high precision timer reference clock */
    e_FM_RTC_SOURCE_CLOCK_SYSTEM,    /**< MAC system clock */
    e_FM_RTC_SOURCE_CLOCK_OSCILATOR  /**< RTC clock oscilator */
}e_FmSrcClk;

/**************************************************************************//**
 @Description   FM RTC configuration parameters structure.

                This structure should be passed to FM_RTC_Config().
*//***************************************************************************/
typedef struct t_FmRtcParams
{
    t_Handle                 h_Fm;               /**< FM Handle*/
    uintptr_t                baseAddress;        /**< Base address of FM RTC registers */
    t_Handle                 h_App;              /**< A handle to an application layer object; This handle will
                                                      be passed by the driver upon calling the above callbacks */
} t_FmRtcParams;


/**************************************************************************//**
 @Function      FM_RTC_Config

 @Description   Configures the FM RTC module according to user's parameters.

                The driver assigns default values to some FM RTC parameters.
                These parameters can be overwritten using the advanced
                configuration routines.

 @Param[in]     p_FmRtcParam    - FM RTC configuration parameters.

 @Return        Handle to the new FM RTC object; NULL pointer on failure.

 @Cautions      None
*//***************************************************************************/
t_Handle FM_RTC_Config(t_FmRtcParams *p_FmRtcParam);

/**************************************************************************//**
 @Function      FM_RTC_Init

 @Description   Initializes the FM RTC driver and hardware.

 @Param[in]     h_FmRtc - Handle to FM RTC object.

 @Return        E_OK on success; Error code otherwise.

 @Cautions      h_FmRtc must have been previously created using FM_RTC_Config().
*//***************************************************************************/
t_Error FM_RTC_Init(t_Handle h_FmRtc);

/**************************************************************************//**
 @Function      FM_RTC_Free

 @Description   Frees the FM RTC object and all allocated resources.

 @Param[in]     h_FmRtc - Handle to FM RTC object.

 @Return        E_OK on success; Error code otherwise.

 @Cautions      h_FmRtc must have been previously created using FM_RTC_Config().
*//***************************************************************************/
t_Error FM_RTC_Free(t_Handle h_FmRtc);


/**************************************************************************//**
 @Group         fm_rtc_adv_config_grp  FM RTC Advanced Configuration Unit

 @Description   FM RTC advanced configuration functions.

 @{
*//***************************************************************************/

/**************************************************************************//**
 @Function      FM_RTC_ConfigPeriod

 @Description   Configures the period of the timestamp if different than
                default [1000].

 @Param[in]     h_FmRtc         - Handle to FM RTC object.
 @Param[in]     period          - Period in nano-seconds.

 @Return        E_OK on success; Error code otherwise.

 @Cautions      h_FmRtc must have been previously created using FM_RTC_Config().
*//***************************************************************************/
t_Error FM_RTC_ConfigPeriod(t_Handle h_FmRtc, uint32_t period);

/**************************************************************************//**
 @Function      FM_RTC_ConfigSourceClock

 @Description   Configures the source clock of the RTC.

 @Param[in]     h_FmRtc         - Handle to FM RTC object.
 @Param[in]     srcClk          - Source clock selection.
 @Param[in]     freqInMhz       - the source-clock frequency (in MHz).

 @Return        E_OK on success; Error code otherwise.

 @Cautions      h_FmRtc must have been previously created using FM_RTC_Config().
*//***************************************************************************/
t_Error FM_RTC_ConfigSourceClock(t_Handle      h_FmRtc,
                                 e_FmSrcClk    srcClk,
                                 uint32_t      freqInMhz);

/**************************************************************************//**
 @Function      FM_RTC_ConfigPulseRealignment

 @Description   Configures the RTC to automatic FIPER pulse realignment in
                response to timer adjustments [FALSE]

                In this mode, the RTC clock is identical to the source clock.
                This feature can be useful when the system contains an external
                RTC with inherent frequency compensation.

 @Param[in]     h_FmRtc     - Handle to FM RTC object.
 @Param[in]     enable      - TRUE to enable automatic realignment.

 @Return        E_OK on success; Error code otherwise.

 @Cautions      h_FmRtc must have been previously created using FM_RTC_Config().
*//***************************************************************************/
t_Error FM_RTC_ConfigPulseRealignment(t_Handle h_FmRtc, bool enable);

/**************************************************************************//**
 @Function      FM_RTC_ConfigFrequencyBypass

 @Description   Configures the RTC to bypass the frequency compensation
                mechanism. [FALSE]

                In this mode, the RTC clock is identical to the source clock.
                This feature can be useful when the system contains an external
                RTC with inherent frequency compensation.

 @Param[in]     h_FmRtc     - Handle to FM RTC object.
 @Param[in]     enabled     - TRUE to bypass frequency compensation;
                              FALSE otherwise.

 @Return        E_OK on success; Error code otherwise.

 @Cautions      h_FmRtc must have been previously created using FM_RTC_Config().
*//***************************************************************************/
t_Error FM_RTC_ConfigFrequencyBypass(t_Handle h_FmRtc, bool enabled);

/**************************************************************************//**
 @Function      FM_RTC_ConfigInvertedInputClockPhase

 @Description   Configures the RTC to invert the source clock phase on input.
                [FALSE]

 @Param[in]     h_FmRtc  - Handle to FM RTC object.
 @Param[in]     inverted    - TRUE to invert the source clock phase on input.
                              FALSE otherwise.

 @Return        E_OK on success; Error code otherwise.

 @Cautions      h_FmRtc must have been previously created using FM_RTC_Config().
*//***************************************************************************/
t_Error FM_RTC_ConfigInvertedInputClockPhase(t_Handle h_FmRtc, bool inverted);

/**************************************************************************//**
 @Function      FM_RTC_ConfigInvertedOutputClockPhase

 @Description   Configures the RTC to invert the output clock phase.
                [FALSE]

 @Param[in]     h_FmRtc  - Handle to FM RTC object.
 @Param[in]     inverted    - TRUE to invert the output clock phase.
                              FALSE otherwise.

 @Return        E_OK on success; Error code otherwise.

 @Cautions      h_FmRtc must have been previously created using FM_RTC_Config().
*//***************************************************************************/
t_Error FM_RTC_ConfigInvertedOutputClockPhase(t_Handle h_FmRtc, bool inverted);

/**************************************************************************//**
 @Function      FM_RTC_ConfigOutputClockDivisor

 @Description   Configures the divisor for generating the output clock from
                the RTC clock. [0x00000002]

 @Param[in]     h_FmRtc  - Handle to FM RTC object.
 @Param[in]     divisor     - Divisor for generation of the output clock.

 @Return        E_OK on success; Error code otherwise.

 @Cautions      h_FmRtc must have been previously created using FM_RTC_Config().
*//***************************************************************************/
t_Error FM_RTC_ConfigOutputClockDivisor(t_Handle h_FmRtc, uint16_t divisor);

/**************************************************************************//**
 @Function      FM_RTC_ConfigAlarmPolarity

 @Description   Configures the polarity (active-high/active-low) of a specific
                alarm signal. [e_FM_RTC_ALARM_POLARITY_ACTIVE_HIGH]

 @Param[in]     h_FmRtc      - Handle to FM RTC object.
 @Param[in]     alarmId         - Alarm ID.
 @Param[in]     alarmPolarity   - Alarm polarity.

 @Return        E_OK on success; Error code otherwise.

 @Cautions      h_FmRtc must have been previously created using FM_RTC_Config().
*//***************************************************************************/
t_Error FM_RTC_ConfigAlarmPolarity(t_Handle             h_FmRtc,
                                   uint8_t              alarmId,
                                   e_FmRtcAlarmPolarity alarmPolarity);

/**************************************************************************//**
 @Function      FM_RTC_ConfigExternalTriggerPolarity

 @Description   Configures the polarity (rising/falling edge) of a specific
                external trigger signal. [e_FM_RTC_TRIGGER_ON_FALLING_EDGE]

 @Param[in]     h_FmRtc      - Handle to FM RTC object.
 @Param[in]     triggerId       - Trigger ID.
 @Param[in]     triggerPolarity - Trigger polarity.

 @Return        E_OK on success; Error code otherwise.

 @Cautions      h_FmRtc must have been previously created using FM_RTC_Config().
*//***************************************************************************/
t_Error FM_RTC_ConfigExternalTriggerPolarity(t_Handle               h_FmRtc,
                                             uint8_t                triggerId,
                                             e_FmRtcTriggerPolarity triggerPolarity);

/** @} */ /* end of fm_rtc_adv_config_grp */
/** @} */ /* end of fm_rtc_init_grp */


/**************************************************************************//**
 @Group         fm_rtc_control_grp FM RTC Control Unit

 @Description   FM RTC runtime control API.

 @{
*//***************************************************************************/

/**************************************************************************//**
 @Function      t_FmRtcExceptionsCallback

 @Description   Exceptions user callback routine, used for RTC different mechanisms.

 @Param[in]     h_App       - User's application descriptor.
 @Param[in]     id          - source id.
*//***************************************************************************/
typedef void (t_FmRtcExceptionsCallback) ( t_Handle  h_App, uint8_t id);

/**************************************************************************//**
 @Description   FM RTC alarm parameters.
*//***************************************************************************/
typedef struct t_FmRtcAlarmParams {
    uint8_t                     alarmId;            /**< 0 or 1 */
    uint64_t                    alarmTime;          /**< In nanoseconds, the time when the alarm
                                                         should go off - must be a multiple of
                                                         the RTC period */
    t_FmRtcExceptionsCallback   *f_AlarmCallback;   /**< This routine will be called when RTC
                                                         reaches alarmTime */
    bool                        clearOnExpiration;  /**< TRUE to turn off the alarm once expired. */
} t_FmRtcAlarmParams;

/**************************************************************************//**
 @Description   FM RTC Periodic Pulse parameters.
*//***************************************************************************/
typedef struct t_FmRtcPeriodicPulseParams {
    uint8_t                     periodicPulseId;            /**< 0 or 1 */
    uint64_t                    periodicPulsePeriod;        /**< In Nanoseconds. Must be
                                                                 a multiple of the RTC period */
    t_FmRtcExceptionsCallback   *f_PeriodicPulseCallback;   /**< This routine will be called every
                                                                 periodicPulsePeriod. */
} t_FmRtcPeriodicPulseParams;

/**************************************************************************//**
 @Description   FM RTC Periodic Pulse parameters.
*//***************************************************************************/
typedef struct t_FmRtcExternalTriggerParams {
    uint8_t                     externalTriggerId;              /**< 0 or 1 */
    bool                        usePulseAsInput;                /**< Use the pulse interrupt instead of
                                                                     an external signal */
    t_FmRtcExceptionsCallback   *f_ExternalTriggerCallback;     /**< This routine will be called every
                                                                     periodicPulsePeriod. */
} t_FmRtcExternalTriggerParams;


/**************************************************************************//**
 @Function      FM_RTC_Enable

 @Description   Enable the RTC (time count is started).

                The user can select to resume the time count from previous
                point, or to restart the time count.

 @Param[in]     h_FmRtc     - Handle to FM RTC object.
 @Param[in]     resetClock  - Restart the time count from zero.

 @Return        E_OK on success; Error code otherwise.

 @Cautions      h_FmRtc must have been previously initialized using FM_RTC_Init().
*//***************************************************************************/
t_Error FM_RTC_Enable(t_Handle h_FmRtc, bool resetClock);

/**************************************************************************//**
 @Function      FM_RTC_Disable

 @Description   Disables the RTC (time count is stopped).

 @Param[in]     h_FmRtc - Handle to FM RTC object.

 @Return        E_OK on success; Error code otherwise.

 @Cautions      h_FmRtc must have been previously initialized using FM_RTC_Init().
*//***************************************************************************/
t_Error FM_RTC_Disable(t_Handle h_FmRtc);

/**************************************************************************//**
 @Function      FM_RTC_SetClockOffset

 @Description   Sets the clock offset (usually relative to another clock).

                The user can pass a negative offset value.

 @Param[in]     h_FmRtc  - Handle to FM RTC object.
 @Param[in]     offset   - New clock offset (in nanoseconds).

 @Return        E_OK on success; Error code otherwise.

 @Cautions      h_FmRtc must have been previously initialized using FM_RTC_Init().
*//***************************************************************************/
t_Error FM_RTC_SetClockOffset(t_Handle h_FmRtc, int64_t offset);

/**************************************************************************//**
 @Function      FM_RTC_SetAlarm

 @Description   Schedules an alarm event to a given RTC time.

 @Param[in]     h_FmRtc             - Handle to FM RTC object.
 @Param[in]     p_FmRtcAlarmParams  - Alarm parameters.

 @Return        E_OK on success; Error code otherwise.

 @Cautions      h_FmRtc must have been previously initialized using FM_RTC_Init().
                Must be called only prior to FM_RTC_Enable().
*//***************************************************************************/
t_Error FM_RTC_SetAlarm(t_Handle h_FmRtc, t_FmRtcAlarmParams *p_FmRtcAlarmParams);

/**************************************************************************//**
 @Function      FM_RTC_SetPeriodicPulse

 @Description   Sets a periodic pulse.

 @Param[in]     h_FmRtc                         - Handle to FM RTC object.
 @Param[in]     p_FmRtcPeriodicPulseParams      - Periodic pulse parameters.

 @Return        E_OK on success; Error code otherwise.

 @Cautions      h_FmRtc must have been previously initialized using FM_RTC_Init().
                Must be called only prior to FM_RTC_Enable().
*//***************************************************************************/
t_Error FM_RTC_SetPeriodicPulse(t_Handle h_FmRtc, t_FmRtcPeriodicPulseParams *p_FmRtcPeriodicPulseParams);

/**************************************************************************//**
 @Function      FM_RTC_ClearPeriodicPulse

 @Description   Clears a periodic pulse.

 @Param[in]     h_FmRtc                         - Handle to FM RTC object.
 @Param[in]     periodicPulseId                 - Periodic pulse id.

 @Return        E_OK on success; Error code otherwise.

 @Cautions      h_FmRtc must have been previously initialized using FM_RTC_Init().
*//***************************************************************************/
t_Error FM_RTC_ClearPeriodicPulse(t_Handle h_FmRtc, uint8_t periodicPulseId);

/**************************************************************************//**
 @Function      FM_RTC_SetExternalTrigger

 @Description   Sets an external trigger indication and define a callback
                routine to be called on such event.

 @Param[in]     h_FmRtc                         - Handle to FM RTC object.
 @Param[in]     p_FmRtcExternalTriggerParams    - External Trigger parameters.

 @Return        E_OK on success; Error code otherwise.

 @Cautions      h_FmRtc must have been previously initialized using FM_RTC_Init().
*//***************************************************************************/
t_Error FM_RTC_SetExternalTrigger(t_Handle h_FmRtc, t_FmRtcExternalTriggerParams *p_FmRtcExternalTriggerParams);

/**************************************************************************//**
 @Function      FM_RTC_ClearExternalTrigger

 @Description   Clears external trigger indication.

 @Param[in]     h_FmRtc                         - Handle to FM RTC object.
 @Param[in]     id                              - External Trigger id.

 @Return        E_OK on success; Error code otherwise.

 @Cautions      h_FmRtc must have been previously initialized using FM_RTC_Init().
*//***************************************************************************/
t_Error FM_RTC_ClearExternalTrigger(t_Handle h_FmRtc, uint8_t id);

/**************************************************************************//**
 @Function      FM_RTC_GetExternalTriggerTimeStamp

 @Description   Reads the External Trigger TimeStamp.

 @Param[in]     h_FmRtc                 - Handle to FM RTC object.
 @Param[in]     triggerId               - External Trigger id.
 @Param[out]    p_TimeStamp             - External Trigger timestamp (in nanoseconds).

 @Return        E_OK on success; Error code otherwise.

 @Cautions      h_FmRtc must have been previously initialized using FM_RTC_Init().
*//***************************************************************************/
t_Error FM_RTC_GetExternalTriggerTimeStamp(t_Handle             h_FmRtc,
                                           uint8_t              triggerId,
                                           uint64_t             *p_TimeStamp);

/**************************************************************************//**
 @Function      FM_RTC_GetCurrentTime

 @Description   Returns the current RTC time.

 @Param[in]     h_FmRtc - Handle to FM RTC object.
 @Param[out]    p_Ts - returned time stamp (in nanoseconds).

 @Return        E_OK on success; Error code otherwise.

 @Cautions      h_FmRtc must have been previously initialized using FM_RTC_Init().
*//***************************************************************************/
t_Error FM_RTC_GetCurrentTime(t_Handle h_FmRtc, uint64_t *p_Ts);

/**************************************************************************//**
 @Function      FM_RTC_SetCurrentTime

 @Description   Sets the current RTC time.

 @Param[in]     h_FmRtc - Handle to FM RTC object.
 @Param[in]     ts - The new time stamp (in nanoseconds).

 @Return        E_OK on success; Error code otherwise.

 @Cautions      h_FmRtc must have been previously initialized using FM_RTC_Init().
*//***************************************************************************/
t_Error FM_RTC_SetCurrentTime(t_Handle h_FmRtc, uint64_t ts);

/**************************************************************************//**
 @Function      FM_RTC_GetFreqCompensation

 @Description   TODO

 @Param[in]     h_FmRtc         - Handle to FM RTC object.
 @Param[out]    p_Compensation  - A pointer to the returned value of compensation.

 @Return        E_OK on success; Error code otherwise.

 @Cautions      h_FmRtc must have been previously initialized using FM_RTC_Init().
*//***************************************************************************/
t_Error FM_RTC_GetFreqCompensation(t_Handle h_FmRtc, uint32_t *p_Compensation);

/**************************************************************************//**
 @Function      FM_RTC_SetFreqCompensation

 @Description   TODO

 @Param[in]     h_FmRtc             - Handle to FM RTC object.
 @Param[in]     freqCompensation    - the new desired compensation value to be set.

 @Return        E_OK on success; Error code otherwise.

 @Cautions      h_FmRtc must have been previously initialized using FM_RTC_Init().
*//***************************************************************************/
t_Error FM_RTC_SetFreqCompensation(t_Handle h_FmRtc, uint32_t freqCompensation);

#if (defined(DEBUG_ERRORS) && (DEBUG_ERRORS > 0))
/**************************************************************************//**
 @Function      FM_RTC_DumpRegs

 @Description   Dumps all FM registers

 @Param[in]     h_FmRtc      A handle to an FM RTC Module.

 @Return        E_OK on success;

 @Cautions      Allowed only FM_Init().
*//***************************************************************************/
t_Error FM_RTC_DumpRegs(t_Handle h_FmRtc);
#endif /* (defined(DEBUG_ERRORS) && ... */

/** @} */ /* end of fm_rtc_control_grp */
/** @} */ /* end of fm_rtc_grp */
/** @} */ /* end of FM_grp group */


#endif /* __FM_RTC_EXT_H__ */