Commit 4bfadee7 authored by Kevin Bracey's avatar Kevin Bracey
Browse files

Lots of Tungsten work.

Version 5.35, 4.79.2.48. Tagged as 'Kernel-5_35-4_79_2_48'
parent 4ecea6cc
Changes to APIs due to 32-bit addressing
========================================
A fully 32-bit OS opens up the possibility of more areas of memory being
above 64MB. Currently the application slot, module area and ROM are all
below 64MB, but it is likely that in the future the module area and ROM
will move higher to allow the application slot to be limited only by
physical RAM (reducing the need for normal programs to create their own
dynamic areas, and wasting logical address space).
When the ROM and RMA move higher (or in a program with a very large
application slot), a number of existing RISC OS APIs that place flags in
the top bits of addresses are liable to fail. This document summarises
API changes to cover this.
OS_ReadLine
-----------
In existing OSes, R0 is interpreted as a 26-bit address, with 6 flag bits, 4
currently unused.
In a 32-bit OS, OS_ReadLine now interprets R0 as a 32-bit address, and acts
as though the flags are both clear. This reflects the most common usage, and
allows applications not wanting to use the flags to remain unaltered.
A new SWI, OS_ReadLine32, takes its flags in R4. Bits 31 and 30 correspond to
the original flags. Bits 29-8 are reserved and must be zero. Bits 7-0 are
used as the echo byte (if bit 30 is set). As before, R4 is preserved by the
call.
ReadLineV, in a 32-bit OS, is called as though from OS_ReadLine32; ie on
entry R0 is the buffer address and R4 contains the flags (always valid,
regardless of which SWI was called).
A ReadLineV claimant may handle this at run-time by beginning their
handler:
ReadLineV_Handler
STMFD R13!, {R4, R14} ; must preserve R4
TEQ PC, PC ; 26 bit OS?
ANDNE R14, R0, #&FC000000 ; if so, extract flags
ANDNE R4, R4, #&FF ; and potential echo byte
ORRNE R4, R4, R14 ; combine into new form
BICNE R0, R0, #&FC000000 ; may corrupt R0
...
; R0 now address
; R4 now flags plus echo byte
Because of the way ReadLineV operates, any OS_ReadLine32 SWI on a 26-bit
OS will return an error if R0 > 64MB.
When using either SWI, applications for existing 26-bit OSes should ensure that the buffer
is in a low address - eg allocated in the RMA or application space.
OS_SubstituteArgs
-----------------
In existing OSes, R0 is interpreted as a 31-bit address, with 1 flag bit.
In a 32-bit OS, OS_SubstituteArgs now interprets R0 as a 32-bit address, and
acts as though the flag is clear. This allows applications not wanting to use
the flags to remain unaltered.
The new SWI OS_SubstituteArgs32 interprets R0 as a 32-bit address, and takes
a flags word in R5. Bit 31 of R5 corresponds to the existing bit 31 of R0;
bits 30-0 are reserved. R5 is preserved across the call.
OS_HeapSort
-----------
In existing OSes, R1 is interpreted as a 29-bit address, with 3 flag bits.
Also, due to a long-standing bug, instead of inspecting bit 31, the call
inspects bit 30, meaning bit 30 causes the documented functions of both bits
30 and 31 to occur, while bit 31 is ineffective.
In a 32-bit OS, the SWI continues to work in the same way, with R1 being
interpreted as a 29-bit address plus flags, and with the flags bug preserved
for backwards compatibility.
The new SWI OS_HeapSort32 interprets R1 as a 32-bit address, and takes a
flags word in R7. Bits 31-29 of R7 correspond to bits 31-29 of R1, but with
the flags bug corrected, so each bit functions as documented on PRM page
1-939.
FileCore background scatter lists
---------------------------------
High (top-bit set) addresses are possible in a scatter list, thus only
negative numbers smaller or equal to than -64K (ie >= unsigned &FFFF0000)
should be interpreted as the end of list marker. This applies to any FileCore
module for RISC OS 3.5 or later.
GraphicsV
---------
R4 = reason code
VSync interrupt occured (Driver -> Kernel)
R4 = 1
out: R0-R3 corrupt
Set mode
R4 = 2
R0 -> VIDC list type 3
Set interlace
R4 = 3
R0 = 0 or 1 (off or on)
Set blank
R4 = 4
R0 = 0 or 1 (unblank or blank)
R1 = DPMS state (0 -3)
Update pointer
R4 = 5
R0 = flags (bit 0 => enable, bit 1 => shape changed)
R1 = x pos
R2 = y pos
R3 -> shape descriptor
Set DAG
R4 = 6
R0 = DAG
R1 = physical address
Vet mode (reserved)
R4 = 7
R0 = VIDC list
R1 = workspace ?
out: R0 = 0 if OK
Features
R4 = 8
out:
R0 = flags word (bit 0 => hardware scroll)
(bit 1 => hardware pointer)
(bit 2 => interlace with progressive framestore)
(bit 3 => separate framestore)
R1 = pixel formats (bits 0-5 => 2^n bpp supported)
R2 = buffer alignment requirement in bytes (power of 2)
Framestore information
R4 = 9
out:
R0 = framestore physical base address
R1 = framestore size
R4 = 0 if external framestore used, preserved if not
Write palette entry
R4 = 10
R0 = type (0 = normal entry, 1 = border, 2 = palette)
R1 = palette entry (&BBGGRRSS)
R2 = palette index
Write palette entries
R4 = 11
R0 = type (0 = normal entry, 1 = border, 2 = palette)
R1 -> palette entry table
R2 = first palette index
R3 = number of entries
Read palette entry
R4 = 12
R0 = type (0 = normal entry, 1 = border, 2 = palette)
R1 = palette entry (&BBGGRRSS)
R2 = palette index
Out:
R1 = palette updated
\ No newline at end of file
......@@ -143,7 +143,7 @@ Word 3: Offset from descriptor to entry table
Word 4: Number of entries available
Word 5: Static workspace required
Eoch of the HAL and the OS must be contiguous within physical memory.
Each of the HAL and the OS must be contiguous within physical memory.
......
......@@ -866,24 +866,35 @@ Determine the framestore buffer alignment required by the hardware.
-- unsigned int64 HAL_MachineID(void)
Returns a 64-bit unique machine identifier. What does it mean? ...
Returns a 64-bit unique machine identifier,this may later be used to
form the ethernet MAC address but otherwise has no great significance on non
networked machines.
-- void *HAL_ControllerAddress(unsigned flags, unsigned controller)
The top 8 bits are a CRC,based on the same algorithm the original DS2401
used - if the CRC fails zero will be substituted
Maps to RISC OS' OS_Memory 9 call - provides a way for people who must poke
the hardware to find it. Bits 0-7 of controller are the sequence number
(starting at zero), and bits 8-31 are the controller type. Currently
allocated types are:
-- void *HAL_ControllerAddress(unsigned controller)
0 = EASI card access speed control register (sequence no = card)
1 = EASI space (sequence no = card)
2 = VIDC1
3 = VIDC20
4 = IOMD
Asks the HAL where various controllers might or might not be.
Podule manager uses this information to determine at run time whether or not
to bother doing anything.
HALEntry HAL_HardwareInfo
HALEntry HAL_SuperIOInfo
Returns r0=logical address of the chosen controller,or zero
0 = EASI card access speed control
1 = EASI space(s)
2 = VIDC1
3 = VIDC20
4 = S space base (IOMD,podules,NICs,blah blah)
5 = Extension ROM(s)
-- HALEntry HAL_HardwareInfo
See OS_ReadSysInfo reason code 2
-- HALEntry HAL_SuperIOInfo
See OS_ReadSysInfo reason code 3
RISC OS entry points from HAL init
----------------------------------
......@@ -927,6 +938,7 @@ This entry must not be called after RISCOS_Start.
uintptr_t sigbits, void *ref)
flags
bit 0: video memory (only first contiguous range will be used)
bit 1: video memory is not suitable for general use
bits 8-11: speed indicator (arbitrary, higher => faster)
other bits reserved (SBZ)
start
......
......@@ -33,7 +33,7 @@ Interrupt specifications are generally described by a 3-word structure.
The 3 words correspond directly to the contents of registers R0,R3 and R4
on entry to OS_ClaimDeviceVector.
struct
typedef struct irq_descriptor
{
int device;
union {
......@@ -46,7 +46,7 @@ struct
void *handle;
} func;
} sub;
}
} irq_descriptor;
OS_ClaimDeviceVector changes:
......@@ -281,6 +281,7 @@ unsigned int HAL_IICType(int bus)
bit 1: Bus supplies the high-level API
bit 2: High-level API supports multi-master operation
bit 3: High-level API supports slave operation
bit 4: High-level API supports background operation
bit 16: Bus supports Fast (400kbps) operation
bit 17: Bus supports High-speed (3.4Mbps) operation
bits 20-31: Version number of I²C supported by high-level API, * 100.
......@@ -311,29 +312,119 @@ __value_in_regs IICLines HAL_IICReadLines(int bus);
High level API
--------------
To be defined.
The high-level interface process a single transfer at a time (from the
initial START to the STOP). It is designed to support background operations.
irq_descriptor HAL_IICDevice(int bus);
Returns the interrupt specification for the bus. This is not meaningful
if bit 4 of the flags word above is not set. The OS will claim the interrupt
and call HAL_IICMonitorTransfer() each time it occurs.
#define IICSTATUS_COMPLETED 0
#define IICSTATUS_INPROGRESS 1 /* transfer proceeding in background */
#define IICSTATUS_NOACK 2 /* slave failed to acknowledge */
#define IICSTATUS_BUSY 3 /* IIC system busy (call back later) */
#define IICSTATUS_SLAVE 4 /* reserved for slave operations */
#define IICSTATUS_ERROR 5 /* other error prevented completion */
typedef struct iic_transfer
{
unsigned addr:8;
unsigned :22;
unsigned checksumonly:1;
unsigned nostart:1;
union
{ unsigned checksum;
void *data;
} d;
unsigned len;
} iic_transfer;
int HAL_IICTransfer(int bus, unsigned n, iic_transfer transfer[static n]);
Initiates an IIC transfer. The transfer shall progress in the background
if bit 4 is set, in which case the normal return should be IICSTATUS_INPROGRESS.
The OS will call HAL_IICMonitorTransfer each time an interrupt occurs - this
will allow the HAL to progress through the transfer if it's not totally automatic.
If the transfer happens in the foreground, return values are as for
IICMonitorTransfer (see below).
If an IIC transfer is currently in progress, the call may return BUSY and the
caller should retry later - although if background transfers are supported it may
queue the transfer and return INPROGRESS. If another master is driving the bus,
it should silently wait until the bus is free (in the background or foreground as
appropriate). If we lose arbitration, the transfer should be retried when the bus
becomes free.
transfer[] is an array of n transfer descriptors. Each descriptor describes part
of the transfer. The direction of the subtransfer is determined by the least
significant bit of addr. If nostart is 0, a START is first transmitted followed
by addr, otherwise the data flow continues where the previous subtransfer
left off. nostart must be 0 for the first subtransfer.
For writes, len bytes of data are read from "data" and transmitted. For reads,
len bytes are received and written to "data", unless "checksumonly" is 1, in which
case the len received bytes are summed and the (32-bit) sum stored in checksum.
If background transfers are in use, the transfer[] array and the data blocks must
remain available in unpaged memory for the duration of the transfer.
IICTransfer is re-entrant, but may return BUSY if re-entered (see above).
int HAL_IICMonitorTransfer(int bus);
Will be called on every interrupt, and should return the status of the transfer
currently in progress. If no transfer is in progress, the call should return
COMPLETED.
If the transfer is still in progress, INPROGRESS is returned.
If the slave failed to acknowledge (either the address or any later transmitted
byte), NOACK is returned.
If we have been addressed as a slave, the call returns SLAVE. More details to
be confirmed.
BUSY is not a valid response.
This will only be called in response to an IIC interrupt, with interrupts disabled.
The interrupt shall be cleared by this call.
Unknown return codes will be ignored.
Machine ID
==========
unsigned int64 HAL_MachineID(void)
Returns a 64-bit unique machine identifier. What does it mean?
Returns a 64-bit unique machine identifier,this may later be used to
form the ethernet MAC address but otherwise has no great significance on non
networked machines.
The top 8 bits are a CRC,based on the same algorithm the original DS2401
used - if the CRC fails zero will be substituted
ControllerAddress
=================
void *HAL_ControllerAddress(unsigned flags, unsigned controller)
Maps to RISC OS' OS_Memory 9 call - provides a way for people who must poke the
hardware to find it. Bits 0-7 of controller are the sequence number
(starting at zero), and bits 8-31 are the controller type. Currently allocated
types are:
0 = EASI card access speed control register (sequence no = card)
1 = EASI space (sequence no = card)
2 = VIDC1
3 = VIDC20
4 = IOMD
void *HAL_ControllerAddress(unsigned controller)
Asks the HAL where various controllers might or might not be.
Podule manager uses this information to determine at run time whether or not
to bother doing anything.
Returns r0=logical address of the chosen controller,or zero
0 = EASI card access speed control
1 = EASI space(s)
2 = VIDC1
3 = VIDC20
4 = S space base (IOMD,podules,NICs,blah blah)
5 = Extension ROM(s)
Matrix Keyboard
===============
......
New ClaimDeviceVector behaviour
R3 and R4 are meaningless, except for podule IRQ and FIQ-as-IRQ, which
keep the same behaviour as previously. (This is currently done in the Kernel,
but should be deferred to the Podule Manager).
For other claimants, if bit 31 of the R0 is set in the OS_ClaimDeviceVector
call, the interrupt will be passed on to earlier claimants unless your
routine claims the vector. This behaviour is then the same as IrqV claimants.
It is up to you to determine whether your device has interrupted. If it has,
you should service it, and claim the vector (by pulling the return address
off the stack). If not, pass the vector along. If no handlers claim the
vector, then the OS knows that there is no device driver able to handle the
interrupt being asserted, so it will mask off that line.
If you do not claim the vector, you must preserve R0 and R3. R1,R2,R12 may
be corrupted.
It is critical that your claiming or not is purely on the basis of whether
your card is interrupting, and is accurate. Not claiming when your card is
interrupting, or claiming when it isn't can both cause incorrect system
behaviour.
New Dynamic Area flags (Page flags)
-----------------------------------
12345678901234567890123456789012345678901234567890123456789012345678901234567890
New flags to support creating DAs whose pages are mapped with specified
cache and/or write buffer policies. For example, to support use of
writethrough/writeback cache, mini data cache, merging write buffer etc. on
XScale.
Define a new 3-bit field, P (bits 12-14), in DA flags word. P controls cache
or write buffer policy in conjunction with C and B bits (bits 5 and 4).
C B P
0 0 0 not cacheable, not bufferable [1]
0 0 >= 1 reserved
0 1 0 not cacheable, bufferable, OS decides buffer policy [2]
0 1 1 not cacheable, bufferable, non-merging
0 1 2 not cacheable, bufferable, merging
0 1 >= 3 reserved
1 0 0 cacheable, not bufferable, writethrough, read allocate data [3]
1 0 >= 1 reserved
1 1 0 bufferable, cacheable, OS decides cache policy [5]
1 1 1 bufferable, cacheable, writethrough, read allocate data
1 1 2 bufferable, cacheable, writeback, read allocate data
1 1 3 bufferable, cacheable, writeback, write allocate data
1 1 4 bufferable, cacheable, use alternative data cache [6]
1 1 >= 5 reserved
Notes:
[1] no cache nor buffer considerations
[2] P selects policy for write buffer; there are no cache considerations
[3] cacheable, not bufferable is not available on many modern ARMs, in which case
it will fall back to not cacheable, not bufferable
[4] writes that hit the WB cache will just be stored in the cache, other
writes go out unbuffered. Cache line writebacks may be buffered. Almost no
plausible use, but it's what the SA-110 does for
[5] buffer policy always decided by OS for all P, when C=1, B=1; policy
choices are for data cache (or unified cache if appropriate); currently
no choices for instruction cache
[6] the OS decides the policy for the alternative data cache
This diff is collapsed.
......@@ -2,16 +2,17 @@
Title: ReadSysInf
Author: Tim Dobson
Version: 0.03
Version: 0.13
Started: 19-Mar-91
Last updated: 21-Oct-91
Last updated: 25-Aug-02
Status: Preliminary
History:
19-Mar-91 TMD Created
04-Apr-91 TMD Updated OS_ReadSysInfo(2)
25-Aug-02 RPS Boy was this out of date
Extensions to SWI OS_ReadSysInfo in RISC OS 2.11 and later versions
===================================================================
Extensions to SWI OS_ReadSysInfo in RISC OS 2.11 and later versions
===================================================================
SWI OS_ReadSysInfo has been extended since RISC OS 2.00 - the full
specification is as follows:-
......@@ -57,25 +58,44 @@ attached monitor will be returned.
-------------------------------------------------------------------------
in: R0 = 2
out: R0 = IOEB ASIC presence flag
0 => absent
1 => present (type 1)
Other values are reserved for future versions of IOEB which are
not backwards compatible.
R1 = 82C710 (or similar) presence flag
0 => absent
1 => present
R2 = LCD ASIC presence flag
0 => absent
1 => present (type 1)
Other values are reserved for future versions of LCD ASIC which
are not backwards compatible.
R3 = word 0 of unique machine ID
R4 = word 1 of unique machine ID
in: r0 = 2
out: r0 = hardware configuration word 0
bits 0-7 = special functions chip type
0 => none
1 => IOEB
bits 8-15 = I/O control chip type
0 => IOC
1 => IOMD
bits 16-23 = memory control chip type
0 => MEMC1/MEMC1a
1 => IOMD
bits 24-31 = video control chip type
0 => VIDC1a
1 => VIDC20
r1 = hardware configuration word 1
bits 0-7 = I/O chip type
0 => absent
1 => 82C710/711 or SMC'665 or similar
bits 8-31 reserved (set to 0)
r2 = hardware configuration word 2
bits 0-7 = LCD controller type
0 => absent
1 => present (type 1) eg A4 portable
2 => present (type 2) eg Stork portable
bits 8-15 = IOMD variant
0 => IOMD
1 => IOMDL ie ARM7500 (Morris)
bits 16-23 = VIDC20 variant
0 => VIDC20
1 => VIDC2L ie ARM7500 (Morris)
bits 24-31 = miscellaneous flags
bit 24 0 => IIC bus slow (100kHz)
1 => IIC bus fast (400kHz)
bit 25 0 => keep I/O clocks running during idle
1 => stop I/O clocks during idle
bits 26-31 reserved (set to 0)
r3 = word 0 of unique machine ID, or 0 if unavailable
r4 = word 1 of unique machine ID, or 0 if unavailable
Some RISC OS computers are fitted with a chip providing a machine ID number
which is unique to each computer. Machines not fitted with an ID will return
......@@ -83,18 +103,24 @@ zero in both R3 and R4.
-------------------------------------------------------------------------
in: R0 = 3 (*** Only available from RISC OS 3.01 onwards ***)
out: R0 = 82C710/82C711 basic features mask 82C710 82C711
Bits 0..3 Basic IDE type 1 1
Bits 4..7 Basic FDC type 1 1
Bits 8..11 Basic parallel port type 1 1
Bits 12..15 Basic 1st serial port type 1 1
Bits 16..19 Basic 2nd serial port type 0 1
Bits 20..23 Basic Configuration type 1 2
Bits 24..31 Reserved
R1 = 82C710/82C711 extra features mask
Reserved for upwards compatible additional functionality
in: r0 = 3 (*** Only available from RISC OS 3.01 onwards ***)
out: r0 = I/O chip base features mask 710 711 665 669 UMC669
Bits 0..3 Base IDE type 1 1 1 1 1
Bits 4..7 Base FDC type 1 1 1 1 1
Bits 8..11 Base parallel type 1 1 1 1 1
Bits 12..15 Base 1st serial type 1 1 1 1 1
Bits 16..19 Base 2nd serial type 0 1 1 1 1
Bits 20..23 Base Config type 1 2 3 4 5
Bits 24..31 Reserved 0 0 0 0 0
r1 = I/O chip extra features mask 710 711 665 669 UMC669
Bits 0..3 IDE extra features 0 0 0 0 0
Bits 4..7 FDC extra features 0 0 0 0 0
Bits 8..11 parallel extra features 0 0 1 1 1
Bits 12..15 1st serial extra features 0 0 1 1 1
Bits 16..19 2nd serial extra features 0 0 1 1 1
Bits 20..23 config extra features 0 0 0 0 0
Bits 24..31 Reserved 0 0 0 0 0
R2-R4 Undefined (reserved for future expansion)
......@@ -127,3 +153,107 @@ returned in R1.
Information on extra sub-units will be accomodated in the remaining bits of
R0, or in R2-R4.
-------------------------------------------------------------------------
in: r0 = 4 (reason code)
out: r0 = LSW of Ethernet Network Address (or 0)
r1 = MSW of Ethernet Network Address (or 0)
-------------------------------------------------------------------------
in: r0 = 5 (reason code)
out: r0 = LSW of Raw data from Dallas Chip
r1 = MSW of Raw data from Dallas Chip
-------------------------------------------------------------------------
in: r0 = 6 (reason code)
r1 -> input block, 1 word per entry, giving number of value
required, terminated by -1
OR: r1 = 0 if just 1 value is required, and this is to beturned in r2
r2 -> output block, 1 word per entry, will be filled in on output
OR: r2 = number of single value required, if r1 = 0
On exit:
if r1 entry != 0:
r0,r1,r2 preserved
output block filled in, filled in value(s) set to 0 if
unrecognised/no longer meaningful value(s)
if r1 entry = 0:
r0,r1 preserved
r2 = single value required, or set to 0 if if unrecognised/
no longer meaningful value
valid value numbers available - see table below
CamEntriesPointer = 0
MaxCamEntry = 1
PageFlags_Unavailable = 2
PhysRamTable = 3
ARMA_Cleaner_flipflop = 4
TickNodeChain = 5
ROMModuleChain = 6
DAList = 7
AppSpaceDANode = 8
Module_List = 9
ModuleSHT_Entries = 10
ModuleSWI_HashTab = 11
IOSystemType = 12
L1PT = 13
L2PT = 14
UNDSTK = 15
SVCSTK = 16
SysHeapStart = 17
-------------------------------------------------------------------------