From 6d7a4d2ee7053488f625faccc8bd4dc4d25d6460 Mon Sep 17 00:00:00 2001 From: Chris Johns Date: Fri, 17 Jun 2016 15:05:41 +1000 Subject: Update the BSP howto. Closes #2590. --- bsp_howto/real_time_clock.rst | 243 ++++++++++++++++++++++-------------------- 1 file changed, 128 insertions(+), 115 deletions(-) (limited to 'bsp_howto/real_time_clock.rst') diff --git a/bsp_howto/real_time_clock.rst b/bsp_howto/real_time_clock.rst index 35ee1f4..f66a410 100644 --- a/bsp_howto/real_time_clock.rst +++ b/bsp_howto/real_time_clock.rst @@ -1,14 +1,17 @@ .. 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. \[NOTE: In this chapter, the abbreviation*TOD* is used for *Time of Day*.] The capabilities provided by this -driver are: +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 @@ -20,113 +23,122 @@ driver are: - Get the Difference Between the RTEMS and RTC TOD -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: +.. 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:: c #include #include #include + 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 \*/ - } + + 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; + 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; + 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:: c +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 + 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 + 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. +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:: c + +.. 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 + if no RTCs are present + return + + invoke the deviceGetTime routine for the preferred RTC + set the RTEMS TOD using rtems_clock_set } setRealTimeFromRTEMS @@ -134,65 +146,66 @@ setRealTimeFromRTEMS The ``setRealTimeFromRTEMS`` routine sets the preferred RTC TOD to the current RTEMS TOD. -.. code:: c + +.. 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 + 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:: c +The ``getRealTime`` returns the preferred RTC TOD to the caller. + +.. code-block:: c - void getRealTime( rtems_time_of_day \*tod ) + void getRealTime( rtems_time_of_day *tod ) { - if no RTCs are present - return - invoke the deviceGetTime routine for the preferred RTC + 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:: c +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 ) + void setRealTime( rtems_time_of_day *tod ) { - if no RTCs are present - return - invoke the deviceSetTime routine for the preferred RTC + 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. +The ``checkRealTime`` routine returns the number of seconds difference between +the RTC TOD and the current RTEMS TOD. + .. code:: 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 - } + if no RTCs are present + return -1 -.. COMMENT: COPYRIGHT (c) 1988-2002. - -.. COMMENT: On-Line Applications Research Corporation (OAR). - -.. COMMENT: All rights reserved. + 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 + } -- cgit v1.2.3