diff options
Diffstat (limited to 'bsp_howto/real_time_clock.rst')
| -rw-r--r-- | bsp_howto/real_time_clock.rst | 211 |
1 files changed, 0 insertions, 211 deletions
diff --git a/bsp_howto/real_time_clock.rst b/bsp_howto/real_time_clock.rst deleted file mode 100644 index 457c6e0..0000000 --- a/bsp_howto/real_time_clock.rst +++ /dev/null @@ -1,211 +0,0 @@ -.. 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 - } |