Pyromaniac

Obtaining help

The help for all configuration options for RISC OS Pyromaniac can be obtained by running:

python pyro.py --help-config --load-internal-modules

Within RISC OS help can be obtained with:

*PyromaniacConfig -help

Configuration group 'APIWarnings'

APIWarnings.enterleaveos

Value: no
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether the OS_EnterOS/OS_LeaveOS SWIs warn about their use. These calls should generally not be used in applications.

APIWarnings.intonoff

Value: no
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether the OS_IntOn/OS_IntOff SWIs warn about their use. These calls should generally not be used in applications.

APIWarnings.synchronisecodeareas

Value: no
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether the OS_SynchroniseCodeAreas SWI warns about efficient unbounded synchronise requests.

Configuration group 'Buffers'

The Buffers configuration group configures how large the buffers are for the standard RISC OS buffers. Most of these buffers are actually not used, and have not been used since the BBC.

Buffers.keyboard_size

Value: 255
Type: int

Configures the number of bytes available in the keyboard input buffer.

Buffers.mouse_size

Value: 63
Type: int

Configures the number of bytes available in the mouse input buffer.

Buffers.printer_size

Value: 1023
Type: int

Configures the number of bytes available in the printer buffer.

Buffers.serialinput_size

Value: 255
Type: int

Configures the number of bytes available in the serial input buffer.

Buffers.serialoutput_size

Value: 191
Type: int

Configures the number of bytes available in the serial output buffer.

Buffers.soundchannel0_size

Value: 3
Type: int

Configures the number of bytes available in the sound buffer for channel 0 (not used by RISC OS).

Buffers.soundchannel1_size

Value: 3
Type: int

Configures the number of bytes available in the sound buffer for channel 1 (not used by RISC OS).

Buffers.soundchannel2_size

Value: 3
Type: int

Configures the number of bytes available in the sound buffer for channel 2 (not used by RISC OS).

Buffers.soundchannel3_size

Value: 3
Type: int

Configures the number of bytes available in the sound buffer for channel 3 (not used by RISC OS).

Buffers.speech_size

Value: 3
Type: int

Configures the number of bytes available in the speech buffer (not used by RISC OS).

Configuration group 'CLI'

CLI.module_hash_enable

Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether the CLI commands prefixed by Module#<name> are directed to the named module or not.

RISC OS classic supports this syntax, but it is obscure and almost never used. It can be helpful in explicitly directing a command to a module, but might preclude the use of a filesystem called Module that supported special fields.

Configuration group 'ClipboardHolder'

ClipboardHolder.enable

Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether the ClipboardHolder module is able to function. If this is disabled, the ClipboardHolder SWIs will return errors.

ClipboardHolder.implementation

Value: pyperclip
Type: str

Configures which implementation will be used for the clipboard. The following implementations are provided:

• static - holds the clipboard in Pyromaniac memory only.
• 'pyperclip' - uses the Python 'pyperclip' package to transfer the clipboard to and from the host system.
• 'posturl' - uses a HTTP POST to submit the clipboard data to a remote server. No mechanism it provided to receive clipboard data.

ClipboardHolder.post_url

Value: http://localhost:8080/
Type: str

Configures the URL to use when the 'posturl' implementation is selected.

The posted data is contained within the body of the request. The media type supplied will be an 'application/riscos' type, with the name of the file containing the filetype number.

ClipboardHolder.scrap_file

Value: <Wimp$ScrapDir>.Clipboard
Type: str

Configures the file that the clipboard will be transferred through when it must be transferred by a file.

Configuration group 'Console'

Console.input_escapes

Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether terminal escapes for function keys, cursor keys and other input, are processed by the input system. If this option is disabled, the escape codes (and therefore cursor keys and function keys) will be passed through verbatim. If this option is enabled, the escape codes will be processed into RISC OS keys, and cursor keys will be seen by RISC OS as expected.

Console.input_escapes_timeout

Value: 0.2
Type: float

Configures how many seconds will be waited before cancelling a terminal escape sequence. Usually this causes the physical escape key to be reported as a key press. It is usually a fraction of a second, in order that the terminal be responsive, but delays in buffering do not cause the escape to be misidentified.

Console.input_utf8

Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether characters input are treated as UTF-8 and converted to the current alphabet. If this option is disabled, input is passed through unmodified.

Configuration group 'Debugger'

Debugger.hide_topbitset

Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether characters with the top bit set will be shown as a '.' character, or displayed directly.

Debugger.memory_bytesperrow

Value: 16
Type: int

Configures the width of the *Memory command's output in bytes.

Debugger.memory_defaultsize

Value: 256
Type: int

Configures the amount of memory which is displayed when *Memory is used without an end address.

Debugger.memoryi_defaultsize

Value: 24
Type: int

Configures the amount of memory which is displayed when *MemoryI is used without an end address.

Debugger.showregs_context

Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether the *ShowRegs command includes context information from the registers which are stored in the exception areas.

Configuration group 'Documentation'

Documentation.enable_launch

Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0

Configuration group 'DynamicArea'

DynamicArea.area_base

Value: &5000000
Type: Hexadecimal value, optionally prefixed by '&'.

Controls where in memory the OS_DynamicArea calls to create new areas with auto-allocated base addresses will start.

DynamicArea.clamp_machinesize

Value: 64 M
Type: Size as a number which may be suffixed by 'K', 'M' or 'G', and '-1'

Configures the default clamp for dynamic areas which request an area which is as large as possible (max size -1).

DynamicArea.clamp_maxsize

Value: 1024 M
Type: Size as a number which may be suffixed by 'K', 'M' or 'G', and '-1'

Configures the default clamp for dynamic areas which request an area with an explicit maximum size (max size not -1).

DynamicArea.clamp_sparsesize

Value: 3072 M
Type: Size as a number which may be suffixed by 'K', 'M' or 'G', and '-1'

Configures the default clamp for dynamic areas which are sparse mapped. Sparse mapping is not currently supported.

Configuration group 'Emulation'

Emulation.disable_interrupt

Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether timers are enabled or not. There may be underlying bugs with the timer implementation that mean that code will execute out of turn - ie be completely fatal. Because of this, timers are disabled by default.

Emulation.internal_backtrace

Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether, when a Python exception occurs during the processing of a SWI, callback, interrupt or other event, a backtrace is produced. The backtrace will not be sent through the RISC OS VDU system, as this may be the reason for the backtrace.

Emulation.internal_recursion_limit

Value: 0
Type: int

Controls the recursion depth for internal python functions. By default, Python uses a limit of 1000-deep function calls (implementation-specific), which may limit some calls in the RISC OS environment which are inherently deeply nested. This option allows the recursion limit to be explicitly raised. If the value is set to 0, no limit raising is performed.

Emulation.kernel_shutdown

Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether, when the OS terminates the Kernel is shut down. The Kernel shutdown means that Service_PreReset is issued and other clean up activities may be performed. Disabling this may ensure that the system terminates cleanly, even when modules may be acting badly.

Emulation.runtime_limit

Value: 0s
Type: Time in the form: {<number>{s|m|h|d|w|y}}*

Configures the maximum runtime that the system may execute for. After this time, the system will be terminated. A value of 0 disables any limits.

Configuration group 'Error'

Error.invalid_effect

Value: message
Type: One of the strings 'message', 'passthrough'

Controls the handling of returns from SWIs with V set and R0 pointing to invalid memory.

• message will replace the error with a message reporting the address.
• passthrough will leave the error block pointing to invalid memory.

Error.nullpointer_effect

Value: ofla
Type: One of the strings 'ofla', 'message', 'passthrough'

Controls the handling of returns from SWIs with V set and R0 = 0.

• ofla will replace the error with a message of 'ofla' (although not the original 'ofla' message).
• message will replace the error with a message reporting that a null pointer was used.
• passthrough will leave the error block as a null pointer.

Error.unaligned_effect

Value: message
Type: One of the strings 'message', 'passthrough'

Controls the handling of returns from SWIs with V set and R0 pointing to a non-word aligned address.

• message will replace the error with a message reporting the address.
• passthrough will leave the error block pointing to invalid memory.

Configuration group 'Execute'

Execute.error_template

Value: Error: %0 (Error number &%1)
Type: str

Configures the template that will be used when the system exits with an error. The message will be written to the destination set by the output option. The template substitutes values from the error:

• %1 will be replaced by the error number as a hexadecimal string.
• %0 will be replaced by the error message.

Execute.exit_template

Value: ` Type:str`

Configures the template that will be used when the system exits normally. The message will be written to the destination set by the output option. The template substitutes values from the error:

• %0 will be replaced by the return code.

Execute.output

Value: stdout
Type: One of the strings 'stdout', 'stderr', 'riscos'

Configures where the messages produced on system exit are sent. The destination can be one of the following values:

• stdout - the host stdout.
• stderr - the host stderr.
• riscos - the RISC OS VDU stream.

Execute.reset_template

Value: RISC OS Reset requested
Type: str

Configures the template that will be used when the system is reset. The message will be written to the destination set by the output option. Although described as a template, there are currently no substitutions performed.

Configuration group 'Filesystem'

The Filesystem configuration group currently covers two parts of the configuration - that for the file system as a whole (what would be FileSwitch in RISC OS Classic), and the native filesystem (which would be a separate file system).

The native filesystem provides an interface to the host disc, rooted at a location defined by native_directory. The files within this directory use the RISC OS storage convention of appending ,xxx for filetypes, or ,llllllll,xxxxxxxx for fully specified load and exec addresses.

Filesystem.filehandle_max

Value: 255
Type: int

Configures the highest file handle that will be used. File handle usage goes down from the highest file handle. Using file handles greater than 255 may result in some interfaces not working as expected.

Filesystem.filehandle_min

Value: 1
Type: int

Configures the lowest file handle that will be used.

Filesystem.info_use_sysdateformat

Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether *Info (and *Ex) use the Sys$DateFormat variable, (as is documented in the PRMs), or use a hard-coded date format (as it implemented in RISC OS Classic). The default in Pyromaniac is to use the variable, as this gives the greatest flexibility, and produces the same output by default.

Filesystem.mask_timestamp

Value: none
Type: Date time in the form YYYY-MM-DD[THH:MM:SS[.CC]], or a hex string or 'none'

Configures what, if any, timestamp will be used for files on the filesystem. When this is set a value other than none, all files will return the timestamp supplied. This can ensure that tests are consistent.

Filesystem.native_boot_option

Value: run
Type: One of the strings 'none', 'load', 'run', 'exec'

Configures the native filesystem's boot option, which would normally be set with *OPT 4, <opt>.

Filesystem.native_directory

Value: .
Type: ValidDirectory

Controls where the native fileystem reads as the root of the disc.

Filesystem.native_freespace

Value: host
Type: 'host', 'error' or Size as a number which may be suffixed by 'K', 'M', 'G', 'T', 'P', or 'E', and '-1'

Configures what should be returned for the free space of the native filesystem. This can be configured to:

• Report a fixed size.
• Report the host system's free space (if possible).
• Raise an error.

Configuration group 'GTK'

GTK.maximum_redraw_rate

Value: 20
Type: int

Configures the maximum rate at which the GTK window will be updated. If this is set too high, the system may spend more time redrawing than executing code. If this is set too low, output may not refresh in a timely manner as it is generated.

GTK.open_at_front

Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether the GTK window will be opened at the front of the stack. By default on some systems the window is opened behind the terminal that launched it. When this option is set, the window should be raised to the front on opening.

Configuration group 'Graphics'

Graphics.implementation

Value: null
Type: str

Configures which implementation will be used for the clipboard. The following implementations are provided:

• gtk - a GTK based application, using cairo graphics as the back end.
• wxwidgets - a WxWidgets based application, using cairo graphics as the back end.
• cairo - a cario based in-memory graphics system.

Graphics.pointer_off_shape

Value: cross
Type: One of the strings 'default', 'cross', 'none'

Configures the UI pointer shape to use when the RISC OS pointer has been turned off. It can take one of the following values:

• default: Leaves the standard pointer alone.
• cross: A system cross pointer shape.
• none: No pointer shape will be shown.

Graphics.pointer_on_shape

Value: riscos
Type: One of the strings 'default', 'cross', 'riscos', 'none'

Configures the UI pointer shape to use when the RISC OS pointer has been turned on. It can take one of the following values:

• default: Leaves the standard pointer alone.
• cross: A system cross pointer shape.
• riscos: The RISC OS pointer shape.
• none: No pointer shape will be shown.

Graphics.screen_banks

Value: 2
Type: int

Configures the number of screen banks available for the the display.

Graphics.vsync_rate

Value: 20
Type: float

Configures how regularly the vysnc event is triggered.

Configuration group 'GraphicsCairo'

GraphicsCairo.antialias

Value: no
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether anti-aliasing (smoother lines) are enabled within Cairo. As RISC OS does not expect this, it is disabled by default.

GraphicsCairo.bitmap_font

Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether the RISC OS bitmap font will be used, or a native system font. As RISC OS expects the bitmap font, that is the default.

GraphicsCairo.save_filename

Value: image.png
Type: Regular expression matching: ^.*\.(png|svg|pbm)$

Configures the native filename to which the graphics screen will be saved on exit. It may be suffixed by .png or .svg to determine the format. The screen is only saved if the save_on_exit is enabled.

GraphicsCairo.save_on_exit

Value: no
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether the contents of the screen are saved when the system exits. The screen will be saved to the filename specified by save_filename.

GraphicsCairo.video_directory

Value: video
Type: str

Configures the directory into which frames from the graphics system will be saved. This is only used when video_enable is set.

GraphicsCairo.video_enable

Value: no
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether each 'frame' of the screen is saved to a file, together with a script to join them to make a video. The frames will be stored in the directory specified by video_directory. The file 'ffmpeg_concat.txt' is also written, which contains the script necessary to create a video from these images. The command necessary to create an MP4 video from these files can be found at the head of the file.

Configuration group 'GraphicsUI'

GraphicsUI.border_colour

Value: &222222
Type: Hexadecimal value, optionally prefixed by '&'.

Configures the colour of the border around the RISC OS screen, between the screen and the window frame. This is a dark grey by default, to differentiate it from the usual black background, but be clearly not part of the screen. Colours are specified in the form '&RRGGBB'.

GraphicsUI.border_size

Value: 4
Type: int

Configures the size of the border around the RISC OS screen, between the screen and the window frame. This is a small value by default, to ensure that curved window borders do not obscure the RISC OS screen content.

GraphicsUI.min_width

Value: 1024
Type: int

GraphicsUI.scale

Value: 1.0
Type: float

Configures the scale factor applied to the Graphics UI as a floating point value. Values larger than 1 will scale the display up. Values smaller than 1 will scale the dispay down.

GraphicsUI.title

Value: RISC OS Pyromaniac
Type: str

Configures the title of the Graphics UI window. Eventually this will include template strings, but currently this is just a bare string.

Configuration group 'Heap'

Heap.clear_alloc_enable

Value: no
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether allocated blocks are cleared by writing a value (clear_value) over them. This can help to identify memory that has not been initialised.

Heap.clear_alloc_value

Value: &a110ced3
Type: Hexadecimal value, optionally prefixed by '&'.

Configures the value which will be used to overwrite allocated values when the clear_alloc_enable option is set.

Heap.clear_free_enable

Value: no
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether freed blocks are cleared by writing a value (clear_value) over them. This can help to identify memory reuse problems.

Heap.clear_free_value

Value: &f0f1f2f3
Type: Hexadecimal value, optionally prefixed by '&'.

Configures the value which will be used to overwrite freed values when the clear_free_enable option is set.

Heap.extend_to_nothing_is_error

Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether resizing a heap to nothing is considered to be an error or not. On RISC OS classic this returns a value of -1 for the block pointer. This is not documented, and it's surprising, as it may result in aborts. Pyromaniac defaults to reporting an error, as this may be a bad effect - if you know you're freeing a block, you should really free it.

Heap.maximum_heap_size

Value: 512 M
Type: Size as a number which may be suffixed by 'K', 'M' or 'G', and '-1'

Configures the largest that a heap can be. This limit ensures that we can detect some corruptions, and may detect oversized initialisations.

Heap.minimum_allocation

Value: 12
Type: int

Configures the smallest memory allocation supported by the heap system. Requests for heap blocks will be limited to this minimum size. RISC OS Classic has a minimum of 12.

Configuration group 'Hourglass'

Hourglass.implementation

Value: console
Type: str

Configures the implementation to use for the hourglass. The following implementations are provided:

• 'console' - displays the hourglass status on the console.
• 'vdu' - displays the hourglass status to the VDU stream.
• 'pointer' - displays a hourglass using the graphics pointer.
• 'null' - has no effect for the hourglass.

Configuration group 'Input'

Input.eof_effect

Value: error
Type: One of the strings 'none', 'error', 'escape', 'exit', 'reset'

Configures the effect that EOF (usually ctrl-d) from the terminal has on the system. The effects can be:

• none - EOF is ignored.
• error - An error is generated, indicating that EOF was received.
• escape - The same effect as pressing the Escape key.
• exit - OS_Exit is called, which may exit the current application.
• reset - OS_Reset is called,which may exit the system.

Input.flush_output_on_read

Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether the VDU output is explicitly flushed when a character is read from the input stream. This ensures that prompts which do not end in a newline are displayed before input is waited on. Together with the VDU options for flushing, this ensures that the experience of using RISC OS is similar to that of other non-RISC OS applications.

Input.keypress_enable

Value: True
Type: One of the strings 'auto', 'force', 'no'

Controls whether key press events are handled by the system. The key presses events handled by KeyV can be enabled or disabled as needed. When enabled they install a ticker which runs every centisecond, which will slow the system.

Options are:

• no - disables the keypress handling
• auto - enables the keypress handling when the UI requests it
• force - enables the keypress handling even when the UI does not request it

Input.readline_native

Value: no
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether the OS_ReadLine interfaces are passed through the native readline (either GNU or BSD).

If this is enabled, the line input will take the same features as the native readline, such as editing and history. However, whilst line editing is in use, RISC OS will be suspended. No interrupts, callbacks or other events will be passed through the system until the line input is complete. This includes the escape key (usually ctrl-c) which will only take effect after the line has been entered.

If this is disabled, the line input will be handled by the RISC OS key input.

Input.readline_native_history_file

Value: ~/.pyromaniac_history
Type: str

Configures where the native readline system stores the history.

Input.readline_native_history_length

Value: 1000
Type: int

Configures how many lines the native readline system will store in the history file.

Input.readline_native_prompt

Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether the VDU output is tracked to produce a native readline prompt that matches the output from RISC OS. For example, the * prompt (CLI$Prompt) from the Supervisor or the > prompt from BASIC will be used as the readline prompt.

If this is disabled, any readline operations which require the whole line to be redrawn will lose the original prompt.

Configuration group 'Internet'

Internet.enable

Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether the Internet module is enabled. If this is disabled, the Socket SWI calls will report errors.

Internet.gifconf_ignore_unknown

Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether SIOCGIFCONF/SIOCOGIFCONF return no information for host interfaces which contain no RISC OS supported address formats. If this is disabled, such interfaces will return their name in the response but with the af_family field set to 0 (which is invalid).

Internet.gifconf_truncate_osockaddr

Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether SIOCGIFCONF truncates interfaces which would not fit into the old sockaddr buffer. Under Internet 5, over long sockaddrs would be truncated (which includes AF_LINK) when they were requested with the SIOCGIFCONF ioctl call. If this is disabled, such over long sockaddrs will instead be omitted from the response.

Internet.tablesize

Value: 128
Type: int

Configures the size of the socket table. This controls how many sockets can be open simultaneously across the whole system. Increasing the size of this may cause problems for clients using Socket_Select, as they may not allocate enough space for the additional bit fields.

Configuration group 'Kernel'

Kernel.boot_fallback

Value: gos
Type: One of the strings 'exit', 'gos', 'bootmenu'

Controls the second operation after booting from the filesystem fails. The options are:

• exit - no further operation.
• bootmenu - attempt to boot from the boot menu (and fall back to the supervisor)
• gos - start the supervisor

Kernel.boot_from_fs

Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether, after reset, the system will attempt to boot from the filesystem. If booting from the filesystem fails, the configuration option boot_fallback determines what the next operation will be.

Kernel.boot_menu

Value: Resources:$.Resources.BootMenu.BootMenu
Type: str

Controls what path is used to execute the boot menu.

Kernel.da_highvectors

Value: 49
Type: int

Controls the dynamic area number for the high CPU vector area. By default this is the registered dynamic area number.

Kernel.da_zeropage

Value: 48
Type: int

Controls the dynamic area number for zero page. By default this is the registered dynamic area number.

Kernel.interrupt_control_swis

Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether the OS_IntOn and OS_IntOff SWIs are effective or not. If this is disabled, the SWIs will have no effect.

Kernel.reset_banner

Value: no
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether, on a reset, the service for the banner will be issued. If this is disabled, no banner will be shown.

Kernel.reset_bell

Value: no
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether, on a reset, the BEL will be issued. When set, the service for the the bell will be issued, which will result in a sound being issued through either the Sound system or the console bell.

Kernel.reset_modechange

Value: no
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether, on a reset, a mode change will be issued. If this is disabled, the mode change is not issued which has effects for the ANSIText VDU implementation which will not clear the screen.

Kernel.swi_recursion_limit

Value: 0
Type: int

Controls the recursion depth for SWI calls. It is possible for SWI calls to recurse until the SVC stack is exhausted. However, this can be artificially forced to fail at an earlier point by setting this limit. If the value is set to 0, no SWI recursion limitting is performed.

Kernel.swimisuse_omit_swis

Value: 
Type: Comma separated list of SWI numbers or names

Configures which SWIs we will never warn about if the debug option 'swimisuse' is enabled.

It is common to find that modules and interrupt handlers use some SWI calls without the X-bit. SWIs such as OS_ReadMonotonicTime, for example, would never be expected to report an error - or if they did, you have much bigger problems. Thus, these might be used in privileged modes without fear that bad effects will happen.

This list controls which SWI numbers will be ignored if a warning would be generated.

Kernel.trace_ignores_write_swis

Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether the OS_Write* SWIs will be ignored by the tracing of SWIs.

Configuration group 'LegacyBBC'

LegacyBBC.envelope_stub

Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether we provide a stub for ENVELOPE (OS_Word 8) which does nothing. When this option is enabled, the ENVELOPE command will do nothing. When it is disabled, the ENVELOPE command will give an error.

By default this option is enabled to make it easier to port programs from the BBC - on RISC OS Classic, unknown OS_Word calls would not generate errors.

Configuration group 'MAC'

The MAC group allows the ethernet MAC address to be configured. The ethernet MAC address is returned by OS_ReadSysInfo 4.

MAC.high

Value: &0
Type: Hexadecimal value, optionally prefixed by '&'.

MAC.low

Value: &0
Type: Hexadecimal value, optionally prefixed by '&'.

Configuration group 'MMIO'

MMIO.enabled

Value: no
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether the memory mapped I/O is able to be used within Pyromaniac. MMIO is very expensive in processing time. It is not currently used within the current implementation of Pyromaniac.

Configuration group 'Memory'

Memory.statistics

Value: no
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether the statistics for the internal Memory objects are collected during execution. These statistics show how much the Memory object is used, and the distribution of the operations performed by the Pyromaniac system. Whilst largely for debugging, this provides information on how the OS itself is accessing memory and may indicate bottlenecks.

Configuration group 'MemoryMap'

The MemoryMap configuration group controls the locations and sizes of memory areas within the Pyromaniac system. Each memory area has 3 settings:

• base, which defines the low address for the memory area
• size, which defines how large the area is on boot
• maxsize, which defines the largest size the area may grow to be.

MemoryMap.appspace_base

Value: &8000
Type: Hexadecimal value, optionally prefixed by '&'.

Configures the base address for application space. Setting this to anything other than &8000 is unlikely to work.

MemoryMap.appspace_maxsize

Value: 48 M
Type: Size as a number which may be suffixed by 'K', 'M' or 'G', and '-1'

Configures the maximum size of the application space.

MemoryMap.appspace_size

Value: 1024 K
Type: Size as a number which may be suffixed by 'K', 'M' or 'G', and '-1'

Configures the initial size of the application space.

MemoryMap.irqstack_base

Value: &4000000
Type: Hexadecimal value, optionally prefixed by '&'.

Configures the base address of the IRQ stack area. The stack must have its base at a megabyte boundary.

MemoryMap.irqstack_maxsize

Value: 16 K
Type: Size as a number which may be suffixed by 'K', 'M' or 'G', and '-1'

Configures the maximum size of the SVC stack area. It is unlikely that resizing the IRQ stack at runtime will function well.

MemoryMap.irqstack_size

Value: 16 K
Type: Size as a number which may be suffixed by 'K', 'M' or 'G', and '-1'

Configures the initial size of the SVC stack area.

MemoryMap.rma_base

Value: &7000000
Type: Hexadecimal value, optionally prefixed by '&'.

Configures the base address of the module area.

MemoryMap.rma_maxsize

Value: 15 M
Type: Size as a number which may be suffixed by 'K', 'M' or 'G', and '-1'

Configures the maximum size of the module area.

MemoryMap.rma_size

Value: 1024 K
Type: Size as a number which may be suffixed by 'K', 'M' or 'G', and '-1'

Configures the initial size of the module area.

MemoryMap.rom_base

Value: &3800000
Type: Hexadecimal value, optionally prefixed by '&'.

Configures the base address of the ROM area.

MemoryMap.rom_maxsize

Value: 8 M
Type: Size as a number which may be suffixed by 'K', 'M' or 'G', and '-1'

Configures the maximum size of the ROM area.

MemoryMap.rom_size

Value: 1024 K
Type: Size as a number which may be suffixed by 'K', 'M' or 'G', and '-1'

Configures the initial size of the ROM area.

MemoryMap.svcstack_base

Value: &4100000
Type: Hexadecimal value, optionally prefixed by '&'.

Configures the base address of the SVC stack area. The stack must have its base at a megabyte boundary.

MemoryMap.svcstack_maxsize

Value: 32 K
Type: Size as a number which may be suffixed by 'K', 'M' or 'G', and '-1'

Configures the maximum size of the SVC stack area. It is unlikely that resizing the SVC stack at runtime will function well.

MemoryMap.svcstack_size

Value: 32 K
Type: Size as a number which may be suffixed by 'K', 'M' or 'G', and '-1'

Configures the initial size of the SVC stack area.

MemoryMap.sysheap_base

Value: &4109000
Type: Hexadecimal value, optionally prefixed by '&'.

Configures the base address of the system heap area. The system heap is used for all internal Pyromaniac allocations.

MemoryMap.sysheap_maxsize

Value: 3040 K
Type: Size as a number which may be suffixed by 'K', 'M' or 'G', and '-1'

Configures the maximum size of the system heap area. The system heap is used for all internal Pyromaniac allocations.

MemoryMap.sysheap_size

Value: 128 K
Type: Size as a number which may be suffixed by 'K', 'M' or 'G', and '-1'

Configures the initial size of the system heap area. The system heap is used for all internal Pyromaniac allocations.

MemoryMap.undstack_base

Value: &8400000
Type: Hexadecimal value, optionally prefixed by '&'.

Configures the base address of the UND stack area. The stack must have its base at a megabyte boundary.

MemoryMap.undstack_maxsize

Value: 16 K
Type: Size as a number which may be suffixed by 'K', 'M' or 'G', and '-1'

Configures the maximum size of the UND stack area. It is unlikely that resizing the UND stack at runtime will function well.

MemoryMap.undstack_size

Value: 16 K
Type: Size as a number which may be suffixed by 'K', 'M' or 'G', and '-1'

Configures the initial size of the UND stack area.

MemoryMap.zeropage_enable

Value: no
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether zero page is given memory or not. If this is disabled, access to zero page will cause an abort.

Configuration group 'MessageTrans'

MessageTrans.support

Value: simple
Type: One of the strings 'none', 'simple', 'full'

Controls how the MessageTrans module functions. It can operate with different levels of support, where to make the system faster, or less encumbered by parts of the OS that do not exist.

• none: Makes all file open requests fail.
• simple: Makes all file open requests succeed, but the actual files will never be used, and the response will be the tokens, or the default values.
• full: Provides as much functionality of MessageTrans as is possible.

Configuration group 'Modules'

Modules.default_postfix

Value: Base
Type: str

Configures what the default module postfix should be for the base instance.

Modules.rominit_errors_fatal

Value: no
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether, during initialisation the ROM modules which produce errors are fatal for the system.

Modules.rominit_noisy

Value: no
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether, during initialisation the ROM module names and any errors are displayed. Mirrors a similar option in the classic Kernel.

Modules.unplug

Value: ROM:
Type: UnplugList

Configures which modules will not be initialised from the internal ROM, or any extension ROMs. This is distinct from the NVRAM configuration which unplugs modules (which is not currently implemented).

The configuration is supplied as a list of ROM sections and module names to be unplugged. The ROM sections and modules are listed in a ; separated list, in the form <section-name>:<modules>, where <modules> is a , separated list.

Valid section names are:

• rom - the system ROM populated by Pyromaniac
• extrom-<number> - a numbered extension ROM.
• card-<number> - a numbered expansion card.
• nic - the network expansion card.

For example:

• rom:ddeutils - would unplug DDEUtils from the system ROM.
• extrom-1:Podule - would unplug the podule manager from extension ROM 1.
• extrom-1:Podule;rom:ddeutils - would unplug both the modules named in the prior examples.
• rom:ddeutils,taskwindow - would unplug DDEUtils and TaskWindow from the system ROM.

Configuration group 'NVRAM'

NVRAM.backingfile

Value: none
Type: str

Configures the backing file used for the NVRAM configuration data, or 'none' to disable reading and writing the configuration data. When set, the backing file will be loaded on boot, and written out whenever the configuration is changed.

NVRAM.format

Value: auto
Type: One of the strings 'auto', 'bytes', 'keyvalue'

Configures how the configuration backing file will be read and written. The format of the backing file can be:

• auto - decide on the format based on the size of the file.
• bytes - a file containing 240 bytes.
• keyvalue - a file containing colon separated byte: value format lines.

Configuration group 'OSConfirm'

OSConfirm.keys_no

Value: n
Type: str

Configures the characters which will be displayed as a 'no' response to the confirmation request. Actually, any key other than those defined in keys_yes will be treated as a 'no' response.

OSConfirm.keys_yes

Value: y
Type: str

Configures the characters which will be displayed and accepted as a 'yes' response to the confirmation request. Lower case versions of this character will also be accepted.

OSConfirm.shape

Value: alternate
Type: One of the strings 'classic', 'alternate'

Configures the shape used for the pointer which is displayed when the OS_Confirm call is made:

• classic: RISC OS Classic confirm pointer.
• alternate: Alternate form.

RISC OS Classic form uses a 'Y' to indicate the key for a positive response. RISC OS Pyromaniac defaults to an alternate form which uses a check mark to indicate a positive response.

A check mark is recognised in more countries as a positive response than the 'Y' character (and we don't have any Internationalisation in Pyromaniac yet).

OSConfirm.show_message

Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether a message is displayed when the OS_Confirm call is made.

OSConfirm.show_pointer

Value: if-active
Type: One of the strings 'never', 'always', 'if-active'

Configures how the pointer will be displayed when the OS_Confirm call is made:

• never: Never changes the pointer shape.
• always: Always changes the pointer shape.
• if-active: Changes the pointer shape if the pointer is already active.

RISC OS Classic uses the behaviour 'if-active', so Pyromaniac defaults to this.

Configuration group 'OSMemory'

The OSMemory configuration group controls the size reported for the memory areas from OS_Memory 8 (read memory amounts). Some of the areas are able to be calculated dynamically, whilst other areas have no meaning and can be configured to fake values.

OSMemory.amount_dram

Value: dynamic
Type: Size suffixed by 'K', 'M' or 'G', or 'dynamic' to calculate at runtime

Configures the amount of memory reported by OS_Memory 8 for the DRAM. The value may be calculated dynamically by setting the value to 'dynamic'.

OSMemory.amount_iospace

Value: 0
Type: Size as a number which may be suffixed by 'K', 'M' or 'G', and '-1'

Configures the amount of memory reported by OS_Memory 8 for the I/O space. As there is no concept of I/O in Pyromaniac, this defaults to 0.

OSMemory.amount_rom

Value: dynamic
Type: Size suffixed by 'K', 'M' or 'G', or 'dynamic' to calculate at runtime

Configures the amount of memory reported by OS_Memory 8 for the ROM. The value may be calculated dynamically by setting the value to 'dynamic'.

OSMemory.amount_softrom

Value: dynamic
Type: Size suffixed by 'K', 'M' or 'G', or 'dynamic' to calculate at runtime

Configures the amount of memory reported by OS_Memory 8 for the soft ROM. The value may be calculated dynamically by setting the value to 'dynamic'. The dynamic value depends on whether we claim that the ROM is softloaded in the platformsupport.os_rom configuration setting.

OSMemory.amount_vram

Value: 0
Type: Size as a number which may be suffixed by 'K', 'M' or 'G', and '-1'

Configures the amount of memory reported by OS_Memory 8 for the VARM. As there is no concept of VRAM in Pyromaniac, this defaults to 0.

Configuration group 'PlatformSupport'

The PlatformSupport configuration group controls the response from OS_ReadSysInfo 8.

PlatformSupport.additional_processor

Value: no
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether the flag for supporting the second processor will be set.

PlatformSupport.os_ram

Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether the flag for the OS being RAM loaded will be set. It defaults to enabled, because the OS is effectively RAM loaded (and isn't protected either).

PlatformSupport.os_rotated_loads

Value: no
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether the flag for whether the OS uses rotated loads will be set. It defaults to disabled, because the 'OS' doesn't actually do any ARM-based load operations, rotated or not.

PlatformSupport.os_unaligned_access

Value: no
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether the flag for whether the OS uses unaligned memory accesses will be set. It defaults to disabled, because the 'OS' doesn't actually do any unaligned memory accesses, or any ARM-based memory accesses at all for that matter.

PlatformSupport.pci

Value: no
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether the flag for supporting PCI cards will be set.

PlatformSupport.podules

Value: no
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether the flag for supporting podules will be set.

Configuration group 'Podule'

Podule.extensionrom1

Value: ` Type:str`

Configures the filename of the ROM image to load into Extension ROM 1. The file should be a ROM image suitable for use with a 32bit operating system. Any recognised modules will be provided through the Podule system, but the Kernel will not be present.

For the loading to work, the linkage address of the ROM must be available in memory. This may mean that the Pyromaniac ROM memory needs to be moved away by changing the memorymap.rom_base option to a different base (0x8800000 may be a suitable location). It is likely that modules in the ROM will need to be unplugged with the modules.unplug option.

At present, only Select-style 32 bit ROMs will function with the loader provided.

Configuration group 'Pointer'

Pointer.colours

Value: wimp
Type: One of the strings 'black', 'wimp'

Configures the colours that are used for the pointer by default. RISC OS Classic defaults to all the pointer colours being black. However, most uses will expect the colours to be those used by the Wimp, so this is what RISC OS Pyromaniac selects by default.

Pointer.enable

Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether the pointer is polled for events from the UI. When enabled, UI clicks will be passed to the mouse buffer and movements will move the mouse.

Pointer.max_height

Value: 32
Type: int

Configures the maximum height of the pointer allowed by the system. RISC OS Classic only allows a pointer 32 pixels high. RISC OS Pyromaniac allows larger pointers, but by default we set the same limits as RISC OS Classic.

Pointer.max_width

Value: 32
Type: int

Configures the maximum width of the pointer allowed by the system. RISC OS Classic only allows a pointer 32 pixels wide. RISC OS Pyromaniac allows larger pointers, but by default we set the same limits as RISC OS Classic.

Configuration group 'PowerControl'

PowerControl.poweroff_support

Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether the power control operations (OS_Reset &OFF and Portable) are supported.

Configuration group 'ProgEnv'

ProgEnv.cli_size

Value: 1024
Type: Size as a number which may be suffixed by 'K', 'M' or 'G', and '-1'

Configures the default length of the CLI supported by the environment. On early RISC OS versions this was 256. With RISC OS 4, it was increased to 1024. Lengths longer than 256 are commonly not supported by BASIC tools, and many other tools may fail with longer strings.

ProgEnv.exception_errors_show_region

Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0

Control whether, on an exception, the error that is generated includes information about the region of the aborts. This was not available in RISC OS classic, but is very useful for debugging.

ProgEnv.exception_show_registers

Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0

Control whether, on an exception, the register dump is written out to the VDU output stream. This may aid in debugging, especially in the case where error handlers themselves are faulty.

Configuration group 'Pyro'

Pyro.reset_effect

Value: reboot
Type: One of the strings 'exit', 'reboot'

Configures how pyro deals with a request to reset the system:

• exit - always caauses the system to exit
• reboot - boot the statem again

Pyro.return_rc

Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether the tool will return the Sys$ReturnCode from the last run process or not. When this option is enabled, the command return code will be set to the value of the Sys$ReturnCode on return from the last command. When this option is disabled, the command return code will be 0 unless an error occurred.

Pyro.stop_on_failing_rc

Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether the execution of actions by the tool will check the Sys$ReturnCode variable for non-0 values. When this option is enabled, a non-0 return code is given, command execution will stop and the system will exit. When this option is disabled, a non-0 return code is ignored. The Obey module's execution of files is closesr to the effect of this option being disabled.

Pyro.system_boot

Value: no
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether the system will go through the normal system boot sequence (filesystem boot, bootmenu, supervisor, as configured) or not.

Configuration group 'PyromaniacModule'

PyromaniacModule.config_allow

Value: ` Type:listlower`

Configures which configuration groups are allowed to be configured by the *PyromanicConfig command. The group names are given in a comma-separated list. If this list is empty, all groups are allowed. If groups are listed, then any configuration which is not named in those groups will give an error.

PyromaniacModule.config_deny

Value: ` Type:listlower`

Configures which configuration groups are not allowed to be configured by the *PyromanicConfig command. The group names are given in a comma-separated list. If this list is empty, all groups are allowed. If groups are listed, then any configuration which is named in those groups will give an error.

PyromaniacModule.config_enable

Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether the *PyromaniacConfig command is allowed to be used. If this is disabled, the command will return an error.

PyromaniacModule.debug_enable

Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether the *PyromaniacDebug command is allowed to be used. If this is disabled, the command will return an error.

PyromaniacModule.enable

Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether the Pyromaniac module is able to function. If this is disabled, the Pyromaniac commands will return errors.

PyromaniacModule.hostcommand_ansiescapes

Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether the *PyromanicHostCommand output is converted from ANSI control codes to RISC OS control codes. Only a very limited subset of the terminal controls are supported. If this is disabled, the output from the host command will be passed directly to the RISC OS VDU stream.

PyromaniacModule.hostcommand_cwd_riscos

Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether the *PyromaniacHostCommand executes within the native working directory, if there is one. When enabled, the commands will run with the working directory set to the equivalent location on the native filesystem. When disabled, the working directory will be unaffected.

PyromaniacModule.hostcommand_enable

Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether the *PyromanicHostCommand is allowed to be used. If this is disabled, the command will return an error.

PyromaniacModule.hostcommand_output_encoding

Value: utf-8
Type: str

Configures what encoding the output from *PyromanicHostCommand is reported in. Most host system tools use UTF-8 as their encoding. This means that to be rendered correctly in RISC OS, the UTF-8 characters must be re-encoded to the current alphabet. This option controls whether the characters from the host command are treated as UTF-8, or some other encoding. Encoding names are those used by Python (not the alphabets used by RISC OS).

The configuration may also use 'identity' to pass through characters directly to the RISC OS system.

PyromaniacModule.hostcommand_print_rc

Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether the *PyromanicHostCommand reports the return code from the host command by printing to the VDU stream at the end of its execution. If this is disabled, no message will be printed.

Whether this option is enabled or not, the Sys$ReturnCode variable will be updated.

PyromaniacModule.timing_enable

Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether the *PyromaniacTiming command is allowed to be used. If this is disabled, the command will return an error.

PyromaniacModule.watchpoint_enable

Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether the *PyromaniacWatchpoint command is allowed to be used. If this is disabled, the command will return an error.

Configuration group 'ROMInformation'

The ROMInformation configuration group controls the values returned by OS_ReadSysInfo 9. Normally these values would be encoded in the end of the ROM image. However, there is no fixed ROM for Pyromaniac, so these may be configured here.

Any of the ROMInformation strings may contain a '\n' sequence to embed a newline in the information string.

ROMInformation.builddate

Value: Tue,17 Nov 2020.23:33:21

Configures the build date for the system. The build date was recorded with each image to ensure that if a ROM was rebuilt from an earlier part number, it would be distinguishable. In Pyromaniac this defaults to the current date and time at the time of execution. The string is intended to be human readable.

ROMInformation.dealername

Value: Gerph

Configures the dealer name for the system. The dealer name was intended to be used for ROMs customised by dealers, to ensure that they were distinguishable from the others. The intent was that the part number was only interpretable together with the dealer name.

ROMInformation.hardwareplatformname

Value: Darwin/x86_64

ROMInformation.osdescription

Value: RISC OS Pyromaniac

Configures the printable OS description for the system.

ROMInformation.osname

Value: RISC OS Pyromaniac

Configures the name of the Operating System, usually in the form:

RISC OS [<variant>] [Select] [\[Beta\]]

ROMInformation.partnumber

Value: None

Configures the part number of the system. The part number was used by RISCOS Ltd to track releases through their artifact repository, with each released build being tracked and both reproducible and recorded. Usually the part numbers took the form:

YYYYMMDD-XXX

or YYYYMMDD-iii-system

ROMInformation.useraddress

Value: None

Configures the address of the user who registered the system. The address would be displayed on startup, to give a little more customisation to the ROM images.

ROMInformation.username

Value: None

Configures the user name who registered the system. The user name would be displayed on startup, to give a little more customisation to the ROM images.

Configuration group 'Resolver'

Resolver.enable

Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether the Resolver module is able to function. If this is disabled, the Resolver SWIs will return errors.

Configuration group 'Sound'

The Sound configuration group controls the way in which the SoundChannels module plays sounds. The SoundChannels module uses the host MIDI functions to provide audible effects. The sound channel is mapped to the MIDI channel (although only 8 channels are supported, like RISC OS). The RISC OS voices are mapped to MIDI instruments, with a default set of instruments selected to sound close to the originals.

The voice_* configuration options all have the same configuration format:

• default
  • never configure anything (leaves the channel configuration alone)
• <program-number>
  • set a program number (1-128) within bank 121 (GM1 Sound Set)
• <program-number>:<msb>
  • set a program number (1-128) within a bank, given the MSB (1-128)
• <program-number>:<msb>:<lsb>
  • set a program number (1-128) within a bank, given the MSB (1-128) and LSB (1-128)
• <name>
  • set a program number to a given instrument in the GM1 Sound Set
• <name>:<lsb>
  • set a program number to a given instrument in the GM1 Sound Set, with LSB

Sound.bbc_style

Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether the SoundChannels module functions like RISC OS, or like the BBC. The difference is in how sounds are queued and where the flags are defined.

BBC style:

• Sounds are queued, and on completion of one note, the next note on the channel is played.
• Flags are present in the channel.

RISC OS style:

• Sounds are played immediately, replacing any currently playing notes.
• Flags are present in the amplitude.

Sound.enable_midi

Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether the SoundChannels module uses the MIDI system for its sound. When disabled, the sound system will go through the motions but will not actually generate sounds.

Sound.voice_percussion_medium

Value: Melodic Tom
Type: Voice configuration, such as GM1 instrument name

Sound.voice_percussion_noise

Value: Bagpipe
Type: Voice configuration, such as GM1 instrument name

Sound.voice_percussion_snare

Value: Synth Drum
Type: Voice configuration, such as GM1 instrument name

Sound.voice_percussion_soft

Value: Woodblock
Type: Voice configuration, such as GM1 instrument name

Sound.voice_stringlib_hard

Value: Electric Guitar (Clean)
Type: Voice configuration, such as GM1 instrument name

Sound.voice_stringlib_pluck

Value: Acoustic Guitar (Nylon)
Type: Voice configuration, such as GM1 instrument name

Sound.voice_stringlib_soft

Value: Violin
Type: Voice configuration, such as GM1 instrument name

Sound.voice_stringlib_steel

Value: Acoustic Guitar (Steel)
Type: Voice configuration, such as GM1 instrument name

Sound.voice_wavesynth_beep

Value: Electric Piano 1
Type: Voice configuration, such as GM1 instrument name

Configuration group 'SysLog'

SysLog.default_flush

Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether reports to SysLog are written out immediately, or only written out on an explicit flush.

In the original module, and the reimplementation, the output would be buffered and written out on a delay in the background. This is not currently implemented.

SysLog.default_loglevel

Value: 125
Type: int

Configures the default log level which is set on log files. This is 125 by convention with the original module.

SysLog.log_directory

Value: $.Logs
Type: str

Configures the directory to which log files will be written. As no boot sequence will commonly have been used, this defaults to '$.Logs'.

SysLog.timestamp_format

Value: %b %d %H:%M:%S
Type: str

Configures the format used by the timestamps in the SysLog file output. This defaults to the same format as the orignal module. The format string is in the strftime style.

Configuration group 'SystemBell'

SystemBell.bell_type

Value: sound
Type: One of the strings 'sound', 'console', 'message'

Configures how the External Bell service should be handled. This service is issued for VDU 7, and can be configured to operate in different manners on different systems. The types of bell supported are:

• sound - call Sound_Control, with the configured sound parameters from OS_Byte. This is how RISC OS usually handles the VDU 7 bell.
• console - writes a BEL to the console, which will perform its own handling of the bell.
• message - write a message to the VDU output stream.

Configuration group 'SystemInformation'

The SystemInformation configuration controls the information returned about the system through a few of the core SWI calls.

SystemInformation.osbyte0_machinetype

Value: 6
Type: int

Configures the value used for the machine type returned by OS_Byte 0. The default value is a machine type for ARM based systems.

SystemInformation.osbyte129_osversion

Value: &ae
Type: Hexadecimal value, optionally prefixed by '&'.

Configures the value used for the OS version returned by OS_Byte 129 (INKEY(-256)). The default value is a version allocated to Pyromaniac.

SystemInformation.platform_class

Value: 16
Type: int

Configures the value used for the platform class returned by OS_ReadSysInfo 8. The default value is the class allocated to Pyromaniac.

Configuration group 'TaskManager'

TaskManager.taskmanager_task

Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether the TaskManager lists itself as a task in the enumeration given by TaskManager_EnumerateTasks.

Configuration group 'TaskWindow'

TaskWindow.in_taskwindow

Value: no
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether the TaskWindow module reports that we are in a TaskWindow or not.

Configuration group 'Territory'

Territory.write_direction

Value: ltr-ttb-horizontal
Type: Regular expression matching: (ltr|rtl)-(ttb|btt)-(horizontal|vertical)

Configures the flags returned from Territory_WriteDirection.

The values take the form: * ltr or rtl for left-to-right or right-to-left * ttb or btt for top-to-bottom or bottom-to-top * horizontal or vertical for the direction that is used primarily.

Configuration group 'Throwback'

Throwback.console_colour

Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether colour is used in the output in the 'console' implementation.

Throwback.implementation

Value: console
Type: str

Configures the implementation to use for throwback reported through the DDEUtils module. The following implementations are provided:

• console - displays the throwback reports on the console.
• null - has no effect for the throwback reports.
• posturl - posts throwback reports to the url.

Throwback.url

Value: data:
Type: str

Configures the URL to which the 'posturl' implementation will send reports. The HTTP POST is formatted as a JSON encoded body, with the following fields from the report:

• reason - the reason number
• reason_name - the reason name ('Processing', 'Error', 'Info')
• filename - the RISC OS filename being reported
• url' - the URL of the file being reported (seeurl_scheme`)
• message - the message for this report (not for 'Processing' reports)
• severity - the severity number
• `severity_name' - the serverity name ('Error', 'Warning', 'Serious Error')
• lineno - the line number

Throwback.url_include_hostname

Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether the 'url' field in the 'posturl' implementation includes a hostname or not. Some console linking implementations require the hostname, whilst others do not explicitly support them.

Throwback.url_scheme

Value: file
Type: One of the strings 'riscos', 'file'

Configures the scheme used for the 'url' field in the 'posturl' and 'console' implementation. This can be one of:

• riscos - uses the format: riscos:///<URL-encoded filename>
• file - uses the 'file' scheme to report the native filename of the file in the report, or the 'riscos' scheme if the file is not on the native filesystem.

In the console output, the URL will be linked with a hyperlink. Consult https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda for more information.

Configuration group 'Time'

Time.offset

Value: 0s
Type: Time in the form: [+|-]{<number>{s|m|h|d|w|y}}*

Configures the time offset applied to the current host clock within RISC OS. The offset is a string which contains the offset in the form of a decimal followed by the single character units, repeated, optionally preceded by a '-' sign. Units supported are:

• s - seconds
• m - minutes
• h - hours
• d - days
• w - weeks
• y - years

For example:

• 1h 15m - would add 1 hour and 15 minutes to the current time.
• -1w - would subtract 1 week from the current time.

Configuration group 'Timings'

The Timings configuration group manages the data collected about the time spent in different areas, and the number of times those areas are entered. The data is reported when the system is exited. The data which is recorded falls into the following groups:

• SWI execution - times each SWI's total execution time. This may include the time spent within the dispatch to executed code, and calls to other SWIs.
• Emulated ARM execution - times the execution of the ARM code. This only includes the ARM code, and not any SWIs that it might call.
• Timer execution - times the execution of calls to timer routines registered with OS_CallEvery/OS_CallAfter.
• Callback execution - times the execution of calls to the transient callback routines registered wtih OS_AddCallBack.
• Non-emulation execution - times the internal overhead of the time not spent executing ARM code. Because of reentrancy, this might include calls into the ARM execution as well.

Timings.execute

Value: no
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether non-SWI timings are collected during execution and reported when the system exits.

Timings.swi

Value: no
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether SWIs counts and timings are collected during execution and reported when the system exits.

Configuration group 'Trace'

Trace.function_registers

Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether when the execution enters a function, the trace will report the registers.

Trace.output

Value: stderr
Type: One of the strings 'stdout', 'stderr', 'riscos'

Configure where the trace output will be send. The output configuration can be:

• stdout - trace to stdout
• stderr - trace to stderr
• file:... - trace to a named file

Trace.recent_blocks_count

Value: 10
Type: int

Configures how many blocks of recent execution will be reported in exceptions.

Trace.report_python_traceback

Value: no
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether reports such as exceptions will include the traceback within the Python code as well as within the emulated system. This may be useful when the location is passing through a Pyromaniac interface which does not otherwise appear in the traceback.

Trace.report_relative_instructions

Value: 15
Type: int

Controls whether reports such as exceptions will include details of the recent blocks that were executed if that information is available.

Trace.show_disassembled_word

Value: no
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether disassembly during a trace will include the instruction word that was executed. Normally this is omitted.

Trace.show_referenced_pointers

Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether disassembly during a trace will include details of the pointer values in registers.

Trace.show_referenced_registers

Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether disassembly during a trace will include details of the registers which are referenced in the instruction. The registers reported are the values before the instruction is executed.

Trace.stack_depth_indicator

Value: no
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether trace lines include a stack indicator using '|' markers to show how deep the stack is at a given point.

Trace.stack_depth_width

Value: 24
Type: int

Configures how many characters are used for the stack indicator when it is in use. If the stack markers exceed this width, it will be made longer.

Trace.stack_value

Value: no
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether trace lines include the value of the stack pointer.

Trace.switraps

Value: 
Type: Comma separated list of hexadecimal SWI numbers, or names

Configures the list of SWIs numbers, names or prefixes which will be trapped. When the SWIs listed are executed, the details of that execution will be recorded to the trace output.

Trace.tracepoints

Value: 
Type: Comma separated list of hexadecimal addresses, or function names

Configures the list of addresses which will be watched for execution. When the address is executed, the details of that execution will be recorded to the trace output.

Trace.watch_lowvectors

Value: yes
Type: One of the strings 'no', 'read', 'write', 'yes'

Controls whether the low CPU vector region is implicitly registered as a watchpoint.

Trace.watchpoints

Value: 
Type: Comma separated list of hexadecimal addresses

Configures the list of addresses which will be watched for changes. When the address is accessed, the details of that access will be recorded to the trace output.

Configuration group 'Twin'

Twin.command

Value: nano -R
Type: str

Configures the command that will be invoked to edit the source. This command will be passed the name of the temporary file which should be edited. After the command returns, the file will be loaded and returned to BASIC.

Twin.enable

Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether the Twin module is able to function. If this is disabled, the Twin commands will return errors.

Configuration group 'URI'

URI.acceptable_schemes

Value: http,https,ftp
Type: listlower

Configures which schemes are able to be launched in the host system by the URI module.

URI.enable

Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether the URI module is able to function. If this is disabled, the URI SWIs will return errors.

Configuration group 'UniqueId'

The UniqueID configuration group allows the machine unique ID to be configured. The UniqueID is returned by OS_ReadSysInfo 2 and 5.

UniqueId.high

Value: &decade
Type: Hexadecimal value, optionally prefixed by '&'.

UniqueId.low

Value: &da2ed
Type: Hexadecimal value, optionally prefixed by '&'.

Configuration group 'UserV'

UserV.effect

Value: message
Type: One of the strings 'null', 'message', 'error', 'warning'

Configures how the UserV handler should function when it is called. By default on RISC OS it does nothing, and it is discouraged from being used. However, it may be useful for certain debugging actions. In particular, being able to trigger a warning through the trace system may help to diagnose issues dynamically.

Effects available are:

• null - Do nothing
• message - Displays a message to the VDU stream
• error - Raises an error
• warning - Reports a warning through the trace system

Configuration group 'VDU'

VDU.alphabet

Value: Latin1
Type: str

Configure the RISC OS alphabet used for the VDU output. The alphabet can be one of the alphabets used by RISC OS which are supported by Pyromaniac. Use the *Alphabets command to list these. The output from the VDU system (either through the graphics system or the console) will be converted from this alphabet to the output_encoding. Usually this is set to 'Latin1'.

VDU.flush

Value: position
Type: One of the strings 'line', 'char', 'position'

Controls when console output is flushed. On RISC OS Classic, output would always appear when it is written. This isn't how most unix-like tools function. They usually buffer output when they're run in a pipe, either with lines or larger chunks. This is more efficient as the number of system calls are reduced and the user mode process can do more work. Because RISC OS does not have this concept, this setting tries to balance the efficiency with responsiveness.

• position will flushes output at the end of a line or when the cursor is explicitly moved. This is a good compromise most of the time.

• line will flush only at the end of the line.

• char will cause a flush for every character, which is the least efficient but most consistent with RISC OS Classic.

The default setting is 'position'. Regardless of the setting, the output will be flushed if input is requested.

VDU.implementation

Value: plain
Type: str

Configures the implementation used for the VDU system. This controls where the VDU system sends its output (in addition to the graphics system). Use --list-implementations to show the VDU implementations.

VDU.mode

Value: 27
Type: int

Configures the RISC OS mode to be selected on boot. Only mode numbers can be supplied.

VDU.newline_format

Value: LF
Type: One of the strings 'lf', 'lfcr', 'crlf', 'cr'

Controls what SWI OS_NewLine will generate - line feeds, carriage return, both or none. By default, this is configured to just LF, which differs from the RISC OS default. This is, however, the expected output for most unix-like tools, so should produce comparable results to other native tools. RISC OS Classic would use LFCR.

VDU.output_encoding

Value: utf-8
Type: str

Configure the Python encoding that will be used for the console output. Usually this is set to 'UTF-8', but it can also be configured to 'identity' to pass through the VDU output without an encoding translation.

VDU.paging

Value: none
Type: One of the strings 'none', 'console', 'shift'

Controls how paged mode (VDU 14) is handled. The following configurations are available: * 'console': A prompt will appear for a key press to continue to the next page. * 'none': Paged mode will still be counted, but it will be as if the paging was always continued immediately. * 'shift': The 'shift' keys will continue paged output, as under RISC OS Classic. This will only be effective when the input system can detect the shift key (such as in the graphics UIs).

VDU.show_controls

Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether unrecognised control codes will be displayed as [<control sequence>]. When disabled, no output will occur for unrecognised control codes.

Configuration group 'VDUANSIText'

VDUANSIText.change_terminal_size

Value: no
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether the terminal size will be changed on a mode change.

VDUANSIText.closest_match

Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether failing to match the primary colours or 8 bit colour matching exactly falls back to finding a closest of those colours. This would not be used if the 24 bit matching was enabled.

VDUANSIText.support_24bit

Value: no
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether 24 bit ANSI colour selection using the 38;2m and 48;2m codes is used. These 24 bit codes will only be used when the primary colours and the 8bit colour codes do not match.

VDUANSIText.support_8bit

Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether 8 bit ANSI colour selection using the 38;5m and 48;5m codes is used. These 8bit codes will only be used when the primary colours do not match.

VDUANSIText.support_primary

Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether the primary colour selection using 30-7m and 40-7m codes is used. These codes are used with support_primarybold to select bold foreground colours.

VDUANSIText.support_primarybold

Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether the primary colour selection for foreground colours also uses bold colour selection. Without this, the primary colour will be used for the full intensity colours.

Configuration group 'WX'

WX.maximum_redraw_rate

Value: 20
Type: int

Configures the maximum rate at which the wxWidgets window will be updated. If this is set too high, the system may spend more time redrawing than executing code. If this is set too low, output may not refresh in a timely manner as it is generated.

Configuration group 'WimpReportErrorBox'

WimpReportErrorBox.disable_beep

Value: no
Type: Boolean state in the form true/false, yes/no, or 1/0

Controls whether the Wimp_ReportError beeps (when not disabled in the call). If enabled, the beep will be issued through the System Bell interface (VDU 7, Service_SystemBell))

WimpReportErrorBox.implementation

Value: vdu
Type: str

Configures the implementation to use for the Wimp_ReportError system. This allows the type of error reports to be controlled. The current implementations that are provided are:

• null - always reports the cancel operation.
• vdu - reports messages to the RISC OS VDU stream, and accepts input from the input stream.
• easygui - uses the EasyGUI python package to provide a host interface. This implementation cannot be used in conjunction with other UI interfaces.