Kernel notes

This page is intended to provide an informal overview of the internals of the RISC OS kernel, to help inform OS maintainers of how everything fits together.

Source files and branches

The kernel source is located at castle/RiscOS/Sources/Kernel in CVS. There are two main branches of interest:

• The main branch. Development stopped on this branch after the 32bit conversion process but before the HAL was introduced. This branch is useful as a reference point to find out how things worked historically.
• The HAL branch. This is the main branch of the kernel, used for all currently supported machine types. It runs on the full range of hardware that RISC OS 5 supports, from ARMv3 to ARMv7.

Other branches (e.g. Cortex, RPi) are typically development branches that have fulfilled their original purpose and have been merged into a parent branch and closed.

There are five main parts to the kernel source:

• The AMBControl source, located in the s.AMBControl folder. AMBControl is the “application memory block” code that is used for lazy task swapping by the Wimp.
• The VDU driver source, located in the s.vdu folder. This contains all the code for handling VDU sequences, character printing, MODE 7 emulation, and the GraphicsV and HAL video interfaces.
• The PMF source, located in the s.PMF folder. It’s probable that most of this code was originally written by Paul Fellows (head of the Arthur project team), hence the folder name being his initials. It’s a collection of mostly disjoint functionality for things such as:
  • IIC support
  • OS_Byte, OS_Word SWIs
  • Mouse & keyboard handling
  • BBC-compatible buffers for the printer, serial, mouse, sound, speech, etc.
  • Real-time clock and date/time handling
• The MMU interface. This deals with the different page table formats required by the type of MMU in the host machine. There are several choices of interface/driver available, but the choice of which one to use must be made at compile time. Each one corresponds to a single source file (and a header file in HdrSrc):
  • s.MEMC1, s.MEMC2 – Obsolete interfaces used for the MEMC1 and MEMC2 chips.
  • s.ARM600 – Used for the integrated MMU that was introduced in the ARM600. The code is sutiable for machines from ARMv3 to ARMv5.
  • s.VMSAv6 – Used for VMSAv6-compatible MMUs, i.e. those found in most ARMv6 and ARMv7 CPUs.
• “The rest”. This is everything else in the ‘s’ folder not listed above, including but not limited to:
  • Dealing with startup and resets
  • The HAL interface
  • IRQ, SWI, service call and vector dispatch
  • Cache/TLB maintenance functions
  • All kinds of memory allocation (dynamic areas, heaps, etc.)
  • The command line interpreter and system variables

Kernel workspace

The kernel workspace is defined in hdr.KernelWS. There are two workspace layouts available:

1. The legacy layout. This uses the first 32K of RAM for storing the bulk of the kernel workspace and the processor vectors. This is currently the default mode for all machine types, and provides the maximum amount of compatability with previous versions of RISC OS.
2. The “high processor vectors”/“zero page relocation” layout. With this layout, the first 16K of workspace and the processor vectors are relocated to &FFFF0000. The 16K of scratch space located at &4000 remains in its legacy location. This mode is only available on CPUs that support the high processor vectors feature (any ARMv6+, and some ARMv5, e.g. the IOP321 used in the Iyonix).

The type of workspace in use is selected via the HighProcVecs option in hdr.Options.

Although the majority of the kernel workspace is kept private, there are several locations exported publicly to the rest of the OS in hdr.PublicWS. However only the legacy locations are exported here; for compatability with kernels that use zero page relocation, programs should first attempt to query the address using OS_ReadSysInfo 6 before falling back on the legacy address.

Significant workspace locations are listed below:

“Zero page” locations

• IRQsema – Although the name suggests that it’s a semaphore, it’s actually more than that. It’s the head of a linked list of all processing that’s been interrupted by IRQs. Various bits of code check IRQsema as method of working out whether the current code is executing in the foreground or the background, or for checking whether specific code sections have been interrupted. See the comments at the top of s.PMF.IIC for a rough guide as to how the linked list is formatted.
• DomainId – The Wimp uses this to store the active task handle. There are still a few pieces of code that rely on this instead of using Wimp_ReadSysInfo 5.
• ESC_Status – This stores the escape status, as returned by OS_ReadEscapeState. There are still pieces of code which read this value directly, but the only significant bit of the byte appears to be bit 6, which is what OS_ReadEscapeState checks for.
• RISCOSLibWord, CLibWord – These are used by the shared C library to store pointers to the modules workspace. This allows the ROM version of the module to continue to function even after its been killed off (the module must continue to function because any C code in the ROM image will have been staticly linked against it)
• FPEAnchor – This stores a pointer to the FPEmulator’s workspace.
• DebuggerSpace – Used by the Debugger module to store breakpoint handlers. When the debugger places a breakpoint it simply places a MOV PC,#xx instruction which jumps to the appropriate handler code in zero page.
• CLibCounter – Used by the tmpnam() implementation in the shared C library
• Modula2_Private – Obsolete entry used by Acorn’s long-abandoned Modula2 project.
• HeapSavedReg_*, Heap_ReturnedReg_* – Register save/restore blocks to allow OS_Heap to be re-entered.
• DUMPER, Abort32_dumparea – Register save blocks used by the abort handlers.
• MMUControlSoftCopy – Soft copy of the MMU control register, aka the CP15 system control register. This is required due to the register being write-only on ARMv3 machines.
• Page_Size – This is used to store the page size of the system. It was vital during the MEMC1/MEMC2 era, but pretty much obsolete now that 4K page size is standard (and lots of code assumes 4K page size anyway).
• ScratchSpace – A 16K block (from &4000 to &8000) of temporary workspace used for various purposes by many different modules.
• PhysRamTable – Each entry is a pair of words. The first word contains the base physical address of a RAM block, and the second word contains the size and flags. The flags are only stored in the lower 12 bits of the word; masking them out will leave you with the size value (measured in bytes). The flags are the same flags as specified by the HAL when it calls RISCOS_AddRAM. Note that versions of RISC OS prior to 5.19 didn’t store the flags at all.

CursorChunkAddress

CursorChunkAddress marks the start of a second area of workspace (currently) located at &FAFF0000. This area is used for the cursor & sound DMA buffers, along with the OSCLI workspace and SWI/IRQ despatchers.

• SWIDespatch – The SWI despatcher is a small routine that gets copied out of ROM (see SVCDespatcher in s.Kernel).
  • This code is branched to directly from the SWI processor vector. (TODO – Check this!)
  • A lookup table directly follows the despatch code, allowing quick access to the kernel SWIs.
  • Non-kernel SWIs drop through to the NotMainMOSSWI routine within the ROM image, where a hash table is used to quickly find the appropriate module.
  • Theoretically the SWI despatcher will cope with SWI calls from Thumb mode, but it’s unknown if this has ever been used or is fully reliable.
  • The kernel SWI despatcher stores the SPSR in R14, allowing the SWIs to easily update the return flags.
  • The RAM-based SLVK_* routines are used to return from the SWI despatcher.
• DefaultIRQ1V – The default IRQ despatcher is a small routine that gets copied out of ROM (see DefaultIRQ1Vcode in s.NewIRQs).
  • This is the routine that can be overridden by OS_ClaimProcessorVector. As such, it doesn’t need to preserve r0-r3,r11 or r12, or worry about IRQsema or triggering callbacks (Initial_IRQ_code handles that).
  • The DefaultIRQ1V code is next to the table of IRQ handlers (OS_ClaimDeviceVector/OS_ReleaseDeviceVector).

The CAM

The CAM is a data structure used to track the allocation of physical RAM pages. It’s implemented as a simple table indexed by the physical page number. Each entry in the table is two words long; the first word contains the logical address which the page is currently mapped to (or the special value of ‘DuffEntry’ if unmapped), and the second word contains the PPL (“Page protection level”) and additional flags (see below table). The PhysRamTable is used to map the physical RAM page numbers to and from physical RAM addresses.

The above flags are all defined in s.ChangeDyn, at the DynamicAreaSWI code.