Dallas/Maxim DS1390 Wallclock Device Driver
Prev Chapter 126. Dallas/Maxim DS1390 Wallclock Device Driver Next

Name

CYGPKG_DEVICES_WALLCLOCK_DALLAS_DS1390 — eCos Support for the Dallas/Maxim DS1390 Serial Real-Time Clock

Description

This package CYGPKG_DEVICES_WALLCLOCK_DALLAS_DS1390 provides a device driver for the wallclock device in the Dallas/Maxim DS1390 Serial Real-Time Clock chips. The driver can also be used with any other chips that provide the same interface to the clock hardware.

The package will usually be loaded into the configuration automatically whenever selecting a target which contains a compatible chip. By default it will provide the standard eCos wallclock device, although another implementation such as software emulation may be selected if desired. By default, for backwards compatability, this driver is configured to provide the original (legacy) “STANDARD” API to the I/O wallclock layer. However, if required the “EXTENDED” API can be configured. The “EXTENDED” API provides for sub-second support as well as standardised alarm handling. If required the default API selection can be overridden by the platform HAL for specific targets. The only other configuration options related to this package allow users to change the compiler flags. If the application does not actually use the wallclock device, directly or indirectly, then the code should get removed automatically at link-time to ensure that the application does not suffer any unnecessary overheads.

Functionality

This wallclock device driver package implements the standard functionality required by the generic wallclock support CYGPKG_IO_WALLCLOCK. The functionality is not normally accessed directly. Instead it is used by the C library time package to implement standard calls such as time and gmtime. The eCos C library also provides a non-standard function cyg_libc_time_settime for changing the current wallclock setting. In addition RedBoot provides a date command which interacts with the wallclock device.

Porting

The DS1390 driver uses the SPI driver API defined by the package CYGPKG_IO_SPI. A suitable SPI device driver must be available for the target. The platform HAL must provide a cyg_spi_device structure cyg_spi_wallclock_ds1390. The platform HAL should initialize this structure and any associated SPI driver specific struture with the correct phase, polarity and chip select parameters for this device.

In addition the DS1390 device driver package CYGPKG_DEVICES_WALLCLOCK_DALLAS_DS1390 should be included in the CDL target entry so that it gets loaded automatically whenever eCos is configured for that target.

Extra API Calls

In addition to the standard wallclock API calls, this driver exports a number of additional functions to permit direct access to additional features of the device. A header, cyg/io/wallclock/ds1390.h is available to define this API. When using the EXTENDED wallclock API this header is included automatically when including the common wallclock I/O driver <cyg/io/wallclock.hxx> header file.

cyg_uint8 cyg_ds1390_read_reg( int addr )
Read and return a single 8-bit register from the DS1390, addr should be in the range 0x00 to 0x0F.
void cyg_ds1390_write_reg( int addr, int val )
Write a single 8-bit register to the DS1390, addr should be in the range 0x00 to 0x0F and val in the range 0x00 to 0xFF.
void cyg_ds1390_set_control( cyg_uint8 val )
Write the DS1390 control register with the content of val.
cyg_uint8 cyg_ds1390_get_control( void )
Read and return the value of the DS1390 control register.
void cyg_ds1390_set_status( cyg_uint8 val )
Write the DS1390 status register with the content of val.
cyg_uint8 cyg_ds1390_get_status( void )
Read and return the value of the DS1390 control register.
void cyg_ds1390_set_charger( cyg_uint8 val )
Write the DS1390 trickle-charge register with the content of val.
cyg_uint8 cyg_ds1390_get_charger( void )
Read and return the value of the DS1390 trickle-charge register.

When the “STANDARD” API is configured the following alarm setting function is exported:

int cyg_wallclock_set_alarm( cyg_uint32 secs )
Set the DS1390 alarm to trigger when the wallclock time matches the value of secs. The DS1390 alarm will match only up to days of the month, so the alarm cannot be set more than one month in the future. This function only initializes the DS1390 to generate the alarm interrupt; it is the responsibility of the caller to attach an ISR to the appropriate vector and unmask it in the interrupt controller.

The following helper function is provided irrespective of the “STANDARD” or “EXTENDED” CYGINT_IO_WALLCLOCK_HAS_ALARM configuration. It provides a mechanism to set an alarm for a specific time-of-day.

int cyg_wallclock_set_alarm_time( cyg_uint8 hour, cyg_uint8 min, cyg_uint8 sec )
Set the DS1390 alarm to trigger when the wallclock time matches the specific time-of-day provided by the parameters hour, min and sec. The DS1390 alarm can only be set up to 24-hours in advance. This function only initializes the DS1390 to generate the alarm interrupt; it is the responsibility of the caller to attach an ISR to the appropriate vector and unmask it in the interrupt controller.

If the platform HAL implements the CYGINT_DEVICES_WALLCLOCK_DALLAS_DS1390_STATUS_OSC interface then the following functions are exported:

cyg_bool cyg_wallclock_was_stopped(void)
This call interrogates the software latched state indicating whether the hardware detected that the oscillator had been stopped.
void cyg_wallclock_clr_stopped(void)
This call resets the internal software latched “oscillator was stopped at some point” state.

If the platform HAL implements the CYGINT_DEVICES_WALLCLOCK_DALLAS_DS1390_STATUS_ALARM interface then the following functions are exported:

cyg_bool cyg_wallclock_woken_by_alarm(void)
This call returns the boolean indication of whether an alarm condition was present in the hardware when the device driver was initialised. This feature may be useful for systems that need to react to an alarm that expired whilst the main CPU was powered-off for example.
cyg_bool cyg_wallclock_clr_startup_alarm_seen(void)
This call resets the internal software latched “alarm seen at driver initialisation” state.
Prev Up Next
Chapter 126. Dallas/Maxim DS1390 Wallclock Device Driver Home Chapter 127. Freescale MCFxxxx On-Chip Wallclock Device Driver