HALDeviceSysPeri_RTC

Hardware Abstraction Layer

» HAL Device API

» List of HAL devices

» Real-time clock

(HALDeviceSysPeri_RTC)

Device API

Currently, only API version 0 is defined. API version 0 only supports RTC devices located on the IIC bus.

struct rtcdevice
{
  struct device dev;
  uint8_t timeformat;
  uint8_t formatflags;
  uint8_t padding[2];
  int (*readtime)(struct rtcdevice *rtc,
                  struct rtctime *time,
                  int (*iicop)(struct iic_transfer *transfers,
                               int count,
                               uint32_t kernel),
                  uint32_t kernel);
  int (*writetime)(struct rtcdevice *rtc,
                   const struct rtctime *time,
                   int (*iicop)(struct iic_transfer *transfers,
                                int count,
                                uint32_t kernel),
                   uint32_t kernel);
};

The timeformat and formatflags fields describe the time format that the RTC expects to use when communicating with RISC OS. Currently the only defined timeformat value is 0, indicated BCD.

formatflags is as follows (for BCD):

For situations where bits 2-3 do not equal 10, RISC OS will use the YearLO and YearHI values stored in CMOS to augment the limited data available from the RTC.

Reading and writing the time

The readtime and writetime entry points are used to read from and write to the RTC, respectively. The parameters are as follows:

Upon completion, one of the following return codes must be used:

The rtctime struct which is used to communicate with RISC OS is as follows:

struct rtctime
{
  uint8_t Centiseconds; // BCD centiseconds (00-99)
  uint8_t Seconds; // BCD seconds (00-59)
  uint8_t Minutes; // BCD minutes (00-59)
  uint8_t Hours; // BCD hours (00-23)
  uint8_t DayOfMonth; // BCD day of month (0- or 1- based)
  uint8_t Month; // BCD month (0- or 1- based)
  uint8_t YearLO; // BCD year low value (00-99)
  uint8_t YearHI; // BCD year high value (19-22 due to 5-byte time limits)
};

Note that the writetime routine must be able to cope with 3 different situations:

1. Full time update – all the rtctime members are valid and are expected to be written to the RTC
2. Time update – The DayOfMonth, Month, YearLO and YearHI members will be set to 255. Only the time portion of the RTC should be updated.
3. Date update – The Centiseconds, Seconds, Minutes and Hours members will be set to 255. Only the date portion of the RTC should be updated.

Performing IIC transfers

The iicop function pointer that’s passed to readtime and writetime should be used to perform IIC transfers when communicating with the RTC hardware. Parameters are as follows:

Upon completion, iicop will return one of the HAL IIC return codes (barring IICSTATUS_INPROGRESS).

Note that the riscos_retry bit of the first iic_transfer in the list can be used to instruct RISC OS to retry the IIC transfer if it fails.

Note – The iicop function pointer is obsolete, as the HAL can just use RISCOS_IICOpV.

Support in RISC OS

Currently the kernel will only use a HAL RTC if (a) the kernel’s own IIC RTC code is disabled or failed to detect an RTC, and (b) the RTC device was registered during the call to HAL_InitDevices.

Also be aware that the kernel currently ignores any RTC device that isn’t attached to IIC bus 0. This limitation is due to be removed, as it serves no purpose.

Known implementations

Information sources: Kernel.Hdr.HALDevice, Kernel.Hdr.RTCDevice in CVS