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 'ADFS'

ADFS.default_drive

Value: 4
Type: int

Configures the default drive returned by the ADFS module. Under RISC OS Pyromaniac this is only used for information.

ADFS.drive0_data_file

Value: 
Type: str

Configures the file that will be used as data read from ADFS for drive 0 on the host system. When set to an empty string, no data will be available and the drive will always appear empty.

ADFS.drive0_data_range

Value: 0-
Type: Half-open 64bit size range such in the form <start>-[<end>] or <start>+<length>

Configures the range used for data read from ADFS drive 0. The data file will only be accessed from a given offset, up to a length. This allows partitioned data to be extracted from a file, if necessary. The format of the range is one of :

• <start>[-[<end>]]
• <start>+[<size>]

If no <end> or <size> is supplied, the end of the data file is assumed. Sizes may be specified as decimal, hexadecimal or suffixed sizes (using the binary multipliers K, M, G, etc).

ADFS.drive0_freespace

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

ADFS.drive0_largestspace

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

ADFS.drive0_name

Value: Floppy0
Type: str

Configures the name returned from ADFS during Describe on drive 0.

ADFS.drive0_readonly

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

Controler whether ADFS drive 0 can be written to.

ADFS.drive1_data_file

Value: 
Type: str

Configures the file that will be used as data read from ADFS for drive 1 on the host system. When set to an empty string, no data will be available and the drive will always appear empty.

ADFS.drive1_data_range

Value: 0-
Type: Half-open 64bit size range such in the form <start>-[<end>] or <start>+<length>

Configures the range used for data read from ADFS drive 1. The data file will only be accessed from a given offset, up to a length. This allows partitioned data to be extracted from a file, if necessary. The format of the range is one of :

• <start>[-[<end>]]
• <start>+[<size>]

If no <end> or <size> is supplied, the end of the data file is assumed. Sizes may be specified as decimal, hexadecimal or suffixed sizes (using the binary multipliers K, M, G, etc).

ADFS.drive1_freespace

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

ADFS.drive1_largestspace

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

ADFS.drive1_name

Value: Floppy1
Type: str

Configures the name returned from ADFS during Describe on drive 1.

ADFS.drive1_readonly

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

Controler whether ADFS drive 1 can be written to.

ADFS.drive2_data_file

Value: 
Type: str

Configures the file that will be used as data read from ADFS for drive 2 on the host system. When set to an empty string, no data will be available and the drive will always appear empty.

ADFS.drive2_data_range

Value: 0-
Type: Half-open 64bit size range such in the form <start>-[<end>] or <start>+<length>

Configures the range used for data read from ADFS drive 2. The data file will only be accessed from a given offset, up to a length. This allows partitioned data to be extracted from a file, if necessary. The format of the range is one of :

• <start>[-[<end>]]
• <start>+[<size>]

If no <end> or <size> is supplied, the end of the data file is assumed. Sizes may be specified as decimal, hexadecimal or suffixed sizes (using the binary multipliers K, M, G, etc).

ADFS.drive2_freespace

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

ADFS.drive2_largestspace

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

ADFS.drive2_name

Value: Floppy2
Type: str

Configures the name returned from ADFS during Describe on drive 2.

ADFS.drive2_readonly

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

Controler whether ADFS drive 2 can be written to.

ADFS.drive3_data_file

Value: 
Type: str

Configures the file that will be used as data read from ADFS for drive 3 on the host system. When set to an empty string, no data will be available and the drive will always appear empty.

ADFS.drive3_data_range

Value: 0-
Type: Half-open 64bit size range such in the form <start>-[<end>] or <start>+<length>

Configures the range used for data read from ADFS drive 3. The data file will only be accessed from a given offset, up to a length. This allows partitioned data to be extracted from a file, if necessary. The format of the range is one of :

• <start>[-[<end>]]
• <start>+[<size>]

If no <end> or <size> is supplied, the end of the data file is assumed. Sizes may be specified as decimal, hexadecimal or suffixed sizes (using the binary multipliers K, M, G, etc).

ADFS.drive3_freespace

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

ADFS.drive3_largestspace

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

ADFS.drive3_name

Value: Floppy3
Type: str

Configures the name returned from ADFS during Describe on drive 3.

ADFS.drive3_readonly

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

Controler whether ADFS drive 3 can be written to.

ADFS.drive4_data_file

Value: 
Type: str

Configures the file that will be used as data read from ADFS for drive 4 on the host system. When set to an empty string, no data will be available and the drive will always appear empty.

ADFS.drive4_data_range

Value: 0-
Type: Half-open 64bit size range such in the form <start>-[<end>] or <start>+<length>

Configures the range used for data read from ADFS drive 4. The data file will only be accessed from a given offset, up to a length. This allows partitioned data to be extracted from a file, if necessary. The format of the range is one of :

• <start>[-[<end>]]
• <start>+[<size>]

If no <end> or <size> is supplied, the end of the data file is assumed. Sizes may be specified as decimal, hexadecimal or suffixed sizes (using the binary multipliers K, M, G, etc).

ADFS.drive4_freespace

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

ADFS.drive4_largestspace

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

ADFS.drive4_name

Value: HardDisc4
Type: str

Configures the name returned from ADFS during Describe on drive 4.

ADFS.drive4_readonly

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

Controler whether ADFS drive 4 can be written to.

ADFS.drive5_data_file

Value: 
Type: str

Configures the file that will be used as data read from ADFS for drive 5 on the host system. When set to an empty string, no data will be available and the drive will always appear empty.

ADFS.drive5_data_range

Value: 0-
Type: Half-open 64bit size range such in the form <start>-[<end>] or <start>+<length>

Configures the range used for data read from ADFS drive 5. The data file will only be accessed from a given offset, up to a length. This allows partitioned data to be extracted from a file, if necessary. The format of the range is one of :

• <start>[-[<end>]]
• <start>+[<size>]

If no <end> or <size> is supplied, the end of the data file is assumed. Sizes may be specified as decimal, hexadecimal or suffixed sizes (using the binary multipliers K, M, G, etc).

ADFS.drive5_freespace

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

ADFS.drive5_largestspace

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

ADFS.drive5_name

Value: HardDisc5
Type: str

Configures the name returned from ADFS during Describe on drive 5.

ADFS.drive5_readonly

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

Controler whether ADFS drive 5 can be written to.

ADFS.drive6_data_file

Value: 
Type: str

Configures the file that will be used as data read from ADFS for drive 6 on the host system. When set to an empty string, no data will be available and the drive will always appear empty.

ADFS.drive6_data_range

Value: 0-
Type: Half-open 64bit size range such in the form <start>-[<end>] or <start>+<length>

Configures the range used for data read from ADFS drive 6. The data file will only be accessed from a given offset, up to a length. This allows partitioned data to be extracted from a file, if necessary. The format of the range is one of :

• <start>[-[<end>]]
• <start>+[<size>]

If no <end> or <size> is supplied, the end of the data file is assumed. Sizes may be specified as decimal, hexadecimal or suffixed sizes (using the binary multipliers K, M, G, etc).

ADFS.drive6_freespace

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

ADFS.drive6_largestspace

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

ADFS.drive6_name

Value: HardDisc6
Type: str

Configures the name returned from ADFS during Describe on drive 6.

ADFS.drive6_readonly

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

Controler whether ADFS drive 6 can be written to.

ADFS.drive7_data_file

Value: 
Type: str

Configures the file that will be used as data read from ADFS for drive 7 on the host system. When set to an empty string, no data will be available and the drive will always appear empty.

ADFS.drive7_data_range

Value: 0-
Type: Half-open 64bit size range such in the form <start>-[<end>] or <start>+<length>

Configures the range used for data read from ADFS drive 7. The data file will only be accessed from a given offset, up to a length. This allows partitioned data to be extracted from a file, if necessary. The format of the range is one of :

• <start>[-[<end>]]
• <start>+[<size>]

If no <end> or <size> is supplied, the end of the data file is assumed. Sizes may be specified as decimal, hexadecimal or suffixed sizes (using the binary multipliers K, M, G, etc).

ADFS.drive7_freespace

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

ADFS.drive7_largestspace

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

ADFS.drive7_name

Value: HardDisc7
Type: str

Configures the name returned from ADFS during Describe on drive 7.

ADFS.drive7_readonly

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

Controler whether ADFS drive 7 can be written to.

ADFS.floppy_drives

Value: 4
Type: int

Configures the number of floppy drives returned by the ADFS module. When used with FileCore, this will be the number of floppy drives reported. When used without FileCore, this will only be used for information.

ADFS.floppy_ejectable

Value: True
Type: bool

Configures whether the floppy drives are marked as being ejectable. When used with FileCore, this will set the appropriate flags. When used without FileCore, this will only be used for information.

ADFS.floppy_removeable

Value: True
Type: bool

Configures whether the floppy drives are marked as being removeable (act like floppies). When used with FileCore, this will set the appropriate flags. When used without FileCore, this will only be used for information.

ADFS.hard_drives

Value: 4
Type: int

Configures the number of hard drives returned by the ADFS module. When used with FileCore, this will be the number of hard drives reported. When used without FileCore, this will only be used for information.

ADFS.hard_ejectable

Value: False
Type: bool

Configures whether the hard drives are marked as being ejectable. When used with FileCore, this will set the appropriate flags. When used without FileCore, this will only be used for information.

ADFS.hard_removeable

Value: False
Type: bool

Configures whether the hard drives are marked as being removeable (act like floppies). When used with FileCore, this will set the appropriate flags. When used without FileCore, this will only be used for information.

ADFS.swis

Value: filecore
Type: One of the strings 'direct', 'filecore'

Configures how the SWIs are handled for the module. RISC OS Classic always passed the SWI calls to FileCore. However, it can be useful to override this and instead always use the configured values directly. Using the values directly (without calling FileCore) is always done when FileCore is not present. When FileCore is present, using the direct values gives greater control over the values returned.

Configurations:

• direct: always processes the SWI calls through the internal fake handlers.
• filecore: always calls FileCore to process the SWIs, which may still call the internal handlers.

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 'CDFSDriver'

CDFSDriver.reinit_drivers

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

Controls whether the module will reinitialise the softload drivers after it has initialised. The standard RISC OS CDFSDriver will reinit the modules which start with CDFSSoft as it initialises. This ensures that those modules register themselves with us.

Configuration group 'CDFSSoftPyromaniac'

CDFSSoftPyromaniac.data_file

Value: 
Type: str

Configures the file that will be used as data read from CDFS on the host system. When set to an empty string, no file will be offered and the drive will always appear empty.

CDFSSoftPyromaniac.inquiry_product

Value: Virtual CD drive
Type: str

Configures the product identifier string returned by the Inquiry SWI. The maximum length of the string is 16 characters.

CDFSSoftPyromaniac.inquiry_vendor

Value: ROPyro
Type: str

Configures the vendor identifier string returned by the Inquiry SWI. The maximum length of the string is 8 characters.

CDFSSoftPyromaniac.inquiry_version

Value: 0.01
Type: str

Configures the version string returned by the Inquiry SWI. The maximum length of the string is 4 characters.

CDFSSoftPyromaniac.max_retries

Value: 0
Type: int

Configures the maximum number of retries reported by the CD drive when read by CD_GetParameters."

CDFSSoftPyromaniac.read_mode

Value: 0
Type: int

Configures the mode used by the CD drive when read by CD_GetParameters. The values 0, 1 and 3 are for data operations. The value 2 is used for audio operations.

CDFSSoftPyromaniac.speed

Value: 32
Type: int

Configures the speed which the CD drive will report that it runs at when queried, in multiples of 150KiB/s.

CDFSSoftPyromaniac.spindown_time

Value: 1
Type: int

Configures the scaler for the spindown time for the device which is reported by CD_GetParameters. The absolute value is not defined, only the multiple of whatever base the CD drive uses.

CDFSSoftPyromaniac.support_audio_playback

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

Controls whether the audio playback operations are supported.

Configuration group 'CH341'

CH341.i2c_speed_kbits

Value: 100
Type: int

Configures the speed that the I2C will communicate at with in kbit per second. By default this will be 100 kbit/s, which is the standard speed for I2C.

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 'CP2112'

CP2112.i2c_speed_kbits

Value: 100
Type: int

Configures the speed that the I2C will communicate at with in kbit per second. By default this will be 100 kbit/s, which is the standard speed for I2C.

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:

• null - Never copies content, and always returns an empty clipboard.
• posturl - POSTs clipboard content to a HTTP server. No mechanism it provided to receive clipboard data.
• pyperclip - Transfers clipboard to and from the host system using the Python pyperclip module.
• static - Holds clipboard whilst the OS is running in Pyromaniac memory.

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 'CompressJPEG'

CompressJPEG.components_invalid

Value: warning
Type: One of the strings 'error', 'warning', 'rgb'

Configures how invalid numbers of components will be handled. RISC OS Classic treated 1 component as grayscale, and anything else as RGB. The following configurations are supported:

• error: report an error if values other than 1 and 3 are used
• rgb: treat 1 as grayscale, anything else as RGB
• warning: treat 1 as grayscale, anything else as RGB, and warn about the use

The default is 'warning' as this is the closest to RISC OS Classic but retains some safety.

CompressJPEG.quality_invalid

Value: warning
Type: One of the strings 'error', 'warning', 'clamped'

Configures how invalid quality values will be handled. RISC OS Classic treated values less than 0 as a 1, and values over 100 as 100. The following configurations are supported:

• error: report an error if values outside the range are used
• clamped: clamp to the range 0 to 100
• warning: clamp to the range 0 to 100, and warn about the use

The default is 'warning' as this is the closest to RISC OS Classic but retains some safety.

Configuration group 'Console'

Console.input_backspace_code

Value: 8
Type: int

Configures the code that the backspace key (the key which reports as code 127 in the terminal) will report to RISC OS. By default this reports as code 8, as this is the value that is espected by most clients. However, it may be configured to any value.

The most common alternative value to report would be code 127 - that is to report as itself.

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 'CryptRandom'

CryptRandom.implementation

Value: python
Type: str

Configures which implementation will be used for the random numbers generated by the CryptRandom module. The following implementations are provided:

• null - Returns a fixed number, the seed.
• python - Generates random numbers for CryptRandom using Python's generator.

CryptRandom.seed

Value: 123456789
Type: int

Configures a seed value which may be used by the implementation to start at the same value. The seed is just a simple integer.

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 'DisassembleARM32'

DisassembleARM32.format

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

Configures how the disassembly will be formatted. By default a RISC OS-like layout will be used for the disassembly. This takes more processing from the Capstone library's output, but will be more familiar. It is possible to use the raw Capstone format to save processing time.

Formats supported:

• capstone - Raw capstone disassembly.
• riscos - Processed disassembly to be more like RISC OS forms.

DisassembleARM32.rename_r13_to_sp

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

Controls whether R13 is disassembled as r13 or sp. By default we make this change. In almost all RISC OS code, register 13 will refer to the stack pointer.

DisassembleARM32.rename_r14_to_lr

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

Controls whether R14 is disassembled as r14 or lr. By default we make this change. In almost all RISC OS code, register 14 will refer to the link register.

DisassembleARM32.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.

DisassembleARM32.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.

DisassembleARM32.support_fpa

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

Controls whether the FPA instructions will be disassembled. By default we enable this, as most of RISC OS will expect to use them and the generic instruction forms will not be familiar. However, the support for these instructions in the disassembler may be incomplete, so they may be disabled.

Configuration group 'DisassembleARM64'

DisassembleARM64.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.

DisassembleARM64.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.

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: 1 G
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: 3 G
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.

DynamicArea.free_size

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

Configures the size of the free space returned by OS_DynamicArea 5. Either an explicit size can be given, or the string dynamic which will calculate the space free based on the amount of DRAM configured in osmemory.amount_dram.

Note: If both these configurations are set to dynamic, the result will be OS_DynamicArea 5 returning no free space, as the memory in use will match that which is available.

DynamicArea.name_control_effect

Value: passthrough+warning
Type: Regular expression matching: (error|hex|passthrough|truncate)(+warning)?

Configures the way that dynamic area creation with a descriptive name which contains control characters is handled. On RISC OS Classic the control characters are copied as part of the description. The option consists of two parts, the terminal action, and any additional actions separated by a '+'.

• error: Report an error if the string includes control characters.
• hex: Use the hex value of the assigned number if it contains controls.
• passthrough: Use the string as supplied, including controls.
• truncate: Use the string, truncated to the control character.

The only additional action that can be performed is warning which reports the use to the trace system.

DynamicArea.name_invalid_effect

Value: error+warning
Type: Regular expression matching: (error|hex|abort)(+warning)?

Configures the way that dynamic area creation with a descriptive name pointer which is invalid is handled. On RISC OS Classic this merely aborts if memory does not exist. The option consists of two parts, the terminal action, and any additional actions separated by a '+'.

• error: Report an error if an invalid pointer is used.
• hex: Use the hex value of the assigned number.
• abort: Use the value supplied and abort.

The only additional action that can be performed is warning which reports the use to the trace system.

DynamicArea.name_max

Value: 31
Type: int

Configures the maximum length of the names on dynamic area creation. In RISC OS Classic the names were unlimited up to RISC OS 4. At that point they became limited to 31 characters. A value of 0 will make the name unlimited in length.

DynamicArea.name_zero_effect

Value: hex+warning
Type: Regular expression matching: (error|hex)(+warning)?

Configures the way that dynamic area creation with a descriptive name pointer of 0 is handled. On RISC OS Classic this was handled differently. On 3.7 and earlier it would copy zero page. On RISC OS 4 and later it will use the hex string for the number. Prior to RISC OS 4, it would copy zero page. The option consists of two parts, the terminal action, and any additional actions separated by a '+'.

• error: Report an error if a name with value 0 is used.
• hex: Use the hex value of the assigned number.

The only additional action that can be performed is warning which reports the use to the trace system.

DynamicArea.sparsemap_support

Value: none
Type: One of the strings 'none', 'fake'

Configures the way in which sparse mapped dynamic areas are supported. Such areas are not completely supported yet, but may be faked by mapping the entire region and ignoring the requests for mapping in and out regions. The values supported are:

• none: Sparse dynamic areas are rejected at creation.
• fake: Sparse dynamic areas map in the entire region and ignore the map in/out requests.

Configuration group 'DynamicAreaHeap'

DynamicAreaHeap.guard_alloc_value

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

Configures the 32bit value which will be used to fill the guard regions which have been allocated, when guards are enabled by guard_size being set to a non-0 value.

DynamicAreaHeap.guard_free_value

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

Configures the 32bit value which will be used to fill the guard regions which have been freed, when guards are enabled by guard_size being set to a non-0 value.

DynamicAreaHeap.guard_size

Value: 0
Type: int

Configures the size of the Dynamic Area heap guard regions. The guard regions are areas that are allocated alongside the heap blocks, before and after the data. The guard regions are given known values and will be checked when necessary to ensure that the the regions have not been corrupted. The size given by this option is the number of bytes that the region will contain. It must be a multiple of 4.

If the size is 0, no guard region will be used and the heap will function as in RISC OS Classic.

DynamicAreaHeap.tracking_full_checks

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

Controls whether the tracked memory is checked on every call to the Dynamic Area heap. Usually the tracked memory is only checked for the blocks that are referenced by the call, but with this option enabled every call will check all the known blocks.

DynamicAreaHeap.tracking_report_size

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

Configures the size of the reports for tracked memory in Dynamic Area heaps when something is found to be wrong.

Configuration group 'Emulation'

Emulation.cpu_model

Value: default
Type: Select a CPU model, or use 'default' for the default CPU model provided by the emulation

Configures the CPU models that can be used within the emulation. Valid values for the models will vary with the version of the emulation system (Unicorn). The accuracy of the CPU models will depend on their implementation in Unicorn, so not all features may be as expected.

Models supported are:

• default

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 'Executables'

Executables.utility_da

Value: private
Type: One of the strings 'rma', 'private'

Controls where utilities will allocate memory from. On RISC OS Classic, utilities always allocated their memory from the RMA. However, they are small and keeping track of them in a dedicated area would mean that the memory usage in the main RMA could be less variable. This can improve tests, but also might mean that we have better understanding of where memory is used.

The option can be specified as:

• rma: Use RMA as in RISC OS Classic.
• private: Use a private dynamic area.

Executables.utility_da_base

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

Configures the base address of the utility dynamic area. This only applies when the utility_da is set to private.

Executables.utility_da_maxsize

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

Configures the maximum size of the utility dynamic area. This only applies when the utility_da is set to private.

Executables.utility_da_number

Value: 50
Type: int

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 'FanDriver'

FanDriver.accuracy

Value: 10
Type: int

Configures the accuracy of the speed that can be selected by the fan.

FanDriver.capabilities

Value: manual,auto
Type: Comma-separated list of flags from 'manual', 'auto', 'moveable', 'can-fail'

Configures the capabilities of the fan as a comma-separated set of flags. The recognised flags are:

• manual: fan supports manual speed selection.
• auto: fan support automatic speed selection.
• moveable: fan can have its location changed.
• can-fail: fan can report that it has failed.

FanDriver.device

Value: chassis
Type: One of the strings 'cpu', 'gpu', 'memory', 'iocard', 'psu', 'backplane', 'radiator', 'chassis', 'external', 'generic'

Configures the logical device cooled by the fan. Some of the devices have spacial qualifiers which position the device more specifically (see position_lateral, position_longitudinal, and position_vertical). Some devices have different position qualifiers. The recognised devices are:

• CPU
• GPU
• Memory
• IOCard
• PSU
• Backplane
• Radiator
• Chassis
• External
• Generic

FanDriver.max_speed

Value: 0
Type: int

Configures the maximum speed supported by the fan, or 0 for no explicit maximum.

FanDriver.position_lateral

Value: left
Type: One of the strings 'unspecified', 'left', 'middle', 'right'

Configures the logical position of the fan device, in lateral (left-to-right) space. This configuration only applies to devices that are spacially distinguished. The recognised positions are:

• unspecified
• left
• middle
• right

FanDriver.position_longitudinal

Value: rear
Type: One of the strings 'unspecified', 'front', 'middle', 'rear'

Configures the logical position of the fan device, in longitudal (front-to-rear) space. This configuration only applies to devices that are spacially distinguished. The recognised positions are:

• unspecified
• front
• middle
• rear

FanDriver.position_vertical

Value: unspecified
Type: One of the strings 'unspecified', 'lower', 'middle', 'upper'

Configures the logical position of the fan device, in vertical (bottom-to-top) space. This configuration only applies to devices that are spacially distinguished. The recognised positions are:

• unspecified
• lower
• middle
• upper

FanDriver.speeds

Value: 
Type: Comma separated list of speeds, or empty for arbitrary speeds

FanDriver.tech

Value: fan
Type: One of the strings 'fan', 'piezoelectric', 'peltier', 'liquid'

Configures the technology of the cooling device that the 'fan' is provided by. The recognised technology types are:

• fan
• piezoelectric
• peltier
• liquid

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.check_open_files

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

Controls whether open files are checked for file operations and denied if they are.

When this option is enabled it means that:

• Files open for write are checked against any files open for read or write.
• Files open for read are checked against any files open for write.
• File modification operations are checked against files open for read or write.

When enabled, this option matches the behaviour of FileCore file systems by generating an error. When disabled, it matches many network file systems.

Filesystem.close_0_effect

Value: error
Type: One of the strings 'error', 'ignore'

Configures the behaviour when OS_Find 0, 0 (close files on current filesystem) is issued. The available behaviours are:

• error: generate an error that this operation is not allowed.
• ignore: ignores the request.

Filesystem.enumerate_context

Value: identity
Type: 'identity' or one of the other mangler names

Configures how the opaque context values are returned from the OS_GBPB enumeration. The values which can be used include:

• identity: The context value will be the offset in the directory.
• biased: The context value be the offset plus a bias value.
• eor: The context value will have some bits inverted from the offset.
• reverse: The context value will have the bit order reversed.
• descending: The context value will decrement instead of incrementing.
• multiplier: The context value is biased by a value, and increased by multiples of a value, as if it were pointers into memory.

Other forms of offset may be available.

Filesystem.enumerate_corrupts_buffer

Value: no
Type: Regular expression matching: no|increment|random|[0-9a-fA-F]{1,2}

Configures the type of buffer corruption applied to the OS_GBPB enumeration buffer. The buffers supplied may be writen in part or not at all by the filesystem. This configuration ensures that the buffer is written to with data to provoke errors.

The corruption options available are:

• no: Do not corrupt.
• increment: Corrupt with incrementing values.
• random: Randomise every byte.
• <hex>: Write the supplied hex value to every byte.

Filesystem.enumerate_last_chunk

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

Configures how the last chunk of an OS_GBPB enumeration will be returned. The values which can be used are:

• efficient: The final chunk will return a context value signalling that it is the final chunk. This is the most efficient way to return directory entries as it avoids a terminating request for confirmation that this is the last chunk.
• classic: The final chunk will return a context as normal, and a subsequent call is required to confirm that there are no further entries remaining.

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.filetype_strict_range

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

Controls whether OS_FSControl 18 (convert filetype to string) will take a strict view on what a filetype is. The Classic implementation (and PRM) declare the filetype to only be bits 0-11; that is, the other bits are ignored. However, it may be useful to only process values in a valid filetype range, so this option is able to be turned on.

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.load_gencode_synchronises

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

Controls whether OS_File Load operations on Generic Code (&F95) files will cause an implicit OS_SynchroniseCodeAreas. Documentation stated that this would happen from RISC OS 3.71, but it does not appear implemented on RISC OS Classic.

By default we operate as documented, but this can be disabled to simulate behaviour of RISC OS Classic.

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.multifile_unsupported_flags

Value: error
Type: One of the strings 'error', 'warning', 'ignore'

Configures the behaviour of unsupported flags passed to *Wipe, *Copy and *Count (and their OS_FSControl counterparts). Not all of the flags in these multi-file operations are supported, and those which are not can have different behaviour:

• error: generate an error to report the unsupported operation.
• warning: report a warning to the trace log.
• ignore: ignore the unsupported flag (as if it were not set).

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

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

Filesystem.native_directory_mapping

Value: 
Type: Comma separated list of paths to map in form <host-path>=<riscos-path>

Configures a list of mount points for native directories within the native directory tree. The mount points are specified as a comma separated list of mappings from the location on the host filing system to locations in the RISC OS source tree.

These individual mappings take the form:

`<host-path>`=`<riscos-path>`

Filesystem.native_encoding

Value: utf-8
Type: str

Configures the encoding that will be used for the native file system. By default this will be utf-8. If the riscos_encoding is set to identity this configuration will be ignored.

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.
• host: Report the host system's free space (if possible).
• error: Raise an error.

Filesystem.register_filesystem

Value: error
Type: One of the strings 'error', 'warning', 'ignore'

Configures the behaviour of adding and removing filing systems. As filing systems are not supported in the current version of Pyromaniac, this can be used to identify allow some software to work which would otherwise fail due to the lack of the filing systems. Configurable behaviours:

• error: generate an error on registering or removing filing systems.
• warning: generate a warning, but ignore the registration or removal.
• ignore: ignore all registrations and removals.

Filesystem.riscos_encoding

Value: latin-1
Type: str

Configures the encoding that will be used for the native file system. By default this will be latin-1, but can be identity to pass through.

Configuration group 'FilesystemStatistics'

FilesystemStatistics.enable

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

Controls whether the file system tracks statistics about the file operations that have been performed.

Configuration group 'Font'

Font.cache_size

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

Configures the amount of space returned when the font cache size is queried through Font_CacheAddr. There is no cache in RISC OS space, so this is a fixed value.

Font.cache_used

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

Configures the amount of space returned when the used font cache space is queried through Font_CacheAddr. There is no cache in RISC OS space, so this is a fixed value.

Font.enforce_trailing_space_on_matrix

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

Controls whether the font qualifier supplied in a font name is required to include a trailing space. The PRM states that this is required, but the FontManager on RISC OS Classic does not actually enforce this. If this option is enabled, the trailing space will be required. If this option is disabled, it may be present or absent.

Font.free_early

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

Controls whether calls to Font_LoseFont cause the underlying implementation to free the font handle immediately. If this is disabled, the font will be retained in case it is needed again. This is closer to the RISC OS Classic implementation.

Font.handle_max

Value: 255
Type: int

Configures the highest font handle to use. Although the font handle should be considered an opaque 32bit value, values > 256 are not representable in certain interfaces (the VDU sequences and the Wimp_LoadTemplate interfaces are two of those that are limited).

Font.handle_min

Value: 1
Type: int

Configures the lowest font handle to use.

Font.reuse_handles

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

Controls whether handles supplied by the underlying implementation will be reused if they match existing usage. If this is disabled, the counters will only ever show a value of 1, and each call to Font_FindFont will get a new handle.

Configuration group 'FontManager'

FontManager.caret_loops

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

Controls whether the Font_Caret SWI will render the caret with 'loops' at the vertical ends. The PRMs document that this is how FontManager renders the caret. RISC OS Classic does not do this, and so this option is disabled by default.

FontManager.converttoos_rounded

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

Controls whether the Font_ConverttoOS SWI will round the OS coordinates to pixels on the screen. The PRMs does not document that the values converted will be rounded. RISC OS Classic does round the values, and so this option is enabled by default.

FontManager.error_on_kerning

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

Controls whether requesting kerning on a Font_Paint or Font_ScanString SWI call will report an error or not.

FontManager.fontv

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

Controls whether the Font SWIs are dispatched through FontV. Classic FontManager does not support this (disabled in 1992), so by default the feature is disabled. However, as the vector is allocated, it can be enabled. The SWI offset is passed in R8, following the scheme used by DrawV, and should be claimed by handlers of the SWIs by returning with R8 = -1.

Configuration group 'Freeway'

Freeway.local_address

Value: 127.0.0.1
Type: IPv4 address in the form 'a.b.c.d' where each component is 0-255

Configures the IPv4 address which is returned for the locally registered objects. Defaults to localhost.

Configuration group 'GPIO'

GPIO.implementation

Value: null
Type: str

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

• ch341 - CH341 USB to I2C/GPIO board.
• cp2112 - CP2112 USB to I2C/GPIO board.
• mcp2221 - MCP2221 USB to IIC/GPIO/ADC/DAC board.
• mcp23008 - MCP23008 I2C to 8 port GPIO interface. Uses standard IIC module.
• mcp23017 - MCP23008 I2C to GPIO interface. Uses standard IIC module.
• null - Fails everything.
• pcf8574 - PCF8574 I2C to 8 port GPIO interface. Uses standard IIC module.
• pcf8575 - PCF8575 I2C to 16 port GPIO interface. Uses standard IIC module.
• pigpio - Raspberry Pi GPIO interface. Uses pigpio Python module. May be over the network.
• rpigpio - Raspberry Pi GPIO interface. Uses RPi.GPIO Python module.
• static - Returns static values, and ignores outputs.
• wxwidgets - WxWidgets display/inputs.

Configuration group 'GPIOMCP23008'

GPIOMCP23008.i2c_address

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

Configures the the I2C address of the MCP23008. By default this is &20, but usually the address can be selected by changing jumpers or bridging contacts. The address is in I2C format, without the W/R bit (ie 7 bit value).

Configuration group 'GPIOMCP23017'

GPIOMCP23017.i2c_address

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

Configures the the I2C address of the MCP23017. By default this is &20, but usually the address can be selected by changing jumpers or bridging contacts. The address is in I2C format, without the W/R bit (ie 7 bit value).

Configuration group 'GPIOPCF8574'

GPIOPCF8574.i2c_address

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

Configures the I2C address of the PCF8574/PCF8575 device. By default this is &20, but usually the address can be selected by changing jumpers or bridging contacts. The address is in I2C format, without the W/R bit (ie 7 bit value).

Configuration group 'GPIOStatic'

GPIOStatic.pin_constants

Value: 1
Type: List of constants for each pin in the GPIO interface

Configures the values returned by each pin provided by the GPIO module. This option is a string of 0 and 1 values for each pin.

GPIOStatic.pin_count

Value: 1
Type: int

Configures the number of pins reported by the GPIO module.

Configuration group 'GPIOWx'

GPIOWx.layout

Value: hgrid
Type: One of the strings 'vertical', 'vgrid', 'hgrid'

Configures the layout of the pins in the WxWidgets window. Options are:

• vertical: a single vertical column of pins
• vgrid: lays out a grid of pins, going down the window first, with a configurable number of rows in layout_wrap.
• hgrid: lays out a grid of pins, going across the window first, with a configurable number of columns in layout_wrap.

GPIOWx.layout_wrap

Value: 4
Type: int

Configures the number of rows or columns that will be used to wrap the display of the pins in the WxWidgets window.

GPIOWx.pin_count

Value: 8
Type: int

Configures the number of pins reported by the GPIO module.

Configuration group 'GSTrans'

GSTrans.bad_number_effect

Value: 8bit+warn
Type: Regular expression matching: (ignore|8bit|error)(+warn)?

Configures how the GSTrans operations will handle cases where a number is specified within <>, which is outside the range 0-255. Under RISC OS Classic this is generally handled by truncating to 8bit (except with OS_GSInit/OS_GSRead). However, it is possible to treat them differently. There are 3 options for the handling of bad numbers:

• ignore: Ignores any invalid numbers, dropping them from the result string.
• 8bit: Truncates the numbers to 8bit values. This is the behaviour of RISC OS Classic.
• error: Reports an error when an invalid value is encountered.

Each option can be suffixed with +warn, which will generate a warning through the trace system.

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.cursorflash_enable

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

Controls whether the cursor will flash on and off. These updates may be more expensive than is desirable, and may introduce a non-determinancy to the system. When enabled they install a ticker which runs every centisecond, which will slow the system.

Options are:

• no: disables the flashing cursor
• auto: enables the flashing cursor when the UI requests it
• force: enables the flashing cursor even when the UI does not request it

Graphics.cursorflash_rate

Value: 32
Type: int

Configures how fast the regular cursor will flash, in centiseconds. RISC OS Classic used a rate that was tied to the VSync system of 16 VSyncs. RISC OS Pyromaniac does not have a VSync control for the cursor flash; instead it's based on the clock. The rate given is measured in centiseconds, and the default of 32 will approximate the rate for a 50Hz display.

Graphics.font_fake

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

Controls whether the fonts returned by the FontManager are entirely fake. When this option is enabled, the standard RISC OS font names are returned but these fonts will not do anything.

Graphics.implementation

Value: null
Type: str

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

• bbcbasic - Generates BBC BASIC equivalent to the operations performed.
• cairo - Bitmap and vector based graphics implementation using Cairo.
• framedevice - Generic Cairo based frame buffer device. See graphicsframedevice.implementations for individual implementations.
• gtk - GTK Cairo graphics implementation. Provides a windowed application in the host.
• null - Ignores graphics operations.
• vnc - VNC Cairo graphics implementation. Accessible over the VNC screen sharing protocol.
• wx - WX Cairo graphics implementation. Provides a windowed application in the host.

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.polyhline_enable

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

Controls whether the PolyHLine address VDU variable is returned by the system. This variable was introduced in RISC OS Select, so isn't guaranteed to be present. When disabled, the variable will return as if it is not present.

Graphics.screen_banks

Value: 2
Type: int

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

Graphics.vsync_enabled

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

Controls whether the VSync event is triggered by the system through the IRQs. If this option is disabled, the VSync event will never be triggered. This is the default as processing the VSync is not normally required for testing most software.

Graphics.vsync_rate

Value: 20
Type: float

Configures how regularly the vsync event is triggered. This also affects the rate that videos will be recorded by the Cairo system.

Configuration group 'GraphicsBBCBasic'

GraphicsBBCBasic.save_filename

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

Configures the native filename to which the graphics screen will be saved on exit. Usually it would be suffixed by ,fd1 to indicate BBC BASIC detokenised text. If the option is empty, the output will be to stdout.

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.fonts_designer_bounds

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

Controls whether the font size returned by Font_ReadInfo will use the font designer's bounds for the characters. When this option is enabled, the font bounds returned by the SWI will cover the font designer's intent for the font in addition to the sizes of typical characters. When disabled, the font bounds returned by the SWI will only use the size of typical characts.

This option is disabled by default because most fonts will include the size of double-width characters, which will increase the size of the font horizontally beyond the usual expectations of RISC OS applications.

GraphicsCairo.fonts_fontconfig

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

Controls whether the FontManager will enumerate fonts from the system installed 'font-config' tool to find fonts which can be used. These fonts will be enumerated and mapped to RISC OS font names.

GraphicsCairo.fonts_fontconfig_allow

Value: 
Type: listlower

Configures the fonts that will be allowed to be returned by the FontConfig system to RISC OS, using the RISC OS names to filter the fonts. The names may be wildcarded with * and ? to match families, etc. If this option is set, and no value is used for the fonts_fontconfig_deny option, only the fonts matching this specification will be allowed. If it is used in conjunction with the fonts_fontconfig_deny option, the allow takes precedence.

This option, together with fonts_fontconfig_deny, can reduce the fonts that are seen by RISC OS from the host system. This may make enumeration faster, or avoid problems with certain fonts.

GraphicsCairo.fonts_fontconfig_deny

Value: 
Type: listlower

Configures the fonts that will not be allowed to be returned by the FontConfig system to RISC OS, using the RISC OS names to filter the fonts. The names may be wildcarded with * and ? to match families, etc.

This option, together with fonts_fontconfig_allow, can reduce the fonts that are seen by RISC OS from the host system. This may make enumeration faster, or avoid problems with certain fonts.

GraphicsCairo.fonts_standard

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

Configures whether the FontManager will use the standard serif, sans-serif and monospace for Trinity, Homerton and Corpus fonts. When this option is enabled, these RISC OS font families will be enumerated and may be selected in their standard variants.

GraphicsCairo.fonts_standard_synthetic

Value: on
Type: Angle as default, synthetic, or degrees clockwise as a decimal

Configures whether the FontManager's handling of the standard fonts will synthesise oblique fonts. It can take one of 3 values:

• off: The standard fonts will use the italic variant determined by Cairo.
• on: The standard fonts will use a synthetic oblique using a standard angle (12.000 degrees by default).
• decimal value: The standard fonts will use a synthetic oblique using the given angle.

This option is provided because on some platforms, in some implementations, the sans-serif font has been seen to not select an italic font. Thus, we can force the use of such sans-serif fonts in that case.

GraphicsCairo.jpeg_transformations

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

Controls whether JPEG_PlotTransformed can render arbitrary transformed images. In RISC OS Classic, this is not possible, so applications may not expect it to work. Similarly, anyone using the feature may find that they want to know how the application works without the transformations. This switch allows them to be turned off.

GraphicsCairo.save_filename

Value: image.png
Type: Regular expression matching: ^.*\.(png|pdf|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.tile_acceleration

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

Controls whether tile plotting uses the accelerated rendering provided by the Cairo rendering system, or falls back to the baseline version. When this option is enabled, rendering will be faster, but it may exhibit differences in positioning compared to the base implementation.

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.

If the resolution is changed, a new video will be started, with a script file named ffmpeg_concat_#.txt. As frames with different resolutions may need to be processed separately to ensure that they render properly, these must be separate streams.

GraphicsCairo.video_pointer

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

Controls whether the pointer is recorded on to the frames of the video.

Configuration group 'GraphicsFrameDevice'

GraphicsFrameDevice.implementation

Value: null
Type: str

Configures the implementation which will be used to provide the frame device system. Implementations may be provided for different physical hardware or virtual frame buffers. The implementations provided are:

• ansi - A 1 bit per pixel console display of the frame buffer, using ANSI colours.
• console - A 1 bit per pixel console display of the frame buffer.
• dreamcheeky - A LED message display using 21 by 7 pixels.
• null - Dummy frame device which throws away its output.
• ssd1306 - An OLED frame device connected to IIC.
• turingsmartscreen - An 3.5" LCD screen connected by USB.

GraphicsFrameDevice.last_frame

Value: clear
Type: One of the strings 'none', 'clear', 'flush'

Controls the behaviour on finalisation for the last frame. By default the frame display is cleared, but it may be useful to flush the final frame to the frame device. This can be useful if it is necessary to see the final frame for testing, or to leave the device in a known state.

The behaviour of the frame device before finalising can be:

• none: no special behaviour.
• clear: clear the device.
• flush: flush the final frame.

GraphicsFrameDevice.redraw_rate

Value: 10
Type: float

Configures the frame rate at which the frame device display 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. In general, the frame devices will be slow, so by default this has a low frame rate.

GraphicsFrameDevice.redraw_rate_mode

Value: limited
Type: One of the strings 'limited', 'fixed'

Configures the manner in which redraw updates are issued to the frame device. There are two modes:

• fixed: Redraws will keep to the fixed redraw rate specified by the  redraw_rate. There may be missed redraws if there is nothing changed between the redraw intervals.
• limited: Redraws will happen immediately there is something to be redrawn, but never more often than the frame rate specified. Thi means that updates are visible as soon as there is a change, but the rate will be limited if there are lots of changes so that we do not spend all the time redrawing.

Configuration group 'GraphicsFrameDeviceANSI'

GraphicsFrameDeviceANSI.size

Value: 128x64
Type: Dimensions in the form: <width>x<height> or <size>

Configures the size of the console frame device in pixels.

Configuration group 'GraphicsFrameDeviceConsole'

GraphicsFrameDeviceConsole.size

Value: 128x64
Type: Dimensions in the form: <width>x<height> or <size>

Configures the size of the console frame device in pixels.

Configuration group 'GraphicsFrameDeviceSSD1306'

GraphicsFrameDeviceSSD1306.fliph

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

Controls whether the output is flipped horizontally, with the left most pixel appearing on the right of the display. If the display is turned upside down, it will usually be necessary to set both the options for fliph and flipv.

GraphicsFrameDeviceSSD1306.flipv

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

Controls whether the output is flipped vertically, with the top most pixel appearing on the bottom of the display. If the display is turned upside down, it will usually be necessary to set both the options for fliph and flipv.

GraphicsFrameDeviceSSD1306.invert

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

Controls whether the display is inverted, with black pixels being lit and other pixels being dark.

GraphicsFrameDeviceSSD1306.rotate

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

Controls whether the output is rotated through 90 degrees. Depending on the orientation of the display, it may be necessary to set the fliph or flipv options.

GraphicsFrameDeviceSSD1306.size

Value: 128x64
Type: Dimensions in the form: <width>x<height> or <size>

Configures the size of the console frame device in pixels. Only certain resolutions are supported:

• 128x64
• 128x32
• 96x16

Configuration group 'GraphicsFrameDeviceTuringSmartScreen'

GraphicsFrameDeviceTuringSmartScreen.fliph

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

Controls whether the output is flipped horizontally, with the left most pixel appearing on the right of the display. If the display is turned upside down, it will usually be necessary to set both the options for fliph and flipv.

GraphicsFrameDeviceTuringSmartScreen.flipv

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

Controls whether the output is flipped vertically, with the top most pixel appearing on the bottom of the display. If the display is turned upside down, it will usually be necessary to set both the options for fliph and flipv.

GraphicsFrameDeviceTuringSmartScreen.rotate

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

Controls whether the output is rotated through 90 degrees. Depending on the orientation of the display, it may be necessary to set the fliph or flipv options.

GraphicsFrameDeviceTuringSmartScreen.serial_device

Value: hwgrep://usbmodem
Type: str

Configures the serial device used for the data from the USB device. This is in the form of a PySerial URL. For example, you might use hwgrep://usbserial to select the first USB serial device.

Configuration group 'GraphicsUI'

GraphicsUI.border_colour

Value: riscos
Type: Hexadecimal colour in the form &RRGGBB, or 'riscos' to use RISC OS defined colour

Configures the colour of the border around the RISC OS screen, between the screen and the window frame. By default, when set to 'riscos', this is configured by RISC OS, but can be overridden by setting an explicit colour in this option.

RISC OS Pyromaniac defaults the border dark grey, 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.free_link_is_heap_offset

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

Controls whether the free link within the heap is an offset from the start of the heap, or an offset from the block. In RISC OS Classic, the free link within the heap is relative to the free block's base, not relative to the base of the heap. The documentation in the PRM implies that it is an offset relative to the heap base, and this is a more logical implementation.

When this option is enabled, the free link will be relative to the heap base. When this option is disabled, the free link will be relative to the free block.

This option cannot be reliably changed whilst the system is running.

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.

Heap.rounding

Value: 8
Type: int

Configures the rounding multiple used for blocks allocated into the heap. The PRM declares that this rounding is 8 bytes. However, it could be larger than this if you wished to provide less granular allocations (which may improve fragmentation).

Configuration group 'Hourglass'

Hourglass.implementation

Value: console
Type: str

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

• console - Writes hourglass status to the host console.
• null - Ignores all hourglass operations.
• pointer - Change the pointer when the hourglass is changing.
• vdu - Writes hourglass status to the VDU stream.

Configuration group 'IIC'

IIC.implementation

Value: internal
Type: str

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

• ch341 - CH341 USB to I2C/GPIO board.
• cp2112 - CP2112 USB to I2C/GPIO board.
• internal - Internal IIC implementation, using registered Python IIC devices.
• mcp2221 - MCP2221 USB to IIC/GPIO/ADC/DAC board.
• null - Ignores writes, returns 0s for reads.
• pigpio - Raspberry Pi GPIO interface. Uses pigpio Python module. May be over the network.

Configuration group 'IICInternal'

IICInternal.devices

Value: pcf8583
Type: str

Configures the devices which will be provided by the IIC internal implementation. Many internal devices may be available and can be mapped to arbitrary addresses with different configurations.

Configuration option:

{`<device>`[=`<hex-iic-address>`][:{`<option>`=`<value>`,}*];}*

Examples:

• pcf8583: configures the PCF8583 device, at its default address
• pcf8583=A0: configures the PCF8583 device, at an explicit address
• pcf8583;pca9555: two devices, at their default addresses
• pca9555=a0:option1=value,option2=value: one device, with an address, and configuration values.

Configuration group 'InetServices'

InetServices.use_host_services

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

Controls whether the InetServices module will use the service database from the host system to resolve port numbers.

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.keyboard_id

Value: 1
Type: int

Configures the ID used by the keyboard system when returning the keyboard identifier. Although the keyboard system is implemented very differently by RISC OS Pyromaniac, this identifier can be configured to an arbitrary value.

Currently defined IDs are:

• 1: Standard Archimedes keyboard (legacy)
• 2: PC external keyboard, or A4 (Acorn portable) internal keyboard
• 3: RCMM handset (NCOS)
• 4: Pandora keyboard/controller
• 255: No keyboard recognised

Input.keypress_enable

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

Controls whether key press events are handled by the system. The key press 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.keypress_event_enable

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

Controls whether Event_Keyboard event is generated by the system. The key press events handled by KeyV can trigger the Event_Keyboard event when this is enabled. As the event is rarely used and may slow the system down, it may be disabled.

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_completion

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

Controls whether the native readline interface performs tab completion. When this option is enabled, *-commands, system variables and filenames will attempt to be completed when the tab key is pressed.

Input.readline_native_encoding

Value: utf-8
Type: str

Configures the encoding that's used for native input. This will almost always be utf-8 on modern systems, but could be set to identity to pass through directly.

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 'International'

International.country

Value: 1
Type: int

Configures the country number used by the International module.

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.errors_0_based

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

Controls whether error numbers are returned based at 0. Under RISC OS versions up to RISC OS Select, the error numbers are returned based at 0. In RISC OS 5, and with Internet 7, the error numbers are based at &20E00.

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.hostname

Value: host
Type: Regular expression matching: none|host|random|[0-9]+|[a-z][a-z0-9]+

Configures the hostname that will be used for the system. By default this will be the host system's hostname, but it can be controlled here. Magic hostname strings will trigger special behaviour:

• none: disables the hostname
• host: selects the host's hostname
• random: selects a random hostname
• number: selects a hostname from the random set
• others: explicitly sets the hostname

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_banner_processor

Value: auto
Type: str

Configures the processor name that is passed to the start up banner when used. The processor name may either be a code name for the processor, an empty string to not pass a processor name to the service, or the string 'auto' to read the processor model from Unicorn. If the default emulation is used, the processor model will be omitted.

Under RISC OS Select the following values were used: 600, 610, 700, 710, 810, SA110, 7500, 7500FE, SA110_2.

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 limiting 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 'KernelDebug'

KernelDebug.implementation

Value: null
Type: str

Configures the implementation that will be used for the KernelDebug interfaces.

• null - No output ever written. No input will be returned.
• socket - Connects to a TCP socket and directs byte data there.
• stderr - Output written to host stderr. No input will be returned.
• stdout - Output written to host stdout. No input will be returned.

Configuration group 'KernelDebugSocket'

KernelDebugSocket.destination

Value: localhost:9000
Type: str

Configures the destination to which the socket will be connected when used. The destination should be in the form <hostname>:<port>.

Configuration group 'LegacyBBC'

LegacyBBC.enable

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

Controls whether the LegacyBBC module will initialise or not. This may be useful to identify behaviour which is BBC specific and would fail if we stopped pretending to be a BBC.

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.

LegacyBBC.warnings

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

Controls whether the LegacyBBC module will report warnings through the trace log when its interfaces are triggered. This may be useful to identify behaviour which is BBC specific and would fail if we stopped pretending to be a BBC.

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 'MCP2221'

MCP2221.device_number

Value: 0
Type: int

Configures the device number that is used for the MCP 2221 interface. If multiple MCP 2221 interfaces are connected, only the one configured device given can be controlled.

MCP2221.i2c_speed_kbits

Value: 100
Type: int

Configures the speed that the I2C will communicate at with in kbit per second. By default this will be 100 kbit/s, which is the standard speed for I2C.

MCP2221.reset_delay

Value: 1.0
Type: float

Configures the delay when the MCP 2221 is reset in seconds.

MCP2221.reset_on_use

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

Controls whether the MCP 2221 will be reset when it is first used, or assumed to be in a working state.

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: 1 M
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: 1 M
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: 1 M
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.overflow_error

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

Controls whether MessageTrans_Lookup returns an error on buffer overflow. When enabled, a Buffer Overflow error is returned. When disabled, the translated string is returned truncated at the buffer length. The classic MessageTrans never returns an overflow error, always truncating, although this is not documented.

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 'Modes'

Modes.numbered_modes

Value: 
Type: {<modenum>:{<variable>=<value>,}*;}*

Configures extra numbered modes that may be used by the guest system.

Mode definition: <number>:<parameters>{;<mode definition>}*

Parameters: <variable>=<value>{,<parameters>}*

Variables may be a number or a named variable:

• base: Pseudo variable name; the base mode, which must be supplied
• width: screen width in pixels
• height: screen height in pixels
• textwidth: screen width in characters
• textheight: screen height in characters
• xeig: x eigenfactor
• yeig: y eigenfactor
• ncolours: number of colours
• log2bpp: log2 bits per pixel

Configuration group 'Modules'

Modules.architecture_flag

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

Configures whether the initialisation offset for modules allow for the 'architecture' flag. When enabled, bit 30 is allowed to be set. This flag indicates that the module flags contain an 'architecture' field, which indicates what architecture the module is for. When disabled, if bit 30 is set, the module will be rejected by the header check (this is in line with RISC OS Classic).

The architecture field in the flags will never be checked on RISC OS Classic.

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 according to the configuration of backingfile_write.

NVRAM.backingfile_write

Value: on-exit
Type: One of the strings 'never', 'always', 'on-exit'

Configures when the backing file used for the NVRAM configuration data, will be written to disc. The options available are:

• never: Never writes the backing file to disc (the file is only used on initialisation).
• always: Writes the backing file after every change.
• on-exit: Writes the backing file when the system finalises.

NVRAM.format

Value: auto
Type: One of the strings 'capstone', 'riscos'

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.implementation

Value: riscos
Type: str

Configures the implementation to use for the OS_Confirm system. This allows the way in which the confirmation is managed to be changed The current implementations that are provided are:

• escape - Always reports the Escape operation.
• no - Always reports the negative operation.
• riscos - Reports using RISC OS messages / pointer shape.
• wxwidgets - Reports using the WxWidgets windows in the host applications.
• yes - Always reports the positive operation.

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.

OSMemory.controller_presence_support

Value: zero
Type: One of the strings 'error', 'zero'

Configures how OS_Memory 9 is supported. The options for this configuration are:

• error: calls to the SWIs will generate errors.
• zero: calls to the SWIs will report 0 for all devices.

In RISC OS Select this was updated to report errors for absent devices. RISC OS 3.5, 4 and 5 report addresses of 0 when the devices are absent.

OSMemory.physical_table_support

Value: error
Type: One of the strings 'error', 'zero', 'small-empty', 'small-populated'

Configures how OS_Memory 6 and OS_Memory 7 are supported. The options for this configuration are:

• error: calls to the SWIs will generate errors.
• zero: calls to the SWIs will report 0 pages available.
• small-empty: calls to the SWI will report a small table with no pages present.
• small-populated: calls to the SWI will report a small table with some example pages present, none of which will be available for allocation.

Configuration group 'OSPlatformFeatures'

OSPlatformFeatures.codefeatures

Value: synchronisecodeareasrequired,hardwarevectorsneed32bitmode,pcstoresplus8,dataabortsearly,operatingsystemis32bit,26bitunavailable,highvectors,nophysicalpages,invalidreasonsaresafe
Type: Comma-separated list of flags from 'synchronisecodeareasrequired', 'irqtriggernecessary', 'hardwarevectorsneed32bitmode', 'pcstoresplus8', 'dataabortsearly', 'cpuhasseparatecaches', 'operatingsystemis32bit', '26bitunavailable', 'cpuhasmextensions', 'cpusupportsthumb', 'cpuhaseextensions', 'cpuhasnoswp', 'cpuhasldrstrex', 'cpuhasclrex', 'cannotdisabledcache', 'cpuextendedsmallpages', 'cpuhasnodwb', 'cpuhasbrokenaborts', 'cpuisxscale', 'xscalejtag', 'highvectors', 'largephysicalram', 'nophysicalpages', 'invalidreasonsaresafe'

Configures the code features returned by OS_PlatformFeatures 0. These are a bit mask of the many features that may be returned by the system.

Feature flags which can be set:

• Bit 0: SynchroniseCodeAreasRequired
• Bit 1: IRQTriggerNecessary
• Bit 2: HardwareVectorsNeed32bitMode
• Bit 3: PCStoresPlus8
• Bit 4: DataAbortsEarly
• Bit 5: CPUHasSeparateCaches
• Bit 6: OperatingSystemIs32Bit
• Bit 7: 26BitUnavailable
• Bit 8: CPUHasMExtensions
• Bit 9: CPUSupportsThumb
• Bit 10: CPUHasEExtensions
• Bit 11: CPUHasNoSWP
• Bit 12: CPUHasLDRSTREX
• Bit 13: CPUHasCLREX
• Bit 14: CannotDisableDCache
• Bit 15: CPUExtendedSmallPages
• Bit 16: CPUHasNoDWB
• Bit 17: CPUHasBrokenAborts
• Bit 18: CPUIsXScale
• Bit 19: XScaleJTAG
• Bit 20: HighVectors
• Bit 21: LargePhysicalRAM
• Bit 22: NoPhysicalPages
• Bit 31: InvalidReasonsAreSafe

Configuration group 'OSPointer'

OSPointer.device_type

Value: 3
Type: int

Configures the device type returned by the OS_Pointer interface. Any value may be used, but the registered types are:

0   PointerDevice_Quadrature
1   PointerDevice_Microsoft
2   PointerDevice_MouseSystems
3   PointerDevice_PS2
4   PointerDevice_Ethernet
5   PointerDevice_RCMM
6   PointerDevice_Remote
7   PointerDevice_USB
8   PointerDevice_Wheel
10  PointerDevice_QuadMouseSTD
13  PointerDevice_Zytouch

Configuration group 'OSReadSysInfo'

OSReadSysInfo.kernel_values_error

Value: no
Type: One of the strings 'no', 'unknown', 'yes'

Controls whether the OS_ReadSysInfo 6 call returns errors. This SWI was defined to report 0 for unknown values in RISC OS 3, but as a SWI it could return an error at any time. Prior to RISC OS 3 it returned errors for all requests. As this call is intended only for components that need to collude with the Kernel, it should not usually be used and cases which do use this information should be replaced with other calls where they exist.

The option can be set to:

• no: Never return errors (RISC OS 3 behaviour).
• unknown: Return errors when request is unknown.
• yes: Always return errors (RISC OS 2 behaviour).

Configuration group 'OSWrite'

OSWrite.bad_address_effect

Value: abort
Type: One of the strings 'abort', 'ignore', 'print', 'error', 'trace', 'trace+abort', 'trace+print', 'trace+error'

Configures the way that OS_Write0, OS_WriteN and OS_PrettyPrint interfaces handle accesses to invalid memory. The options are:

• abort: Generate a data abort (as on RISC OS Classic).
• ignore: Return without error.
• print: Print a message about the bad memory.
• error: Return an error.
• trace: Report a warning through the trace system.
• trace+abort: Report a warning through the trace system, then abort.
• trace+print: Report a warning through the trace system, then print a message.
• trace+error: Report a warning through the trace system, then error.

OSWrite.writen_max

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

Configures the longest output that OS_WriteN can use before triggering an error.

OSWrite.writen_max_effect

Value: trace+error
Type: One of the strings 'trace', 'error'

Configures how exceeding the maximum length for OS_WriteN is handled. Options are:

• trace: Reports a warning through the trace system.
• error: Generates an error.
• trace+error: Reports a warning through the trace system, then error.

Configuration group 'OwnerBanner'

OwnerBanner.enable

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

Controls whether the OwnerBanner module will initialise or not.

Configuration group 'PIGPIO'

PIGPIO.bus

Value: 1
Type: int

Configures which bus the pigpio will connect to. By default this is 1 for the first bus on the system.

PIGPIO.remote

Value: 
Type: str

Configures the name of the remote system to which pigpio will connect. By default this is empty, indicating that the connection will be to the local system. It may be set to a host name to connect to a remote pigpiod server. A port may be appended to the hostname, in the form <hostname>:<port>.

Configuration group 'Parallel'

Parallel.hardware_address

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

Configures the value which will be returned by the Parallel_HardwareAddress SWI, as a hexadecimal number, or 'error' to report an error. The API expects to return 0 on non-IOEB machines, so this is the default.

Parallel.implementation

Value: null
Type: str

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

• file - Writes to a native file using the configuration ParallelFile.native_file_output, and reads from a native file using the configuration ParallelFile.native_file_input.
• null - Ignores all parallel operations.
• socket - Connects to a TCP socket and directs byte data there.

Configuration group 'ParallelFile'

ParallelFile.native_file_input

Value: parallel.dat
Type: str

Configures the native file which is read from by the file implementation.

ParallelFile.native_file_output

Value: parallel.dat
Type: str

Configures the native file which is written to by the file implementation.

Configuration group 'ParallelSocket'

ParallelSocket.destination

Value: localhost:9000
Type: str

Configures the destination to which the socket will be connected when used. The destination should be in the form <hostname>:<port>.

Configuration group 'PathUtils'

PathUtils.enumerate_context

Value: identity
Type: 'identity' or one of the other mangler names

Configures how the opaque context values are returned from the PathUtils enumeration. The values which can be used include:

• identity: The context value will be the counter from 1.
• biased: The context value be the offset plus a bias value.
• eor: The context value will have some bits inverted from the offset.
• reverse: The context value will have the bit order reversed.
• descending: The context value will decrement instead of incrementing.
• multiplier: The context value is biased by a value, and increased by multiples of a value, as if it were pointers into memory.

Other forms of offset may be available.

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 CPU implementation does not support rotated loads in the same way as it did in earlier ARM systems.

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 CPU implementation does not support unaligned memory accesses in the same way as it did in earlier ARM systems.

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.

Pointer.mode_change_effect

Value: centre
Type: One of the strings 'origin', 'centre', 'null'

Configures the effect of a mode change on the mouse position. RISC OS Classic resets the mouse position to the origin. RISC OS Pyromaniac defaults to setting the position to the centre of the screen.

The effects which may be used are:

• origin: Place the mouse at the origin (0, 0).
• centre: Place the mouse at the centre of the screen.
• null: Do not change the mouse position.

Pointer.scrollwheel_enable

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

Controls whether the scrollwheel events are supported and passed through the system.

Configuration group 'Portable'

Portable.implementation

Value: psutil
Type: str

Configures the implementation to use for the Portable module's control. The following implementations are provided:

• null - Ignores all portable operations.
• osx - Uses the OSX commands to report information about the system.
• psutil - PSUtil calls the PSUtil python module for its information.

Portable.sensor_bmu_temperature

Value: 35.0
Type: List of sensor value for each unit in Celcius

Configures the temperature returned by Portable_ReadSensors for the BMU temperature. The temperature is supplied in units of degrees Celcius, and is converted internally to units of 0.1 Kelvin. It is a list of temperatures, which are returned for each unit.

Portable.sensor_cpu_temperature

Value: 65.0
Type: List of sensor value for each unit in Celcius

Configures the temperature returned by Portable_ReadSensors for the CPU temperature. The temperature is supplied in units of degrees Celcius, and is converted internally to units of 0.1 Kelvin. It is a list of temperatures, which are returned for each unit.

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: 1 K
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 system 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 closest 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 'PyromaniacGit'

PyromaniacGit.askpass_enable

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

Controls whether the git client supports username and password requests. These are required if credentials are required to access a repository. The host git requires special handling to request the user name and password. This could cause problems for some clients, so it is possible to disable the support for requesting these details.

PyromaniacGit.command_allow

Value: 
Type: listlower

Configures the list of commands that we allow to be used by the PyromaniacGit module, as a comma separated list. If empty, all commands are implicitly allowed. If a list is configured, and a command which is not in the list is used, it will generate an error.

PyromaniacGit.command_deny

Value: 
Type: listlower

Configures the list of commands that we do not allow to be used by the PyromaniacGit module, as a comma separated list. If empty, all commands are implicitly allowed. If a named command is used, it will generate an error.

PyromaniacGit.config_file

Value: /dev/null
Type: str

Configures the configuration file which will be used for git operations. By default this is set to /dev/null to prevent any user configuration from leaking into the guest.

PyromaniacGit.credential_store_filename

Value: <Git$Credentials$Store>
Type: str

Configures where credentials will be stored on the RISC OS filesystem. This option provides a direct configuration of the credential.helper for the store helper. The filename is in the RISC OS form, and defaults to <Git$Credentials$Store> to allow it to be configured within RISC OS.

PyromaniacGit.credential_store_native_filename

Value: 
Type: str

Configures where credentials will be stored on the native filesystem. This option provides a direct configuration of the credential.helper for the store helper. The filename is in the native form.

PyromaniacGit.default_email

Value: riscosuser@example.com
Type: str

Configures the default email address which will be used for Git operations.

PyromaniacGit.default_name

Value: RISC OS user
Type: str

Configures the default user name which will be used for Git operations.

PyromaniacGit.editor_enable

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

Controls whether the git client supports calling back to the RISC OS system to request an editor be launched. The editor will use the configured text editor implementation.

PyromaniacGit.enable

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

Controls whether the PyromanicGit module is able to function. If this is disabled, the module will not initialise.

PyromaniacGit.git_command

Value: git
Type: str

Configures the git command which will be used on the host system.

PyromaniacGit.hide_host_config

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

Controls whether the host configuration for Git will be hidden from the invocations of the host git tool. When this option is enabled, the ~/.gitconfig and $XDG_CONFIG_HOME/git/config files will not be used. This isolates the RISC OS system from the host environment. When this option is disabled, the invocations of the git tool will be able to access these files. The configuration in these files may invoke other host tools, or may allow the use of aliases to access commands which are undesirable to the RISC OS system.

PyromaniacGit.language

Value: en
Type: str

Configures the language used for git command output. By default this is 'en' for English. However, it can be changed to override the output format.

Configuration group 'PyromaniacModule'

PyromaniacModule.config_allow

Value: 
Type: listlower

Configures which configuration groups are allowed to be configured by the *PyromaniacConfig 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 *PyromaniacConfig 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 *PyromaniacHostCommand 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 *PyromaniacHostCommand is allowed to be used. If this is disabled, the command will return an error.

PyromaniacModule.hostcommand_input

Value: no
Type: One of the strings 'no', 'yes', 'fkeys'

Controls whether the *PyromaniacHostCommand input is taken from the RISC OS input system or not. This option can take different values for the input control:

• no: no input is passed to the command.
• yes: RISC OS input is passed to the command.
• fkeys: RISC OS input is passed to the command, with function keys and cursors converted to ANSI input sequences.

PyromaniacModule.hostcommand_output_encoding

Value: utf-8
Type: str

Configures what encoding the output from *PyromaniacHostCommand 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 *PyromaniacHostCommand 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.hostcommand_term

Value: vt100
Type: str

Configures what TERM setting will be used within the commands invoked by *PyromaniacHostCommand. By default this is vt100, which is probably the most supported terminal type, although the RISC OS Pyromaniac support for some of the VT100 features is limited. You may find that vt52 is more effective for some tools.

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.urlcopy_enable

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

Controls whether the *URLCopy command is supported or not.

PyromaniacModule.urlcopy_protocol_allow

Value: 
Type: listlower

Configures the protocols that are allowed to be accessed with the *URLCopy command. If the list is empty, all protocols are allowed.

PyromaniacModule.urlcopy_protocol_deny

Value: 
Type: listlower

Configures the protocols that are not allowed to be accessed with the *URLCopy command. If the list is empty, all protocols are allowed.

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 'PyromaniacWimpDebug'

The PyromaniacWimpDebug module is an experimental mechanism for reporting on the state of Wimp operations through the wimp messages. The module tracks tasks and reports on the messages through FilterManager.

PyromaniacWimpDebug.enable

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

Controls whether the PyromaniacWimpDebug module is able to function. If this option is disabled, the module will not start.

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: Sun,11 Feb 2024.13:06:04

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 'RTCHWDS1307'

RTCHWDS1307.enable

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

Controls whether the RTC module which uses the DS1307 I2C device is enabled or not. By default this is disabled as we do not provide such a device within RISC OS Pyromaniac.

RTCHWDS1307.i2c_address

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

Configures the the I2C address of the DS1307. By default this is &68, but usually the address can be selected by changing jumpers or bridging contacts. The address is in I2C format, without the W/R bit (ie 7 bit value).

Configuration group 'RTCHWDS3231'

RTCHWDS3231.enable

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

Controls whether the RTC module which uses the DS3231 I2C device is enabled or not. By default this is disabled as we do not provide such a device within RISC OS Pyromaniac.

RTCHWDS3231.i2c_address

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

Configures the the I2C address of the DS3231. By default this is &68, but usually the address can be selected by changing jumpers or bridging contacts. The address is in I2C format, without the W/R bit (ie 7 bit value).

Configuration group 'RTCHWPCF8563'

RTCHWPCF8563.enable

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

Controls whether the RTC module which uses the PCF8563 I2C device is enabled or not. By default this is disabled as we do not provide such a device within RISC OS Pyromaniac.

RTCHWPCF8563.i2c_address

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

Configures the the I2C address of the PCF8563. By default this is &51, but usually the address can be selected by changing jumpers or bridging contacts. The address is in I2C format, without the W/R bit (ie 7 bit value).

Configuration group 'RTCHWPCF8583'

RTCHWPCF8583.enable

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

Controls whether the RTC module which uses the PCF8583 I2C device is enabled or not. By default this is disabled as we do not provide such a device within RISC OS Pyromaniac.

RTCHWPCF8583.i2c_address

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

Configures the the I2C address of the PCF8583. By default this is &51, but usually the address can be selected by changing jumpers or bridging contacts. The address is in I2C format, without the W/R bit (ie 7 bit value).

Configuration group 'RequestInput'

RequestInput.implementation

Value: readline
Type: str

Configures the implementation which will be used for requesting input on the host system. The implementations available are:

• readline - RISC OS OS_ReadLine implementation.
• wxwidgets - Input window within WxWidgets graphics implementation.

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.

Resolver.hosts_file

Value: InetDBase:hosts
Type: str

Configures the name of the file that will be read by the Resolver module for the local Hosts file.

Configuration group 'ResourceFS'

ResourceFS.enable

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

Controls whether the ResourceFS module initialises or not. By default it will initialise, but some parts of the system might expect that if they registered content they will be able to access it. The ResourceFS module does not provide a real filesystem at the current time.

Configuration group 'Serial'

Serial.implementation

Value: null
Type: str

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

• file - Writes to a native file using the configuration SerialFile.native_file_output, and reads from a native file using the configuration SerialFile.native_file_input.
• null - Has no effect other than to track state.
• pyserial - Read and write to native serial ports (and others) using PySerial.

Configuration group 'SerialFile'

SerialFile.native_file_input

Value: serial.dat
Type: str

Configures the native file which is read from by the file implementation.

SerialFile.native_file_output

Value: serial.dat
Type: str

Configures the native file which is written to by the file implementation.

Configuration group 'SerialPySerial'

SerialPySerial.device

Value: loop://
Type: One of the strings 'cpu', 'gpu', 'memory', 'iocard', 'psu', 'backplane', 'radiator', 'chassis', 'external', 'generic'

Configures the device which the PySerial talks to. Any of the devices supplied by PySerial may be used, either as explicit file devices, or URL specifications. For example:

• /dev/ttyUSB0
• socket://hostname:port/
• rfc2217://hostname:port/

See https://pythonhosted.org/pyserial/url_handlers.html for more details. To see detected devices by filename, use the PySerial tool:

`python -m serial.tools.list_ports`

Configuration group 'ShareFS'

ShareFS.use_freeway

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

Controls whether Freeway will be used to declare disc objects. As the implementation of ShareFS provided here never actually shares any discs on the network, this may be confusing if a real Freeway was announcing resources available. However, as the RISC OS Pyromaniac version of Freeway does not perform any network operations, this will merely be consistent.

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.channels_max

Value: 8
Type: int

Configures the maximum number of channels which are available to the system. This defaults to 8, but may be increased to 16 without exceeding the limits of the APIs.

Sound.channels_used

Value: 1
Type: int

Configures the number of channels which are in use when the system starts. This may be a value from 1 to channels_max.

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.enable_warnings

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

Controls whether the SoundChannels module will generate trace warnings when Sound_Control/Sound_ControlPacked SWIs are used with invalid parameters. In either case, the invalid parameters are ignored without error.

Sound.scheduler_type

Value: clocked
Type: One of the strings 'null', 'clocked'

Configures the type of sound scheduler which is implemented. The configuration types are:

• null: Never schedules anything, and beats never increment.
• clocked: Never schedules anything. Beats will increment logically with the real time.

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 'Speak'

Speak.enable

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

Controls whether the Speak module is enabled. When the option in disabled it will not initialise.

Speak.implementation

Value: null
Type: str

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

• console - Writes operations to the VDU console output.
• null - Does nothing at all.
• osx - Uses OSX Speech Synthesis.

Configuration group 'SpeakConsole'

SpeakConsole.voices

Value: Rick:en:M:70,Morty:en:M:14,Summer:en:F:17,Beth:en:F:34,Jerry:en:M:34
Type: Comma-separated list of a voices in the form: <name>[:[<language>][:[MFN][:<age>]]]

Configures the list of voices returned by the console Speak implementaion. The definition is a comma-separated list of a voices in the form:

• <name>[:[<language>][:[MFN][:<age>]]]

Configuration group 'Speech'

Speech.enable

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

Controls whether the Speech module is enabled. When the option in disabled it will not initialise.

Configuration group 'Spell'

Spell.implementation

Value: null
Type: str

Configures the implementation of the Impression Spell Checker. The following implementations are provided:

• null - Null implementation which fails everything.
• wordsfile - Use a file containing a list of words as the dictionary.

Configuration group 'SpellWordsFile'

SpellWordsFile.anagram_algorithm

Value: exact
Type: One of the strings 'none', 'exact'

Configures the algorithm used by the anagram word checking. There are some provided anagram match algorithms:

• none: only matches exactly
• exact: applies anagrams that use all the letters

SpellWordsFile.filename

Value: 
Type: str

Configures the RISC OS filename for the words file that we will read. The file should consist of one word per line. If no filename is given, the native_filename option will be used instead.

SpellWordsFile.fuzzy_algorithm

Value: soundex-american
Type: One of the strings 'soundex-american', 'soundex-sql'

Configures the algorithm used by the fuzzy word checking. There are some provided fuzzy match algorithms:

• none: only matches exactly
• soundex-american: applies the Soundex algorithm
• soundex-sql: applies the Soundex algorithm as used by SQL engines

The SQL variation is slightly faster.

SpellWordsFile.native_filename

Value: auto
Type: str

Configures the native filename for the words file that we will read. The file should consist of one word per line. The string auto may be used to use a system file determined at runtime, or none for no wordsfile.

Configuration group 'SpriteOp'

SpriteOp.empty_transformation

Value: ignore
Type: One of the strings 'ignore', 'error'

Configures how tranformations that produce empty regions will be handled. This includes the case where the multiplier on scale blocks are 0, or the determinant is 0 for a transformation matrix. It may take one of the values:

• ignore: ignore the plot (this is the behaviour of RISC OS Classic).
• error: generate an error.

SpriteOp.support_plot

Value: yes
Type: One of the strings 'yes', 'error', 'ignore'

Configures how plotting is supported by the sprite system. It may take one of three values:

• yes: plotting is supported
• error: generates an error when a plot call is made
• ignore: ignore the plot call

Configuration group 'SpriteUtils'

SpriteUtils.system_sprites_enable

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

Controls whether the system sprite area is created. If enabled, the dynamic area will be created, allowing the use of the system sprite area. If disabled, the area will not be created.

SpriteUtils.system_sprites_max

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

Configures the maximum size of the system sprite area, when it is enabled.

SpriteUtils.system_sprites_size

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

Configures the default size of the system sprite area, when it is enabled.

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 'SysRqServer'

SysRqServer.enable

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

Controls whether the system requests server will start. When enabled, the server will accept connections on the TCP port specified by the port option, and take line input to control the system.

SysRqServer.port

Value: 8809
Type: int

Configures the port on which the system requests server will listen for connections. Connections on this port will be accepted and this will allow the control of the RISC OS Pyromaniac system.

SysRqServer.prompt

Value: Pyro>
Type: str

Configures the prompt that will be used by the SysRq server for each input line.

Configuration group 'SysVars'

SysVars.read_corrupts_buffer

Value: no
Type: Regular expression matching: no|increment|random|[0-9a-fA-F]{1,2}

Configures the type of buffer corruption applied to the system variable buffer when a read request is made. The buffers supplied may be writen in part or not at all by the system. This configuration ensures that the buffer is written to with data to provoke errors.

The corruption options available are:

• no: Do not corrupt.
• increment: Corrupt with incrementing values.
• random: Randomise every byte.
• <hex>: Write the supplied hex value to every byte.

Configuration group 'SystemBell'

SystemBell.implementation

Value: sound
Type: str

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:

• console - Writes a BEL to the host console, which will perform its own handling of the bell.
• message - Writes a message to the VDU output stream.
• null - Does nothing.
• sound - Call Sound_Control with the configured sound parameters from OS_Byte. This is how RISC OS usually handles the VDU 7 bell.
• wxwidgets - Triggers the host system bell when using the WxWidgets graphics implementation.

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 RISC OS 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 RISC OS Pyromaniac.

Configuration group 'TaskManager'

TaskManager.enumerate_terminator

Value: 0
Type: One of the strings '0', 'cr'

Configures how task names are terminated when returned by the TaskManager_EnumerateTasks SWI. RISC OS classic returns the task names terminated as supplied control terminated on Wimp_Initialise. However, most tasks will have used 0-termination. This option allows the tasks to be forcibly terminated with either 0 or CR (13).

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.

TaskManager.tasks

Value: 
Type: Comma-separated list of <name>[:(M|D|<size>)]

Configures the additional tasks that will be included in the enumeration of tasks returned by TaskManager_EnumerateTasks. The tasks are specified as a comma-separated list of task definitions to be returned. The definitions may be suffixed by a : and a set of flags to return to the user. These flags take the form:

• M: Task is a module task (otherwise it is an application task).
• D: Task slot is draggable (otherwise it is not draggable).
• <number>: Size of task slot in Kilobytes.

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 'Teletext'

Teletext.implementation

Value: videov
Type: str

Configures the implementation used for the Teletext system. This controls how the teletext modes are presented. RISC OS Select abstracted the implementation of the teletext modes using VideoV. It is not known how RISC OS 5 has abstracted this. The implementations available are:

• videov - Implementation of Teletext which goes through VideoV.

Configuration group 'TeletextVideoV'

TeletextVideoV.flash_time_cs

Value: 100
Type: int

Configures the time that text will flash for within Teletext displays. The time is measured in centiseconds.

TeletextVideoV.high_quality

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

Controls whether we default to the high quality font based text rendering for teletext modes, rather than the bitmap text rendering.

TeletextVideoV.update_delay_cs

Value: 5
Type: int

Configures the delay between writing to the screen and the display being updated. On RISC OS Classic this was measured in VSync periods, but RISC OS Pyromaniac does not have VSync at present, so we measure the period in centiseconds. If set to 0, the update will be performed immediately after each write operation.

Configuration group 'Territory'

Territory.format_standarddate

Value: %W3, %DY %M3 %CE%YR
Type: str

Configures the format that will be used for the Territory_ConvertStandardDate call.

Territory.format_standarddateandtime

Value: %W3, %DY %M3 %CE%YR %24:%MN:%SE
Type: str

Configures the format that will be used for the Territory_ConvertStandardDateAndTime call.

Territory.format_standardtime

Value: %24:%MN:%SE
Type: str

Configures the format that will be used for the Territory_ConvertStandardTime call.

Territory.number

Value: 1
Type: int

Configures the territory number that we claim to be.

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 'TextEditor'

TextEditor.enable

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

Controls whether the Text editing system is available. When disabled, attempting to edit any file will result in an error.

TextEditor.encoding

Value: alphabet
Type: str

Configures the encoding that will be used for the content that is edited. This option can be set to the name of an encoding to store the content, for example 'iso8859-1'.

Two special encoding names may be used:

• alphabet: content is encoded according to the current RISC OS alphabet.
• identity: content will be passed through as-is.

TextEditor.implementation

Value: command
Type: str

Configures the implementation which will be used for editing text on the host system. The implementations available are:

• command - Host based command execution to run editor.
• wxwidgets - Text editing window within WxWidgets graphics implementation.

Configuration group 'TextEditorCommand'

TextEditorCommand.chdir

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

Controls whether the tool will change directory to the temporary directory for the duration of the command. This might be a problem if other operations are happening on threads.

TextEditorCommand.command_edit

Value: nano -R -I --
Type: str

Configures the command that will be invoked to edit the text file. This command will be passed the name of the temporary file which should be edited. Under POSIX systems commands, the nano tool can be used, which might take the following options:

• -R: restricted editor, with no operations other than editing the one file supplied.
• -t: save on exit, without prompting.
• -I: ignore rcfiles.

TextEditorCommand.command_view

Value: nano -R -I --view --
Type: str

Configures the command that will be invoked to view the text files. This command will be passed the name of the temporary file which should be edited. By default this uses nano with the --view option. It is possible to use more or less, but these tools may allow other files to be accessed.

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 - Writes the throwback operations to the VDU console.
• null - Does nothing at all.
• posturl - Sends throwback reports to a HTTP server as JSON.

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 (see url_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 'Ticker'

Ticker.dispatch_rate

Value: 1.0
Type: float

How many times slower the tickers dispatch than real time. By default they will dispatch in real time, so a 1cs ticker event would be dispatched after 1cs has elapsed. Larger numbers will make the ticker events be dispatched less often. For example, a dispatch_rate of 5 would dispatch a 1cs ticker event after 5cs.

Ticker.statistics

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

Controls whether statistics are gathered for Ticker processing. The statistics can have an overhead on the system, and so by default they are disabled.

Configuration group 'Time'

Time.force_boot_time

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

Configures the time that the system will report from boot. By default this option is disabled, using the value none, to mean that the clock runs with the real world clock. When set, however, the clock runs from the time specified.

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.

Time.osword15_uses_cset

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

Controls whether OS_Word 15 (Write time) returns C flag set when there is an error. This is the defined behaviour, but any SWI can also return an error, so it would also be valid to return the V set an an error pointer.

Configuration group 'TimerManager'

TimerManager.base_frequencies

Value: 2000000
Type: Comma-separated list of integers

Configures the base tick frequency of the timers that are available in TimerManager.

The configuration is a comma-separated list of frequencies for each timer. Any timer not supplied will use the final value in the list. By default the timers have a frequency of 2000000, which was the base rate used by IOMD. However, any frequency value could be used.

TimerManager.count

Value: 2
Type: int

Configures how many timers are made available from the TimerManager.

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.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, suffixed with :<operation>

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. Each SWI number, name or prefix, may be followed by an operation that is to be performed when the trap fires separated by a ':'.

• report - produce a debug report for the entry and exit of the SWI. This is the default.
• trace - enable tracing within the SWI.
• traceon - enable tracing from the start of this SWI.
• traceoff - disable tracing from the start of this SWI.

For example, this option may be set to Wimp_SlotSize:trace to enable instruction tracing whilst the Wimp_SlotSize SWI is being executed.

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.

In addition to hexadecimal addresses, each tracepoint may have one of the following formats:

• <function-pattern> - matches the function pattern in any module, or dynamic area containing code (only the Application space at present).
• module:<module>:<function-pattern> - matches the function pattern, but only in a specific module.
• area:<area-name>:<function-pattern> - matches the function pattern in a specific dynamic area.
• @:<function-pattern> - matches the function pattern in the application space.

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'

An editor may be invoked from BASIC by the command TWIN, or by the *Edit command. This operation is managed by the Twin module. The configuration controls whether the Twin module will function when invoked in this way. It uses the TextEditor configuration to launch the actual editor.

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 'UtilityModule'

UtilityModule.kill_effect

Value: error-in-use
Type: One of the strings 'error', 'error-in-use', 'allow'

Configures the effect of attempting to delete the UtilityModule. The options available are:

• error: Report an error.
• error-in-use: Report an error if the module is in use, and allow otherwise.
• allow: Always allow the deleting of the UtilityModule.

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). The implementations currently available are:

• ansitext - Converts control sequences to ANSI where possible.
• plain - Base VDU implementation.

VDU.mode

Value: 27
Type: A mode number, or 'swi' for the current state of the Wimp_SetMode SWI

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.output_fd

Value: stdout
Type: Regular expression matching: null|stdout|stderr|[1-9][0-9]*

Configure the file descriptor used for output from the system. This may be a numbered file descriptor, or a named file descriptor - stdout or stderr.

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.

VDU.wrchv

Value: as-required
Type: One of the strings 'always', 'never', 'as-required'

Controls when the WrchV vector is used by the VDU system. WrchV is used for passing characters written to the VDU stream, so that clients may see or modify them. However, this may involve a significant amount of extra work in the emulation and avoids a number of optimisations that can be performed by the RISC OS Pyromaniac system.

By default the configuration is to only use the vector when it has claimants. This is similar to the behaviour of the RISC OS Classic system.

Configuration values may be:

• always: pass every character to WrchV, even if there are no claimants.
• never: never pass any character to WrchV, which is fastest.
• as-required: pass to WrchV when there are claimants, but otherwise use the fast path.

Configuration group 'VDUANSIText'

VDUANSIText.always_windowed

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

Controls whether the ANSI text system treats the output as always windowed. When enabled, character positioning in the ANSI text system will be closer to the VDU mode output, with newlines inserted when text reaches the end of the line. This option defaults to False, as it will generates more output when enabled, and may break lines at non-obvious positions within the terminal.

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 'VDUMode'

VDUMode.allow_0dpi_spritemodes

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

Controls whether strict or lax checks are performed on the sprite mode words. If enabled, sprite mode words with a DPI value of 0 will be allowed. If disabled, such sprite mode words will report an error stating that an invalid DPI has been used.

!Paint uses a check of the sprite mode word with a DPI value of 0 to determine whether deep modes are available. If this option is disabled, !Paint will be unable to create deep sprites in its original form.

VDUMode.display_depths

Value: 1,2,4,8,16,24
Type: Comma-separated list of flags from '1', '2', '4', '8', '16', '24'

Restricts the display depths that may be used by the display. Only those bit depths that are present in the list will be allowed. If the list is empty, any depth is allowed. Valid values are:

• 1: 2 colour paletted mode
• 2: 4 colour paletted mode
• 4: 16 colour paletted mode
• 8: 256 colour paletted mode
• 16: 16-bit true colour mode
• 24: 24-bit true colour mode

VDUMode.display_height

Value: -
Type: Open size range such in the form [<start>]-[<end>], <value> or <start>+<length>

VDUMode.display_resolutions

Value: 
Type: A comma-separated list of dimensions in the form <width>x<height>

Restricts the display resolutions that may be used by the display. Only those resolutions that are present in the list will be allowed. If the list is empty, any resolution is allowed.

VDUMode.display_width

Value: -
Type: Open size range such in the form [<start>]-[<end>], <value> or <start>+<length>

VDUMode.enumerate_numbered_lowres

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

Controls whether OS_ScreenMode 2 (Enumerate modes) synthetic mode enumeration will include low resolution modes (less than 640 pixels across or 256 pixels high).

By default this is enabled, so that we get many of the modes that we expect to be available listed in menus.

VDUMode.enumerate_numbered_modes

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

Controls whether OS_ScreenMode 2 (Enumerate modes) will include a synthetic list of modes generated from the numbered modes. Normally the list of modes would be provided by the ScreenModes module, based on a Mode Definition File. However, there's no real reason why Pyromaniac needs to do this, as timings are irrelevant.

By default this is enabled, which allows any extension modes that are defined through the configuration, or through the Service_ModeExtension interface, to be available in Display Manager.

VDUMode.enumerate_numbered_nonsquare

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

Controls whether OS_ScreenMode 2 (Enumerate modes) synthetic mode enumeration will include modes that have rectangular pixels.

By default this is disabled, as these modes will appear stretched if they are selected from menus without a set of eigen-factors present.

VDUMode.modeextension_format

Value: 3.5
Type: One of the strings '3.1', '3.5'

Configures the format that the Service_ModeExtension will be issued in. There are two formats supported:

• 3.1: Does not supply the memory bandwidth and video memory available.
• 3.5: Supplies memory bandwidth and video memory available.

VDUMode.modeselector_fullpalette_invalid

Value: error
Type: One of the strings 'warning', 'error', 'ignore'

Configures the effect of supplying the 'Full Palette' mode flag when not in a 256 colour mode. RISC OS 4 and earlier would accept this even if it didn't make sense. RISC OS 5 validates this variable when it is supplied and rejects the mode selector. This option allows the behaviour to be changed:

• error: Returns an error when the value is inconsistent.
• ignore: Ignores the inconsistency, and resets the value to the default.
• warning: Reports a warning through the trace system, and then resets the value to the default.

To be the most useful, warning is the default value.

VDUMode.modeselector_ncolour_invalid

Value: error
Type: One of the strings 'warning', 'error', 'ignore'

Configures the effect of supplying an inconsistent NColour value in a mode selector block to a SWI that accepts a mode specifier. RISC OS 4 and earlier would pass this value through directly to the mode variables, even if it did not make sense (eg NColour = 77 for a 8bit paletted mode). RISC OS 5 validates this variable when it is supplied and rejects the mode selector. This option allows the behaviour to be changed:

• error: Returns an error when the value is inconsistent.
• ignore: Ignores the inconsistency, and resets the value to the default.
• warning: Reports a warning through the trace system, and then resets the value to the default.

To be the most useful, warning is the default value.

VDUMode.readmodevariable_invalid

Value: warning
Type: One of the strings 'error', 'cset', 'warning'

Configures the effect of supplying an invalid mode to the OS_ReadModeVariable SWI. RISC OS Classic would always set the C flag, indicating that the mode was invalid. This is often not helpful in diagnosing problems, and applications should always be able to handle errors returned from any SWI call. This option allows the behaviour to be changed:

• error: Returns an error when the mode or variable is invalid
• cset: Returns with the C flag set, as expected by RISC OS Classic.
• warning: Returns with the C flag set and reports a warning through the trace system.

To be the most useful, warning is the default value.

VDUMode.support_vidclist_01

Value: True
Type: bool

Controls whether mode extension using the VIDC List formats 0 and 1 is supported through the Service_ModeExtension interface. These hardware lists include explicit VIDC register parameters which will not be used by RISC OS Pyromaniac.

When this option is disabled, any mode extensions returned with either of these formats will be rejected as Bad Modes.

VDUMode.support_vidclist_3

Value: True
Type: bool

Controls whether mode extension using the VIDC List format 3 is supported through the Service_ModeExtension interface. This interface returns generic parameters which should be used by the hardware.

When this option is disabled, any mode extensions returned with either of these formats will be rejected as Bad Modes.

VDUMode.video_bandwidth

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

Configures the video bandwidth available in Service_ModeExtension, in bytes per second. The default value is just shy of 2GB/s, because Pyromaniac has no limits and this value avoids making the number negative if treated as unsigned.

Configuration group 'VNC'

VNC.maximum_clients

Value: 2
Type: int

Configures the maximum number of clients that the VNC server will allow.

VNC.maximum_redraw_rate

Value: 20
Type: int

Configures the maximum rate at which the VNC clients 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.

VNC.password

Value: 
Type: str

Configures the password to use for the VNC server (full access, including input). An empty string means that no password will be used.

VNC.password_readonly

Value: 
Type: str

Configures the password to use for the VNC server (read only, no input). An empty string means that no password will be used.

VNC.port

Value: 5902
Type: int

Configures the port on which the VNC server will listen for connections.

Configuration group 'WX'

WX.console_ansi

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

Controls whether console outputs will be have terminal control codes, such as the ANSI colour control sequences, processed. This allows the display to be show coloured output from the console. When disabled, the console output will not process control codes.

WX.console_capture

Value: none
Type: One of the strings 'none', 'stdout', 'stderr', 'stdout+stderr'

Configures the console window used by WxWidgets. By default there is no console window, and output will appear on stdout or stderr as expected. This configuration option allows the output to be captured into a window to make it easy to see debug output. Options are:

• none: no output captured by default
• stdout: capture stdout
• stderr: capture stderr
• stdout+stderr: capture both stdout and stderr

WX.console_open

Value: if-enabled
Type: One of the strings 'no', 'yes', 'if-enabled'

Controls whether the console window will be opened when the application starts. By default the console is configured to open only when the console_capture is in one of the enabled states. Options are:

• no: do not open on application start.
• yes: open on application start.
• if-enabled: open if the console is enabled.

WX.emulate_menu_button

Value: meta-click
Type: One of the strings 'none', 'meta', 'meta-click'

Configures whether the menu_button is emulated with key combinations. This is useful on systems that do not have a dedicated middle button. Options are:

• none: middle mouse button is not emulated at all.
• meta: the meta key (Command or Windows key) triggers the middle mouse button.
• meta-click: meta and the left mouse button triggers the middle mouse button.

WX.explorer_dirname

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

Controls whether the directory name appears at the top of the explorer windows.

WX.explorer_display

Value: large
Type: One of the strings 'large', 'small', 'fullinfo'

Configures the display format for the explorer windows. The options for the default display format are:

• large: Displays large icons.
• small: Displays small icons.
• fullinfo: Displays full information.

WX.explorer_enable

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

Controls whether the file explorer window is available or not.

WX.explorer_sort

Value: name
Type: One of the strings 'name', 'size', 'filetype', 'timestamp'

Configures the sort order for the explorer windows. The options for the default sort order are:

• name: Sort by name.
• filetype: Sort by file type.
• size: Sort by size.
• timestamp: Sort by date/time.

WX.explorer_writeable

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

Controls whether the explorer windows are writeable or not. This means that the options to create new directories, delete files and rename files will not be present if this option is disabled.

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.

WX.modechange_centres_window

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

Controls whether a change in the size of the mode causes the window to resize around the centre of the window. When this option is disabled, the window will retain the position of the top left corner when resized. When the option is enabled, the window will move to be centred on its current position.

WX.pythonshell_enable

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

Controls whether the Python shell window is available or not.

WX.textwindow_size

Value: 80x20
Type: Dimensions in the form: <width>x<height> or <size>

Configures the default size of the window used to display and edit text. This window is used by the file explorer, Git and Twin, when configured with 'texteditor.implementation' set to 'wxwidgets'.

WX.window_close

Value: quit
Type: One of the strings 'close', 'quit'

Configures the effect of the interface window being closed. The values for this option are:

• close - close the window, but keep the system and application running.
• quit - quit the system, and the application.

WX.window_resize

Value: aspect
Type: One of the strings 'none', 'scale', 'aspect'

Configures how the interface window resizes, and whether the Full screen option can be used. The values for this option are:

• none: no resizing of the window is possible for the user.
• scale: arbitrary resizing of the window is possible (greater than the minimum size).
• aspect: arbitrary resizing of the window is possible, but the image will retain the same aspect ratio.

Configuration group 'WatchRegions'

The WatchRegions allow blocks of memory to be trapped in the same way. The configuration can allow for different accesses monitoring, with different effects, in the form <type>[=<effect>]. The type can have values:

• no - does not treat the watched memory specially
• read - watches for reads in the watched memory
• write - watches for writes in the watched memory
• yes - watches for either reads or writes in the watched memory

The effect can have values:

• trace - report the access to the trace stream (default)
• abort - report the access to the trace stream and then abort
• abort-on-write - report the access to the trace stream, and if the access was a write abort.

WatchRegions.daheap

Value: no
Type: Regular expression matching: (no|read|write|yes)(:(abort|abort-on-write|trace))?

Configures how regions within the DAHeaps that have been marked as protected are handled. This helps to identify memory corruption within the heap regions.

When enabled, any protected regions such as the heap header, or heap block headers, will be reported on. The option dynamicareaheaps.guard_size adds more protected space around allocated blocks. The most useful settings would be:

• no - No checking on the heap accesses.
• yes - Report on reads and writes of the protected regions. Very noisy as components read the length in order to resize blocks (eg C library realloc).
• write=abort - Report on reads, and abort on writes.

WatchRegions.lowmemory

Value: yes=abort-on-write
Type: Regular expression matching: (no|read|write|yes)(:(abort|abort-on-write|trace))?

Configures how the low memory region (addresses 32 - &FE8) is registered as a watchpoint. This memory region is used for Kernel workspace on RISC OS classic. Addresses from &FE8 - &1000 are excluded from this watch point as they are used by various components (WindowManager, FPEmulator and SharedCLibrary in particular).

WatchRegions.lowvectors

Value: yes=abort-on-write
Type: Regular expression matching: (no|read|write|yes)(:(abort|abort-on-write|trace))?

Configures how the low CPU vector region (addresses 0 - 32) is registered as a watchpoint.

WatchRegions.scratchspace

Value: no
Type: Regular expression matching: (no|read|write|yes)(:(abort|abort-on-write|trace))?

Configures how the scratch space (addresses &4000 - &8000) is registered as a watchpoint. This memory region is used by a variety of components, but has been migrated away from.

WatchRegions.sharedpointers

Value: no
Type: Regular expression matching: (no|read|write|yes)(:(abort|abort-on-write|trace))?

Configures how the shared pointer region (addresses &FE8 - &1000) is registered as a watchpoint. This memory region is used for WindowManager, FPEmulator and SharedCLibrary to store pointers that are shared with other components.

WatchRegions.svcstack

Value: write=abort
Type: Regular expression matching: (no|read|write|yes)(:(abort|abort-on-write|trace))?

Configures how the SVC stack smash checks are managed. Parts of the SVC stack which contain data placed there by the operating system are marked as watchpoints with the specified configuration. If they are overwritten, a SVC stack corruption error will be raised.

WatchRegions.svcstackguard

Value: write=abort
Type: Regular expression matching: (no|read|write|yes)(:(abort|abort-on-write|trace))?

Configures how the guard at the base of the SVC stack smash is managed. This is a section of memory of 1K above the base of the SVC stack, of size 1K. It is marked as ROM in RISC OS Select to detect stack overflow during execution. In RISC OS Pyromaniac it is configured as a watchpoint and may abort in a similar manner to RISC OS Select.

WatchRegions.vdumemory

Value: no
Type: Regular expression matching: (no|read|write|yes)(:(abort|abort-on-write|trace))?

Configures how the VDU workspace (addresses &1000 - &4000) is registered as a watchpoint. This memory region is used for VDU workspace on RISC OS classic.

Configuration group 'WimpCommandWindow'

WimpCommandWindow.colour_border

Value: grey34
Type: Colour as 'r,g,b', '&BBGGRR00', bbc palette, 'greyGGG', 'wimpCC' or colour name

Configures the colour used by the Wimp command window for the window border.

The colour can be specified in the form:

• R, G, B: Decimal colour values from 0-255 for each component.
• &BBGGRR00: Palette entry value in hex.
• N: BBC 16 colour palette number.
• greyGGG: Decimal grey values from 0-255 (0 black, 255 white).
• wimpN: Wimp 16 colour palette number.
• NAME: Colour name from BBC palette.

WimpCommandWindow.colour_textfg

Value: black
Type: Colour as 'r,g,b', '&BBGGRR00', bbc palette, 'greyGGG', 'wimpCC' or colour name

Configures the colour used by the Wimp command window for the text region's foreground.

The colour can be specified in the form:

• R, G, B: Decimal colour values from 0-255 for each component.
• &BBGGRR00: Palette entry value in hex.
• N: BBC 16 colour palette number.
• greyGGG: Decimal grey values from 0-255 (0 black, 255 white).
• wimpN: Wimp 16 colour palette number.
• NAME: Colour name from BBC palette.

WimpCommandWindow.colour_textfill

Value: white
Type: Colour as 'r,g,b', '&BBGGRR00', bbc palette, 'greyGGG', 'wimpCC' or colour name

Configures the colour used by the Wimp command window for the text region's background.

The colour can be specified in the form:

• R, G, B: Decimal colour values from 0-255 for each component.
• &BBGGRR00: Palette entry value in hex.
• N: BBC 16 colour palette number.
• greyGGG: Decimal grey values from 0-255 (0 black, 255 white).
• wimpN: Wimp 16 colour palette number.
• NAME: Colour name from BBC palette.

WimpCommandWindow.colour_titlefg

Value: black
Type: Colour as 'r,g,b', '&BBGGRR00', bbc palette, 'greyGGG', 'wimpCC' or colour name

Configures the colour used by the Wimp command window for the titlebar's text.

The colour can be specified in the form:

• R, G, B: Decimal colour values from 0-255 for each component.
• &BBGGRR00: Palette entry value in hex.
• N: BBC 16 colour palette number.
• greyGGG: Decimal grey values from 0-255 (0 black, 255 white).
• wimpN: Wimp 16 colour palette number.
• NAME: Colour name from BBC palette.

WimpCommandWindow.colour_titlefill

Value: wimp12
Type: Colour as 'r,g,b', '&BBGGRR00', bbc palette, 'greyGGG', 'wimpCC' or colour name

Configures the colour used by the Wimp command window for the titlebar's background.

The colour can be specified in the form:

• R, G, B: Decimal colour values from 0-255 for each component.
• &BBGGRR00: Palette entry value in hex.
• N: BBC 16 colour palette number.
• greyGGG: Decimal grey values from 0-255 (0 black, 255 white).
• wimpN: Wimp 16 colour palette number.
• NAME: Colour name from BBC palette.

WimpCommandWindow.immediate_effect

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

Controls whether the command window comes into effect immediately, or is deferred until the vector traps indicate that the window is to be used. RISC OS Classic always uses deferred mode.

WimpCommandWindow.prompt

Value: \nPress SPACE or click mouse to continue
Type: str

Configures the prompt to display when exiting the command window.

Configuration group 'WimpIcon'

WimpIcon.multiline_alignment

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

Controls whether multi-line text icons (using 'L' validation) will align left, right, horizontally and vertically. RISC OS Classic will always align the multi-line text horizontally and vertically centred, but RISC OS Pyromaniac supports all the options.

WimpIcon.render_sprites

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

Controls whether sprites are rendered in icons. When this option is disabled, sprites will be drawn as a bare rectangle, rather than being rendered.

WimpIcon.shaded_style

Value: background-blend
Type: One of the strings 'grey', 'grey-blend', 'background-blend'

Configures how the shaded icons are rendered. There are different ways in which the blend can be performed:

• grey: changes colours to be grey, and lighter. This is similar to the effect used by versions of RISC OS before RISC OS 4.
• grey-blend: blends toways a light grey, but retains colours.
• background-blend: changes colours to be grey, in a scale towards the background colour. This is similar to the effect used by RISC OS Select.

WimpIcon.validation_c

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

Controls whether the C validation, which controls 24-bit colour for icons, is supported. It was introduced in RISC OS 4, and prior OS versions did not honour it.

Configuration group 'WimpReadSysInfo'

WimpReadSysInfo.current_task

Value: none
Type: str

Configures the name of the task that will be returned for Wimp_ReadSysInfo 5 (current task). The name will be looked up through the internal interface to TaskManager. The string 'none' can be used to return no current task.

WimpReadSysInfo.desktop_state

Value: swi
Type: One of the strings 'command', 'desktop', 'swi'

Configures the value returned for Wimp_ReadSysInfo 3 (desktop state). Values:

• command: at the command line
• desktop: within the desktop
• swi: from the state of Wimp_CommandWindow

WimpReadSysInfo.iconsprites_suffix

Value: 22
Type: str

Configures the value returned for Wimp_ReadSysInfo 2 (icon sprites suffix). The value auto may be used to read the suffix to use from the current mode.

WimpReadSysInfo.mode

Value: swi
Type: A mode number, or 'swi' for the current state of the Wimp_SetMode SWI

Configures the value returned for Wimp_ReadSysInfo 1 (current wimp mode).

WimpReadSysInfo.task_count

Value: 0
Type: int

Configures the value returned for Wimp_ReadSysInfo 0 (task count).

WimpReadSysInfo.wimp_version

Value: 3.99
Type: Regular expression matching: [1-9]\.[0-9][0-9]

Configures the value returned for Wimp_ReadSysInfo 7 (WindowManager version).

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:

• easygui - Report errors in the host UI, using EasyGUI module.
• graphics - Report errors as a graphical error box.
• null - Ignore all error box requests (everything is cancel).
• vdu - Report errors to the VDU steam.
• wxwidgets - Report errors in the host UI, using WxWidgets module.

Configuration group 'WimpReportErrorBoxGraphics'

WimpReportErrorBoxGraphics.application_sprite

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

Controls whether the application sprite appears on the side of the error box. RISC OS 2 did not include the application sprite.

WimpReportErrorBoxGraphics.category_both_sides

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

WimpReportErrorBoxGraphics.centre_buttons

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

Controls whether the buttons are centred in the window, instead of right aligned. RISC OS 2 centred the buttons.

WimpReportErrorBoxGraphics.divider_style

Value: auto
Type: One of the strings 'none', 'solid', 'indent', 'sprite', 'auto'

Configures how the divider will be shown in the window. The option may be one of:

• none - no divider will be used.
• solid - a solid line will separate the error and the buttons.
• indent - a R4-style indented border will be used.
• sprite - the divider sprite will be used.
• auto - the divider sprite will be used if present, otherwise the the indent will be used.

WimpReportErrorBoxGraphics.message_border

Value: no
Type: One of the strings 'no', 'yes', 'sunk'

Controls whether the message area is bordered. RISC OS 2 had a solid border. RISC OS 3 onwards did not use a border. Some styles of error boxes had sunk borders. Options are:

• no: no border (RISC OS 3 style).
• yes: solid border (RISC OS 2 style).
• sunk: sunken border.

Configuration group 'WimpSpritePool'

WimpSpritePool.maxsize

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

Configures the maximum size of each of the sprite areas in the pool.

WimpSpritePool.priority_filename

Value: 
Type: str

Configures the RISC OS filename to use for the Wimp sprite pool's priority sprites. The priority sprites will be tried before any sprites loaded into the RAM pool.

When set to an empty string no sprites will be loaded.

WimpSpritePool.priority_native_filename

Value: 
Type: str

Configures the native filename to use for the Wimp sprite pool's priority sprites. The priority sprites will be tried before any sprites loaded into the RAM pool. The native filename will be tried only if there isn't a RISC OS file available.

When set to an empty string no sprites will be loaded.

WimpSpritePool.protect_rom_sprites

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

Controls whether the ROM sprites are considered the high priority or low priority. When enabled, the ROM sprites are used in preference to the regular icon sprites. When disabled, the icon sprites are used in preference to the icon sprites. The priorty pool is always used in preference to both these pools.

WimpSpritePool.ram_filename

Value: 
Type: str

Configures the RISC OS filename to use for the Wimp sprite pool's RAM sprites. The RAM sprites will be tried before any sprites loaded into the ROM pool.

When set to an empty string no sprites will be loaded.

WimpSpritePool.ram_native_filename

Value: 
Type: str

Configures the native filename to use for the Wimp sprite pool's RAM sprites. The RAM sprites will be tried before any sprites loaded into the ROM pool. The native filename will be tried only if there isn't a RISC OS file available.

When set to an empty string no sprites will be loaded.

WimpSpritePool.rom_filename

Value: 
Type: str

Configures the RISC OS filename to use for the Wimp sprite pool's ROM sprites. The ROM sprites will be tried after any sprites loaded into the RAM pool.

When set to an empty string no sprites will be loaded.

WimpSpritePool.rom_native_filename

Value: 
Type: str

Configures the native filename to use for the Wimp sprite pool's ROM sprites. The ROM sprites will be tried after any sprites loaded into the RAM pool. The native filename will be tried only if there isn't a RISC OS file available.

When set to an empty string no sprites will be loaded.

Configuration group 'WimpTextOp'

WimpTextOp.font_name

Value: Homerton.Medium
Type: str

Configures the name of the font that will be used for the Wimp font. When set to an empty string the system font will be used. This configuration sets the default Wimp$Font variables.

WimpTextOp.font_size

Value: 12.0
Type: Dimensions in the form: <width>x<height> or <size>

Configures the size of the font that will be used for the title bar, in points. The size can be a fractional value, but RISC OS FontManager only supports 16 divisions of a point, ie multiples of 0.0625. This configuration sets the default Wimp$FontSize and Wimp$FontWidth variables.

Configuration group 'WimpToolSprites'

WimpToolSprites.filename

Value: 
Type: str

Configures the RISC OS filename to use for the Wimp tool sprites.

When set to an empty string no sprites will be loaded.

WimpToolSprites.maxsize

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

Configures the maximum size of the sprite area.

WimpToolSprites.native_filename

Value: 
Type: str

Configures the native filename to use for the Wimp tool sprites. The native filename will be tried only if there isn't a RISC OS file available.

When set to an empty string no sprites will be loaded.

Configuration group 'ZeroPage'

ZeroPage.lowvectors

Value: error:DEAD
Type: Regular expression matching: (no|read|write|yes)(:(abort|abort-on-write|trace))?

Configures how the low vector area (addresses 0 - 32) will be populated. The region can be configured to contain either 0s, -1s, or a string that might look like an error block.

The configuration may be set to one of:

• 0 sets all the words to 0.
• -1 sets all the words to -1.
• error:<type> populates the location with a block which looks like an error.

The error block will be given an error number based on the <type> supplied. These have different properties which may be useful during diagnostics:

• 0DED will use the error number &44454400, which starts with a 0 byte, and would thus produce an empty string if used in a zero-terminated string context.
• DED0 will use the error number &00444544, which has bits 24-31 clear, which would produce the string 'DED' in a zero-terminated string context.
• DEAD will use the error number &44414544, which has bits 0 and 1 clear.
• EBAD will use the error number &44414245, which has bit 0 set and bit 1 clear.
• ZERO will use the error number &4F52455A, which has bit 0 clear and bit 1 set.
• OFLA will use the error number &414C464F, which has bits 0 and 1 set.
• -1 will use the error number &FFFFFFFF, which has all bits set.

Note that although the content at address 0 may appear like an error block, the use of a value 0 as an error pointer will be trapped depending on the configuration of error.nullpointer_effect. Unless this is set to passthrough, this configuration will not be seen.

Configuration group 'Zipper'

Zipper.strict_fileopen

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

Controls whether the Zipper_UnZipFileOpen faults opening files without closing them. The original Zipper module claimed to fault opening multiple files, but didn't. When this option is enabled, the UnzipFileOpen will fault the opening of multiple files.