The Datafile PD-CD 5/DATAFILE_PDCD5.iso/utilities/t/tornado/TNdemo1/_Kernel

Text File | 1996-01-09 | 18.0 KB | 436 lines

Tornado kernel
-=-=-=-=-=-=-=

This is cursory documentation covering the tornado kernel v0.10 (29-12-1995).

The Tornado kernel extends the RISC-OS kernel by providing:
 * Management of tornado code
    - Its own service call handler
    - Its own vector handler
    - Function and procedure calls to interface with RISC-OS
    - Tornado_Register
    - Tornado_Function
 * Extended memory and heap management facilites
    - Tornado_Initheap
    - Tornado_Getblk
    - Tornado_Freeblk
    - Tornado_Extblk
    - Tornado_HeapInfo
    - Tornado_ExtHeap
    - Tornado_Getaddr
    - Tornado_GarbageHeap
 * Extended sprite (bitmap) facilities
    - Tornado_SpriteOp (#001)
 * Miscellaneous extensions
    - Tornado_Hourglass (#002)

   ... and general control of TShell and TLib running under the kernel.

The tornado kernel is loaded in as a RISC-OS module, and during initiation
claims workspace:
 +00: reserved
 +04: Tornado version * 100
 +08: RISC-OS kernel version * 100
 +12: handle of list of clients
 +16: handle of function vector list
 +256: start of tornado shared system heap

The only facilities at present contained within the kernel are the heap
management SWIs. All other facilties are vectored out of the kernel into
subsiduary modules which link themselves into tornado during initiation.

*Note* that tornado extension modules do NOT usually participate in RISC-OS
operations unless it is through the tornado kernel. In other words, they do
not provide their own SWIs, listen in on RISC-OS service calls etc - however,
they can, will and do use RISC-OS facilities as vectoring these through the
tornado kernel (which would only pass them onto RISC-OS anyway) is
resource-wasteful.

You will notice tornado has undergone quite a change since you previously
heard from me last summer (1995). It has been hacked down into a much more
modular form, made much more streamlined and flexible. I am not a great
believer in monolithic operating systems, and tornado I felt was becoming a
little monolithic in nature. Thus, I broke the hourglass handling routines
etc into seperate modules which now register their presence with tornado when
they load in.

These docs aren't hugely detailed. Below is simply a list of SWIs, data
structures and various other bits and pieces currently defined.

 Niall Douglas.
 5th January 1996.





The current format of tornado extended heaps:
   +00:&70616548 = "Heap", like with OS_Heap    |
   +04:Offset to free list            | Note this is the standard
   +08:Offset to heap base            | OS_Heap header
   +12:Offset to heap end            |
   +16:&20 = the Heap+ identifier - also to OS_Heap indicates a block length
   +20:offset within heap to the list of non-relocatable blocks
      +0: length of list in bytes (beginning=0)
      +4: offset within heap to an allocated block descriptor
   +24:offset within heap to the list of relocatable blocks
      +0: length of list in bytes (beginning=0)
      +4: offset within heap to an allocated block descriptor
          This is negative if block is locked
   +28:flags
      bit 0: this heap is auto-extending using Wimp_SlotSize
      bit 1: this heap is auto-extending using OS_Module
      bit 2: this heap is auto-extending using Tornado_Extblk
      bit 30:this heap is auto-extending as the Tornado system heap
      bit 31:disable garbage collection if bit 30 set (ie; is negative)
   +32: base of heap+ heap containing this heap+ heap if bit 2 of +28 is set
        MUST be physical address OR special address eg; 0,1,-1,-2,-3 etc
   +36: block within above heap that holds this heap
   +40: Reserved for future use

Also, the format of each allocated blk:
 ___
/    -36: Filetype of file
|    -32: First block of file
|    -28: Total length of file contained in these blocks (higher word)
|    -24: Total length of file contained in these blocks (lower word)
|    -20: reloc ptr of linked block before this one (=0 if first)
|    -16: reloc ptr of linked block after this one (=0 if last)
|    -12: normally nothing before this, but when the block is one of a
|         linked list (denoted by bit 29 in the flags) then this word is the
|         fragment length of the block (max len this block can be before it
\___      spawns another block)
 /|\
  |
**  Note this may be replaced with a far simple approach later  **

   -08: Flags
        bit 30: clear=nonreloc, set=reloc
        bit 29: set means this block is one of a linked list
   -04: length of data (not including this header). Negative if the data is
        on disc and not in memory.
   +00: start of data if data is in memory, or end of block if data is on
        disc. Blocks are stored in the format (for example)
        "<Tornado$MemoryCache>.F.F.F.F.F.F.F.F" for block -1.




Tornado_Register                    (SWI &78000)
On entry:
   R0=flags
      bit 0: clear to register, set to deregister
   R1=addr of module name (same as RO)
   R2=ptr to entry vectors
On exit:
   R0=corrupted
   R1=ptr to heap base
   All registers preserved
Interrupts: IRQ's enabled
Processor mode: SVC
Re-entrancy: Full
Use:
   Used to register an extension module with the tornado kernel. The entry
vectors is in the following format:
 +00: B initialise
 +04: B finalise
 +08: B service
   The initialise and finalise entries should be seperate from your module's
initialise and finalise entries in that tornado may call your module through
finalise then initialise to restart your module should it get into
difficulties. Your module's initialise and finalise entries should merely
register and deregister itself using this SWI.

Tornado_Function                    (SWI &78001)
On entry:
   R0=flags
On exit:
   All registers preserved
Interrupts: IRQ's enabled
Processor mode: SVC
Re-entrancy: Full
Use:

Tornado_Initheap                    (SWI &) On entry:
   R0=flags
      bit 0: This heap is a Wimp postslot heap
      bit 1: This heap is a heap within an OS_Module block in RMA
      bit 2: This heap is a heap within a Heap+ block
      bit 30: This heap being initialised is the proposed Tornado system heap
   R1=ptr to proposed heap base
   R2=ptr to addr of heap base if bit 2 set
   R3=length of proposed heap (must be >1024 bytes)
   R4=handle of block within heap pointed to by R1 if bit 2 set
On exit:
   R0=corrupted
   R1=ptr to heap base
   All registers preserved
Interrupts: IRQ's enabled
Processor mode: SVC
Re-entrancy: Full
Use:
   Used to initialise a Tornado Heap+ type heap. This heap format is based on
OS_Heap style heaps, and offers complete internal format compatibility with
OS_Heap style heaps, and thus relies on the current structure of OS_Heap
heaps. It will complain if OS_Heap uses a format it does not know about.
   The area of memory you intend to initialise will be verified, and header
and other information written into it. Note minimum size is 1024 bytes, and
the base must begin on a word-aligned address. The length must be a multiple
of 4 bytes.
   Note that if bit 0 is set then the task's wimpslot is automatically
extended by an appropriate amount and the heap set up at the previous
environment end address which should be passed in R1 on entry. From now on,
any extensions to the heap needed will be done automatically, extending the
wimpslot as necessary. Bit 1 will extend it using OS_Module; bit 2 will
extend it using Tornado_Extblk, which may cause a cascade extension down
through blocks in heaps below the heap being extended.
   Note also that the heap+ structure itself is relocatable - this means all
heap+ heaps can also be stored in a Heap+ or otherwise relocatable block.

Tornado_Getblk                        (SWI &)
On entry:
   R0=flags
      bit 0: this block is relocatable
      bit 1: Don't return address of block in R2
      bit 2: don't do a garbage collection after this call
      bit 29:(internal) this is the subtask heap
      bit 30:(internal) this is the system heap
   R1=heap+ ptr, 0 if system heap, 1 if subtask heap
      -1,-2 refers to task heaps (NOT IMPLEMENTED YET!)
   R3=size of block wanted
   Other registers not used as yet
On exit:
   R0=corrupted
   R1=updated heap+ ptr if R1<>magic heap no on entry
   R2=addr of block, otherwise preserved if bit 1 is set
   R3=handle of block
   All other registers preserved
Interrupts: IRQ's enabled
Processor mode: SVC
Re-entrancy: Full
Use:
   Used to claim a block from a Heap+ heap. As in other tornado heap calls,
R1 may either point to an actual heap, or may be a 'magic' heap number. These
are currently defined as:
  0: Tornado shared system heap (stored in RMA)
  1: Tornado subtask shared heap (undefined location currently)
 -1: Private heap of first tornado task
 -2: Private heap of second tornado task
 -3: etc
   If you ask for a relocatable block (by setting bit 0), which is _strongly_
recommended, then you will be given a handle which from hence you can use to
reference the block by. It will always be a negative number, and any data
contained within the block must be able to be relocated at arbitrary times.
You will not know if/when/how/why the block has been moved. To get the
_current_ address of the block, use Tornado_Getaddr. Read its entry for
further details of use. You are guaranteed that your block will NOT move
between calls concerning your heap to tornado, except for shared heaps which
may be accessed by another party without your knowledge. Thus, you should
take measures to prevent your block moving while you use it.
   If you ask for a non-relocatable block, the handle will be equal to the
start of the block. However, it is good programming practice to also call
Tornado_Getaddr for this handle, just to be sure you are getting the address
of the block (also makes sure if you change it later you won't have to change
too much of your code).
   Unless you specifically ask otherwise, an automatic garbage collection
will be performed after this call, unless it has been disabled (only for
system heap). Also, for your convenience the current position of the block is
returned in R2.
   Note that if you have specified auto-extending in Tornado_Initheap call,
then this call will only return an error if the entire heap couldn't be
extended, otherwise it's because the heap is full.
   Note also that recursion is possible here: this heap being extended by
this call may cause the heap it's in to extend which may cause the heap it's
in to also extend. Failure of any one of these will return an error from this
command. Also, this command thus may take a while having to garbage and
extend multiple heaps.

Tornado_Freeblk                        (SWI &)
On entry:
   R0=flags
      bit 2: don't do a garbage collection after this call
      bit 29:(internal) this is the subtask heap
      bit 30:(internal) this is the system heap
   R1=heap+ ptr, or 'magic' heap no
   R3=handle of block
On exit:
   R0=corrupted
   R1=updated heap+ ptr if R1<>'magic' heap no
   All other registers preserved
Interrupts: IRQ's enabled
Processor mode: SVC
Re-entrancy: Full
Use:
   Used to free a claimed block.
   Unless you specifically ask otherwise, an automatic garbage collection
will be performed after this call, and if auto-extending is set, then the
heap will be automatically shrunk if possible. This, as above, may lead to
all heaps in the tree above to shrink as well. Thus, this command may take a
while having to garbage and shrink multiple heaps.

Tornado_Extblk                        (SWI &)
On entry:
   R0=flags
      bit 0: don't bother returning new size
      bit 1: don't bother returning current address
      bit 2: don't do a garbage collection after this call
      bit 29:(internal) this is the subtask heap
      bit 30:(internal) this is the system heap
   R1=heap+ ptr, or 'magic' heap no
   R2=signed change in bytes
   R3=handle of block
On exit:
   R0=corrupted
   R1=updated heap+ ptr if R1<>'magic' heap no
   R2=current addr of block
   R3=new handle of block
   R4=new size of block
   All other registers preserved
Interrupts: IRQ's enabled
Processor mode: SVC
Re-entrancy: Full
Use:
   Used to change the size of a claimed block. Note that the new size of the
block may be larger than you intended, as it is always rounded up to the
nearest word. This is alright: just take care to redo any future resizing
decisions (ie; if storing the size, don't store previous size changed by the
requested size change, store the size returned by R2 instead). This will
prevent bytes 'appearing' on the end of the block that you will never use.
   The new handle for the block will be the same if the block was
relocatable, but note it is good programming practice if you restore the
handle anyway, in case you may later have to alter the relocatable nature of
the data.
   Unless you specifically ask otherwise, an automatic garbage collection
will be performed after this call, and the repercussions are as for
Tornado_Getblk and Tornado_Freeblk.

Tornado_HeapInfo                    (SWI &) On entry:
   R0=flags
      bit 29:(internal) this is the subtask heap
      bit 30:(internal) this is the system heap
   R1=heap+ ptr, 0 if system heap, 1 if subtask heap
On exit:
   R0=size of heap
   R1=heap addr, filled in if R1=0,1 on entry
   R2=largest free block in heap
   R3=amount of free space available
   R4=number of relocatable blocks in heap
   R5=number of non-relocatable blocks in heap
   R6=bytes occupied by relocatable blocks
   R7=bytes occupied by non-relocatable blocks
   All other registers preserved
Interrupts: IRQ's enabled
Processor mode: SVC
Re-entrancy: Full
Use:
Used to determine the current state of a heap+ heap.
Related calls:
   All tornado heap calls;

Tornado_ExtHeap                        (SWI &)
On entry:
   R0=flags
      bit 29:(internal) this is the subtask heap
      bit 30:(internal) this is the system heap
   R1=heap+ ptr, 0 if system heap, 1 if subtask heap
   R2=signed change in size
On exit:
   R2=new size
   All other registers preserved
Interrupts: IRQ's enabled
Processor mode: SVC
Re-entrancy: Full
Use:
Used to manually change the size of a Heap+ heap. Usually automated. Note
this may cause auto-extending heaps above this to garbage and also change
size.
Related calls:
   All tornado heap calls;

Tornado_Getaddr                        (SWI &)
On entry:
   R0=flags
      bit 0: don't cache block
      bit 1: preserve R4 on exit (ie; don't bother calculating it)
      bit 29:(internal) this is the subtask heap
      bit 30:(internal) this is the system heap
   R1=heap+ ptr, 0 if system heap, 1 if subtask heap
   R2=offset within block you wish to access (if block fragmented)
   R3=handle of block
   R4=number of bytes to be made contiguous (-1=full length)
On exit:
   R2=actual address of block (points to offset given by R2)
   R3=reloc handle of block if bit 0 was set on entry; otherwise preserved
   R4=number of bytes from R2 you can access before you must call this SWI
      again (may be to end of block though)
   All other registers preserved
Interrupts: IRQ's enabled
Processor mode: SVC
Re-entrancy: Full
Use:
Used to determine the actual address of a claimed block. If the handle passed
is non-negative, then the same handle is currently returned in R2.
   The offset contained within R2 is the patch of data within the block you
wish to access. This should be given even if the block isn't fragmented, as
the user may have specified that a cap be placed on requests.
   You can work out what memory can be accessed using R3 ie; you won't need
to call this SWI to access as far as this. You can still do anyway, and this
call is quite quick so little difference in speed will be noticed.
   Note you can only access R4 bytes from where you asked for. This is
because only that much data has been loaded within that block.
   Setting bit 0 on entry means that a new reloc block is created of R4
bytes, and one or more fragmented blocks are loaded into it to make it a
contiguous area of data. Make sure that when you're finished with this block
and the data (ie; before calling Tornado_Getaddr again), free the block. Note
finally that setting bit 0 is quite slow in operation, and having blocks
already in memory doesn't matter - they remain in memory - and thus, quite a
lot of memory can be wasted. Use a routine capable of using fixed size data
blocks to manipulate the data if possible.
   This call also resets the time elapsed since last access to this block, or
fragment of a block. This is used for virtual memory, where when the system
heap becomes full the oldest blocks get dumped to disc. Using this call
indicates that you want to use this block. If the block is currently on disc,
it is reloaded into the heap and its address returned to you. Note no garbage
collection occurs when this happens.
   You can be guaranteed that this address will remain the same until the
next specific call to Tornado_<call>, as all the calls done under
interrupts/vectors etc. by Tornado do not garbage collect the heap.
   PLEASE NOTE: When preempting code and referring to the system heap, you
MUST use Tornado_GarbageHeap to force disabling of garbaging. If you do this,
you must be prepared to regularly do a Tornado_GarbageHeap followed with
another Tornado_Getaddr to ensure fragmentation does not become endemic. This
is because other Tornado apps may cause the heap to be garbaged.
Related calls:
   All tornado heap calls;

Tornado_GarbageHeap                    (SWI &)
On entry:
   R0=flags
      bit 0:disable auto-garbaging (if R1=0)
      bit 1:reenable auto-garbaging (if R1=0)
      bit 2:do not garbage heap
      bit 29:(internal) this is the subtask heap
      bit 30:(internal) this is the system heap
   R1=heap+ ptr, 0 if system heap, 1 if subtask heap
On exit:
   R1=updated heap+ ptr if R1<>0 on entry
   All other registers preserved
Interrupts: IRQ's enabled
Processor mode: SVC
Re-entrancy: Full
Use:
Used to disable auto-garbaging on the system heap, and to force a garbage
collection.
   If bit 0 is set, garbaging on the system heap is disabled and it is stored
that it was your task which requested it.
   Note that this call may not garbage the heap if someone else has disabled
it (R1=0, system heap). Also, if reenabling garbaging and no-one else has
disabled it, an immediate garbage is done.
   This call with flags %000 is performed after every Tornado_Getblk,
Tornado_Freeblk and Tornado_Extblk. If the system heap isn't being referred
to then there is nothing the task can do to stop auto-garbaging ie; you
cannot disable garbaging on private Heap+ heaps.
   Note again treed auto-extending heaps may have to garbage and change size.
Related calls:
   All tornado heap calls;