HAL26 v0.04 (11 Feb 2003)
-------------------------

HAL26 is a module designed to provide certain hardware features present in
RISC OS 5 and RISC OS 3.5 to earlier machines, allowing programs to work
across the whole range of RISC OS computers.  These comprise:

For machines before RISC OS 5:
An implementation of the Hardware Abstraction Layer (HAL), which provides
facilities to control interrupts, fast interrupts, timers and counters
(both with sub-microsecond resolution) in a hardware independent way.

For machines before RISC OS 3.5:
An implementation of the Podule_ReadInfo and Podule_SetSpeed SWIs.  These
enable podule drivers to be written in a hardware independent manner without
having to provide a special case for earlier machines.  If written in this
way, drivers should work on all machines from A305 to Iyonix.

Documentation on how to use these features can be found elsewhere, notably:

HAL: From Castle Technology http://www.iyonix.com/32bit/

Podule_ SWIs: In the programmer's reference manuals volume 5/5a, or recent
StrongHelp http://spoon.dellah.org/manuals/shelp/

HAL26 WILL NOT WORK UNDER 32-BIT VERSIONS OF RISC OS (currently RISC OS 5 and
above).  This should not be a problem since it would do nothing useful on
them in any case.

Installation
------------

To install simply merge the supplied !System with your central copy, using
!Boot (or !SysMerge on RISC OS 3.1).  Applications wishing to use the module
should *RMEnsure it in the normal way.  Programmers should note that it is
recommended that if it is already loaded you don't load a newer version
unless it is absolutely necessary, since this may upset existing users.

Also included in this archive are a number of test programs.  Note that for
ease of development some are contain BASIC in text format rather than
tokenised - these can still be loaded into BASIC in the normal way (or use
TEXTLOAD/TEXTSAVE).

Implementation notes
--------------------

The HAL specification is not completely clear in some areas, and there are
other things the programmer should be aware of.  These are detailed here.
Please read this section before making use of this module.


This implementation is based on the HAL specification version 0.10 (Dec
2002), and implements calls HAL_IRQEnable (1) to HAL_CounterDelay (22).

The OS does not know the SWI name "OS_Hardware" even after the module is
loaded.  So attempting SYS "OS_Hardware" in BASIC will not work - it is
suggested the following code is used instead:
  OS_Hardware = &7A
  SYS OS_Hardware,    <whatever>

Interrupt device numbers are assigned as follows:
Register A (&03200010) device number += 0
Register B (&03200020) device number += 8
Register C (&03200060) device number +=16 (IOMD/ARM7500 machines only)
Register D (&03200070) device number +=24 (IOMD/ARM7500 machines only)

Bit 0 in a register: device += 0
...
Bit 7 in a register: device +=7

So, for example, the expansion card interrupt is bit 5 of register B, which
is device number 8+5=13.  Device numbers 0-15 map onto those of the same
number passed to OS_ClaimDeviceVector - the PRMs are a little unclear as to
how the vectors map onto hardware beyond there.  See the ARM7500FE data sheet
for details of the uses of registers C and D in those machines.

Register A is taken as having the highest priority, and register D the
lowest.  Within a register, bit 7 has the highest priority and bit 0 the
lowest.

HAL_IRQClear is only supported for devices 0 to 7 (because that's all the
hardware supports).  HAL_FIQClear is ignored.

HAL_TimerPeriod for timer 1 returns 0 until HAL_TimerSetPeriod is used.  This
is because it is not possible to read the current setting from the hardware. 
Timer 0 is assumed to be set to 20000, since this is the OS' default. 
HAL_CounterDelay also makes this assumption, and its calculations will be
wrong if this is changed.

The timer code does not enable timer interrupts, nor install a handler for
them - use HAL_IRQEnable and OS_ClaimDeviceVector for this.

HAL_CounterDelay has not been tested for delays over 100s.  Note also that
delays are performed in the current mode; interrupt status is not altered.

Timings produced by HAL_CounterDelay have been calibrated with an external
frequency counter.  The results can be seen in the Calibrate directory.


The implementation of Podule_ SWIs is performed by implementing a
block of SWIs with the same base and names as those held by the
Podule Manager.  SWIs that are supported natively will be passed
on to the Podule Manager - this may result in a few instructions delay on
each SWI.  All SWIs are passed on unless the Podule Manager v1.34 or earlier
is in use.

Attempting to read EASI and DMA parameters from Podule_ReadInfo under RISC OS
3.1 will raise an error.  Similarly an error will be returned if an ethernet
address is requested, but cannot be found in the podule ROM.

Podule_SetSpeed is ignored under RISC OS 3.1, and will always return speed A.

References
----------

RISC OS PRMs volume 1, 5, 5a
Acorn RISC Machine Family Data Manual, VLSI Technology 1990
CL-PS7500FE data sheet, Cirrus Logic

Contacts
--------

The author may be contacted at 
theo@markettos.org.uk or
theom@chiark.greenend.org.uk

Newer versions (if any) may be found at
http://www.markettos.org.uk/ (including link to HAL26's CVS)

Copyright Theo Markettos 2003

Licence
-------

The Artistic License
Preamble

The intent of this document is to state the conditions under which a Package
may be copied, such that the Copyright Holder maintains some semblance of
artistic control over the development of the package, while giving the users
of the package the right to use and distribute the Package in a more-or-less
customary fashion, plus the right to make reasonable modifications.
Definitions:

"Package" refers to the collection of files distributed by the Copyright
Holder, and derivatives of that collection of files created through textual
modification.

"Standard Version" refers to such a Package if it has not been modified, or
has been modified in accordance with the wishes of the Copyright Holder as
specified below.

"Copyright Holder" is whoever is named in the copyright or copyrights for the
package.

"You" is you, if you're thinking about copying or distributing this Package.

"Reasonable copying fee" is whatever you can justify on the basis of media
cost, duplication charges, time of people involved, and so on. (You will not
be required to justify it to the Copyright Holder, but only to the computing
community at large as a market that must bear the fee.)

"Freely Available" means that no fee is charged for the item itself, though
there may be fees involved in handling the item. It also means that
recipients of the item may redistribute it under the same conditions they
received it.

1. You may make and give away verbatim copies of the source form of the
Standard Version of this Package without restriction, provided that you
duplicate all of the original copyright notices and associated disclaimers.

2. You may apply bug fixes, portability fixes and other modifications derived
from the Public Domain or from the Copyright Holder. A Package modified in
such a way shall still be considered the Standard Version.

3. You may otherwise modify your copy of this Package in any way, provided
that you insert a prominent notice in each changed file stating how and when
you changed that file, and provided that you do at least ONE of the
following:

a. place your modifications in the Public Domain or otherwise make them
Freely Available, such as by posting said modifications to Usenet or an
equivalent medium, or placing the modifications on a major archive site such
as uunet.uu.net, or by allowing the Copyright Holder to include your
modifications in the Standard Version of the Package.

b. use the modified Package only within your corporation or organization.

c. rename any non-standard executables so the names do not conflict with
standard executables, which must also be provided, and provide a separate
manual page for each non-standard executable that clearly documents how it
differs from the Standard Version.

d. make other distribution arrangements with the Copyright Holder.

4. You may distribute the programs of this Package in object code or
executable form, provided that you do at least ONE of the following:

a. distribute a Standard Version of the executables and library files,
together with instructions (in the manual page or equivalent) on where to get
the Standard Version.

b. accompany the distribution with the machine-readable source of the Package
with your modifications.

c. give non-standard executables non-standard names, and clearly document the
differences in manual pages (or equivalent), together with instructions on
where to get the Standard Version.

d. make other distribution arrangements with the Copyright Holder.

5. You may charge a reasonable copying fee for any distribution of this
Package. You may charge any fee you choose for support of this Package. You
may not charge a fee for this Package itself. However, you may distribute
this Package in aggregate with other (possibly commercial) programs as part
of a larger (possibly commercial) software distribution provided that you do
not advertise this Package as a product of your own.

6. The scripts supplied as input to or produced as output from the programs
of this Package do not automatically fall under the copyright of this
Package, but belong to whoever generated them, and may be sold commercially,
and may be aggregated with this Package.

7. The name of the Copyright Holder may not be used to endorse or promote
products derived from this software without specific prior written
permission.

8. THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.

The End
