How to use the RTC driver

How to use the RTC driver

****************************************************************
1. Introducation
****************************************************************
ADSP21535 has one Real Time Clock RTC device, and the RTC driver
is designed as a standard Linux RTC driver.

The RTC device major/minor numbers:
major             minor
10                135

The RTC device name is /dev/rtc.

When the read function is called, the application is blocked
until the RTC interrupt is generated.

****************************************************************
2. system call
****************************************************************
The RTC device driver is designed as a standard Linux RTC
driver, and the following system calls are supported.

2.1 open: The standard open function call.
int open("/dev/rtc", int oflag, /* mode_t mode */...);

The open function is used to establish the connection between the RTC
device with a file descriptor.
- oflag:
  O_RDONLY   Open for reading only
  O_WRONLY   Open for writing only
  O_RDWR     Open for reading and writing

USAGE:
------
int fd;

fd = open("/dev/rtc", O_RDONLY, 0);
...
close(fd);

2.2 close: The standard open function call.
int close(int file_handler);

The close function is used to disconnect the RTC device with the relevant
file descriptor.

USAGE:
------
int fd;

fd = open("/dev/rtc", O_RDONLY, 0);
...
close(fd);

2.3 ioctl: the standard ioctl function call(refer to section 3).
int ioctl(int file_handler, int request, /* arg */...);

The ioctl command is used to configure the RTC device.

USAGE:
------
int fd;
struct rtc_time rtc_tm;
int ret;

fd = open("/dev/rtc", O_RDONLY, 0);
...
// the ioctl command RTC_RD_TIME is used to read the current timer.
// about the detail ioctl command, refer to section 3
ret = ioctl(rtc_fd, RTC_RD_TIME, &rtc_tm);
...
close(fd);

2.4 read:  the standard read function call.
ssize_t read(int file_handler, viod *buf, size_t nbytes);

In the RTC driver, the read function is used to wait for the RTC device interrupt.
When call the read function, the application is locked until a interrupt is generated.

USAGE:
------
int fd;
int ret;
struct rtc_time rtc_tm;
unsigned long data;

fd = open("/dev/rtc", O_RDONLY, 0);
ret = ioctl(fd, RTC_ALM_SET, &rtc_tm);
// call the read function to wait the Alarm interrupt
ret = read(fd, &data, sizeof(unsigned long));
...
close(fd);

****************************************************************
3. RTC deivce ioctl
****************************************************************
RTC_SWCNT_OFF: This ioctl does not need an argument, and it can
               be used to disable the RTC stop-watch interrupt.

RTC_SWCNT_ON:  This ioctl does not need an argument, and it can
               be used to enable the RTC stop-watch interrupt.

RTC_AIE_OFF:   This ioctl does not need an argument, and it can
               be used to disable the RTC alarm interrupt.   

RTC_AIE_ON:    This ioctl does not need an argument, and it can
               be used to enable the RTC alarm interrupt.    

RTC_UIE_OFF:   This ioctl does not need an argument, and it can
               be used to disable the RTC update interrupt.   

RTC_UIE_ON:    This ioctl does not need an argument, and it can
               be used to enable the RTC update interrupt.   

RTC_ALM_READ:  This ioctl needs one argument(struct rtc_time *),
               and it can be used to get the current RTC alarm
               parameter.   

RTC_ALM_SET:   This ioctl needs one argument(struct rtc_time *),
               and it can be used to set the RTC alarm.   

RTC_RD_TIME:   This ioctl needs one argument(struct rtc_time *),
               and it can be used to get the current RTC time.   

RTC_SET_TIME:  This ioctl needs one argument(struct rtc_time *),
               and it can be used to set the current RTC time.   

RTC_EPOCH_READ:This ioctl needs one argument(long *), and it
               can be used to get the current RTC epoch.   

RTC_EPOCH_SET: This ioctl needs one argument(long), and it can
               be used to set the current RTC epoch.   

RTC_SWCNT_SET: This ioctl needs one argument(long), and it can
               be used to set the current RTC stop-watch (the
               unit is minute).   

RTC_SWCNT_RD:  This ioctl needs one argument(long *), and it
               can be used to get the current RTC stop-watch
               (the unit is minute).   

****************************************************************
4. Caution
****************************************************************