Time

Real Time Clock Vector

The Real Time Clock Vector is a means for alternate clock implementations to be provided for differing hardware. The calls which are provided by the Operating System (either within the Kernel or through an extension module) for setting the system time - OS_Word 14 calls - are decoded and passed to this vector for processing.

The time values passed to the RTCV handlers will be specified as UTC time. That is, they will have had any time zone or daylight saving time adjustments removed from them. Handlers should use the values directly with the suitable hardware.

Certain clock implementations, for example the Risc PC clock chip, do not provide sufficient information to allow the values to be read directly from the chip and returned. In such cases, additional steps may be taken by the hardware driver.

The Risc PC clock chip driver code is limited by only storing a year value in the range 0-3. As such, two NVRAM bytes have been allocated to augment this (byte &80 and &81). Should similar adjustments be required for other hardware, it is recommended that these bytes be used. During the vector call it is safe to issue NVRAM OS_Byte calls.

Vector RTCV (&3F)

On entry

   R0 = reason code :
        0 : Read time
        1 : Write time
   Other : reserved
   R1..R8 = parameters dependant on the reason code

On exit

   R0 = -1 if reason claimed

The Real Time Clock vector is called to manipulate the real time clock.

RTCV 0 (read time)

On entry

   R0 = 0 (reason code)

On exit

   R0 = -1 if claimed
   R1 = centiseconds (0-99)
   R2 = seconds (0-59)
   R3 = minutes (0-59)
   R4 = hours (0-23)
   R5 = day of month (1-31)
   R6 = month (1-12)
   R7 = year (0-99)
   R8 = century (19-21)

This reason code is called when it is necessary to synchronise the internal clock with the hardware-supplied time source. For devices which take a significant time to be read, the driver may initiate a request of the time from the hardware and pass on the call. When the hardware has been read, such a driver should call SWI OS_ResyncTime request to update the Operating System with the new values and notify other clients of an updated internal clock.

Where inaccurate values are available from hardware, the driver should return the middle value for the relevant range.

RTCV 1 (write time)

On entry

   R0 = 1 (reason code)
   R1 = centiseconds (0-99)
   R2 = seconds (0-59)
   R3 = minutes (0-59)
   R4 = hours (0-23)
   R5 = day of month (1-31)
   R6 = month (1-12)
   R7 = year (0-99)
   R8 = century (19-21)

On exit

   R0 = -1 if claimed
   R1-R8 preserved

This reason code is called when a request is made to set the hardware clock to a specific value. The Operating System's internal representation will not been updated to reflect these values yet. Any of the values passed in R1-R8 value may be -1 to indicate that it is not to be modified.

This documentation is copyright 3QD Developments Ltd 2013 and may not be reproduced or published in any form without the copyright holders permission. RISC OS is subject to continuous development and improvement as such all information is reproduced by 3QD Developments Ltd in good faith and is believed to be correct at the time of publication E&OE. 3QD Developments Ltd cannot accept any liability for any loss or damage arising from the use of any information provided as part of the RISC OS Documentation.

HTML document version 1.03 3rd November 2015