Applied updates from remote work while doing class.

doc/bsp_howto/rtc.t

@@ -8,5 +8,180 @@
 
 @chapter Real-Time Clock Driver
 
-XXX FILL ME IN
+@section Introduction
+
+The Real-Time Clock (@b{RTC}) driver is responsible for providing an
+interface to an @b{RTC} device.  [NOTE: In this chapter, the abbreviation
+@b{TOD} is used for @b{Time of Day}.]  The capabilities provided by this
+driver are:
+
+@itemize @bullet
+@item Set the RTC TOD to RTEMS TOD
+@item Set the RTEMS TOD to the RTC TOD
+@item Get the RTC TOD
+@item Set the RTC TOD to the Specified TOD
+@item Get the Difference Between the RTEMS and RTC TOD
+@end itemize
+
+The reference implementation for a real-time clock driver can 
+be found in @code{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 @code{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 uses the shared libchip implementation of the RTC
+driver.  Its @code{RTC_Table} configuration table can be found in
+@code{c/src/lib/libbsp/powerpc/dmv177/tod/config.c}.
+
+@section Initialization
+
+The @code{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 @code{RTC_Table}.  Each chip
+defined in the table may or may not be present on this particular board.
+It is the responsibility of the @code{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:
+
+@example
+@group
+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
+@}
+@end group
+@end example
+
+The @code{deviceProbe} routine returns TRUE if the device
+configured by this entry in the @code{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 @code{deviceProbe} configured
+for Vendor A's RTC chip would need to return TRUE if the
+board was a first generation one.  The @code{deviceProbe}
+routines are very board dependent.
+
+@section setRealTimeToRTEMS
+
+The @code{setRealTimeToRTEMS} routine sets the current RTEMS TOD to that
+of the preferred RTC.  
+
+@example
+@group
+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
+@}
+@end group
+@end example
+
+@section setRealTimeFromRTEMS
+
+The @code{setRealTimeFromRTEMS} routine sets the preferred RTC TOD to the
+current RTEMS TOD.
+
+@example
+@group
+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
+@}
+@end group
+@end example
+
+@section getRealTime
+
+The @code{getRealTime} returns the preferred RTC TOD to the
+caller.
+
+@example
+@group
+void getRealTime( rtems_time_of_day *tod )
+@{
+  if no RTCs are present
+    return
+
+  invoke the deviceGetTime routine for the preferred RTC
+@}
+@end group
+@end example
+
+@section setRealTime
+
+The @code{setRealTime} routine sets the preferred RTC TOD to the
+TOD specified by the caller.
+
+@example
+@group
+void setRealTime( rtems_time_of_day *tod )
+@{
+  if no RTCs are present
+    return
+
+  invoke the deviceSetTime routine for the preferred RTC
+@}
+@end group
+@end example
+
+@section checkRealTime
+
+The @code{checkRealTime} routine returns the number of seconds
+difference between the RTC TOD and the current RTEMS TOD.
+
+@example
+@group
+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
+@}
+@end group
+@end example