h6. [[Hardware Abstraction Layer]] h6(. » [[HAL Device API]] h6((. » [[List of HAL devices]] h6(((. » Real-time clock h5. (HALDeviceSysPeri_RTC) h4. Device API Currently, only API version 0 is defined. API version 0 only supports RTC devices located on the IIC bus. <pre> struct rtcdevice { struct device dev; uint8_t timeformat; uint8_t formatflags; uint8_t padding[2]; int (*readtime)(struct rtcdevice *rtc, struct rtctime *time); int (*writetime)(struct rtcdevice *rtc, const struct rtctime *time); }; </pre> 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, indicating BCD. _formatflags_ is as follows (for BCD): |_<. Bit(s) |_<. Description | |/2^. 0 |0=Day is 0-based | |1=Day is 1-based | |/2^. 1 |0=Month is 0-based | |1=Month is 1-based | |/4^. 3-2 |00=INVALID | |01=YearLO is a 2-bit int, and YearHI is not stored | |10=YearLO and YearHI are both 2-digit BCD | |11=YearLO is 2-digit BCD, and YearHI is not stored | 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. h5. 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: |_<. Parameter |_<. Description | |rtc |Pointer to the _rtcdevice_ in use | |time |Pointer to the _rtctime_ struct that is used to communicate the time value to/from RISC OS | Upon completion, one of the following return codes must be used: |_<. Code |_<. Description | |0 |OK - read/write request completed successfully | |-1 |Error - a nonspecific error occured during read/write | |-2 |InvalidTime - For write operations, indicates that the RTC cannot be programmed with the supplied time. For read operations, indicates that the RTC has been detected as containing an invalid time (e.g. following power loss) | The _rtctime_ struct which is used to communicate with RISC OS is as follows: <pre> 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) }; </pre> Note that the _writetime_ routine must be able to cope with 3 different situations: # Full time update - all the _rtctime_ members are valid and are expected to be written to the RTC # Time update - The DayOfMonth, Month, YearLO and YearHI members will be set to 255. Only the time portion of the RTC should be updated. # Date update - The Centiseconds, Seconds, Minutes and Hours members will be set to 255. Only the date portion of the RTC should be updated. h4. Support in RISC OS The [[RTC]] driver module will use a HAL RTC if the RTC device was registered during the call to [[HAL_InitDevices]], otherwise requests to read or write the RTC will only update the soft copy which is initialised to 02-Jan-1970. h4. Known implementations |_<. Device ID |_<. Description |_<. Implemented in | |HALDeviceID_RTC_TPS65950 |TPS65950-compatible real-time clock |HAL.OMAP3.s.RTC | |HALDeviceID_RTC_TWL6030 |TWL6030-compatible real-time clock |HAL.OMAP4.s.RTC | |HALDeviceID_RTC_DS1307 |DS1307 real-time clock |HAL.Tungsten.s.RTC | |HALDeviceID_RTC_PCF8583 |PCF8583 real-time clock |HAL.IOMD.s.RTC | |HALDeviceID_RTC_DS1307 |DS1307 real-time clock |HAL.BCM2835.s.RTC | h6. Information sources: Kernel.Hdr.HALDevice, Kernel.Hdr.RTCDevice in CVS