ScreenBlanker module
--------------------

This ScreenBlanker module contains support for the Portable: instant
blanking and unblanking, backlight control and "flashing" mode for
drawing the user's attention to important messages about battery life.

See Hdr.ScrBlank for symbol definitions.

Command
-------

*BlankTime [W] [O] [delay]

Set the delay (in seconds) before blanking occurs.  Zero indicates that
blanking is not wanted.

The W option enables monitoring of character output to the VDU stream.
If the user selects this mode, then character output delays blanking just
as user input does.  The O option turns this off.  It is normally off.


SWI
---

ScreenBlanker_Control (&43100)
------------------------------

R0 is a reason code:
        ScreenBlankerReason_Blank       (0) : blank immediately.
        ScreenBlankerReason_Unblank     (1) : unblank immediately.
        ScreenBlankerReason_Flash       (2) : enter flashing mode.
        ScreenBlankerReason_SetTimeout  (3) : set timeout
        ScreenBlankerReason_ReadTimeout (4) : read timeout
        ScreenBlankerReason_ReadTimeout (5) : read timeout (corrected version of above)
        ScreenBlankerReason_SetDimTime  (6) : set screen dim timer
        ScreenBlankerReason_ReadTime    (7) : read screen dim timer

ScreenBlankerReason_Blank
-------------------------
The screen is blanked immediately, even if the user has disabled
blanking.  The screen is automatically unblanked.  If flashing is in
progress is is cancelled, even if a minimum number of flashes was
specified.

R0 corrupted.  

ScreenBlankerReason_Unblank
---------------------------
The screen is unblanked immediately.  The screen is automatically
unblanked.  If flashing is in progress is is cancelled, even if a
minimum number of flashes was specified.

R0 corrupted.  

ScreenBlankerReason_Flash
-------------------------
R1 = delay before blanking, in centiseconds
R2 = delay before unblanking, in centiseconds.
R3 = number of initial flash cycles before user wakeup allowed
R4 = flags
        This word is passed through R0 when the service Service_ScreenBlanked
        and Servive_ScreenRestored are issued.  See the section on service
        calls for details.

This reason code makes the screen flash on and off at the rate
indicated by R1 and R2.  The user-configured blanking delay is
temporarily overridden.  This feature is intended to avoid the problem
of very important messages being missed due to screen blanking (e.g,
low battery message in a portable machine).

If the screen is blanked when this SWI is called, it is immediately
unblanked.

Every blank and unblank is accompanied by Service_ScreenBlanked and
Service_ScreenRestored; the service call handler will receive a copy
of the flags word in R0.

Wake-up by keyboard activity or by reason code
ScreenBlankerReason_Unblank cancels flashing and leaves the screen at
the beginning of its normal "unblanked" period.  A call of reason code
ScreenBlankerReason_Blank cancels flashing and leaves the screen at the
beginning of its normal "blanked" period.

The minimum timeout allowed is 40 cs.  If a value less than 40 is
passed, then 40 will be assumed.

R3 specifies a number of initial flash cycles during which user wakeup will
NOT be allowed.  Keyboard and mouse activity will be ignored for this
many flash cycles, but wakeup by reason codes ScreenBlankerReason_Blank or
ScreenBlankerReason_Unblank will not be ignored.

While flashing is in progress, wakeup by WrchV activity is disabled.

R0, R1, R2, R3 and R4 are corrupted.


ScreenBlankerReason_SetTimeout
------------------------------
R1 = delay before blanking, in centiseconds.  0 means never blank.

This reason code sets the normal (non-flashing) blanking delay.  It is equivalent
to the *BlankTime command.

The screen is automatically unblanked.  If flashing is in progress is
is cancelled, even if a minimum number of flashes was specified.

The minimum timeout allowed is 500 centiseconds.  If a value less than 500 is
passed, then 500 will be assumed.

R0 and R1 are corrupted.


ScreenBlankerReason_ReadTimeout
-------------------------------
This reason code reads the user's blanking delay.

R0 is corrupted.
R1 is updated with the blanking delay (in centiseconds). >>>RCM says this is wrong, software
                                                         >>>RCM returns delay in seconds

This call always returns the user's blanking delay, even if flashing is
active.

This call is mainly provided so that callers of ScreenBlankerReason_Flash
can match the user's preferred blanking delay if they want to.  Be aware
that this value might be zero, indicating no blanking.  If you pass zero
to ScreenBlankerReason_Flash then the minimum of 50 centiseconds will be selected,
ensuring that the "on" period under flashing is short (instead of infinite!)


ScreenBlankerReason_SetDimTime
------------------------------
R1 = delay before dimming, in centiseconds.  0 means never dim.

It is equivalent to the *DimTime command.

The screen is automatically undimmed.

The minimum timeout allowed is 500 centiseconds.  If a value less than 500 is
passed, then 500 will be assumed.

R0 and R1 are corrupted.


ScreenBlankerReason_ReadDimTime
-------------------------------
This reason code reads the user's 'dim-screen' delay.

R0 is corrupted.
R1 is updated with the dim delay (in centiseconds).


CMOS RAM
--------

The initial blanking delay is obtained from the setting of CMOS RAM byte
Misc1CMOS (&BC) bits 3-5, according to the following:-
  0 = Never, 1 = 30s, 2 = 1 min, 3 = 2 min, 4 = 5 min,
  5 = 10 min, 6 = 15 min, 7 = 30 min.
Bit 6 controls whether the blanker initially ignores character output:
  0 = ignore wrch, 1 = unblank on wrch.


Service calls
-------------

When blanking occurs, for any reason, the following service call is issued:-

        R1 = Service_ScreenBlanked
        R0: flags word

When unblanking occurs, for any reason, the following service call is issued:-

        R1 = Service_ScreenRestored
        R0: flags word

R0 is normally zero.  If however the call results from a flash cycle,
then it will be set to the value of R4 that was passed into
ScreenBlankerReason_Flash.

How the blanking is done
------------------------

Blanking is achieved by using the new 'blank screen' PaletteV call. 
Previous versions of ScreenBlanker did the job themselves, but this was
found to cause confusion about who owned the real version of the palette. 
The owner of PaletteV (kernel or Portable module) is now entirely
responsible for doing blanking appropriate to the particular screen device.

The Portable
------------

Previous versions of ScreenBlanker turned off the LCD display drivers and
the backlight when blanking on a portable machine.  The new version relies
on the Portable module to do this on receipt of the PaletteV call to blank
the screen.  The Portable module is also responsible for refusing to switch
the backlight on if the lid is shut - support for this is now absent from
ScreenBlanker.
