diff options
Diffstat (limited to 'bsp-howto/real_time_clock.rst')
| -rw-r--r-- | bsp-howto/real_time_clock.rst | 211 |
1 files changed, 211 insertions, 0 deletions
diff --git a/bsp-howto/real_time_clock.rst b/bsp-howto/real_time_clock.rst new file mode 100644 index 0000000..457c6e0 --- /dev/null +++ b/bsp-howto/real_time_clock.rst @@ -0,0 +1,211 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. COMMENT: COPYRIGHT (c) 1988-2002. +.. COMMENT: On-Line Applications Research Corporation (OAR). +.. COMMENT: All rights reserved. + +Real-Time Clock Driver +###################### + +Introduction +============ + +The Real-Time Clock (*RTC*) driver is responsible for providing an interface to +an *RTC* device. The capabilities provided by this driver are: + +- Set the RTC TOD to RTEMS TOD + +- Set the RTEMS TOD to the RTC TOD + +- Get the RTC TOD + +- Set the RTC TOD to the Specified TOD + +- Get the Difference Between the RTEMS and RTC TOD + +.. note:: + + In this chapter, the abbreviation `TOD` is used for *Time of Day*. + +The reference implementation for a real-time clock driver can be found in +``c/src/lib/libbsp/shared/tod.c``. This driver is based on the libchip concept +and can be easily configured to work with any of the RTC chips supported by the +RTC chip drivers in the directory ``c/src/lib/lib/libchip/rtc``. There is a +README file in this directory for each supported RTC chip. Each of these +README explains how to configure the shared libchip implementation of the RTC +driver for that particular RTC chip. + +The DY-4 DMV177 BSP used the shared libchip implementation of the RTC driver. +There were no DMV177 specific configuration routines. A BSP could use +configuration routines to dynamically determine what type of real-time clock is +on a particular board. This would be useful for a BSP supporting multiple +board models. The relevant ports of the DMV177's ``RTC_Table`` configuration +table is below: + +.. code-block:: c + + #include <bsp.h> + #include <libchip/rtc.h> + #include <libchip/icm7170.h> + + bool dmv177_icm7170_probe(int minor); + + rtc_tbl RTC_Table[] = { + { "/dev/rtc0", /* sDeviceName */ + RTC_ICM7170, /* deviceType */ + &icm7170_fns, /* pDeviceFns */ + dmv177_icm7170_probe, /* deviceProbe */ + (void *) ICM7170_AT_1_MHZ, /* pDeviceParams */ + DMV170_RTC_ADDRESS, /* ulCtrlPort1 */ + 0, /* ulDataPort */ + icm7170_get_register_8, /* getRegister */ + icm7170_set_register_8, /* setRegister */ + } + }; + unsigned long RTC_Count = (sizeof(RTC_Table)/sizeof(rtc_tbl)); + rtems_device_minor_number RTC_Minor; + + bool dmv177_icm7170_probe(int minor) + { + volatile unsigned16 *card_resource_reg; + card_resource_reg = (volatile unsigned16 *) DMV170_CARD_RESORCE_REG; + if ( (*card_resource_reg & DMV170_RTC_INST_MASK) == DMV170_RTC_INSTALLED ) + return TRUE; + return FALSE; + } + +Initialization +============== + +The ``rtc_initialize`` routine is responsible for initializing the RTC chip so +it can be used. The shared libchip implementation of this driver supports +multiple RTCs and bases its initialization order on the order the chips are +defined in the ``RTC_Table``. Each chip defined in the table may or may not be +present on this particular board. It is the responsibility of the +``deviceProbe`` to indicate the presence of a particular RTC chip. The first +RTC found to be present is considered the preferred RTC. + +In the shared libchip based implementation of the driver, the following actions +are performed: + +.. code-block:: c + + rtems_device_driver rtc_initialize( + rtems_device_major_number major, + rtems_device_minor_number minor_arg, + void *arg + ) + { + for each RTC configured in RTC_Table + if the deviceProbe for this RTC indicates it is present + set RTC_Minor to this device + set RTC_Present to TRUE + break out of this loop + + if RTC_Present is not TRUE + return RTEMS_INVALID_NUMBER to indicate that no RTC is present + + register this minor number as the "/dev/rtc" + + perform the deviceInitialize routine for the preferred RTC chip + + for RTCs past this one in the RTC_Table + if the deviceProbe for this RTC indicates it is present + perform the deviceInitialize routine for this RTC chip + register the configured name for this RTC + } + +The ``deviceProbe`` routine returns TRUE if the device configured by this entry +in the ``RTC_Table`` is present. This configuration scheme allows one to +support multiple versions of the same board with a single BSP. For example, if +the first generation of a board had Vendor A's RTC chip and the second +generation had Vendor B's RTC chip, RTC_Table could contain information for +both. The ``deviceProbe`` configured for Vendor A's RTC chip would need to +return TRUE if the board was a first generation one. The ``deviceProbe`` +routines are very board dependent and must be provided by the BSP. + +setRealTimeToRTEMS +================== + +The ``setRealTimeToRTEMS`` routine sets the current RTEMS TOD to that +of the preferred RTC. + +.. code-block:: c + + void setRealTimeToRTEMS(void) + { + if no RTCs are present + return + + invoke the deviceGetTime routine for the preferred RTC + set the RTEMS TOD using rtems_clock_set + } + +setRealTimeFromRTEMS +==================== + +The ``setRealTimeFromRTEMS`` routine sets the preferred RTC TOD to the +current RTEMS TOD. + +.. code-block:: c + + void setRealTimeFromRTEMS(void) + { + if no RTCs are present + return + + obtain the RTEMS TOD using rtems_clock_get + invoke the deviceSetTime routine for the preferred RTC + } + +getRealTime +=========== + +The ``getRealTime`` returns the preferred RTC TOD to the caller. + +.. code-block:: c + + void getRealTime( rtems_time_of_day *tod ) + { + if no RTCs are present + return + + invoke the deviceGetTime routine for the preferred RTC + } + +setRealTime +=========== + +The ``setRealTime`` routine sets the preferred RTC TOD to the TOD specified by +the caller. + +.. code-block:: c + + void setRealTime( rtems_time_of_day *tod ) + { + if no RTCs are present + return + + invoke the deviceSetTime routine for the preferred RTC + } + +checkRealTime +============= + +The ``checkRealTime`` routine returns the number of seconds difference between +the RTC TOD and the current RTEMS TOD. + +.. code-block:: c + + int checkRealTime( void ) + { + if no RTCs are present + return -1 + + obtain the RTEMS TOD using rtems_clock_get + get the TOD from the preferred RTC using the deviceGetTime routine + convert the RTEMS TOD to seconds + convert the RTC TOD to seconds + + return the RTEMS TOD in seconds - RTC TOD in seconds + } |