m48t37 [lopec] - M48T37 library
m48t37RtcSet( ) - set the RTC's date/time per caller's values.
m48t37RtcShow( ) - Show the date/time on the user's display.
m48t37RtcGet( ) - Get current RTC date/time.
m48t37DateTimeHook( ) - This is a hook routine for the dosFsLib.
m48t37AlarmSet( ) - Set an alarm clock per the caller's settings.
m48t37AlarmCancel( ) - Disable the alarm clock.
m48t37AlarmGet( ) - Populate an ALARM_DATE_TIME structure with current alarm clock settings.
m48t37AlarmShow( ) - Display current alarm clock settings on the user's display.
m48t37FailsafeSet( ) - Set failsafe timer parameters/feed failsafe timer.
m48t37FailsafeGet( ) - Get failsafe timer parameters.
m48t37FailsafeCausedReset( ) - Determine if failsafe timer caused last board reset.
m48t37FailsafeShow( ) - Show the current failsafe timer parameters.
m48t37Init( ) - Initialize the M48T37.
m48t37FailsafeCancel( ) - cancel the failsafe timer
This library provides support routines for the real-time clock, alarm clock, and Watchdog Timer sub-functions of the M48T37 "Timekeeper" RTC chip.
- Alarm Clock
- The alarm clock sub-function of the M48T37 can be configured to go off once a month on a predetermined day, hour, minute, and second, to go off once a day at a predetermined hour, minute, and second, to go off once an hour at a predetermined minute and second, to go off once a minute at a predetermined second, or to go off once a second.
When the clock information matches the alarm clock settings an interrupt is generated.
To disable the alarm clock, you write "0" to the alarm date registers. An alarm clock interrupt is cleared by a read to the FLAGS register.
A call to m48t37AlarmShow( ) will display the current alarm clock configuration values.
- Real-Time Clock
- The real-time clock sub-function of the M48T37 consists of 8 registers to store the date and time. The 8 values are as follows:
Year 00-99 Month 01-12 Date ( day of month ) 01-31 Day ( day of week ) 01-07 Hour 00-23 Min 00-59 Sec 00-59 Century 00-99All values in the RTC registers are stored in BCD ( binary coded decimal ). Since the RTC_DATE_TIME and ALARM_DATE_TIME structures contain integers two macros have been defined in m48t37.h which convert from binary to BCD and vice-versa. The macros are BIN_TO_BCD (bin) and BCD_TO_BIN (bcd).
- Failsafe Timer
- The Failsafe sub-function is disabled at power-up and after a reset. The first call to m48t37FailsafeSet( ) arms the failsafe and subsequent calls to m48t37FailsafeSet( ) will extend the failsafe timer and prevent it from expiring.
If m48t37FailsafeSet( ) is called with a timeout of zero, the failsafe timer will be disabled. The timer can also be disabled with a call to m48t37FailsafeCancel( ).
Failsafe expiration can be annunciated as either a maskable interrupt (IRQ 15) or as a board reset event. The selection is made by the "reset" parameter passed to m48t37FailsafeSet( ). If "reset" is TRUE, a board reset event occurs when the failsafe expires. If "reset" is FALSE, an interrupt is generated.
A call to m48t37FailsafeCausedReset( ) will return a boolean indicating whether the failsafe timer caused the last board reset. To determine if the failsafe timer caused the last reset you must call this routine before setting an alarm, since setting the alarm will clear the failsafe timer flag.
When failsafe expiration is annunciated using an interrupt, an interrupt handler must be attached to the proper vector using intConnect( ) and the interrupt must be enabled using intEnable( ) before calling m48t37FailsafeSet( ) to arm the failsafe timer. If recovery from the interrupt is desired, the interrupt service routine must call m48t37FailsafeSet( ) with "seconds" set to 0, or m48t37FailsafeCancel( ). This operation disables the failsafe timer and clears the timer interrupt. If desired, the failsafe timer can be re-enabled by calling m48t37FailsafeSet( ) with the "seconds" parameter set non-zero.
A two-stage failsafe can be implemented by initially configuring the failsafe timer for interrupt generation and re-configuring it for reset generation during the failsafe service interrupt. The second occurrence of the failsafe will trigger a board reset.
The m48t37FailsafeGet( ) function returns the current failsafe configuration (not the amount of time remaining until timer expiration). Failsafe service code can use this function to extend the failsafe timeout without knowing the initial setting as follows:
UCHAR seconds; BOOL reset; m48t37FailsafeGet (&seconds, &reset); m48t37FailsafeSet (seconds, reset);A call to m48t37FailsafeShow( ) will display the current configuration of the failsafe timer. m48t37FailsafeShow( ) simply displays the results of a call to m48t37FailsafeGet( ).
m48t37.h
m48t37RtcSet( ) - set the RTC's date/time per caller's values.
STATUS m48t37RtcSet ( RTC_DATE_TIME * rtc_time /* pointer to time keeping structure */ )
This routine allows the caller to set the RTC time and date. The caller must allocate space for an RTC_DATE_TIME structure, fill the structure with the desired time and date, and call this routine.
OK, or ERROR if date/time values are invalid.
m48t37RtcShow( ) - Show the date/time on the user's display.
STATUS m48t37RtcShow (void)
This routine retrieves the current RTC date and time and sends it in a user-readable fashion to the user's display.
OK, or ERROR if unable to retrieve or print the current RTC date and time.
m48t37RtcGet( ) - Get current RTC date/time.
STATUS m48t37RtcGet ( RTC_DATE_TIME * rtc_time /* pointer to time keeping structure */ )
This routine allows the caller to obtain the current RTC time and date. The caller must allocate space for an RTC_DATE_TIME structure, then call this routine.
OK, or ERROR if unable to retrieve the current RTC date and time.
m48t37DateTimeHook( ) - This is a hook routine for the dosFsLib.
void m48t37DateTimeHook ( DOS_DATE_TIME * pDateTime /* pointer to time keeping structure */ )
This routine fills in a DOS_DATE_TIME structure with the current date and time. This is used by the standard VxWorks dosFsLib as a way to update the date/time values used for file timestamps. This is "hooked" into the dosFsLib during board initialization if both the dosFsLib and the RTC support is included in the BSP.
void.
m48t37, dosFsDateTimeInstall( ), and the dosFsLib documentation.
m48t37AlarmSet( ) - Set an alarm clock per the caller's settings.
STATUS m48t37AlarmSet ( UCHAR method, /* ALARM_EVERY_XXXX */ ALARM_DATE_TIME * alarm_time /* pointer to time keeping structure */ )
This routine sets an alarm clock. The alarm can be programmed to go off once a month at a predetermined day, hour, minute, and second, to go off once a day at a predetermined hour, minute, and second, to go off once an hour at a predetermined minute and second, to go off once a minute at a predetermined second, or to go off once a second.
method can have the following values:
ALARM_EVERY_MONTH = once a month ALARM_EVERY_DAY = once a day ALARM_EVERY_HOUR = once an hour ALARM_EVERY_MINUTE = once a minute ALARM_EVERY_SECOND = once a secondThe alarm values for second, minute, hour, and day_of_month must be passed to the function in an ALARM_DATE_TIME structure.
OK, or ERROR if the settings are invalid.
m48t37AlarmCancel( ) - Disable the alarm clock.
STATUS m48t37AlarmCancel (void)
This routine disables the alarm clock.
OK always.
m48t37AlarmGet( ) - Populate an ALARM_DATE_TIME structure with current alarm clock settings.
STATUS m48t37AlarmGet ( UCHAR * method, /* method = ALARM_EVERY_XXXX */ ALARM_DATE_TIME * alarm_time /* pointer to alarm parameters */ )
This routine will retrieve the current alarm clock settings and place them in an ALARM_DATE_TIME structure and method which the user must pass in.
OK, or error if the alarm settings are not valid.
m48t37AlarmShow( ) - Display current alarm clock settings on the user's display.
STATUS m48t37AlarmShow (void)
This routine retrieves the current alarm clock settings and sends them to the user's display.
OK, or ERROR if unable to retrieve current settings.
m48t37FailsafeSet( ) - Set failsafe timer parameters/feed failsafe timer.
STATUS m48t37FailsafeSet ( UCHAR seconds, /* timer interval, 0 = disarm, 1-31 = arm, */ /* else ERROR */ BOOL reset /* board reset or interrupt on timer expiration */ )
This routine sets the failsafe timer configuration parameters. It is also used to "feed" the failsafe to prevent expiration of the timer.
The reset parameter determines whether timer expiration will generate an interrupt or a board reset. If set to FALSE an interrupt will be generated. If set to TRUE a board reset will occur.
If failsafe timer expiration is configured to generate an interrupt, the interrupt must be enabled and a handler attached before m48t37FailsafeSet is called to arm the failsafe timer. When the failsafe interrupt occurs, m48t37FailsafeSet must be called with "seconds" set to 0 to clear the interrupt, or m48t37FailsafeCancel must be called before the handler returns.
OK if successful or ERROR if parameter error.
m48t37, m48t37FailsafeGet ()
m48t37FailsafeGet( ) - Get failsafe timer parameters.
STATUS m48t37FailsafeGet ( UCHAR * seconds, /* address for returning seconds (or NULL) */ BOOL * reset /* address for returning expiration action */ /* (or NULL) */ )
This routine gets the failsafe timer configuration parameters. Note that it returns the current configuration of the timer, not the amount of time remaining until timer expiration.
OK always.
m48t37, m48t37FailsafeSet ()
m48t37FailsafeCausedReset( ) - Determine if failsafe timer caused last board reset.
BOOL m48t37FailsafeCausedReset (void)
This routine determines whether the failsafe timer caused the last board reset.
TRUE if failsafe timer caused last board reset, FALSE if not.
m48t37FailsafeShow( ) - Show the current failsafe timer parameters.
STATUS m48t37FailsafeShow (void)
This routine displays the current failsafe timer configuration parameters.
OK always
m48t37, m48t37FailsafeSet (), m48t37FailsafeGet ()
m48t37Init( ) - Initialize the M48T37.
STATUS m48t37Init (void)
This routine initializes the M48T37 by connecting the interrupt handler function pointer to the RTC interrupt line. This routine enables the RTC interrupt.
OK always
m48t37FailsafeCancel( ) - cancel the failsafe timer
STATUS m48t37FailsafeCancel (void)
This routine cancels the failsafe timer.
OK always.
m48t37, m48t37FailsafeSet ()