1 /******************************************************************************
3 * Copyright (C) 2015 Xilinx, Inc. All rights reserved.
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:
12 * The above copyright notice and this permission notice shall be included in
13 * all copies or substantial portions of the Software.
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.
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
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.
31 ******************************************************************************/
32 /*****************************************************************************/
35 * @addtogroup rtcpsu_v1_0
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.
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.
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.
61 * <b>Initialization & Configuration</b>
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
67 * To support multiple runtime loading and initialization strategies employed
68 * by various operating systems, the driver instance can be initialized in the
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
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.
82 * - Alarm is generated.
83 * - A new second is generated.
85 * The application can control which interrupts are enabled using the
86 * XRtcPsu_SetInterruptMask() function.
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.
96 * MODIFICATION HISTORY:
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).
106 ******************************************************************************/
109 #ifndef XRTC_H_ /* prevent circular inclusions */
110 #define XRTC_H_ /* by using protection macros */
116 /***************************** Include Files *********************************/
119 #include "xil_assert.h"
121 #include "xrtcpsu_hw.h"
122 #include "xil_types.h"
124 /************************** Constant Definitions *****************************/
126 /** @name Callback events
128 * These constants specify the handler events that an application can handle
129 * using its specific handler function. Note that these constants are not bit
130 * mask, so only one event can be passed to an application at a time.
134 #define XRTCPSU_EVENT_ALARM_GEN 1U /**< Alarm generated event */
135 #define XRTCPSU_EVENT_SECS_GEN 2U /**< A new second generated event */
138 #define XRTCPSU_CRYSTAL_OSC_EN (u32)1 << XRTC_CTL_OSC_SHIFT
139 /**< Separate Mask for Crystal oscillator bit Enable */
141 /**************************** Type Definitions *******************************/
143 /******************************************************************************/
145 * This data type defines a handler that an application defines to communicate
146 * with interrupt system to retrieve state information about an application.
148 * @param CallBackRef is a callback reference passed in by the upper layer
149 * when setting the handler, and is passed back to the upper layer
150 * when the handler is called. It is used to find the device driver
152 * @param Event contains one of the event constants indicating events that
154 * @param EventData contains the number of bytes sent or received at the
155 * time of the call for send and receive events and contains the
156 * modem status for modem events.
158 ******************************************************************************/
159 typedef void (*XRtcPsu_Handler) (void *CallBackRef, u32 Event);
162 * This typedef contains configuration information for a device.
165 u16 DeviceId; /**< Unique ID of device */
166 u32 BaseAddr; /**< Register base address */
170 * The XRtcPsu driver instance data. The user is required to allocate a
171 * variable of this type for the RTC device in the system. A pointer
172 * to a variable of this type is then passed to the driver API functions.
175 XRtcPsu_Config RtcConfig; /**< Device configuration */
176 u32 IsReady; /**< Device is initialized and ready */
177 u32 PeriodicAlarmTime;
180 u32 CalibrationValue;
181 XRtcPsu_Handler Handler;
182 void *CallBackRef; /**< Callback reference for event handler */
188 * This typedef contains DateTime format structure.
201 /************************* Variable Definitions ******************************/
204 /***************** Macros (Inline Functions) Definitions *********************/
206 #define XRTC_CALIBRATION_VALUE 0x00198231U
207 #define XRTC_TYPICAL_OSC_FREQ 33330U
209 /****************************************************************************/
212 * This macro updates the current time of RTC device.
214 * @param InstancePtr is a pointer to the XRtcPsu instance.
215 * @param Time is the desired time for RTC in seconds.
219 * @note C-Style signature:
220 * void XRtcPsu_SetTime(XRtcPsu *InstancePtr, u32 Time)
222 *****************************************************************************/
223 #define XRtcPsu_WriteSetTime(InstancePtr,Time) \
224 XRtcPsu_WriteReg(((InstancePtr)->RtcConfig.BaseAddr + \
225 XRTC_SET_TIME_WR_OFFSET),(Time))
227 /****************************************************************************/
230 * This macro returns the last set time of RTC device. Whenever a reset
231 * happens, the last set time will be zeroth day first sec.
233 * @param InstancePtr is a pointer to the XRtcPsu instance.
235 * @return The last set time in seconds.
237 * @note C-Style signature:
238 * u32 XRtcPsu_GetLastSetTime(XRtcPsu *InstancePtr)
240 *****************************************************************************/
241 #define XRtcPsu_GetLastSetTime(InstancePtr) \
242 XRtcPsu_ReadReg((InstancePtr)->RtcConfig.BaseAddr + XRTC_SET_TIME_RD_OFFSET)
244 /****************************************************************************/
247 * This macro returns the calibration value of RTC device.
249 * @param InstancePtr is a pointer to the XRtcPsu instance.
251 * @return Calibration value for RTC.
253 * @note C-Style signature:
254 * u32 XRtcPsu_GetCalibration(XRtcPsu *InstancePtr)
256 *****************************************************************************/
257 #define XRtcPsu_GetCalibration(InstancePtr) \
258 XRtcPsu_ReadReg((InstancePtr)->RtcConfig.BaseAddr+XRTC_CALIB_RD_OFFSET)
260 /****************************************************************************/
263 * This macro returns the current time of RTC device.
265 * @param InstancePtr is a pointer to the XRtcPsu instance.
267 * @return Current Time. This current time will be in seconds.
269 * @note C-Style signature:
270 * u32 XRtcPsu_ReadCurrentTime(XRtcPsu *InstancePtr)
272 *****************************************************************************/
273 #define XRtcPsu_ReadCurrentTime(InstancePtr) \
274 XRtcPsu_ReadReg((InstancePtr)->RtcConfig.BaseAddr+XRTC_CUR_TIME_OFFSET)
276 /****************************************************************************/
279 * This macro sets the control register value of RTC device.
281 * @param InstancePtr is a pointer to the XRtcPsu instance.
282 * @param Value is the desired control register value for RTC.
286 * @note C-Style signature:
287 * void XRtcPsu_SetControlRegister(XRtcPsu *InstancePtr, u32 Value)
289 *****************************************************************************/
290 #define XRtcPsu_SetControlRegister(InstancePtr, Value) \
291 XRtcPsu_WriteReg((InstancePtr)->RtcConfig.BaseAddr + \
292 XRTC_CTL_OFFSET,(Value))
294 /****************************************************************************/
297 * This macro returns the safety check register value of RTC device.
299 * @param InstancePtr is a pointer to the XRtcPsu instance.
301 * @return Safety check register value.
303 * @note C-Style signature:
304 * u32 XRtcPsu_GetSafetyCheck(XRtcPsu *InstancePtr)
306 *****************************************************************************/
307 #define XRtcPsu_GetSafetyCheck(InstancePtr) \
308 XRtcPsu_ReadReg((InstancePtr)->RtcConfig.BaseAddr+XRTC_SFTY_CHK_OFFSET)
310 /****************************************************************************/
313 * This macro sets the safety check register value of RTC device.
315 * @param InstancePtr is a pointer to the XRtcPsu instance.
316 * @param Value is a safety check value to be written in register.
320 * @note C-Style signature:
321 * void XRtcPsu_SetSafetyCheck(XRtcPsu *InstancePtr, u32 Value)
323 *****************************************************************************/
324 #define XRtcPsu_SetSafetyCheck(InstancePtr, Value) \
325 XRtcPsu_WriteReg((InstancePtr)->RtcConfig.BaseAddr + \
326 XRTC_SFTY_CHK_OFFSET,(Value))
328 /****************************************************************************/
331 * This macro resets the alarm register
333 * @param InstancePtr is a pointer to the XRtcPsu instance.
337 * @note C-Style signature:
338 * u32 XRtcPsu_ResetAlarm(XRtcPsu *InstancePtr)
340 *****************************************************************************/
341 #define XRtcPsu_ResetAlarm(InstancePtr) \
342 XRtcPsu_WriteReg((InstancePtr)->RtcConfig.BaseAddr + \
343 XRTC_ALRM_OFFSET,XRTC_ALRM_RSTVAL)
345 /****************************************************************************/
348 * This macro rounds off the given number
350 * @param Number is the one that needs to be rounded off..
352 * @return The rounded off value of the input number.
354 * @note C-Style signature:
355 * u32 XRtcPsu_RoundOff(float Number)
357 *****************************************************************************/
358 #define XRtcPsu_RoundOff(Number) \
359 (u32)(((Number) < (u32)0) ? ((Number) - (u32)0.5) : ((Number) + (u32)0.5))
361 /************************** Function Prototypes ******************************/
363 /* Functions in xrtcpsu.c */
364 s32 XRtcPsu_CfgInitialize(XRtcPsu *InstancePtr, XRtcPsu_Config *ConfigPtr,
367 void XRtcPsu_SetAlarm(XRtcPsu *InstancePtr, u32 Alarm, u32 Periodic);
368 void XRtcPsu_SecToDateTime(u32 Seconds, XRtcPsu_DT *dt);
369 u32 XRtcPsu_DateTimeToSec(XRtcPsu_DT *dt);
370 void XRtcPsu_CalculateCalibration(XRtcPsu *InstancePtr,u32 TimeReal,
372 u32 XRtcPsu_IsSecondsEventGenerated(XRtcPsu *InstancePtr);
373 u32 XRtcPsu_IsAlarmEventGenerated(XRtcPsu *InstancePtr);
374 u32 XRtcPsu_GetCurrentTime(XRtcPsu *InstancePtr);
375 void XRtcPsu_SetTime(XRtcPsu *InstancePtr,u32 Time);
377 /* interrupt functions in xrtcpsu_intr.c */
378 void XRtcPsu_SetInterruptMask(XRtcPsu *InstancePtr, u32 Mask);
379 void XRtcPsu_ClearInterruptMask(XRtcPsu *InstancePtr, u32 Mask);
380 void XRtcPsu_InterruptHandler(XRtcPsu *InstancePtr);
381 void XRtcPsu_SetHandler(XRtcPsu *InstancePtr, XRtcPsu_Handler FuncPtr,
384 /* Functions in xrtcpsu_selftest.c */
385 s32 XRtcPsu_SelfTest(XRtcPsu *InstancePtr);
387 /* Functions in xrtcpsu_sinit.c */
388 XRtcPsu_Config *XRtcPsu_LookupConfig(u16 DeviceId);