git.sur5r.net Git - freertos/blob - FreeRTOS/Demo/CORTEX_A53_64-bit_UltraScale_MPSoC/RTOSDemo_A53_bsp/psu_cortexa53_0/libsrc/rtcpsu_v1_2/src/xrtcpsu.h

   1 /******************************************************************************
   2 *
   3 * Copyright (C) 2015 Xilinx, Inc.  All rights reserved.
   4 *
   5 * Permission is hereby granted, free of charge, to any person obtaining a copy
   6 * of this software and associated documentation files (the "Software"), to deal
   7 * in the Software without restriction, including without limitation the rights
   8 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
   9 * copies of the Software, and to permit persons to whom the Software is
  10 * furnished to do so, subject to the following conditions:
  11 *
  12 * The above copyright notice and this permission notice shall be included in
  13 * all copies or substantial portions of the Software.
  14 *
  15 * Use of the Software is limited solely to applications:
  16 * (a) running on a Xilinx device, or
  17 * (b) that interact with a Xilinx device through a bus or interconnect.
  18 *
  19 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  20 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  21 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  22 * XILINX CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
  23 * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF
  24 * OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  25 * SOFTWARE.
  26 *
  27 * Except as contained in this notice, the name of the Xilinx shall not be used
  28 * in advertising or otherwise to promote the sale, use or other dealings in
  29 * this Software without prior written authorization from Xilinx.
  30 *
  31 ******************************************************************************/
  32 /*****************************************************************************/
  33 /**
  34 * @file xrtcpsu.h
  35 * @addtogroup rtcpsu_v1_0
  36 * @{
  37 * @details
  38 *
  39 * The Xilinx RTC driver component.  This component supports the Xilinx
  40 * RTC Controller. RTC Core and RTC controller are the two main important sub-
  41 * components for this RTC module. RTC core can run even in the battery powered
  42 * domain when the power from auxiliary source is down. Because of this, RTC core
  43 * latches the calibration,programmed time. This core interfaces with the crystal
  44 * oscillator and maintains current time in seconds.Calibration circuitry
  45 * calculates a second with maximum 1 PPM inaccuracy using a crystal oscillator
  46 * with arbitrary static inaccuracy. Core also responsible to maintain control
  47 * value used by the oscillator and power switching circuitry.
  48 *
  49 * RTC controller includes an APB interface responsible for register access with
  50 * in controller and core. It contains alarm generation logic including the alarm
  51 * register to hold alarm time in seconds.Interrupt management using Interrupt
  52 * status, Interrupt mask, Interrupt enable, Interrupt disable registers are
  53 * included to manage alarm and seconds interrupts. Address Slave error interrupts
  54 * are not being handled by this driver component.
  55 *
  56 * This driver supports the following features:
  57 * - Setting the RTC time.
  58 * - Setting the Alarm value that can be one-time alarm or a periodic alarm.
  59 * - Modifying the calibration value.
  60 *
  61 * <b>Initialization & Configuration</b>
  62 *
  63 * The XRtcPsu_Config structure is used by the driver to configure itself.
  64 * Fields inside this structure are properties of XRtcPsu based on its hardware
  65 * build.
  66 *
  67 * To support multiple runtime loading and initialization strategies employed
  68 * by various operating systems, the driver instance can be initialized in the
  69 * following way:
  70 *
  71 *   - XRtcPsu_CfgInitialize(InstancePtr, CfgPtr, EffectiveAddr) - Uses a
  72 *        configuration structure provided by the caller. If running in a system
  73 *        with address translation, the parameter EffectiveAddr should be the
  74 *         virtual address.
  75 *
  76 * <b>Interrupts</b>
  77 *
  78 * The driver defaults to no interrupts at initialization such that interrupts
  79 * must be enabled if desired. An interrupt is generated for one of the
  80 * following conditions.
  81 *
  82 * - Alarm is generated.
  83 * - A new second is generated.
  84 *
  85 * The application can control which interrupts are enabled using the
  86 * XRtcPsu_SetInterruptMask() function.
  87 *
  88 * In order to use interrupts, it is necessary for the user to connect the
  89 * driver interrupt handler, XRtcPsu_InterruptHandler(), to the interrupt
  90 * system of the application. A separate handler should be provided by the
  91 * application to communicate with the interrupt system, and conduct
  92 * application specific interrupt handling. An application registers its own
  93 * handler through the XRtcPsu_SetHandler() function.
  94 *
  95 * <pre>
  96 * MODIFICATION HISTORY:
  97 *
  98 * Ver   Who    Date     Changes
  99 * ----- -----  -------- -----------------------------------------------
 100 * 1.00  kvn    04/21/15 First release
 101 * 1.1   kvn    09/25/15 Modify control register to enable battery
 102 *                       switching when vcc_psaux is not available.
 103 * </pre>
 104 *
 105 ******************************************************************************/
 106
 107
 108 #ifndef XRTC_H_                 /* prevent circular inclusions */
 109 #define XRTC_H_                 /* by using protection macros */
 110
 111 #ifdef __cplusplus
 112 extern "C" {
 113 #endif
 114
 115 /***************************** Include Files *********************************/
 116
 117 #include "xstatus.h"
 118 #include "xil_assert.h"
 119 #include "xil_io.h"
 120 #include "xrtcpsu_hw.h"
 121 #include "xil_types.h"
 122
 123 /************************** Constant Definitions *****************************/
 124
 125 /** @name Callback events
 126  *
 127  * These constants specify the handler events that an application can handle
 128  * using its specific handler function. Note that these constants are not bit
 129  * mask, so only one event can be passed to an application at a time.
 130  *
 131  * @{
 132  */
 133 #define XRTCPSU_EVENT_ALARM_GEN         1U /**< Alarm generated event */
 134 #define XRTCPSU_EVENT_SECS_GEN          2U /**< A new second generated event */
 135 /*@}*/
 136
 137 #define XRTCPSU_CRYSTAL_OSC_EN          (u32)1 << XRTC_CTL_OSC_SHIFT
 138 /**< Separate Mask for Crystal oscillator bit Enable */
 139
 140 /**************************** Type Definitions *******************************/
 141
 142 /******************************************************************************/
 143 /**
 144  * This data type defines a handler that an application defines to communicate
 145  * with interrupt system to retrieve state information about an application.
 146  *
 147  * @param       CallBackRef is a callback reference passed in by the upper layer
 148  *              when setting the handler, and is passed back to the upper layer
 149  *              when the handler is called. It is used to find the device driver
 150  *              instance.
 151  * @param       Event contains one of the event constants indicating events that
 152  *              have occurred.
 153  * @param       EventData contains the number of bytes sent or received at the
 154  *              time of the call for send and receive events and contains the
 155  *              modem status for modem events.
 156  *
 157  ******************************************************************************/
 158 typedef void (*XRtcPsu_Handler) (void *CallBackRef, u32 Event);
 159
 160 /**
 161  * This typedef contains configuration information for a device.
 162  */
 163 typedef struct {
 164         u16 DeviceId;           /**< Unique ID of device */
 165         u32 BaseAddr;           /**< Register base address */
 166 } XRtcPsu_Config;
 167
 168 /**
 169  * The XRtcPsu driver instance data. The user is required to allocate a
 170  * variable of this type for the RTC device in the system. A pointer
 171  * to a variable of this type is then passed to the driver API functions.
 172  */
 173 typedef struct {
 174         XRtcPsu_Config RtcConfig;       /**< Device configuration */
 175         u32 IsReady;                            /**< Device is initialized and ready */
 176         u32 PeriodicAlarmTime;
 177         u8 IsPeriodicAlarm;
 178         u32 OscillatorFreq;
 179         u32 CalibrationValue;
 180         XRtcPsu_Handler Handler;
 181         void *CallBackRef;                      /**< Callback reference for event handler */
 182 } XRtcPsu;
 183
 184 /**
 185  * This typedef contains DateTime format structure.
 186  */
 187 typedef struct {
 188         u32 Year;
 189         u32 Month;
 190         u32 Day;
 191         u32 Hour;
 192         u32 Min;
 193         u32 Sec;
 194         u32 WeekDay;
 195 } XRtcPsu_DT;
 196
 197
 198 /************************* Variable Definitions ******************************/
 199
 200
 201 /***************** Macros (Inline Functions) Definitions *********************/
 202
 203 #define XRTC_CALIBRATION_VALUE 0x00198231U
 204 #define XRTC_TYPICAL_OSC_FREQ 33330U
 205
 206 /****************************************************************************/
 207 /**
 208 *
 209 * This macro updates the current time of RTC device.
 210 *
 211 * @param        InstancePtr is a pointer to the XRtcPsu instance.
 212 * @param        Time is the desired time for RTC in seconds.
 213 *
 214 * @return       None.
 215 *
 216 * @note         C-Style signature:
 217 *               void XRtcPsu_SetTime(XRtcPsu *InstancePtr, u32 Time)
 218 *
 219 *****************************************************************************/
 220 #define XRtcPsu_SetTime(InstancePtr,Time) \
 221         XRtcPsu_WriteReg(((InstancePtr)->RtcConfig.BaseAddr + \
 222                                 XRTC_SET_TIME_WR_OFFSET),(Time))
 223
 224 /****************************************************************************/
 225 /**
 226 *
 227 * This macro returns the last set time of RTC device. Whenever a reset
 228 * happens, the last set time will be zeroth day first sec.
 229 *
 230 * @param        InstancePtr is a pointer to the XRtcPsu instance.
 231 *
 232 * @return       The last set time in seconds.
 233 *
 234 * @note         C-Style signature:
 235 *               u32 XRtcPsu_GetLastSetTime(XRtcPsu *InstancePtr)
 236 *
 237 *****************************************************************************/
 238 #define XRtcPsu_GetLastSetTime(InstancePtr) \
 239         XRtcPsu_ReadReg((InstancePtr)->RtcConfig.BaseAddr + XRTC_SET_TIME_RD_OFFSET)
 240
 241 /****************************************************************************/
 242 /**
 243 *
 244 * This macro returns the calibration value of RTC device.
 245 *
 246 * @param        InstancePtr is a pointer to the XRtcPsu instance.
 247 *
 248 * @return       Calibration value for RTC.
 249 *
 250 * @note         C-Style signature:
 251 *               u32 XRtcPsu_GetCalibration(XRtcPsu *InstancePtr)
 252 *
 253 *****************************************************************************/
 254 #define XRtcPsu_GetCalibration(InstancePtr) \
 255         XRtcPsu_ReadReg((InstancePtr)->RtcConfig.BaseAddr+XRTC_CALIB_RD_OFFSET)
 256
 257 /****************************************************************************/
 258 /**
 259 *
 260 * This macro returns the current time of RTC device.
 261 *
 262 * @param        InstancePtr is a pointer to the XRtcPsu instance.
 263 *
 264 * @return       Current Time. This current time will be in seconds.
 265 *
 266 * @note         C-Style signature:
 267 *               u32 XRtcPsu_GetCurrentTime(XRtcPsu *InstancePtr)
 268 *
 269 *****************************************************************************/
 270 #define XRtcPsu_GetCurrentTime(InstancePtr) \
 271         XRtcPsu_ReadReg((InstancePtr)->RtcConfig.BaseAddr+XRTC_CUR_TIME_OFFSET)
 272
 273 /****************************************************************************/
 274 /**
 275 *
 276 * This macro sets the control register value of RTC device.
 277 *
 278 * @param        InstancePtr is a pointer to the XRtcPsu instance.
 279 * @param        Value is the desired control register value for RTC.
 280 *
 281 * @return       None.
 282 *
 283 * @note         C-Style signature:
 284 *               void XRtcPsu_SetControlRegister(XRtcPsu *InstancePtr, u32 Value)
 285 *
 286 *****************************************************************************/
 287 #define XRtcPsu_SetControlRegister(InstancePtr, Value) \
 288         XRtcPsu_WriteReg((InstancePtr)->RtcConfig.BaseAddr + \
 289                         XRTC_CTL_OFFSET,(Value))
 290
 291 /****************************************************************************/
 292 /**
 293 *
 294 * This macro returns the safety check register value of RTC device.
 295 *
 296 * @param        InstancePtr is a pointer to the XRtcPsu instance.
 297 *
 298 * @return       Safety check register value.
 299 *
 300 * @note         C-Style signature:
 301 *               u32 XRtcPsu_GetSafetyCheck(XRtcPsu *InstancePtr)
 302 *
 303 *****************************************************************************/
 304 #define XRtcPsu_GetSafetyCheck(InstancePtr)     \
 305         XRtcPsu_ReadReg((InstancePtr)->RtcConfig.BaseAddr+XRTC_SFTY_CHK_OFFSET)
 306
 307 /****************************************************************************/
 308 /**
 309 *
 310 * This macro sets the safety check register value of RTC device.
 311 *
 312 * @param        InstancePtr is a pointer to the XRtcPsu instance.
 313 * @param        Value is a safety check value to be written in register.
 314 *
 315 * @return       None.
 316 *
 317 * @note         C-Style signature:
 318 *               void XRtcPsu_SetSafetyCheck(XRtcPsu *InstancePtr, u32 Value)
 319 *
 320 *****************************************************************************/
 321 #define XRtcPsu_SetSafetyCheck(InstancePtr, Value)      \
 322         XRtcPsu_WriteReg((InstancePtr)->RtcConfig.BaseAddr + \
 323                         XRTC_SFTY_CHK_OFFSET,(Value))
 324
 325 /****************************************************************************/
 326 /**
 327 *
 328 * This macro resets the alarm register
 329 *
 330 * @param        InstancePtr is a pointer to the XRtcPsu instance.
 331 *
 332 * @return       None.
 333 *
 334 * @note         C-Style signature:
 335 *               u32 XRtcPsu_ResetAlarm(XRtcPsu *InstancePtr)
 336 *
 337 *****************************************************************************/
 338 #define XRtcPsu_ResetAlarm(InstancePtr) \
 339                 XRtcPsu_WriteReg((InstancePtr)->RtcConfig.BaseAddr + \
 340                                 XRTC_ALRM_OFFSET,XRTC_ALRM_RSTVAL)
 341
 342 /****************************************************************************/
 343 /**
 344 *
 345 * This macro rounds off the given number
 346 *
 347 * @param        Number is the one that needs to be rounded off..
 348 *
 349 * @return       The rounded off value of the input number.
 350 *
 351 * @note         C-Style signature:
 352 *               u32 XRtcPsu_RoundOff(float Number)
 353 *
 354 *****************************************************************************/
 355 #define XRtcPsu_RoundOff(Number) \
 356         (u32)(((Number) < (u32)0) ? ((Number) - (u32)0.5) : ((Number) + (u32)0.5))
 357
 358 /************************** Function Prototypes ******************************/
 359
 360 /* Functions in xrtcpsu.c */
 361 s32 XRtcPsu_CfgInitialize(XRtcPsu *InstancePtr, XRtcPsu_Config *ConfigPtr,
 362                                 u32 EffectiveAddr);
 363
 364 void XRtcPsu_SetAlarm(XRtcPsu *InstancePtr, u32 Alarm, u32 Periodic);
 365 void XRtcPsu_SecToDateTime(u32 Seconds, XRtcPsu_DT *dt);
 366 u32 XRtcPsu_DateTimeToSec(XRtcPsu_DT *dt);
 367 void XRtcPsu_CalculateCalibration(XRtcPsu *InstancePtr,u32 TimeReal,
 368                 u32 CrystalOscFreq);
 369 u32 XRtcPsu_IsSecondsEventGenerated(XRtcPsu *InstancePtr);
 370 u32 XRtcPsu_IsAlarmEventGenerated(XRtcPsu *InstancePtr);
 371
 372 /* interrupt functions in xrtcpsu_intr.c */
 373 void XRtcPsu_SetInterruptMask(XRtcPsu *InstancePtr, u32 Mask);
 374 void XRtcPsu_ClearInterruptMask(XRtcPsu *InstancePtr, u32 Mask);
 375 void XRtcPsu_InterruptHandler(XRtcPsu *InstancePtr);
 376 void XRtcPsu_SetHandler(XRtcPsu *InstancePtr, XRtcPsu_Handler FuncPtr,
 377                          void *CallBackRef);
 378
 379 /* Functions in xrtcpsu_selftest.c */
 380 s32 XRtcPsu_SelfTest(XRtcPsu *InstancePtr);
 381
 382 /* Functions in xrtcpsu_sinit.c */
 383 XRtcPsu_Config *XRtcPsu_LookupConfig(u16 DeviceId);
 384
 385
 386 #endif /* XRTC_H_ */
 387 /** @} */