/**************************************************************************** * include/nuttx/rtc.h * * Copyright(C) 2011 Uros Platise. All rights reserved. * Author: Uros Platise * * With extensions, modifications by: * * Copyright (C) 2011-2012 Gregory Nutt. All rights reserved. * Author: Gregroy Nutt * * 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 NuttX nor the names of its contributors may be * used to endorse or promote products derived from this software * without specific prior written permission. * * 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. * ****************************************************************************/ #ifndef __INCLUDE_NUTTX_RTC_H #define __INCLUDE_NUTTX_RTC_H /**************************************************************************** * Included Files ****************************************************************************/ #include #include #include #include /**************************************************************************** * Pre-processor Definitions ****************************************************************************/ /* Configuration ************************************************************/ /* CONFIG_RTC - Enables general support for a hardware RTC. Specific * architectures may require other specific settings. * * CONFIG_RTC_DATETIME - There are two general types of RTC: (1) A simple * battery backed counter that keeps the time when power is down, and (2) * A full date / time RTC the provides the date and time information, often * in BCD format. If CONFIG_RTC_DATETIME is selected, it specifies this * second kind of RTC. In this case, the RTC is used to "seed" the normal * NuttX timer and the NuttX system timer provides for higher resoution * time. * * CONFIG_RTC_HIRES - If CONFIG_RTC_DATETIME not selected, then the simple, * battery backed counter is used. There are two different implementations * of such simple counters based on the time resolution of the counter: * The typical RTC keeps time to resolution of 1 second, usually * supporting a 32-bit time_t value. In this case, the RTC is used to * "seed" the normal NuttX timer and the NuttX timer provides for higher * resoution time. * * If CONFIG_RTC_HIRES is enabled in the NuttX configuration, then the * RTC provides higher resolution time and completely replaces the system * timer for purpose of date and time. * * CONFIG_RTC_FREQUENCY - If CONFIG_RTC_HIRES is defined, then the frequency * of the high resolution RTC must be provided. If CONFIG_RTC_HIRES is * not defined, CONFIG_RTC_FREQUENCY is assumed to be one. * * CONFIG_RTC_ALARM - Enable if the RTC hardware supports setting of an * alarm. A callback function will be executed when the alarm goes off */ #ifdef CONFIG_RTC_HIRES # ifdef CONFIG_RTC_DATETIME # error "CONFIG_RTC_HIRES and CONFIG_RTC_DATETIME are both defined" # endif # ifndef CONFIG_RTC_FREQUENCY # error "CONFIG_RTC_FREQUENCY is required for CONFIG_RTC_HIRES" # endif #else # ifndef CONFIG_RTC_FREQUENCY # define CONFIG_RTC_FREQUENCY 1 # endif # if CONFIG_RTC_FREQUENCY != 1 # error "The low resolution RTC must have frequency 1Hz" # endif #endif /**************************************************************************** * Public Types ****************************************************************************/ /* The form of an alarm callback */ typedef CODE void (*alarmcb_t)(void); /**************************************************************************** * Public Variables ****************************************************************************/ /* Variable determines the state of the RTC module. * * After initialization value is set to 'true' if RTC starts successfully. * The value can be changed to false also during operation if RTC for * some reason fails. */ extern volatile bool g_rtc_enabled; /**************************************************************************** * Public Functions ****************************************************************************/ #undef EXTERN #if defined(__cplusplus) #define EXTERN extern "C" extern "C" { #else #define EXTERN extern #endif /************************************************************************************ * Name: up_rtcinitialize * * Description: * Initialize the hardware RTC per the selected configuration. This function is * called once during the OS initialization sequence * * Input Parameters: * None * * Returned Value: * Zero (OK) on success; a negated errno on failure * ************************************************************************************/ EXTERN int up_rtcinitialize(void); /************************************************************************************ * Name: up_rtc_time * * Description: * Get the current time in seconds. This is similar to the standard time() * function. This interface is only required if the low-resolution RTC/counter * hardware implementation selected. It is only used by the RTOS during * initializeation to set up the system time when CONFIG_RTC is set but neither * CONFIG_RTC_HIRES nor CONFIG_RTC_DATETIME are set. * * Input Parameters: * None * * Returned Value: * The current time in seconds * ************************************************************************************/ #ifndef CONFIG_RTC_HIRES EXTERN time_t up_rtc_time(void); #endif /************************************************************************************ * Name: up_rtc_gettime * * Description: * Get the current time from the high resolution RTC clock/counter. This interface * is only supported by the high-resolution RTC/counter hardware implementation. * It is used to replace the system timer. * * Input Parameters: * tp - The location to return the high resolution time value. * * Returned Value: * Zero (OK) on success; a negated errno on failure * ************************************************************************************/ #ifdef CONFIG_RTC_HIRES EXTERN int up_rtc_gettime(FAR struct timespec *tp); #endif /************************************************************************************ * Name: up_rtc_getdatetime * * Description: * Get the current date and time from the date/time RTC. This interface * is only supported by the date/time RTC hardware implementation. * It is used to replace the system timer. It is only used by the RTOS during * initializeation to set up the system time when CONFIG_RTC and CONFIG_RTC_DATETIME * are selected (and CONFIG_RTC_HIRES is not). * * NOTE: Some date/time RTC hardware is capability of sub-second accuracy. That * sub-second accuracy is lost in this interface. However, since the system time * is reinitialized on each power-up/reset, there will be no timing inaccuracy in * the long run. * * Input Parameters: * tp - The location to return the high resolution time value. * * Returned Value: * Zero (OK) on success; a negated errno on failure * ************************************************************************************/ #ifdef CONFIG_RTC_DATETIME EXTERN int up_rtc_getdatetime(FAR struct tm *tp); #endif /************************************************************************************ * Name: up_rtc_settime * * Description: * Set the RTC to the provided time. All RTC implementations must be able to * set their time based on a standard timespec. * * Input Parameters: * tp - the time to use * * Returned Value: * Zero (OK) on success; a negated errno on failure * ************************************************************************************/ EXTERN int up_rtc_settime(FAR const struct timespec *tp); /************************************************************************************ * Name: up_rtc_setalarm * * Description: * Set up an alarm. * * Input Parameters: * tp - the time to set the alarm * callback - the function to call when the alarm expires. * * Returned Value: * Zero (OK) on success; a negated errno on failure * ************************************************************************************/ #ifdef CONFIG_RTC_ALARM EXTERN int up_rtc_setalarm(FAR const struct timespec *tp, alarmcb_t callback); #endif /************************************************************************************ * Name: up_rtc_cancelalarm * * Description: * Cancel a pending alarm alarm * * Input Parameters: * none * * Returned Value: * Zero (OK) on success; a negated errno on failure * ************************************************************************************/ #ifdef CONFIG_RTC_ALARM EXTERN int up_rtc_cancelalarm(void); #endif #undef EXTERN #if defined(__cplusplus) } #endif #endif /* __INCLUDE_NUTTX_RTC_H */