Pyromaniac

Pyromaniac PRM: Real Time Clock Vector

Pyromaniac PRM: Real Time Clock Vector

RISC OS PyromaniacReal Time Clock Vector

Introduction

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 RiscPC 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 RiscPC 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.

Software vectors

Vector RTCVVector 3F
Abstracted interface to the real time clock
R0=reason code:

ValueMeaning
0Read time from hardware Real Time Clock
1Update hardware Real Time Clock with a new value

R0 - R8=Dependant on the reason code
R0=-1 if reason claimed
Interrupts are undefined
Fast interrupts are enabled
Processor is in SVC mode
Vector is not re-entrant

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

Vector RTCV 0Vector 3F
Read time from hardware Real Time Clock
R0=0 (reason code)
R0=-1 if reason 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)
Interrupts are undefined
Fast interrupts are enabled
Processor is in SVC mode
Vector is not re-entrant

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.

Vector RTCV 1Vector 3F
Update hardware Real Time Clock with a new value
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)
R0=-1 if reason claimed
R1 - R8preserved
Interrupts are undefined
Fast interrupts are enabled
Processor is in SVC mode
Vector is not re-entrant

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 yet have been updated to reflect these values. Any of the values passed in R1-R8 value may be -1 to indicate that it is not to be modified.