Technical Reference Manual

SYSTEM TIMING

GENERAL

System timing is controlled by two interrupts:

1. The NMI interrupt handles the real-time clock and auto-switch off delay.
2. The KEYBOARD INTERRUPT provides a frame-counter and handles keyboard delays and display timing etc.

REAL TIME CLOCK

The clock time is stored in binary in 6 fields from $20C5 to $20CA:

Note that:

1. A month of 0 represents JANUARY and a date of 0 represents the 1st day of the month.
2. On a cold start only, the clock is initialised to 1 JAN 1987 00:00:00
3. The real-time clock should not be read directly from these variables because it may be being updated by an NMI. Instead system service TM$TGET should be used to get a valid time. Similarly these variables should not be written to without checking for an NMI.
4. With Models CM, XP and LA TMB_YEAR rolls over to 00 after 99. This behavior is known as the y2k-bug. It is possible to poke a higher value into TMB_YEAR but the date is nevertheless displayed incorrectly and TMB_YEAR will again roll over to 00 at the end of the year.
5. The time stored always represents G.M.T., so on LZ machines the world times and daylight-saving are calculated as offsets from this.

On the LZ there is another time-related system variable:

TMB_24F ($20A6)

TMB_24F stores 2 flags:

• Bit 7 is set for daylight-saving ON, clear for OFF.
• Bit 0 is set for 24 hour mode, clear for 12 hour mode.

These flags can be read or written to at any time.

KEEPING TIME WITH NMI ON

An NMI interrupt is generated from the semi-custom chip every second to provide an accurate real-time clock. When the machine is on, the NMI interrupt updates the time by 1 second, see TM$UPDT.

KEEPING TIME WITH NMI OFF

When NMIs are switched off the processor, (e.g. when the machine is switched off) an internal counter in the semi-custom chip is connected to the NMI line so that NMIs can still be counted, enabling the time to be updated when restoring NMIs to the processor.

The counter has 11 bits, so the maximum time it can store is 2048 secs. When the counter reaches this value, the ACOUT bit of PORT 5 goes high and the machine switches on. Hence the machine can be forced to switch on automatically at any time up to 34mins 8secs after switching off, be pre-counting the counter. This is done when an alarm is due.

Whenever the machine switches on it updates the real-time clock by the amount in the counter (less any pre-counting). If ACOUT is high, and no alarm was due, the machine switches back off immediately after updating the clock. This can be seen as the screen flashes on for an instant, every 34 mins and 8 secs while the machine is off.

To disable NMIs and keep the time, system services BT$NOF and BT$NON should be used.

AUTO-SWITCH-OFF TIME OUT

The following three variables control the auto-switch-off:

The time before the machine switches off (in secs) is stored in TMW_TCNT and is set to $012C on cold start (5 mins). The contents of TMW_TCNT are copied into TMW_TOUT whenever a key is pressed or KB$GETK is called and TMW_TOUT is decremented until zero by the NMI routine every second. If TMW_TOUT is found to be zero in KB$TEST, the machine will switch off.

The contents of TMW_TCNT can be changed at any time to alter the auto-switch-off time, up to a maximum of 65535 seconds (18 hours, 12 mins and 15 secs). If it is set to less than 15, the machine will will still stay on for 15 secs.

To disable the auto-switch-off completely, TMB_SWOF should be set to zero. This will inhibit the NMI from decrementing TMW_TOUT and prevent KB$TEST testing it.

KEYBOARD INTERRUPT TIMERS

The timer 1 compare interrupt is used to scan the keyboard to allow keyboard buffering and to provide a timing service. The time between interrupts is controlled by the variable KBW_TDEL which is initialised on cold start to be $B3DD. This value makes the KI interrupt occur exactly every 50 milliseconds and is used extensively by the operating system for timing purposes.

TMW_FRAM

TMW_FRAM is incremented by 1 on each keyboard interrupt. When $FFFF is reached, it wraps back to $0000. It can be read at any time and used for accurate timing.

DPW_REDY

DPW_REDY is decremented by 1 on each keyboard interrupt until zero is reached. It can be used to provide delays (e.g. TM$WAIT stores D in DPW_REDY and waits for it to reach zero - see below).

SYSTEM SERVICES

Note that some services work from any buffer containing a 6 byte time representation exactly like the real-time clock (TMB_YEAR...). These routines should not operate on the real-time clock itself if an NMI is imminent, so NMIs must be checked for or TM$TGET should be used to copy the time to another buffer.

TM$DAYV

Calculates the day of the week for a given date.

TM$TGET

Get a copy of the real-time clock into a buffer. It is not possible to read the clock directly in case it is being updated by an NMI.

TM$UPDT

Updates a time buffer by a given number of minutes and seconds.

TM$WAIT

Waits for a number of ticks (1 tick is the interval between keyboard interrupts, controlled by KBW_TDEL and set to 50ms by default). If interrupts are disabled (I flag set) then this routine waits for the given number x 50ms.

TM$NDYS (LZ only)

Returns the number of days since 01/01/1900

TM$WEEK (LZ only)

Returns the week number of the supplied date. The first MONDAY of the year starts WEEK 0. Any dates before this MONDAY are in the last week of the previous year. Applications (e.g. the DIARY) convert the week number from 0-52 to 1-53.

TM$DNAM (LZ only)

Returns a 3 letter day name for a given day of the week in the currently selected language.

TM$MNAM (LZ only)

Returns a 3 letter month name for a given month in the currently selected language.

TM$TSET (LZ only)

Sets the system time to a given time. The time should not be simply poke'd into the system time variables since an NMI may be updating the time.