Pyromaniac
Pyromaniac features
System
- The system supports only some of the modes:
- SVC mode is used for modules (and the OS).
- IRQ mode is used for timed events.
- USR mode for applications and utilities.
- UND mode is used for the undefined instruction handler.
- Modes FIQ, ABT, SYS, MON and HYP are not used.
- Only 32bit modes are supported.
- MMU is not enabled - all the execution happens within a flat memory space environment.
- Memory protection is not used within any memory regions (including the ROM area).
- The low CPU vector area at address 0 is implicitly trapped with watchpoints to report accesses to the memory range for diagnostic purposes.
- Internal exceptions may be fatal. They are reported with a python backtrace (configurably) and then trigger the Error handler using a hardware error code. Sometimes that might mean that multiple exceptions are reported from a single failure, due to further problems handling the exception.
- Timers are managed without an interrupt system, but IRQ mode is still used for them.
- Exception vectors are implemented in high address space.
SWIs
- SWIs are provided for most of the Kernel operations.
- Most of the standard SWIs from RISC OS to 3 are supported, with some of the RISC OS 4 and Select specific features.
- A few of the RISC OS 5 SWIs are supported.
- Unsupported SWIs:
OS_BreakPt
- Not supported.
OS_UpdateMEMC
- Not relevant to RISC OS Pyromaniac.
OS_InstallKeyHandler
- Not supported.
OS_ClaimScreenMemory
- Kernel does not manage the screen buffer, so this is redundant.
OS_ReadRAMFsLimits
- Kernel does not manage RAMFS, so this is redundant.
OS_ClaimDeviceVector
, OS_ReleaseDeviceVector
- Without physical hardware and interrupts, these are redundant.
OS_DelinkApplication
, OS_RelinkApplication
- Not supported.
OS_HeapSort
, OS_HeapSort32
- Not supported by the Kernel (provided by the OSSWIs module)
OS_ExitAndDie
- Not supported.
OS_ReadMemMapEntries
, OS_SetMemMapEntries
, OS_FindMemMapEntries
- Without physical pages, these are redundant.
OS_SerialOp
- Not supported
OS_ClaimSWI
, OS_ReleaseSWI
- Not supported (not sure these were ever defined)
OS_Pointer
- Not supported
OS_AbortTrap
- Not supported
OS_MMUControl
- Without an MMU, controlling it is redundant.
OS_SpecialControl
- Not supported (not sure what this was intended for)
OS_EnterUSR32
, OS_EnterUSR26
- Not supported
OS_TaskControl
- Not supported (not sure what this was intended for)
OS_DeviceDriver
- Not supported
OS_Hardware
- Not supported
OS_IICOp
- Not supported
OS_ConvertVariform
- Not supported
- Kernel SWIs can be trapped with
OS_ClaimOSSWIs
.
- SWIs can warn about misuses:
- SWIs issued in SVC mode without the X-bit set may report warnings to the trace output.
- SWIs issued in SVC mode without the X-bit which cause errors may report errors into the trace output.
- SWIs issued in IRQ mode will report a warning in the trace output.
- SWI execution depth may be explicitly limited.
- Configuration
kernel.swi_recursion_limit
may be set to the number of nested SWI calls that may be performed before an error is raised.
- Configuration
emulation.internal_recursion_limit
may be required to increase the limit of Python function call nesting to allow the SWI recursion limit to be effective.
Memory (Memory management)
- Dynamic areas are partially implemented, but don't support the full range of features:
- Creation - supported
- Deletion - supported
- Resizing - supported
- Sparse mappings - not supported
- Handlers - supported:
- Pre/Post Shrink/Grow will be called on resize.
- Shrinkable areas - not supported
- Physical map addresses/specific pages - not supported
- Abortable areas - not supported
- Clamping - supported
- Domain mappings - not supported
- Heap DAs - supported
- Heap DAs automatically resize when they need to grow.
- Heap DAs are used for the System Heap and the RMA.
- Corruption in Heap DAs (including the system heap and RMA) triggers a report into the trace output when it is detected.
- Enumeration - supported
- Renumbering - supported
- Access permissions - not supported
- Locked areas - supported
- Doubly mapped areas - not supported
- Application space, RMA, ROM, the System Heap, SVC and UND stack dynamic areas are implemented.
- New dynamic areas have been created:
- Zero page is registered as a Dynamic Area.
- By default this is 0 bytes and so would be inaccessible.
- It can be configured to be accessible, which allows the modules like SharedCLibrary and Debugger to initialise, which would otherwise try to access data in the zero page area (in the Select versions)
- CPU vectors region is registered as a Dynamic Area.
- Application space is remappable using the
OS_AMBControl
SWIs.
OS_AMBControl
doesn't allow remapping into different areas of memory. It can only map into the application space.
- Lazy mappings are not supported.
- Application space can be resized directly. The free pool does not exist, so resizing it does not push pages into the application space.
OS_AMBControl 9
provides information on the mappings.
- Without the MMU, memory protection is not relevant.
OS_ValidateAddress
reports only the state of the base address.
OS_Memory
calls are only supported enough to read the system size. Physical pages do not exist, so it is not possible to enumerate or remap memory.
- The memory returned for regions is configurable, but may also be forced to specific sizes.
- Memory mapped I/O regions (external hardware registers mapped into memory space) are supported, but are incredibly slow, so are disabled by default. At the present time, no memory mapped regions are offered by the implementation.
- Addresses and sizes of DynamicAreas in the memory map are configurable (through the
memorymap
configuration group), although the system may not function as expected for some configurations.
- The base address for new dynamic area allocations is configurable.
OS_Heap
managed areas are configurable:
- Minimum size of allocations can be set (
heap.minimum_allocation
).
- Maximum size of a heap can be controlled (
heap.maximum_heap_size
), which makes it easier to recognise heap header corruption.
- Extends which reduce to 0 or less can be reported as errors, rather than returning -1 (
heap_extend_to_nothing_is_error
)
- Blocks claimed and freed can be implicitly cleared so that they do not contain left over values, or make it easier to spot invalid uses (
heap.clear_*
).
Interrupts
- Generalised interrupts not supported.
- Ticker events are implemented:
OS_CallEvery
and OS_CallAfter
can be used to register timed events, and they will be called back at the appropriate time.
- Interrupting ticker events require a special build of Unicorn at present - see https://github.com/unicorn-engine/unicorn/issues/1105 for more details.
- Interrupting ticker events are believed to be unreliable, causing interrupts that break the current execution, and are disabled at present.
- Ticker events are triggered when the system is idle and has threaded out of the ARM execution, which may mean that events are delayed.
- TickerV is supported.
- No VSync (although some of the machinery for it is present).
Modules
- Modules are loadable into ROM, RMA and may be provided in ROM images through Podule manager:
- ROM modules are initialised first.
- Early init modules will be initialised before other modules.
- ROM modules are not protected.
- ROM modules may report errors and will not fail the boot.
- RMA modules are initialised once the OS has booted.
- RMA modules which report errors will fail pyro initialisation.
- Podule Manager can provide additional modules which are treated like ROM modules.
- Module entry points are partially implemented:
- Initialise/Finalise - implemented.
- Services - implemented, supporting Ursula style service tables.
- Start - implemented.
- Help and commands - partially implemented.
- Commands can be dispatched (through the command line and with
OS_CLI
)
- GSTrans mappings and the parameter limits in the infoword are honoured.
- Informational and Help-only commands are supported.
- FileSystem commands are dispatched when the filesystem is selected.
- Syntax messages which don't start with
Syntax: *
are warned about (configurable).
- SWIs - implemented (but not the SWI decoding code).
- Extended flags - non-32bit modules are rejected, early init modules are started first.
- Allocations within the RMA (Claim, Release, Extend, etc) are implemented.
- Module, ROM and extension/expansion ROM enumeration is supported.
OS_SWINumberToString
/OS_SWINumberFromString
are implemented, resolving names from a file of constants and from dynamically loaded modules.
- Modules may be multiply instantiated, and preferred.
- Modules may be reinitialised. ROM modules may be reinitialised if they had been killed.
- Modules are implementable in Python to provide implementations without having to load the original module.
- Initialise/Finalise - implemented.
- Start - not implemented.
- Service - implemented, but no Ursula style service tables.
- SWIs - implemented.
- Help - implemented.
- Commands - implemented.
- Module notification services are not supported.
- Podules supported through the Podule PyModule.
- Only a single extension ROM is currently supported with
--config podule.extensionrom1
.
- Podules can only load full RISC OS ROM images at present (actual podule images not supported).
- Podule chunk directories will be synthesised from the ROM images.
- RISC OS Select 32bit images are supported (requires
memorymap.rom_base
to be assigned to a different location such as &8800000
to avoid memory area clashes).
- RISC OS 5 images are partially supported.
- Unplugging modules through the NVRAM configuration is not supported.
- Unplugging modules is supported through the Pyromaniac configuration (
modules.unplug
configuration option)
OS_Byte
- Dispatched through ByteV.
- Only some of the SWI calls are implemented:
- 78 implemented at time of writing; see
--list-registered OS_Byte
for named handlers.
- See individual sections of the features for more detail on support.
- Status variables (
OS_Byte &A6
upward) are supported, although they may not be used by the system.
- NVRAM is implemented through this
OS_Byte
161/162 (but not checksumed).
- NVRAM can be preserved by supplying a backing file with
--config nvram.backingfile=<filename>
.
- NVRAM backing files can be 240 bytes of data, or a file containing the values.
- NVRAM backing files will be written every time the data is updated.
- An IIC implementation is provided which contains the NVRAM storage, although this is currently not used.
OS_Byte 129
and OS_Byte 0
have configurable values to return for the OS version and Machine type.
OS_Byte 1
(user flag) is supported.
- Event enabling and disabling with
OS_Byte
13/14 is supported, and will be honoured by OS_GenerateEvent
and internally generated events.
- Other OS_Byte operations are documented in the following sections.
OS_Word
- Dispatched through WordV.
- Only a few calls implemented:
- System clock - implemented
- Interval timer - not implemented
- Time conversions - some read, no write implemented
- Read character definition - implemented
- Palette operations - read and write palette are implemented
- Pointer operations - some implemented (see the Graphics system for more details)
OS_ReadSysInfo
- A few of the calls are implemented, enough to return the hardware as having none of the features of the other platforms:
- Screen size (
OS_ReadSysInfo 0
) - 0
- Mode/Monitor/Sync (
OS_ReadSysInfo 1
) - configured module, with monitor type 'MDFs', and vertical sync.
- Chips and ID (
OS_ReadSysInfo 2
) - no chips, same ID as OS_ReadSysInfo 5
- IO Features (
OS_ReadSysInfo 3
) - no chips present
- Mac address (
OS_ReadSysInfo 4
) - configurable
- Unique ID (
OS_ReadSysInfo 5
) - configurable
- Kernel values (
OS_ReadSysInfo 6
) - most values are 0; values only returned where implemented
- Abort information (
OS_ReadSysInfo 7
) - correctly returned
- Platform Class (
OS_ReadSysInfo 8
) - configurable
- ROM Information (
OS_ReadSysInfo 9
) - configurable
- OS Version (
OS_ReadSysInfo 10
) - not implemented
- Debug handlers (
OS_ReadSysInfo 11
) - not implemented
OS_PlatformFeatures 0
supported, but returns no IRQ trigger function, and limited features.
OS_SynchroniseCodeAreas
supported, and used for internal recaching of changed memory regions. May be a very slow operation.
- Aborts update DFAR/DFSR, IFAR/IFSR and are reported by the Debugger module.
Services
- Services are dispatched internally and to modules.
- Many of the system operations do not dispatch services in the way they do under RISC OS Classic; only a few have been implemented.
- Fast service dispatch using the RISC OS 4 service tables is supported.
- PyModules do not currently support fast service dispatch.
Vectors
- Vectors may be claimed (
OS_Claim
), added to (OS_AddToVector
), released (OS_Release
) and dispatched (OS_CallAVector
).
- When called, the vectors may be claimed (by pulling from the stack).
- Post-processing and multiple calls to lower level handlers are not supported.
- Most OS SWIs call the vectors as expected.
UserV
is implemented as a simple message printer (configurable), to allow testing of the vector dispatch.
- The Debugger module includes a
*Vector
command to list the vectors in a similar way to the tool of the same name.
Variables (System variables)
- Basic setting and reading of variables is supported.
- Variables are GSTrans'd on set if requested.
- Variables are EvaluateExpression on set if requested.
- Macros are GSTrans'd on read.
- Code variables are supported (both within RISC OS and PyModules)
- Enumeration is supported.
- Deleting is supported.
- Variables are isolated to the emulated environment (not propagated from host environment - this would not really make sense as they have completely different interpretations).
- Default system variables:
CLI$Prompt
set to *
.
File$Path
set to @.
.
Run$Path
set to ,%.
.
Alias$.
set to Cat
.
FileSwitch$CurrentFilingSystem
set to HostFS
.
FileSwitch$HostFS$CSD
(and friends) set to $
.
Sys$Time
set to a code variable to give the current time.
Sys$Date
set to a code variable to give the current date.
Sys$DateFormat
set to %24:%mi:%se %dy-%m3-%ce%yr
Sys$Year
set to a code variable to give the current year.
Sys$ReturnCode
set to 0
.
Sys$RCLimit
set to 256
.
Conversions
OS_Convert*
family are implemented (except the new OS_ConvertVariform
).
OS_GSTrans
is implemented. OS_GSInit
and OS_GSRead
are implemented in terms of OS_GSTrans
(where in RISC OS Classic, it was the other way around).
Buffers
- Buffers 0-9 are supported internally, but largely unused.
- Buffer 0 (keyboard input) is read as part of read key interface, but key presses are not inserted into the buffer (they're read directly). This means that
OS_Byte 138
to insert characters works and takes precedence over the input from the keyboard.
- Buffer 9 (mouse events) is updated by the pointer, but is never read.
OS_Byte 15
and OS_Byte 21
supported for flushing buffers
OS_Byte 128
, OS_Byte 138
, OS_Byte 145
, OS_Byte 152
. OS_Byte 153
are supported for reading size, inserting and removing bytes from the buffers.
InsV
, RemV
and CnPV
are supported for the buffer insertion, removal, counting and flushing. Both byte and block interfaces are supported.
BufferManager
module does not exist yet - the buffers are all handled internally.
OS_ReadC
, OS_Byte &81
(INKEY) and OS_ReadLine
are implemented, and take input from stdin, if available.
OS_ReadC
dispatched through ReadCV
(RdChV
)
OS_ReadLine
/OS_ReadLine32
are supported:
ReadLineV
is used to dispatch such calls.
- Configurably may use native 'readline' to give history and line editing.
- May infer the prompt within the output.
- History file and the truncation length are configurable.
- Will output its read line to the graphics implementation only on a complete line being supplied.
- Escape within a read line is supported (only partially with the native 'readline')
OS_ChangeRedirection
is implemented.
*Exec
input is implemented.
INKEY
is implemented.
- Buffered keys (passed through buffer 0) are returned from the console.
- Keyboard scan only works if the UI component supports it (GTK and WxWidgets currently support input)
- Under console the keyboard scan will always return no keys pressed:
OS_Byte &79
always returns 'no keys pressed'.
OS_Byte &81
with -ve values always returns 'no keys pressed'.
- Function key input is expanded from
Key$*
if the key input is triggered.
- Function keys can be triggered from the UI where the UI passes these through.
- Function keys can be triggered by buffer insertions with
OS_Byte 138
.
- Console input can be trigger function keys for certain terminal control sequences (configurable with
input.terminal_escape
)
- Cursor key operations can be controlled with
OS_Byte 4
.
- Mode 0 (cursor editing) is not supported (silently swallows cursor key presses).
- Mode 1 (generating codes) generates key codes.
- Mode 2 (act as function keys) triggers function keys, as above.
- Input of the cursor keys is supported through the GTK and WxWidgets UI.
- Input of the cursor and function keys in the console is supported for certain terminal control sequences.
- Input encoding is configurable.
- Input encoding defaults to UTF-8 (configurable with
input.utf_support
).
- The input encoding will be converted to the current alphabet before being inserted into the buffers.
OS_Byte 219
to redefine the tab character is supported.
- Escape should be handled correctly.
- Escape is triggered by either reprogramming the escape key using
OS_Byte 220
, or by ctrl-c interrupt.
- Escape effects configured using
OS_Byte 200
are honoured.
- Escape effects configured using
OS_Byte 230
are not supported.
- In GTK and WxWidgets UIs, the Escape key is functional.
- Escape should follow the regular pattern for RISC OS, although behaviour such as flushing buffers is not effective if keys are not being passed through buffers (as is the case for console).
- Escape cannot be detected whilst in the native readline input.
- KeyV can be triggered by the UI (configurable with
input.keypress_enable
).
- Generates character input into the buffers on key presses.
- Key press state in
OS_Byte &79
and OS_Byte &81
are not implemented yet.
- Key repeats delay and rate are supported.
- Key status flags in
OS_Byte &CA
is supported.
- KeyV updates the flags in this OS_Byte value when Shift, Ctrl, Caps Lock, Scroll Lock and Num Lock are pressed.
- Caps Lock and Anti-Caps Lock ('Shift enable') are honoured from these flags when characters are inserted into the buffer.
- Scroll Lock has no effect.
- Num Lock has no effect.
- Configurable whether KeyV is used outside of the UI (console input never passes through KeyV).
- On Windows, console input is read in the background when requested, so as to not block timers.
- EOF (ctrl-d) can be configured to raise an error, issue
OS_Exit
or OS_Reset
, fake an Escape key press, or be ignored.
Output (Character output and VDU)
OS_Write
family are implemented, and write to stdout.
OS_NewLine
supported.
- When used in the plain VDU implementation is is configurable whether it generates combinations of
\r
and \n
.
- When used in ANSIText VDU implementation will always generate a
\n
.
OS_PrettyPrint
will print formatted output, honouring the current text window. This may result in oddly positioned line breaks in console mode as the text window will most likely not match the size of the text output console.
- Redirection of output is not fully supported:
OS_ChangeRedirection
is supported, but never acted upon.
OS_Byte 3
, character output destination, is not honoured, although it does track state.
- Printer output is passed around internally, but is not directly diverted to a separate device.
VDUXV
redirection is supported.
*Spool
/*SpoolOn
is supported.
- Stdout is converted from the current alphabet (controllable by
OS_Byte &47
and *Alphabet
) to the output encoding (which defaults to UTF-8). These character sets (alphabet and output encoding) are configurable with --config vdu.alphabet
and --config vdu.output_encoding
).
- Output is flushed on the console in a configurable manner (with
--config vdu.flush
). Output can be flushed at the end of a line, after each character, or only when the logical position of the cursor changes outside the usual console progression.
- VDU sequences are supported, and state is retained for most of the calls. When unsupported, they will be consumed, but the default action is to print the sequence as a diagnostic when they occur, eg '[^:]' (configurable).
VDU 1
/VDU 2
/VDU 3
is tracked and passes to an internal 'printer' which does nothing with it.
VDU 5
/VDU 4
state is tracked and output diverted to the graphics system if necessary.
VDU 21
/VDU 6
state is implemented.
VDU 7
is issued as Service_ExternalBell
(SystemBell
internal module will convert this to a Sound call).
VDU 8
-VDU 13
(except VDU 12
) cursor movement are passed through to the console as appropriate. VDU 9
is passed to the console as a space to match RISC OS behaviour.
VDU 12
(CLS) is ignored by the console (the ANSIText implementation will clear the screen as expected).
VDU 14
/VDU 15
is tracked, and paging actions can be configured through vdu.paging
.
VDU 16
(CLG) is passed to the graphics system.
VDU 17
(set text colour) is ignored by the plain implementation (the ANSIText implementation will set the colour)
VDU 18
(set graphics colour) is passed to the graphics system.
VDU 19
(set palette) records the palette (only a single colour is recorded).
VDU 20
(reset colours) resets the palette entries and colours, and passes to the graphics system.
VDU 22
(change mode) changes the effective mode to a numbered mode, and passes to the graphics system.
VDU 23
is processed and unknown calls will be passed to UKVDU23V
(which is many of them).
- Character definitions and reading are supported.
- Resetting character definitions with
OS_Byte 20
and OS_Byte 25
are supported.
- The default definitions are the default definitions provided by the RISC OS Kernel.
- Character redefinition by alphabet is provided by the International module.
- Text cursor shape definition is supported (although not used within the Cairo graphics implementation).
- Text window is supported in limited ways (appears correctly on UI through Cairo)
- Text character movement direction is supported.
- Colour tint selection is supported.
- Text colour swapping is supported.
- Character sizes are supported in Cairo.
- Teletext option selection is not supported.
- ECF definition is not supported.
- ECF origin is supported, but never used.
- Scrolled text window operations are supported in character mode in the graphics system, but not in byte mode.
- Teletext configuration is not supported.
VDU 24
(set graphics window) is passed to the graphics system.
VDU 25
(plot) is passed to the graphics system.
VDU 26
(reset windows) resets the text and graphics windows.
VDU 28
(set text window) records the text window (although the positioning is not supported fully in ANSIText; should be correct in the graphics system).
VDU 29
(set origin) is passed to the graphics system.
VDU 30
/VDU 31
cursor supported for moving the cursor (in ANSIText).
VDU 127
deletes a character.
- Paged mode is supported and the manner of waiting for output can be configured:
- Paged mode does not detect a
Shift
to continue at the console, or in the graphics UI.
- A configuration option can be set to change the behaviour to wait for a key press before continuing.
- Slow output mode (triggered by holding down the ctrl key during VDU 4 output), is not supported.
- Palette operations are tracked.
OS_ReadPalette
is supported, for main palette and the pointer; border colours are not supported.
- In ANSIText the palette changes are effective after the change (ie do not change existing text).
OS_Byte 9/10
and VDU 23,9/10
to change flashing colour timings are supported, but ignored.
OS_SetColour
is supported for both text and graphics output, but not for patterns.
- Tinted colours are supported when in 64/256 colour modes.
- Teletext mode is not supported.
- Alternative VDU implementations may be provided and are configured through
--config vdu.implementation=<value>
; use --list-implementations VDU
for a list of VDU implementations):
- 'plain' provides the output described above.
- 'ansiext' augments the 'plain' output by converting RISC OS text colour sequences to ANSI colour sequences.
OS_Byte &86
always reads cursor input position as the current cursor output position.
OS_Byte
calls to read character at input or output cursor are supported only in graphics implementations at present.
OS_ReadModeVariable
/OS_ReadVduVariables
is implemented for VDU and graphics parameters. See Graphics section for details of the graphics parameters implemented. Text parameters:
- Text window bounds supported.
- Text window size supported.
- Text colour and tint supported.
- Highest numbered mode supported.
- Text character size and spacing supported.
- ANSIText implementation supports:
- Foreground and background colours (and palette changes, but only for subsequent output) using standard colours, 256 colours and 24-bit interfaces (configurable)
- Cursor positioning.
- Clear screen.
- Cursor movement.
- Cursor shape (block/underline), flash state, and visibility.
- Changing size of terminal to match screen mode (configurable).
OS_PrintChar
is implemented internally but goes nowhere.
OS_RemoveCursors
/OS_RestoreCursors
are internally implemented but do nothing (no flashing cursor currently implemented).
- A few
ColourTrans
SWIs have been implemented to make it possible to use some applications which need to work with colour:
- ColourTrans_SetTextColour is supported to select colours.
Graphics
- Graphics calls are understood, and passed on to selected implementation.
null
does not support any output, but tracks the interfaces to give useful returns from SWIs.
cairo
provides the primary graphics implementation.
- When selected directly it may render to a bitmap or an SVG.
- At the end of execution, the contents of the graphics system will be saved to a configurable file.
gtk
provides a UI implementation based on GTK 3 (see the Video section)
- The underlying graphics are derived from the Cairo implementation.
wx
provides a UI implementation based on WXWidgets (see the Video section)
- The underlying graphics are derived from the Cairo implementation.
- The state of the graphics system is tracked where possible, and may be used by the different implementations.
OS_Plot
calls are interpreted and may be acted upon by the different implementations.
- Debug option
plotsvg
can be used to output diagnostics of what OS_Plot operations were performed as SVG statements. These can be dropped into an SVG file and will render a partial image of what would have been plotted. Currently this is upside down due to the differences in coordinate systems.
- Unhandled Plot calls are passed to
UKPlotV
.
OS_ChangedBox
state updated by the implementation if it is acted upon. If the implementation provides updates, they will be returned by the SWI.
- VDU 4 and 5 output is passed to the graphics system.
- Dot-dash patterns are supported within the Cairo implementation.
- ECFs are understood but never acted upon.
- Colour selection works for shallow colour, and 256 colour modes.
- Modes exist and can be operated on:
- Numbered modes can be selected with
VDU 22
:
- Mode descriptors are not supported.
- Default screen mode is configurable (
vdu.mode
).
OS_ReadModeVariables
and OS_CheckModeValid
are implemented.
OS_ScreenMode
0 is the only call implemented, and only supports numbered modes.
Service_ModeExtension
is used for unknown modes.
- Only the mode variables will be set from the returned modes; VIDC parameters are ignored.
- Substitute modes are supported.
Service_ModeChanging
and Service_ModeChanged
are issued on the change of the mode.
OS_Byte &87
reads the current mode (and character at cursor, if it is decodable using the current bitmap font).
OS_ReadModeVariable
/OS_ReadVduVariables
are implemented for VDU and graphics parameters. See Character output and VDU section for details of the text parameters implemented. Graphics parameters:
- Graphics window supported.
- Cursor position history supported (in both the internal and external variants).
- Graphics origin supported.
- Graphics colours and tints supported.
- Graphics character size and spacing supported.
- Display and screen base addresses, and screen memory size not supported (as there is no frame buffer; see Video section)
- VIDCClockSpeed not supported.
- Horizontal line is supported (as used by the classic Draw module).
- PolyHLine not supported.
- VideoDisplayNumber not supported.
- Graphics colour patterns ECFs, colours to write to the screen, are not supported.
- VSync is not explicitly supported (
EventV VSync
is not triggered), but OS_Byte 19
will wait until an appropriate period has passed.
- Sprites are stubbed:
- Redirection to the screen will return without doing anything.
- Screen banks are supported, although whether they are effective and how many is dependant on the graphics implementation.
- Cairo graphics support:
- Output buffer is either SVG or a 24bit bitmap; paletted modes are emulated.
- The output may be saved to a PNG, SVG or PBM on exit (configurable with
graphicscairo.save_on_exit
and graphicscairo.save_filename
)
- 'Video' may be created by configuring the creation of frames, which can then be passed to
ffmpeg
to create a video (configurable by graphicscairo.video_enable
and graphicscairo.video_directory
)
- For line drawing when output is a bitmap, drawing may be anti-aliased (disabled by default).
- Lines supported.
- End point selection not supported (all lines have both ends).
- Dotted lines are supported.
- End point selection not supported (all lines have both ends).
- Continuation pattern not supported (all patterns start at the beginning).
- Points supported.
- Triangles supported.
- Rectangles, Parallelograms supported.
- Circles supported (may not render as expected in non-square pixel modes)
- Arcs, segments, sectors, ellipses not supported.
- Flood fill not supported.
- Block copy, block move are supported.
- Solid colours supported.
- ECF not supported.
- GCOL actions are not supported (all operations are solid)
- Gap modes are rendered correctly for text output (in both BBC gap mode style and regular style), although graphics operations in gap modes may produce odd effects.
VDU 12
and VDU 16
(CLS
and CLG
) are supported.
VDU 4
output is passed to the graphics implementation and will be rendered appropriately.
VDU 5
text supported, both as bitmaps and as a native font (not through FontManager), configurably.
VDU 5
text movement supported as expected, and should bound correctly at the graphics window edges.
VDU 4
and VDU 5
text size configuration are honoured.
- Text window scrolling is supported (not hardware scrolling).
- Graphics window bounds all graphics.
- Reading text characters from screen is supported in bitmap mode.
OS_ReadPoint
is supported for the current known colours.
- Palette changes only affect subsequent output, not existing output on the screen.
Draw
path and fill rendering supported:
- Paths are supported, although the gap operations may not work as expected.
- Fill rule NonZero and EvenOdd are supported, but Positive and Negative are not.
- Triangle caps not supported.
- All fills are interior (boundary regions, and exterior fills not supported)
- Line widths are supported.
- Flattening value is ignored
- Dash pattern is ignored.
- Matrix transform operations are supported.
- Screen banks are supported:
- 2^32-1 screen banks are supported, and will come into existance when referenced.
- Display and VDU banks are honoured correctly.
- Some graphics ColourTrans calls are supported:
ColourTrans_SetGCOL
is supported, but will never use ECFs.
ColourTrans_ReturnGCOL
is supported, but returns a palette number not a GCOL.
ColourTrans_SetFontColours
calls to Font_SetColourTable
.
Video
- No frame buffer is currently supported (no Direct Screen Access).
- UI Configurables:
- Window title is configurable.
- Scale factor is configurable.
- Border around the graphics display is configuable in colour and size (
graphicsui.border_colour
and graphicsui.border_size
).
- Minimum width is configurable, allowing scale up of very small modes.
gtk
implementation:
- Closing the window will terminate the system.
- Dynamic scaling not supported.
- Eigenfactors supported.
- Redraws are able to be capped at a redraw rate, to prevent the system running away with refresh as fast as possible.
- No VSync equivalent.
- Key presses are passed on to the input system.
- Mouse movement is passed on to the pointer system.
- UI pointer shape is updated from RISC OS (configurable).
- Border is rendered around the graphics output (configurable colour; not using RISC OS palette definition).
- Menus offer RISC OS interaction options:
- Screenshot (to file and to clipboard)
- Reboot
wx
implementation:
- Closing the window will terminate the system.
- Dynamic scaling not supported.
- Eigenfactors supported.
- Redraws are able to be capped at a redraw rate, to prevent the system running away with refresh as fast as possible.
- No VSync equivalent.
- Key presses are passed on to the input system.
- Mouse movement is passed on to the pointer system.
- UI pointer shape is updated from RISC OS (configurable).
- Border is rendered around the graphics output (configurable colour; not using RISC OS palette definition).
- Menus offer RISC OS interaction options:
- Screenshot (to file and to clipboard)
- Reboot
OS_Byte 144
(*TV
) is supported, but does nothing.
Pointer (Pointer and mouse)
- Outside of the UIs, pointer and mouse operations only track their settings, they never generate any input.
- Mouse clicks may be passed through from the UI, and partially use the mouse buffer (the events are queued but never retrieved).
- KEYV calls for the mouse clicks not supported.
- Pointer configuration is partially supported:
- Pointer shape can be configured with
OS_Word 21
, and is passed to the graphics system.
- GTK and Wx widgets may display the configured pointer in the UI using the native pointer.
- Pointer colours are supported, although some graphics UI systems may not be able to display full colour and may default to monochrome.
OS_SpriteOp
calls to set the pointer from a sprite are not supported.
- Mouse and pointer are always linked.
- The
OSPointer
module provides a *Pointer
command (which in RISC OS Classic is provided by the Wimp).
- Mouse bounding box not supported.
- PointerV is not used.
- Alternative pointer ('Mouse scroll') events are not supported.
Filesystem
- Only a host filesystem is implemented - filesystems cannot be registered yet (although a RISC OS FileSwitch may be loaded which allows regular filesystems to be used).
- Filenames are passed through GSTrans to expand variables.
- Filesystem operations are passed through vectors as expected.
- Only a single 'host' filing system supported; temporary and current filing systems are not supported.
- The base of the native filesystem can be set by a command line switch (
filesystem.native_directory
).
OS_File
is fully implemented, for the limitations of the host system.
- Load actions are supported.
- Timestamping may not be performed on file write.
OS_Find
can open and close files.
- Error handling, and the extra bits on open are not well supported.
OS_Args
can read the EOF state, pointer, extent and allocated space, path name.
- SCB flags are partially supported.
- Temporary filesystem read by
OS_Args 0,0
returns as 0 (no filesystem).
OS_Byte
can be used to read the EOF state of a file.
OS_BGet
/OS_BPut
can read and write a byte, and report EOF condition followed by errors on subsequent reads.
OS_GBPB
can read and write multiple bytes, and supports the directory enumeration interfaces.
OS_FSControl
is vectored, but only a few interfaces are supported:
- Shutting files is supported, but generates an explicit error.
- Changing and unseetting the current directory, library and URD are supported.
- Changing and reading directories 'unchecked' is supported.
*Back
and *Up
supported.
- Unsetting directory, library and URD is supported.
- StartApplication supported, but doesn't deal with temporary filing system.
- Run file supported:
- Calls RunAbsolute for absolute files.
- Calls RunUtility for utility files.
- Calls RunUntyped for untyped files.
- RunAbsolute supported:
- Loads the code (if necesary).
- Calls the executable at &8000.
- Does not issue the UKCompression services.
- Does not check for suitability for the system.
- RunUtility supported:
- Does not check the header.
- May not free the workspace on certain exit types.
- Cataloguing directories (
*Cat
, *LCat
, *Ex
, *LEx
, *EnumDir
) is supported.
- Information on a file is supported for
*Info
and *FileInfo
.
*Info
can be configured to use Sys$DateFormat
value or a fixed value.
- RunUntyped supported, and executes Run actions as necessary.
*Wipe
not supported.
*Copy
is supported for a limited set of options (unsupported: Look, User buffers, Newer, Structure only, Delete source, Prompt for disc change, Confirm, Date range)
*Count
is supported, although the Confirm option is not implemented.
- Access permissions (
*Access
) not supported.
- Rename file is supported.
- Shutdown filesystem not supported.
- Convert filetype name to number supported.
- Convert filetype number to name supported.
- Convert file information to filetype supported.
- Canonicalise filename supported.
- Reading boot option is implemented, and returns a configured value for the host filesystem.
- Setting boot option not supported.
- Boot from filesystem attempts to execute
&.!Boot
according to the boot option.
- Reading and setting defects not supported.
- Reading free space with OS_FSControl 49 and 55 is supported (configurably may return host filesystem or fixed values).
*Free
will report the free space on the currently selected directory, or a given path.
- Registering, selecting filesystems not supported.
- Reading internal file handles is supported, but without filesystems the filesystem information word is 0.
- Timestamps on objects may be configured to always return a fixed value (useful for consistency during testing).
- Filehandles are numbered from a high limit, downwards
- The upper and lower limits on the file handle numbers are configurable.
- File handles can be enumerated through
OS_FSControl 58
.
- Native filesystem operations treat filetypes as
,xxx
extensions, and load/exec addresses as ,llllllll,eeeeeeee
extensions.
- Native filesystem does not support access bits (all files are WR/WR)
- 'Filesystems' (in the sense of
ADFS:<specifier>
are not supported - everything is rooted at $
).
CLI
- Dispatched through CLIV.
- Command line buffer is 1024 bytes.
- Configurable through
progenv.cli_size
.
- Size is readable through
OS_ChangeEnvironment 33
.
- Empty commands and comments - supported.
- File execution - supported (by filename, by
/
prefix, by *Run
command)
- Aliases - supported
- Filesystem prefix - supported if the filesystem interfaces support it (supplied interfaces do not, but classic FileSwitch does)
- Filesystem commands - supported if the filesystem interfaces support it (supplied interfaces do not, but classic FileSwitch does)
- Module name directed commands - supported (
Module#<module>
configurable)
- Commands are directed to the preferred module instance.
- Redirection - recognised and stripped, but not honoured.
- GSTrans - supported
- Argument counting - supported
Service_UKCommand
- supported (LegacyBBC
python module will handle commands which don't have a space after them, eg *FX
).
RTC (Real Time Clock)
OS_ReadMonotonicTime
implemented.
RTCV
is not used.
- Time reading through
OS_Word
implemented.
- Time conversion functions not implemented.
- Time offsets may be configured, to alter the real time clock by a specified amount.
- An IIC implementation is provided which contains the RTC chip, although this is currently not used.
- Timezone is supported in the
Territory
module as the host time zone.
Sound
- Internal
SoundChannels
module provided, playing back sound through MIDI.
- Voices are supported only as MIDI voices:
- The default voices are mapped to approximately sensible MIDI voices, and may be configured.
- Voice information can be read.
- MIDI channels are only configured on first use, to avoid affecting existing MIDI usage if no sound is output.
- Global volume supported.
- Sound operations are passed through the Python rtmidi module.
- Gate only, no parameter modification.
- Sounds are asynchronous and up to 16 channels can in theory be used (although only 8 currently supported).
- Sound buffering can be configured to work like RISC OS or the BBC (actually defaults to BBC, because it's a much nicer system).
- Tuning is not supported.
*Voices
, *ChannelVoice
and *Sound
supported.
OS_Byte 210
to suppress sound is supported (not documented in the PRM, but supported by RISC OS Classic).
- Service_SoundControl - issued and if claimed will abort processing.
- Service_Sound - issued on initialisation and finalisation.
- Does not issue service on startup.
- SoundDMA is supplied as a stub which only tracks state..
- This means no sampled sound output.
- 16bit sound extension SWIs are not supported.
- SoundScheduler not provided - no queued sounds (unless BBC style sound system in use).
- SharedSound not provided (without SoundDMA it isn't useful).
Networking
- Simple
Internet
module providing a native socket interface.
- Only some of the SWIs are sending and receiving data (
recv
, recvfrom
/_1
, sendto
, sendmsg
/_1
, read
, write
).
- New style and old style calls have differing degrees of support (mostly this relates to the
sockaddr
structure layout).
Socket_Ioctl
supports some operations:
- non-blocking configuration (
FIONBIO
)
- data in buffers (
FIONREAD
and FIONWRITE
- new to RISC OS)
- asynchronous notifications (
FIOASYNC
)
- interface information reading (
AF_INET
, AF_LINK
and AF_INET6
) (SIOCGIFCONF
)
- Interface names will be converted to RISC OS format (specifically this applies to RISC OS where the long UUIDs will be converted to numbered 'host' interfaces).
- Addresses follow the standard sockaddr_in6 and sockaddr_dl (
SIOCGIFADDR
)
- Flags for the interface are translated to give RISC OS style flags, possibly synthesised on Windows (
SIOCGIFFLAGS
)
- Broadcast addresses can be read (
SIOCGIFBRDADDR
)
- Netmask addresses can be read (
SIOCGIFNETMASK
)
- Destination addresses can be read (
SIOCGIFDSTADDR
)
- MTU can be read (
SIOCGIFMTU
)
- Destination addresses are not supported (
SIOCGIFDSTADDR
)
- Metrics are supported, but return a fixed value (
SIOCGIFMETRIC
)
Socket_Select
supported.
Socket_Setsockopt
supports the options supported by the underlying system.
- Blocking operations will block tickers from happening.
- Asynchronous sockets will trigger
Event_Internet
in the background:
- The situations in which the events are called may differ slightly from the original implementation.
- No
Socket_InternalLookup
support, which means kvm
access to read statistics and interface hardware information is not possible the way that it used to be done.
AF_LINK
sockets can be used to read the interface hardware addresses. A modified version of ifconfig
is required to take advantage of this.
- No routing information available (
AF_ROUTE
sockets on the host system may not work as expected by RISC OS, although you can still use them but must know about the host representation)
- On startup, initialises
Inet$Hostname
and Inet$LocalDomain
with values from the host system.
- Unimplemented SWIs:
Socket_Recvmsg
, Socket_Shutdown
, Socket_Getsockopt
, Socket_Stat
, Socket_Readv
, Socket_Writev
, Socket_Sendtosm
, Socket_Sysctl
, Socket_Recvmsg_1
, Socket_InternalLookup
, Socket_Filter
.
- The module's operation can be disabled through a configuration option.
- Resolver module provides limited functionality
Resolver_GetHostByName
supported for remote names.
- Local hosts file not supported.
- Lookup through LanManFS not supported.
- Lookup through ResolverMDNS not supported.
- Lookup through Freeway not suported.
Resolver_GetHost
not supported.
- No services issued on resolution.
- Configuration of resolver is limited.
- The
Resolver_CacheControl
SWIs are not supported.
- The module itself may be disabled through a configuration option.
- No caching present.
- Network applications will probably fail if they attempt to read the internet database (
InetDBase$Path
) files, such as InetDBase:Files.Services
, if these are not available in the filesystem.
Misc (Miscellaneous Kernel functions)
OS_CRC
supported.
OS_ReadArgs
supported.
OS_SubstituteArgs
/ OS_SubstituteArgs32
supported.
OS_EvaluateExpression
supported, although some of the operators are not yet implemented.
OS_Confirm
supported.
- Configurable to allow the display of a message when a confirmation response is required.
- Configurable to program the pointer and read the mouse buttons for input.
- The characters used for confirmation are configurable (in RISC OS Classic the characters were defined in the Kernel Messages file).
OS_ClaimOSSWI
supported.
OS_ClaimProcessorVector
supported, although only the undefined instruction vector has been heavily tested.
OS_Reset
supported (configurable whether it resets or exits, and may explicitly exit with 'power off' extension).
MessageTrans
- Partially implemented as a module, which can operate in one of 3 ways:
none
: All SWIs return errors
simple
: All SWIs return as if they file were open and give either a fake response, or the default value. Useful for testing when the expected Messages files do not exist.
full
: A full implementation which reads Messages files and returns tokens properly. Not actually a 'full' implementation right now as some SWIs are not implemented.
- In
simple
configuration:
MessageTrans_ErrorLookup
supported to pass through the error code, as a simple means by which errors can be reported (as this SWI is commonly used to report errors, it is better that it return a useful message, rather than 'SWI not known').
MessageTrans_OpenFile
, MessageTrans_CloseFile
return without doing anything.
MessageTrans_FileInfo
returns a fake size.
MessageTrans_ErrorLookup
, MessageTrans_Lookup
, use the default value supplied. If no default is supplied, a message based on the token and parameters is generated.
MessageTrans_GSLookup
works as MessageTrans_Lookup
but then GSTrans's the output.
MessageTrans_MakeMenus
is not supported.
MessageTrans_CopyError
is not supported.
- In
full
configuration:
- Never directly accesses files in memory (ResourceFS access is more costly).
- Never loads the files into memory.
- Error numbers are not returned correctly.
- Default dictionary is not supported.
MessageTrans_MakeMenus
is not supported.
MessageTrans_CopyError
is not supported.
- Other SWIs should operate as expected.
ProgEnv (Program environment)
- The environment runs utilities (&FFC) and absolutes (&FF8) in 32bit USR mode.
OS_GetEnv
/OS_WriteEnv
supported.
OS_UpCall
supported.
OS_ChangeEnvironment
and its deprecated friends are implemented.
- Pass through
ChangeEnvironmentV
.
- MemoryLimit is set on boot, and updated in the application space DA handler on resize.
- ApplicationSpaceSize is set on boot, and updated in the application space DA handler on resize.
- Error handler is called when an error is raised within an entered module or application.
- UpCall handler is called when
OS_UpCall
is issued.
- Abort handlers called when exceptions are raised, and the default handlers generate errors as expected. Types of aborts are reported according to the DFSR.
- New BranchThroughZero handler (32) is called on detecting execution at address 0.
- ExceptionDumpArea is implemented and is used by the default handlers.
- Non-transient callbacks are dispatched but don't always work as expected (
OS_SetCallBack
and exits from Escape and Event handlers are honoured).
- Escape conditions should be honoured and processed by the environment handlers as expected. Acknowledging escape generates most of the same side effects as RISC OS would (although some are incomplete).
- Exit handlers are called as expected on application exits; the default handler exits the environment.
- Event handler is not implemented (will not be called for events).
- UpCall handler is implemented (will be called for events).
- Breakpoint handler is not implemented.
- OtherExceptionHandler is never called.
- CAOPointer is supported, but not used properly for application startup.
- Special handler 33 has been defined to be report the space used by the command line, and how large it is.
OS_EnterOS
/OS_LeaveOS
are implemented (sorry) as they are used as part of the test framework.
OS_IntOn
/OS_IntOff
are implemented, but may be configured to report errors.
OS_CallASWI
/OS_CallASWIR12
are implemented internally.
- Transient callbacks (
OS_AddCallBack
/OS_RemoveCallBack
) are supported, and will be triggered when the OS is returning back to USR mode.
- Interrupt signals (ctrl-c on POSIX tty systems) are trapped and will be passed as an Escape (regardless of the definition of the escape key) to the system.
- Break/Escape actions and effects are not currently supported completely.
- Break is not generatable.
- Escape is generated by ctrl-c, or by the defined escape character.
- Escape may be disabled (
OS_Byte 200
).
- Escape effects (
OS_Byte 230
) are not supported.
- Escape Event is not raised.
- Escape is not passed through the buffer system.
Errors (Error handling)
- Data aborts, prefetch aborts and undefined instructions are passed to the exception handlers as expected. May be configured to display the registers at the time of the exception automatically.
- Additional information is available when the trace interface is in use.
- The region for the address being reported may be reported in the error message.
- C backtrace may be available if it is recognised by the trace system.
- A new environment handler is used to report Branch Through Zero.
- Failures within the Utility or Absolute code through
OS_GenerateError
are reported as such from the tool.
- Failures within the Python, will be reported through backtraces, which is converted to a hardware error in RISC OS.
- Errors raised within an entered module or absolute will cause the Error handler to be called as expected; if the default handler is present, these will cause the system to exit.
- Errors are passed through
ErrorV
.
- Error pointers are checked for validity and may be replaced:
- A pointer of 0 is configurable with
error.nullpointer_effect
to either pass the null pointer on (passthrough
), generate an explicit Null error pointer
message (message
), or report the string ofla
(ofla
).
- A pointer to invalid memory of 0 is configurable with
error.invalid_effect
to either pass the null pointer on (passthrough
) or generate an explicit Invalid error pointer
message (message
).
- A pointer to an unaligned address is configurable with
error.unaligned_effect
to either pass the null pointer on (passthrough
) or generate an explicit Unaligned error pointer
message (message
).
- These checks will be reported through the trace system as warnings.
Booting
- By default the system sets up a minimal environment, but passes through many of the stages which were originally performed by RISC OS Classic.
- As not all of the boot-time operations are relevant to the Pyromaniac system, they may not all be issued. A non-exhaustive list of the start up operations (see
riscos/kernel.py
in Kernel.initialise
/Kernel.boot
/Kernel.system_boot
for more information):
- Creation of system dynamic areas.
- Initialisation of the SVC stack (with a BTS-aware initialised base).
- ROM module initialisations.
- Podule module enumeration and module initialisations.
- Module initialisations.
- Alphabet configuration.
- Memory size configuration (not supported).
- Configured filesystem selection (not supported).
Service_PostInit
issued.
- Queued transient callbacks called.
- Mode selection (configurable).
- Startup banner (configurable).
Service_Reset
.
- Startup bell (configurable).
- System boot (which is the running of the boot sequence, etc) is not performed by default. When enabled it triggers:
- Boot from filesystem (configurable).
- Boot into configured language (not supported).
- Run BootMenu (configurable).
- Enter supervisor (configurable).
- The system startup is intended to be able to provide enough to start tools, without precluding the ability to initialise as a full startup which loaded RISC OS modules might expect.
Desktop
- No WindowManager is supplied, but certain SWIs are supported to ensure that command line tools operate as expected.
Wimp_ReportError
provides a text interface to report errors and get responses from the user.
Service WimpReportError
is raised, but the extended RISC OS 3.5 services are not.
- RISC OS 3.5 extended services are not supported.
- RISC OS 3.5 categories are supported.
- Sprites are not supported.
- Application names are not supported ('application' will be used).
- Serious errors do not have their errors replaced.
- Three implementations are provided.
null
which does nothing.
vdu
which outputs the information on the VDU stream.
easygui
which opens dialogues on the native system.
TaskWindow
module is supplied, which can return a configurable state for TaskWindow_TaskInfo
.
TaskManager
module is supplied, which returns a list containing only itself when enumerating tasks (configurable).
Invocation
- Configuration of the emulated system is possible through command line switches (
--config <system>.<var>=<value
).
- Internal modules can be enabled by command line switch (
--load-internal-modules
). They may be disabled by using the unplug configuration (--config modules.unplug=<modules-list>
).
- RISC OS Modules can be loaded by command line switches (
--load-module <file>
and --load-rom-module <file>
)
- System variables can be set by a command line switch (
--set-variable <var>=<value>
)
- Invocation allows:
- Running of utilities (specify native filename).
- Running of absolutes (specify native filename).
- Entering modules (
--enter-module <module>
)
- Executing module commands (
--command <command>
). May be specified multiple times.
- On exit,
Service_PreReset
will be issued (configurable with pyro.reset_effect
).
- Total execution time can be limited (
--config emulation.runtime_limit=<seconds>
).
- When multiple actions (commands, module entry, system boot, etc) are performed, the terminating behaviour is:
- They will terminate when an error is returned.
- If
pyro.stop_on_failing_rc
is enabled, execution will terminate once Sys$ReturnCode
is non-0.
- If
pyro.return_rc
is enabled, the tool's exit code will be set to 1 if a RISC OS error occurred, or the Sys$ReturnCode
value. If the option is disabled, the exit code will be either 0 or 1, based on those same conditions (ie 0 is success, and 1 is failure).
- Terminating messages are configurable, and may be written to stdout, stderr or to the RISC OS drivers (
--config execute.output
):
- Errors generated are printed by default (
--config execute.error_template
).
- Exit is silent by default (
--config execute.exit_template
).
- OS_Reset prints a message by default (
--config execute.reset_template
).
- Exit codes for the tool are dependant on the type of error (see
--help-exit-codes
):
- Exits with errors (SWIs generating errors without the X bit) will return a non-0 return code.
- Successful exit with
OS_Exit
(or through MOV pc, lr
in the case of Utilities and module commands) will return a 0 return code, or the return code of the OS_Exit
SWI if ABEX
was supplied.
- Aborts return code 125.
- Failure during the booting (usually module errors) return code 124.
- Incorrect configuration returns code 123.
- Bad command arguments returns code 122.
- Exit due to a reboot (
OS_Reset
) returns code 121 (configurable whether a reboot restarts the system).
- Exit due to a timeout returns code 120.
- Exit due to explicit termination (such as by closing the UI window) returns code 119.
PyModules (Supplied Modules)
SystemBell
- generates a bell through the regular SoundChannels
interface, or through the console depending on configuration.
systembell.bell_type
controls the bell's effect. sound
issues the Sound_Control
calls in the regular way. console
issues a bell through the console. message
prints a message to the RISC OS output.
SoundDMA
- stub implementation which just tracks configured values.
SoundChannels
- sound implemention that uses python-rtmidi.
- This provides asynchronous sound with up to 15 channels.
- May provide a BBC-style buffering system for the
SOUND
calls, in addition to the RISC OS system. The BBC would buffer notes and could play multiple notes simultaneously, with the next starting when a note on the channel completed. The RISC OS system only plays notes immediately.
- SoundScheduler is not provided.
- MIDI instruments can be selected by choosing the voice configuration with
sound.voice_*
settings.
- See the Sound section for more detail.
IIC
- a means of communicating with the I²C hardware, together with an implementation of the PCF8583 Clock/RAM chip.
Internet
- an implementation of the BSD Sockets interface, as provided by the Internet 5 module. See the 'Networking' section for more specific implementation details.
Resolver
- a simple implementation of the DNS resolver. Does not support background operations. See the 'Networking' section for more specific implementation details.
TWIN
- a rudimentary command handler for *TWIN
which allows BASIC TWIN
commands to launch an editor. The host's nano
editor (configurable) is invoked on the BASIC program.
LegacyBBC
- provides some older interfaces from the BBC:
*FX<number>
support (and *Key
, *TV
, and *Opt
) without spaces
OS_Byte 160
legacy interface to OS_ReadVduVariables
(required for ARMBasicEditor, not supplied).
OS_Word 7
(SOUND) is passed to Sound_Control
OS_Word 8
(ENVELOPE) is recognised and ignored.
BASICTrans
- provides a translation of some messages used by the BASIC module.
TaskWindow
- dummy module which always returns that we are not in a TaskWindow (configurable)
TaskManager
- Allows enumeration of the Tasks present on the system (only the TaskManager itself is present; configurable).
DDEUtils
- provides only a few interfaces:
- The extended command line interface is supported.
- Throwback SWIs are supported, and have multiple implementations:
null
- does nothing.
console
- writes the throwback information to the console, and may be configured to use links to open the referenced files.
posturl
- sends the throwback information to a remote URL.
Portable
- Can power off the system, and may pass through the host power state.
- Reports host battery configuration where possible.
Territory
- Stub implementation, which only supports a few SWIs.
- Supported alphabet SWIs:
Territory_AlphabetNumberToName
, Territory_SelectAlphabet
, Territory_WriteDirection
- Supported time SWIs:
Territory_ReadCurrentTimeZone
, Territory_ConvertDateAndTime
, Territory_ReadTimeZones
, Territory_ConvertDateAndTime
, Territory_ConvertTimeToOrdinals
, Territory_ConvertOrdinalsToTime
.
- Supported character SWIs:
Territory_CharacterPropertyTable
, Territory_LowercaseTable
, Territory_UppercaseTable
, Territory_ReadSymbols
, Territory_ControlTable
, Territory_PlainTable
, Territory_ValueTable
.
- The character property tables are generated from the Unicode categories for characters in Latin 1. This means that the control characters in the C1 range (&80-&BF) will not be correct for Acorn Latin 1. The accent information is inferred, as accents are not special to Unicode, and may be labelled incorrectly.
- TimeZone information is read from the host system.
URI
- can launch URIs in the host system (configurable whether it's able to function)
- Configurable to disable the module, or disable the launching of certain schemes.
ClipboardHolder
- can transfer clipboard text to and from the host system (configurable whether it's able to function).
*Clipboard_FromFile
copies a file in RISC OS to the host clipboard.
*Clipboard_ToFile
copies the host clipboard to a file in RISC OS.
- Multiple implementations are available:
null
- does nothing
static
- holds the content and never transfers it out of the system.
pyperclip
- uses the python pyperclip package to interface with the native clipboard.
posturl
- sends clipboard contents to an external URL.
OSCommands
- provides simple CLI commands
- Supported commands:
*FX
, *TV
, *Key
, *Time
, *Quit
, *Error
, *Set
, *SetEval
, *Unset
, *SetMacro
, *Show
, *Help
, *Go
, *Echo
, *ChangeDynamicArea
, *If
.
- Missing commands:
*Ignore
, *Shadow
, *Configure
, *Status
.
*Help DynamicAreas
will list the state of the dynamic areas.
ModuleCommands
- provides some module commands.
- Supported commands:
*RMLoad
, *RMKill
, *RMRun
, *Modules
(and *Help Modules
), *ROMModules
, *RMEnsure
.
- Missing commands:
*RMClear
, *RMInsert
, *RMTidy
, *Unplug
.
*Help Modules
includes text indicating which are internal Pyromaniac modules.
Debugger
- provides disassembly SWI and CLI commands.
- Supported commands:
*Memory
, *MemoryI
, *ShowRegs
, *InitStore
.
- Missing commands:
*MemoryA
, *Debug
, *BreakSet
, *BreakClr
, *BreakList
, *Continue
- New commands:
*Vector
shows current vector claimants, or lists all the vectors.
- Does not know about the FP instructions, but that's ok as we don't support executing them either.
*ShowRegs
includes information about the region for R14 and R15, and the state of IFSR and DFSR.
EvaluateExpression
- provides the implementation of OS_EvaluateExpression
.
- Supported command:
*Eval
.
- May not evaluate the same as the original EvaluateExpression in some cases (particularly unary operators are not as well supported).
- Supported extensions:
LEAFNAME
, DIRNAME
, CANONICALISE
- convert argument as a filename
TIMEFORMAT
- format the current time in a given format
INSTR
- return the offset of a substring
SET
- check whether a system variable is set
MODULEVERSION
- return the version of a module * 100, or -1.
FileTypes
- sets up the system variables for the standard filetypes.
FileSwitchCommands
- provides many of the commands that were previously within the FileSwitch
module, and some that are in FSCommands
.
- Fileswitch commands supported:
*Cat
, *LCat
, *Ex
, *LEx
, *EnumDir
, *Info
, *Dir
, *Back
, *Up
, *CDir
, *URD
, *Lib
, *SetType
, *Run
, *Rename
, *Spool
, *SpoolOn
, *Copy
, *Count
, *NoDir
, *NoLib
, *NoURD
.
- Fileswitch commands missing:
*Access
, *Shut
, *Shutdown
, *Stamp
, *Wipe
.
- FSCommands commands supported:
*Append
, *Build
, *Load
, *Save
, *Delete
, *Remove
, *Exec
, *Create
, *Type
, *List
, *Print
, *Dump
.
- FSCommands commands missing:
*Close
, *Opt
.
- New commands:
*Help OpenFiles
, *Free
(previously this was in filesystem modules).
MimeMap
- provides translations between different filename formats.
- RISC OS Type (name and number), Media Types, Extensions and Mac Types are supported.
- Wildcard matching on Media Types is not supported.
- Configuration of the MimeMap file is not supported.
SpriteUtils
- provides the *ScreenSave
command, which saves the screen if the graphics implementation supports it. The Cairo implementation saves as a PNG.
- No other operations are performed by SpriteUtils - there is no sprite support.
Pyromaniac
- provides an interface to the workings of the Pyromaniac system.
- All features of the Pyromaniac module are configurable, to allow the restriction of its operation within the guest:
pyromaniacmodule.enable
- controls whether any of the module functions are available.
pyromaniacmodule.debug_enable
- controls whether the *PyromaniacDebug
command is usable.
pyromaniacmodule.watchpoints_enable
- controls whether the *PyromaniacWatchpoints
command is usable.
pyromaniacmodule.config_enable
- controls whether the *PyromaniacConfig
command is usable.
pyromaniacmodule.config_allow
- provides a list of configuration groups are allowed to be accessed. If empty, all groups are allowed.
pyromaniacmodule.config_deny
- provides a list of configuration groups are not allowed to be accessed. If empty, all groups are allowed. The deny list is checked before the allow list and so takes precedence.
pyromaniacmodule.hostcommand_enable
- controls whether the *PyromaniacHostCommand
command is usable.
pyromaniacmodule.hostcommand_cwd_riscos
- controls whether the current directory is used for execution.
pyromaniacmodule.hostcommand_print_rc
- controls whether the return code is printed after execution.
pyromaniacmodule.hostcommand_output_encoding
- controls whether the output is reencoded in the current alphabet.
pyromaniacmodule.hostcommand_ansiescapes
- controls whether ANSI escapes in the output will be converted to RISC OS colour operations
*PyromaniacFeatures
- displays this document within the emulated system, paged if configured to do so. The document may be viewed in sections for easier viewing.
*PyromaniacConfig
- interacts with the configuration system. Not all configurations will take effect immediately, and some may be destructive to the running environment, so care should be taken. Configurations may be prefixed with -help
for information on the group or option.
*PyromaniacDebug
- interacts with the debug system. All debug options should be safe to change whilst the system is running, although some may make the system unusable.
*PyromaniacWatchpoint
- provides a convenience for setting memory watchpoints.
*PyromaniacTimings
- controls the timings and counters interface.
*PyromaniacHostCommand
- executes commands on the host system. Output will be encoded to the current alphabet (controlled by output_encoding
), and ANSI escapes can be converted to RISC OS colour operations with hostcommand_ansiescapes
.
OSPointer
- limited functionality for the pointer.
- Does not provide pointer operations in the way that it does under Select.
- Provides
*Pointer
command, and programs a pointer shape when selected. This command was in the WindowManager in RISC OS Classic.
Hourglass
- provides a variety of implementations:
- Implementation
vdu
and console
provide text output for the hourglass module's operations.
- Implementation
pointer
provides a pointer animation in the graphics system.
- Hourglass percentages not supported.
- Hourglass LEDs not supported.
Podule
- provides a way to load collections of modules from a ROM image.
- RISC OS Select 32bit ROM images and RISC OS 5 ROM images are supported, but it is vital that some modules be unplugged to prevent them from interacting badly with the system.
*Help Podules
gives more information on the loaded ROM images.
International
- provides alphabet translations and the selection of BBC fonts according to those alphabets.
BootCommands
- provides a few commands command:
*Do
- supported.
*X
- supported.
*AppSize
- supported, by resizing the application space.
*FreePool
- does nothing (no Free Pool dynamic area exists)
*IfThere
- supported.
SysLog
- provides the SysLog interfaces.
- Supported SWIs:
SysLog_LogMessage
, SysLog_GetLogLevel
, SysLog_FlushLog
, SysLog_SetLogLevel
, SysLog_LogUnstamped
, SysLog_Indent
, SysLog_UnIndent
, SysLog_NoIndent
, SysLog_ReadErrorMessage
, SysLog_LogComplete
, SysLog_LogCharacter
- Unsupported SWIs:
SysLog_OpenSessionLog
, SysLog_CloseSessionLog
, SysLog_LogData
, SysLog_LogFormatted
, SysLog_IRQMode
, SysLog_Control
, SysLog_Enumerate
- Session logs are not supported.
- Network logging is not supported.
- Configuration of logs is not supported.
- Background flushing of logs is not supported.
- Error messages are just tokens.
- Timestamp format is configurable.
- Default logging directory is configurable.