Reorganising RTC handling

Aims

To remove the RTC hardware knowhow from the kernel.

Background

Currently the handling of real time clocks is somewhat diffuse, some platforms present a HAL device which describes the RTC, and some rely on the kernel to probe known IIC addresses after which the kernel manages the hardware using its built in drivers. The kernel doesn’t need an RTC to boot (compare with the other hardware it knows about: RAM, ROM, CPU, CMOS) so doesn’t need to hang on to managing this driver.

The RTCAdjust module also talks to the clock, effectively containing a duplicate (read only) set of hardware drivers for the IIC addresses the kernel understands. Currently RTCAdjust doesn’t support the HAL device based clocks, hence platforms presenting their clocks via that interface can be subject to drift while the computer is running.

Lastly, where enabled, the NetTime module can request updates to the clock from a remote time server. It contains yet another duplicate set of clock correction code, using the same algorithm as RTCAdjust.

Proposed SWIs

The RTC module provides 4 SWIs.

For a definition of ‘rtctime’ see the HALDeviceSysPeri_RTC. All rtctime values are in UTC, any timezone and daylight saving changes are applied higher up the software stack.

_kernel_oserror *RTC_Features(int *flags);

A rough parallel to FileCore_Features allowing functionality to be added later and for clients to be able to determine the extra (potentially incompatible) programmer interfaces. Also, can be used as a cheap test of whether the module is present or not. All flags are initially zero.

_kernel_oserror *RTC_Read(struct rtctime *);

This is broadly equivalent to the kernel’s ReadTime function. The time is read from the hardware.

_kernel_oserror *RTC_Write(const struct rtctime *);

This is broadly equivalent to the kernel’s SetTime function. The time is written to the hardware.

_kernel_oserror *RTC_Adjust(const struct rtctime *, int priority);

Propose a time slew correction to apply over the next hour. The value of ‘priority’ will indicate the quality of the time correction, allowing adjustments potentially from multiple sources – for example a default adjustment by checking the hardware clock and an external adjustment from a trusted time server. The priority values will be centrally allocated, possibly in a simple text description (in a similar manner to the task priority assignments as used by the RTSupport scheduler).

Proposed commands

No star commands offered.

Implementation

The module will be written in C.

This module will only operate on HAL based systems, since there’s no net increase in functionality and the RTC is currently served by the kernel’s driver and the RTCAdjust module, both of which are further abstracted by OS_Word 14 and 15.

Where the HAL device indicates that the RTC hardware doesn’t store years (or centuries) these will be saved in the conventional ‘YearCMOS’ CMOS locations.

If the HAL does not offer any RTC peripherals a fallback software clock will be run, resetting to 01-Jan-1970 (the Unix epoch) on every power cycle.

Affected components

NetTime current kills the RTCAdjust module and attempts to adjust the clock itself when network time updates are available. this module will need updating to preferentially use the RTC_Adjust SWI instead (falling back to its old behaviour when used on earlier systems).

The RTCAdjust module will be removed from ROM builds.

The kernel will be updated to exclusively call the RTC module, and no longer probe for one at power up. Probing for CMOS will still be performed, so in the case of a combined clock and CMOS (eg. on IOMD) the kernel may also require access to the IIC peripheral at times.

The Tungsten HAL will be updated to add a HALDeviceSysPeri_RTC device.

The IOMD HAL will be updated to add a HALDeviceSysPeri_RTC device.

The HALDeviceSysPeri_RTC will use RISCOS_IICOpV and drop the ‘iicop’ function pointer, as well as permitting the IIC device to be on a bus other than bus 0.

That sounds fine to me. I’m assuming that RTC_Read will return a variety of errors based around the RTC state? (no RTC, RTC is stopped, RTC read failed, etc. – much like the return codes used by the HAL device)

For RTC_Adjust, are you sure it’s a good idea to pass in an rtctime value? Calculating the correct deltas might be a bit tricky compared to (say) specifying a simple centisecond offset. Case in point: The OMAP3 (and I’m assuming OMAP4) RTC has a register that allows the RTC to be fine-tuned, by specifying a value to add/subtract from the 32kHz RTC timer every hour. It would be nice if the RTC module API allowed support for that feature to be easily implemented, as hardware-based drift correction has the obvious advantage that (once properly calibrated) it will continue to function even when the machine is turned off.

Will the OMAP HALs need amending?

If the HAL does not offer any RTC peripherals a fallback software clock will be run, resetting to 01-Jan-1970 (the Unix epoch) on every power cycle.

Acorn generally had the clock setting to 01-Jan- ‘ROM Build Year’ My vote is for 01-Jan-‘ROM Build Year-1’ and an error box on booting to tell users their clock is not set.
I have on a RiscPC RO 3.70 an obey file in $.Boot.Choices.Boot.Tasks called CheckYear of:

If Sys$Year<“2006” Then Error 0 The date is incorrect i.e. less than 2006

Something to that effect would be useful.

It contains yet another duplicate set of clock correction code, using the same algorithm as RTCAdjust.

Yeah… It’s starting to sound a little bit illogical.

Also, can be used as a cheap test of whether the module is present or not.

Couldn’t you just try to look up the SWI number from the name and see if that fails? ;-)

Should there not be a SWI to force-sync the soft clock from hardware, or vice versa? This would remove the requirement to need to read and write the RTC specifically. This, a net time client could update the RISC OS clock and then call the sync function to ensure that the hardware is in step.
This would be analogous to clock() vs hwclock() on a Linux system, with the syncing part handled by the module where it can be done with one SWI and no memory block allocations or fiddling…

No star commands offered.

As above, maybe a *SyncClock (akin to hwclock --systohc).

If the HAL does not offer any RTC peripherals a fallback software clock will be run, resetting to 01-Jan-1970 (the Unix epoch) on every power cycle.

Since we aren’t Unix, could we default to something a little less ridiculous? 1970 predates me, never mind RISC OS! I like the (build_year – 1) suggestion.

I like the (build_year – 1) suggestion.

Regular new build releases:
“Dear ROOL helpdesk¹ my beagle/pi/xxxx keeps altering the time to last year, is the hardware broken?”
“Dear ROOL helpdesk my beagle/pi/xxxx has last years date, I don’t know if this is recent and the time is a bit funny”

Nah, sorry, setting a default failure mode that points to before dektop devices is a more familiar failure mode for most users.

¹ One day it will be so fashionable to run RO that ROOL have to have a helpdesk

I’m assuming that RTC_Read will return a variety of errors based around the RTC state?

Correct, probably with a 1:1 mapping!

For RTC_Adjust, are you sure it’s a good idea to pass in an rtctime value?

I think so, though I reserve the right to change my mind on a whim. I guess I’m biassed by NetTime which gets a UTC time from the time server, so why burden it in having to ask for the time and calculate a delta (which all clients would have to do) when this could be handled centrally by the RTC module (which needs to get it into a delta anyway). I hadn’t particularly considered clock hardware that an trim itself – my thinking is if the generic module adjusts the clock correctly already then writing and debugging another method is probably wasted effort. It can always be added later with a feature flag I suppose.

Will the OMAP HALs need amending?

I don’t think so, beyond lifting the IIC bus restrictions, since they already support HALDeviceSysPeri_RTC.

Also, can be used as a cheap test of whether the module is present or not.

Couldn’t you just try to look up the SWI number from the name and see if that fails?

True, but string comparison always feels a bit clumsy when there’s a way to do it with numbers.

Should there not be a SWI to force-sync the soft clock from hardware, or vice versa?

There is, it’s OS_ResyncTime (RISC OS 3.80 and later).

Acorn generally had the clock setting to 01-Jan- ‘ROM Build Year’ My vote is for 01-Jan-‘ROM Build Year-1’ and an error box on booting to tell users their clock is not set.

Well it’s Acorn’s kernel that’s setting it to 1970 currently, so my proposal isn’t proposing to change anything. Change is bad. 1970’s is good.

There is, it’s OS_ResyncTime (RISC OS 3.80 and later).

I think maybe we need a PRM 5b?

Well it’s Acorn’s kernel that’s setting it to 1970 currently, so my proposal isn’t proposing to change anything. Change is bad. 1970’s is good.

Mmm I think there is a difference between what happens if not clock is readable and after doing a power on delete. Almost no one ever had an unreadable clock¹. Many users will have experienced a CMOS reset.
On RISC OS 3.70 a power on delete gives 1997 the build year 1996+ the year increment from the clock chip.

Therefore 1970 would be a new thing for 99% of people. So I think build year -1 is still best.

re booting with an error message if year found to less than boot year, there is one problem I foresee if the computer is set to auto run say a control program. Getting a non multitasking error box which would stop the program restarting after a power outage is not good. Presumably a non error window could be used offering to run Alarm/nettime?

Does a Pandora have a battery backed RTC?

Yes.

Actually Andrew has reminded me it is more complicated than I wrote. When you fit a Clock Module to a Pi or change the battery on a RiscPC it often goes back to 1900 I think that is always on a Pi and it varies on a RiscPC depending on the OS version fitted. You may remember this was why we groaned when setting the year was changed and you could no longer enter it from the keyboard, 113 increments takes a long time!

You may remember this was why we groaned when setting the year was changed and you could no longer enter it from the keyboard, 113 increments takes a long time!

I’ve long been a fan of LTMDI¹ so I find that a few clicks once leaves me no problems thereafter.

¹ Let The Machine Do It – in this instance this is Let NTP Do It.

just remembered that BeagleBoard users without a batter fitted and PandaBoard users without a clock fitted will have been in that situation but I doubt there are many who haven’t now upgraded with battery/clock board.

Me! ;-) CJE (<cough>you</cough>) offered me a good price for a battery, but I’m concerned with the necessity for setting charging currents and such. I was going to ask around what the “life” of a battery is, must I power up the Beagle daily, weekly, monthly, etc. However, it work we’re going a run of six day weeks and that question, like pretty much everything else in my life, was put aside and forgotten about.

At any rate, yes, the 1970 thing was a surprise to me given I was used to RO3.7 style behaviour. And… didn’t 3.1 default to something odd like 1981?

There is, I remember, precedent for 1970. That’s what the clock on the IBX-100 “Bush box” is stuck at. Gee, pat me on the head for digging up a ten year old memory from nowhere!

You may remember this was why we groaned when setting the year was changed and you could no longer enter it from the keyboard, 113 increments takes a long time!

??? Ain’t no WAY I’ll be wasting time with that many year increments (113? aren’t you 70 over?). There’s an easier way. Go to the command line and set Sys$Year…

with that many year increments (113? aren’t you 70 over?)

No the Pi defaults to 1900 the first time it is powered up after fitting one of our clock modules. 1900+113=2013 if using base 10!

Go to the command line and set Sys$Year…

Does that get written to the clock? I thought it was just a software setting?

Which reminds me, I just loved working out the serendipity that 6×9=42 in base 13. Apparently Douglas Adams didn’t realise it, until it was pointed out to him.

I think there is a difference between what happens if not clock is readable and after doing a power on delete.

The logic is very simple

• if it’s a CMOS reset, the year bytes in the CMOS (not the clock!) are set to 2000
• if there is no clock then a fake one starts at the Unix epoch (1970)
• if there is a clock that is used
• if there is a clock but it only has a limited support for years (eg. 2 year bits) you get the year out of the CMOS mixed with however many bits the hardware implements

On a Pi then, if you boot up with no clock initially it’ll end up with 1970 in the year CMOS. If you then turn off and add a clock expansion board with a DS1338 (1 byte year) the next power on is going to be 1900 (19 from the CMOS + 00 from the clock).

This logic isn’t in the scope of this module, this is covered in chapter 4 of my new book “Feature creep when you ask more than one person for an opinion” available from all good booksellers.

Which reminds me, I just loved working out the serendipity that 6×9=42 in base 13.

That will have my mind in knots for days/weeks/years if I accept it.

Sorry, “working out the seredipity”? Serendipity IS
I really think you need to understand that seredipity just simply is not something to be “worked out”

I recommend looking at a decent dictionary.

This logic isn’t in the scope of this module, this is covered in chapter 4 of my new book “Feature creep when you ask more than one person for an opinion” available from all good booksellers.

Ah, that one.
A while back I adopted a wonderful technique which always satisfies all relevant parties:

Look at the request, decide what they need(not what they asked for), document (and submit to requestor) implement.
Await complaint and point back to document.

BTW. Whilst the comment might simply be one techie sympathising with another – I totally agree on the logic for the date setting. Alternately we could have it set to a random date/time.
Unless people want ONE single default failback time setting leave things alone.

“Which reminds me, I just loved working out the serendipity that 6×9=42 in base 13.”
That will have my mind in knots for days/weeks/years if I accept it.

Yes that was very badly worded, what I should have said was: “I worked out that 6×9=42 in base 13 and thought how clever, but then found out that it was serendipity.”

The logic is very simple
if it’s a CMOS reset, the year bytes in the CMOS (not the clock!) are set to 2000
if there is no clock then a fake one starts at the Unix epoch (1970)
if there is a clock that is used
if there is a clock but it only has a limited support for years (eg. 2 year bits) you get the year out of the CMOS mixed with however many bits the hardware implements
On a Pi then, if you boot up with no clock initially it’ll end up with 1970 in the year CMOS. If you then turn off and add a clock expansion board with a DS1338 (1 byte year) the next power on is going to be 1900 (19 from the CMOS + 00 from the clock).

Thanks for the explanation Sprow

This logic isn’t in the scope of this module, this is covered in chapter 4 of my new book “Feature creep when you ask more than one person for an opinion” available from all good booksellers.

Which module has it within its scope?

Surely the relevant module when Detecting a stupid date e.g. 1.1.1900 could improve the situation?