git.sur5r.net Git - freertos/blob - FreeRTOS/Demo/CORTEX_R5_UltraScale_MPSoC/RTOSDemo_R5_bsp/psu_cortexr5_0/libsrc/rtcpsu_v1_5/src/xrtcpsu.h

   1 /******************************************************************************
   2 *
   3 * Copyright (C) 2015 - 2017 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
  22 * XILINX 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_5
  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 * 1.3   vak    04/25/16 Corrected the RTC read and write time logic(cr#948833).
 104 * 1.4   MNK    01/27/17 Corrected calibration and frequency macros based on
 105 *                       rtc input oscillator frequency ( 32.768Khz).
 106 *       ms     03/17/17 Added readme.txt file in examples folder for doxygen
 107 *                       generation.
 108 *       ms     04/10/17 Modified filename tag in examples to include them in
 109 *                       doxygen examples.
 110 * 1.5   ms     08/27/17 Fixed compilation warnings in xrtcpsu.c file.
 111 *       ms     08/29/17 Updated the code as per source code style.
 112 * </pre>
 113 *
 114 ******************************************************************************/
 115
 116
 117 #ifndef XRTC_H_                 /* prevent circular inclusions */
 118 #define XRTC_H_                 /* by using protection macros */
 119
 120 #ifdef __cplusplus
 121 extern "C" {
 122 #endif
 123
 124 /***************************** Include Files *********************************/
 125
 126 #include "xstatus.h"
 127 #include "xil_assert.h"
 128 #include "xil_io.h"
 129 #include "xrtcpsu_hw.h"
 130 #include "xil_types.h"
 131
 132 /************************** Constant Definitions *****************************/
 133
 134 /** @name Callback events
 135  *
 136  * These constants specify the handler events that an application can handle
 137  * using its specific handler function. Note that these constants are not bit
 138  * mask, so only one event can be passed to an application at a time.
 139  *
 140  * @{
 141  */
 142 #define XRTCPSU_EVENT_ALARM_GEN         1U /**< Alarm generated event */
 143 #define XRTCPSU_EVENT_SECS_GEN          2U /**< A new second generated event */
 144 /*@}*/
 145
 146 #define XRTCPSU_CRYSTAL_OSC_EN          (u32)1 << XRTC_CTL_OSC_SHIFT
 147 /**< Separate Mask for Crystal oscillator bit Enable */
 148
 149 /**************************** Type Definitions *******************************/
 150
 151 /******************************************************************************/
 152 /**
 153  * This data type defines a handler that an application defines to communicate
 154  * with interrupt system to retrieve state information about an application.
 155  *
 156  * @param       CallBackRef is a callback reference passed in by the upper layer
 157  *              when setting the handler, and is passed back to the upper layer
 158  *              when the handler is called. It is used to find the device driver
 159  *              instance.
 160  * @param       Event contains one of the event constants indicating events that
 161  *              have occurred.
 162  * @param       EventData contains the number of bytes sent or received at the
 163  *              time of the call for send and receive events and contains the
 164  *              modem status for modem events.
 165  *
 166  ******************************************************************************/
 167 typedef void (*XRtcPsu_Handler) (void *CallBackRef, u32 Event);
 168
 169 /**
 170  * This typedef contains configuration information for a device.
 171  */
 172 typedef struct {
 173         u16 DeviceId;           /**< Unique ID of device */
 174         u32 BaseAddr;           /**< Register base address */
 175 } XRtcPsu_Config;
 176
 177 /**
 178  * The XRtcPsu driver instance data. The user is required to allocate a
 179  * variable of this type for the RTC device in the system. A pointer
 180  * to a variable of this type is then passed to the driver API functions.
 181  */
 182 typedef struct {
 183         XRtcPsu_Config RtcConfig;       /**< Device configuration */
 184         u32 IsReady;                            /**< Device is initialized and ready */
 185         u32 PeriodicAlarmTime;
 186         u8 IsPeriodicAlarm;
 187         u32 OscillatorFreq;
 188         u32 CalibrationValue;
 189         XRtcPsu_Handler Handler;
 190         void *CallBackRef;                      /**< Callback reference for event handler */
 191         u32 TimeUpdated;
 192         u32 CurrTimeUpdated;
 193 } XRtcPsu;
 194
 195 /**
 196  * This typedef contains DateTime format structure.
 197  */
 198 typedef struct {
 199         u32 Year;
 200         u32 Month;
 201         u32 Day;
 202         u32 Hour;
 203         u32 Min;
 204         u32 Sec;
 205         u32 WeekDay;
 206 } XRtcPsu_DT;
 207
 208
 209 /************************* Variable Definitions ******************************/
 210
 211
 212 /***************** Macros (Inline Functions) Definitions *********************/
 213
 214 #define XRTC_CALIBRATION_VALUE 0x8000U
 215 #define XRTC_TYPICAL_OSC_FREQ 32768U
 216
 217 /****************************************************************************/
 218 /**
 219 *
 220 * This macro updates the current time of RTC device.
 221 *
 222 * @param        InstancePtr is a pointer to the XRtcPsu instance.
 223 * @param        Time is the desired time for RTC in seconds.
 224 *
 225 * @return       None.
 226 *
 227 * @note         C-Style signature:
 228 *               void XRtcPsu_SetTime(XRtcPsu *InstancePtr, u32 Time)
 229 *
 230 *****************************************************************************/
 231 #define XRtcPsu_WriteSetTime(InstancePtr,Time) \
 232         XRtcPsu_WriteReg(((InstancePtr)->RtcConfig.BaseAddr + \
 233                                 XRTC_SET_TIME_WR_OFFSET),(Time))
 234
 235 /****************************************************************************/
 236 /**
 237 *
 238 * This macro returns the last set time of RTC device. Whenever a reset
 239 * happens, the last set time will be zeroth day first sec.
 240 *
 241 * @param        InstancePtr is a pointer to the XRtcPsu instance.
 242 *
 243 * @return       The last set time in seconds.
 244 *
 245 * @note         C-Style signature:
 246 *               u32 XRtcPsu_GetLastSetTime(XRtcPsu *InstancePtr)
 247 *
 248 *****************************************************************************/
 249 #define XRtcPsu_GetLastSetTime(InstancePtr) \
 250         XRtcPsu_ReadReg((InstancePtr)->RtcConfig.BaseAddr + XRTC_SET_TIME_RD_OFFSET)
 251
 252 /****************************************************************************/
 253 /**
 254 *
 255 * This macro returns the calibration value of RTC device.
 256 *
 257 * @param        InstancePtr is a pointer to the XRtcPsu instance.
 258 *
 259 * @return       Calibration value for RTC.
 260 *
 261 * @note         C-Style signature:
 262 *               u32 XRtcPsu_GetCalibration(XRtcPsu *InstancePtr)
 263 *
 264 *****************************************************************************/
 265 #define XRtcPsu_GetCalibration(InstancePtr) \
 266         XRtcPsu_ReadReg((InstancePtr)->RtcConfig.BaseAddr+XRTC_CALIB_RD_OFFSET)
 267
 268 /****************************************************************************/
 269 /**
 270 *
 271 * This macro returns the current time of RTC device.
 272 *
 273 * @param        InstancePtr is a pointer to the XRtcPsu instance.
 274 *
 275 * @return       Current Time. This current time will be in seconds.
 276 *
 277 * @note         C-Style signature:
 278 *               u32 XRtcPsu_ReadCurrentTime(XRtcPsu *InstancePtr)
 279 *
 280 *****************************************************************************/
 281 #define XRtcPsu_ReadCurrentTime(InstancePtr) \
 282         XRtcPsu_ReadReg((InstancePtr)->RtcConfig.BaseAddr+XRTC_CUR_TIME_OFFSET)
 283
 284 /****************************************************************************/
 285 /**
 286 *
 287 * This macro sets the control register value of RTC device.
 288 *
 289 * @param        InstancePtr is a pointer to the XRtcPsu instance.
 290 * @param        Value is the desired control register value for RTC.
 291 *
 292 * @return       None.
 293 *
 294 * @note         C-Style signature:
 295 *               void XRtcPsu_SetControlRegister(XRtcPsu *InstancePtr, u32 Value)
 296 *
 297 *****************************************************************************/
 298 #define XRtcPsu_SetControlRegister(InstancePtr, Value) \
 299         XRtcPsu_WriteReg((InstancePtr)->RtcConfig.BaseAddr + \
 300                         XRTC_CTL_OFFSET,(Value))
 301
 302 /****************************************************************************/
 303 /**
 304 *
 305 * This macro returns the safety check register value of RTC device.
 306 *
 307 * @param        InstancePtr is a pointer to the XRtcPsu instance.
 308 *
 309 * @return       Safety check register value.
 310 *
 311 * @note         C-Style signature:
 312 *               u32 XRtcPsu_GetSafetyCheck(XRtcPsu *InstancePtr)
 313 *
 314 *****************************************************************************/
 315 #define XRtcPsu_GetSafetyCheck(InstancePtr)     \
 316         XRtcPsu_ReadReg((InstancePtr)->RtcConfig.BaseAddr+XRTC_SFTY_CHK_OFFSET)
 317
 318 /****************************************************************************/
 319 /**
 320 *
 321 * This macro sets the safety check register value of RTC device.
 322 *
 323 * @param        InstancePtr is a pointer to the XRtcPsu instance.
 324 * @param        Value is a safety check value to be written in register.
 325 *
 326 * @return       None.
 327 *
 328 * @note         C-Style signature:
 329 *               void XRtcPsu_SetSafetyCheck(XRtcPsu *InstancePtr, u32 Value)
 330 *
 331 *****************************************************************************/
 332 #define XRtcPsu_SetSafetyCheck(InstancePtr, Value)      \
 333         XRtcPsu_WriteReg((InstancePtr)->RtcConfig.BaseAddr + \
 334                         XRTC_SFTY_CHK_OFFSET,(Value))
 335
 336 /****************************************************************************/
 337 /**
 338 *
 339 * This macro resets the alarm register
 340 *
 341 * @param        InstancePtr is a pointer to the XRtcPsu instance.
 342 *
 343 * @return       None.
 344 *
 345 * @note         C-Style signature:
 346 *               u32 XRtcPsu_ResetAlarm(XRtcPsu *InstancePtr)
 347 *
 348 *****************************************************************************/
 349 #define XRtcPsu_ResetAlarm(InstancePtr) \
 350                 XRtcPsu_WriteReg((InstancePtr)->RtcConfig.BaseAddr + \
 351                                 XRTC_ALRM_OFFSET,XRTC_ALRM_RSTVAL)
 352
 353 /****************************************************************************/
 354 /**
 355 *
 356 * This macro rounds off the given number
 357 *
 358 * @param        Number is the one that needs to be rounded off..
 359 *
 360 * @return       The rounded off value of the input number.
 361 *
 362 * @note         C-Style signature:
 363 *               u32 XRtcPsu_RoundOff(float Number)
 364 *
 365 *****************************************************************************/
 366 #define XRtcPsu_RoundOff(Number) \
 367         (u32)(((Number) < (u32)0) ? ((Number) - (u32)0.5) : ((Number) + (u32)0.5))
 368
 369 /************************** Function Prototypes ******************************/
 370
 371 /* Functions in xrtcpsu.c */
 372 s32 XRtcPsu_CfgInitialize(XRtcPsu *InstancePtr, XRtcPsu_Config *ConfigPtr,
 373                                 u32 EffectiveAddr);
 374
 375 void XRtcPsu_SetAlarm(XRtcPsu *InstancePtr, u32 Alarm, u32 Periodic);
 376 void XRtcPsu_SecToDateTime(u32 Seconds, XRtcPsu_DT *dt);
 377 u32 XRtcPsu_DateTimeToSec(XRtcPsu_DT *dt);
 378 void XRtcPsu_CalculateCalibration(XRtcPsu *InstancePtr,u32 TimeReal,
 379                 u32 CrystalOscFreq);
 380 u32 XRtcPsu_IsSecondsEventGenerated(XRtcPsu *InstancePtr);
 381 u32 XRtcPsu_IsAlarmEventGenerated(XRtcPsu *InstancePtr);
 382 u32 XRtcPsu_GetCurrentTime(XRtcPsu *InstancePtr);
 383 void XRtcPsu_SetTime(XRtcPsu *InstancePtr,u32 Time);
 384
 385 /* interrupt functions in xrtcpsu_intr.c */
 386 void XRtcPsu_SetInterruptMask(XRtcPsu *InstancePtr, u32 Mask);
 387 void XRtcPsu_ClearInterruptMask(XRtcPsu *InstancePtr, u32 Mask);
 388 void XRtcPsu_InterruptHandler(XRtcPsu *InstancePtr);
 389 void XRtcPsu_SetHandler(XRtcPsu *InstancePtr, XRtcPsu_Handler FuncPtr,
 390                          void *CallBackRef);
 391
 392 /* Functions in xrtcpsu_selftest.c */
 393 s32 XRtcPsu_SelfTest(XRtcPsu *InstancePtr);
 394
 395 /* Functions in xrtcpsu_sinit.c */
 396 XRtcPsu_Config *XRtcPsu_LookupConfig(u16 DeviceId);
 397
 398
 399 #endif /* XRTC_H_ */
 400 /** @} */