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):
Bit | Description |
---|---|
0 | 0=Day is 0-based |
1=Day is 1-based | |
1 | 0=Month is 0-based |
1=Month is 1-based | |
2 | 0=The full two-byte year field is stored |
1=The full two-byte year field is not stored |
If bit 2 is set, RISC OS behaves as if only the two least significant bits of YearLO are stored, and will construct the rest of the year from the value held in CMOS RAM.
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 |
iicop | Pointer to routine to use to perform IIC transfers |
kernel | Parameter that must be passed to iicop to help the kernel identify the originator of the IIC request |
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:
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) };
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:
Parameter | Description |
---|---|
transfers | Pointer to array of iic_transfer structures |
count | Number of iic_transfer structures |
kernel | kernel value given to readtime_/_writetime |
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.
HALDeviceSysPeri_RTC is currently only supported by the Cortex branch of the kernel. Additionally, only RTCs on IIC bus 0 are currently supported, and a HAL RTC will only be used if (a) the kernel’s own IIC RTC code is disabled or failed to detect an RTC, and (b) the device was registered during the call to HAL_InitDevices.
Device ID | Description | Implemented in |
---|---|---|
HALDeviceID_RTC_TPS65950 | TPS65950-compatible real-time clock | HAL.OMAP3.s.RTC |