Update the BSP howto.

Closes #2590.

1 files changed, 128 insertions, 115 deletions

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 <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 \*/
-    }
+
+    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
+    }