From bc950e878a06243e272493eff8a9509b4e416483 Mon Sep 17 00:00:00 2001 From: Joel Sherrill Date: Thu, 19 Nov 1998 16:02:06 +0000 Subject: Applied updates from remote work while doing class. --- doc/bsp_howto/rtc.t | 177 +++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 176 insertions(+), 1 deletion(-) (limited to 'doc/bsp_howto/rtc.t') diff --git a/doc/bsp_howto/rtc.t b/doc/bsp_howto/rtc.t index f0e3bccabb..6134452dd7 100644 --- a/doc/bsp_howto/rtc.t +++ b/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 -- cgit v1.2.3