clock.h

* This a software code module for a time-of-day clock object. * The clock may be fixed 12-hour, fi

/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 *
 *  Copyright (c) 2007 by Qu chun lei [e-mail]
 *
 *  Filename:  CLOCK.H
 *  Module:    1302C
 *  Language:  ANSI C
 *  $Revision: 18 $
 *
 *  DEFINITION
 *   This is a software code module for a time-of-day clock object.
 *   The clock may be fixed 12-hour, fixed 24-hour, or dynamically
 *   configurable between these two types. Clock data can be accessed
 *   as a binary number representing the number of minutes since midnight
 *   or a BCD number formatted according to the time-of-day description
 *   in the TIME module 0404x. The functions work with time-of-day values
 *   which conform to normally accepted clock values of 1:00 to
 *   12:59 BCD / 0 to 719 binary for a 12-hour clock or clock values
 *   00:00 to 23:59 BCD / 0 to 1439 binary for a 24-hour clock.  On power-up
 *   the clock is 12:00 BCD / 0 binary for a 12-hour or dynamically
 *   configurable clock, or 00:00 BCD / 0 binary for a 24-hour clock.
 *
 *  CONSTRAINTS
 *  Requires module 0404C TIME for time math functions
 *
 *  ACCESS FUNCTIONS
 *  ClockBinary            Returns the current binary time of day
 *  ClockBinarySet         Sets the clock to a new binary time value
 *  ClockBcd               Returns the current BCD time of day
 *  ClockBcdSet            Sets the clock to a new BCD time value
 *  ClockStart             Starts the clock
 *  ClockStop              Stops the clock
 *  ClockActive            Reports whether or not the clock is running
 *  ClockConfig            Reports the current 12/24 clock mode
 *  ClockConfigSet         Sets the current 12/24 clock mode
 *  ClockAmPmBinary        Reports current binary time of day and am/pm
 *  ClockAmPmBcd           Reports current BCD time of day and am/pm
 *  ClockProcess           Updates the time of day
 *
 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */

#ifndef CLOCK_H
#define CLOCK_H

#include "dac.h"
#include "time.h"


/*------------------*
 |  Module options
 *------------------*/

#define CLOCK_CONTROL        FALSE  /* True to allow the clock to be turned
                                       on and off dynamically such as on
                                       power-up or during user entry, or
                                       false to run continuously and exclude
                                       the start/stop functions which saves
                                       memory                                */
#define CLOCK_CONFIGURABLE   FALSE  /* True to allow dynamic selection of
                                       12/24 hour mode                       */
#define CLOCK_24             FALSE  /* True for 24-hour clock configuration
                                       or false for 12-hour clock
                                       configuration, ignored if
                                       CLOCK_CONFIGURABLE is TRUE            */
#define CLOCK_AM_PM_BINARY   FALSE  /* True if ClockAmPmBinary function is
                                       included, false if excluded           */
#define CLOCK_AM_PM_BCD      FALSE  /* True if ClockAmPmBcd is included,
                                         false if excluded                   */
#define CLOCK_BINARY         TRUE   /* True if ClockBinary function is
                                         included, false if excluded         */
#define CLOCK_BCD            TRUE   /* True if ClockBcd is included, false
                                         if excluded                         */
#define CLOCK_BINARY_SET     FALSE  /* True if ClockBinarySet is included,
                                         false if excluded                   */
#define CLOCK_BCD_SET        TRUE   /* True if ClockBcdSet is included,
                                         false if excluded                   */
#define CLOCK_OPTIMIZE_ROM   TRUE   /* True to optimize ROM, false to
                                       optimize RAM                          */
#define CLOCK_DAY_OF_WEEK    FALSE  /* True if ClockDayOfWeek is included,
                                         false otherwise */


/*------------------*
 |  Types
 *------------------*/

typedef UINT8 TClockAmPm;
#define CLOCK_AM           (TClockAmPm)0
#define CLOCK_PM           (TClockAmPm)1

typedef UINT8 TClockDayOfWeek;
#define CLOCK_SUNDAY       (TClockDayOfWeek)0
#define CLOCK_MONDAY       (TClockDayOfWeek)1
#define CLOCK_TUESDAY      (TClockDayOfWeek)2
#define CLOCK_WEDNESDAY    (TClockDayOfWeek)3
#define CLOCK_THURSDAY     (TClockDayOfWeek)4
#define CLOCK_FRIDAY       (TClockDayOfWeek)5
#define CLOCK_SATURDAY     (TClockDayOfWeek)6



/*--------------------*
 |  Public functions
 *--------------------*/


#if CLOCK_BINARY
/*---------------------------------------------------------------------------*
 |  ClockBinary
 |
 |  Returns the current binary time of day in minutes since midnight
 |
 |  On Entry:  No requirements.
 |
 |  On Exit:   Returns the time of day.
 *---------------------------------------------------------------------------*/

UINT16 ClockBinary(void);
#endif


#if CLOCK_BINARY_SET
/*---------------------------------------------------------------------------*
 |  ClockBinarySet
 |
 |  Saves a new binary time value as the current time of day in minutes
 |  since midnight
 |
 |  On Entry:  New binary time value.
 |
 |  On Exit:   Returns whether new time was stored as the clock value
 |             (whether new time was valid)
 *---------------------------------------------------------------------------*/

BOOLEAN ClockBinarySet(UINT16 newTime);
#endif


#if CLOCK_BCD
/*---------------------------------------------------------------------------*
 |  ClockBcd
 |
 |  Returns the current BCD time of day
 |
 |  On Entry:  No requirements.
 |
 |  On Exit:   Returns the time of day.
 *---------------------------------------------------------------------------*/

TTimeOfDay ClockBcd(void);
#endif


#if CLOCK_BCD_SET
/*---------------------------------------------------------------------------*
 |  ClockBcdSet
 |
 |  Saves a new BCD time value as the current time of day
 |
 |
 |  On Entry:  New BCD time value.
 |
 |  On Exit:   Returns whether new time was stored as the clock value
 |            (whether new time was valid)
 *---------------------------------------------------------------------------*/

BOOLEAN ClockBcdSet(TTimeOfDay newTime);
#endif


#if CLOCK_DAY_OF_WEEK
/*---------------------------------------------------------------------------*
 |  ClockDayOfWeek
 |
 |  Returns the current day of week
 |
 |  On Entry:  No requirements.
 |
 |  On Exit:   Returns the day of week.
 *---------------------------------------------------------------------------*/

TClockDayOfWeek ClockDayOfWeek(void);
#endif


#if CLOCK_DAY_OF_WEEK
/*---------------------------------------------------------------------------*
 |  ClockDayOfWeekSet
 |
 |  Sets the current day of week
 |
 |  On Entry:  Day of week.
 |
 |  On Exit:   TRUE if valid value, otherwise FALSE.
 *---------------------------------------------------------------------------*/

BOOLEAN ClockDayOfWeekSet(TClockDayOfWeek day);
#endif


#if CLOCK_CONTROL
/*---------------------------------------------------------------------------*
 |  ClockStart
 |
 |  Starts the clock
 |
 |  On Entry:  No requirements
 |
 |  On Exit:   Returns nothing
 *---------------------------------------------------------------------------*/

void ClockStart(void);
#endif


#if CLOCK_CONTROL
/*---------------------------------------------------------------------------*
 |  ClockStop
 |
 |  Stops the clock
 |
 |  On Entry:  No requirements
 |
 |  On Exit:   Returns nothing
 *---------------------------------------------------------------------------*/

void ClockStop(void);
#endif


#if CLOCK_CONTROL
/*---------------------------------------------------------------------------*
 |  ClockActive
 |
 |  Reports the current clock status (on/off)
 |
 |  On Entry:  No requirements
 |
 |  On Exit:   Returns true if clock is active, false if not active
 *---------------------------------------------------------------------------*/

BOOLEAN ClockActive(void);
#endif


#if CLOCK_CONFIGURABLE
/*---------------------------------------------------------------------------*
 |  ClockConfig
 |
 |  Reports the current 12/24 clock mode
 |
 |  On Entry:  No requirements
 |
 |  On Exit:   Returns time of day format
 *---------------------------------------------------------------------------*/

TTimeOfDayFormat ClockConfig(void);
#else
#define ClockConfig()      CLOCK_24
#endif


#if CLOCK_CONFIGURABLE
/*---------------------------------------------------------------------------*
 |  ClockConfigSet
 |
 |  Sets the current 12/24 clock mode
 |
 |  On Entry:  New time of day format
 |
 |  On Exit:   Returns nothing
 *---------------------------------------------------------------------------*/

void ClockConfigSet(TTimeOfDayFormat newClockFormat);
#endif


#if CLOCK_AM_PM_BINARY
/*---------------------------------------------------------------------------*
 |  ClockAmPmBinary
 |
 |  Returns proper binary time of day in proper configuration and am/pm
 |
 |  On Entry:  No requirements
 |
 |  On Exit:   Time of day and AM/PM
 *---------------------------------------------------------------------------*/

UINT16 ClockAmPmBinary(TClockAmPm *amPm);
#endif


#if CLOCK_AM_PM_BCD
/*---------------------------------------------------------------------------*
 |  ClockAmPmBcd
 |
 |  Returns proper BCD time of day in proper configuration and am/pm
 |
 |  On Entry:  No requirements
 |
 |  On Exit:   Time of day and AM/PM
 *---------------------------------------------------------------------------*/

TTimeOfDay ClockAmPmBcd(TClockAmPm *amPm);
#endif


/*---------------------------------------------------------------------------*
 |  ClockProcess
 |
 |  Updates the time of day clock.  This function should be called once per
 |  minute.  Time of day hours, minutes, are updated.
 |
 |  On Entry:  No requirements
 |
 |  On Exit:   Returns nothing
 *---------------------------------------------------------------------------*/

void ClockProcess(void);


#endif