> net#arf:$.a500.RiscOS+.doc.Kernel

 Description: Documentation of changes to kernel for PRM
 Author:  Tim Dobson
 Status:  Preliminary
 History:
    06-Oct-89  TMD     Created
    13-Oct-89  TMD     Added documentation of OS_RemoveCallBack
    27-Oct-89  TMD     Added documentation of VDU variable VIDCClockSpeed
    01-Dec-89  NRaine  Added documentation of OS_FindMemMapEntries
    04-Dec-89  TMD     Documentation of OS_FindMemMapEntries updated slightly

The description of bug fixes below is in a very rough state at the moment -
it will need to be tidied up before publication. Not all of the information
below is relevant to the average user.

 Documentation updates since RISC OS 2.00 release
 ------------------------------------------------

 Changes applying to RISC OS 2.01
 --------------------------------

A new SWI, OS_ChangeRedirection, has been added, to allow the reading and
writing of the handles associated with OS_CLI input/output redirection. This
call was provided for future versions of the task window module, so that
these handles can be made local to the task running in a task window.

        SWI OS_ChangeRedirection

        Read or write OS_CLI input/output redirection handles

in:     R0 = new input  handle (0 => not redirected, -1 => leave alone)
        R1 = new output handle (0 => not redirected, -1 => leave alone)

out:    R0 = old input  handle (0 => not redirected)
        R1 = old output handle (0 => not redirected)

****************************************************************************

In RISC OS 2.00, the SWI OS_AddCallBack allowed interrupt routines to
request a callback, which was granted later when RISC OS was about to
exit to a user mode routine with IRQs enabled. However there was no way to
cancel a callback request before it was granted. This could cause problems,
for example if a module is being killed, and it has outstanding callback
requests, it must refuse to die, otherwise the callback may be granted after
that memory has been reused for something else. For this reason a new SWI,
OS_RemoveCallBack, has been added.

        SWI OS_RemoveCallBack

        Remove a transient callback from the list

in:     R0 = address that was to be called
        R1 = value of R12 that the routine was to be called with

out:    R0 = preserved
        R1 = preserved

****************************************************************************

A new VDU variable, VIDCClockSpeed (variable number 172), has been added.
The value of this variable is the current VIDC clock rate, in kHz. This
value changes when a screen mode is selected which requires a different
clock rate. The value is read in the same way as other VDU variables, by
issuing the SWI OS_ReadVduVariables.

Typical values are 24000 (ie 24MHz) for TV standard modes, 25175 (ie
25.175MHz) for VGA modes, and 36000 (ie 36MHz) for super-VGA modes.

****************************************************************************

A number of routines were changed to improve IRQ latency:-

a) New version of ChangeDynamicArea which reenables interrupts.

b) Heap manager extend block has improved IRQ latency.

c) Made OS_Byte &87 restore caller's IRQ state during call.

d) Made OS_Word &0E,0 enable IRQs during call.

e) Made OS_Word &15,0 enable IRQs during call.

The heap manager has been optimised in a few places.

The routine that converts a date and time value (in hours, minutes, seconds
etc) into a 5-byte centisecond value has been made smaller and much faster.

 Bug fixes
 ---------

Fixed bug in extend heap call (stack imbalance when returning 'No RAM for
extending heap' error)

Fixed "*%" (LDREQB not LDREQ).

Fixed OS_ReadArgs with a /E argument that evaluates to a string (always used
to give 'Buffer full' - also fixed 2 other bugs lurking in the background,
viz. did STRB of buffer addr assuming it was non-zero to indicate a string,
and didn't allow for length and type bytes in amount free value.

Fixed OS_Word &15 reason code 4 (Read unbuffered mouse position) - it used
to generate undefined instruction trap due to stack mismatch.

Fixed OS_SWINumberToString with negative numbers.

Fixed ROMModules never saying 'Running'.

Made OS_SpriteOp reentrant by pushing register dump area on stack.

Fixed sideways scroll by one 'byte' in MODEs 3 and 6.

Fixed incarnation names being terminated by 1st character.

Fixed *Unplug using address as extra terminator for module name.

Fixed podule IRQ despatcher corrupting R0 (prevented it from correctly
disabling the podule IRQ (or podule FIQ-as-IRQ) interrupt if no handler)

RR-2047: Fixed bug in GSRead with quoted termination.

RR-2060: Fixed bug in AddCallBack which freed the wrong heap node.

RR-2066: Fixed bug which occasionally left soft cursors on the screen.

RR-2067: Fixed bug in keyboard driver (pressing Break (as escape) key when
keyboard buffer full did nothing)

RR-2079: Fixed bug in CallAfter/Every which returned duff error pointers.
Changed error message from null string to 'Invalid time interval'.

RR-2080: Fixed rename incarnation bug.

RR-2099: Fixed bug in monadic plus/minus in EvaluateExpression (eg *Eval
50*-3)

RR-2105: Added help on LEN in *Help Eval.

RR-2108: Fixed bug in prefer incarnation which returned duff error pointers.


 Changes applying to RISC OS 2.04
 --------------------------------

A new SWI OS_FindMemMapEntries has been added to allow fast scanning of the
soft CAM map to find the correct page numbers for a given range of addresses.
For efficiency, the caller supplies the  probable page numbers as well as the
addresses, so that the routine can take a quick look to check if the page
number is already correct before scanning the rest of the CAM map.

        SWI OS_FindMemMapEntries
        In:  R0 -> table of 12-byte page entries
                +0      4       probable page number (0..npages-1) (use 0 if no idea)
                +4      4       logical address to match with
                +8      4       undefined
             terminated by a single word containing -1
        Out: table of 12-byte entries updated:
                +0      4       actual page number (-1 => not found)
                +4      4       address (preserved)
                +8      4       page protection level
             terminator preserved

