- Obtaining help
- Configuration group 'APIWarnings'
- Configuration group 'Buffers'
- Configuration group 'CLI'
- Configuration group 'ClipboardHolder'
- Configuration group 'Console'
- Configuration group 'Debugger'
- Configuration group 'Documentation'
- Configuration group 'DynamicArea'
- Configuration group 'Emulation'
- Configuration group 'Error'
- Configuration group 'Execute'
- Configuration group 'Filesystem'
- Configuration group 'GTK'
- Configuration group 'Graphics'
- Configuration group 'GraphicsCairo'
- Configuration group 'GraphicsUI'
- Configuration group 'Heap'
- Configuration group 'Hourglass'
- Configuration group 'Input'
- Configuration group 'Internet'
- Configuration group 'Kernel'
- Configuration group 'LegacyBBC'
- Configuration group 'MAC'
- Configuration group 'MMIO'
- Configuration group 'Memory'
- Configuration group 'MemoryMap'
- Configuration group 'MessageTrans'
- Configuration group 'Modules'
- Configuration group 'NVRAM'
- Configuration group 'OSConfirm'
- Configuration group 'OSMemory'
- Configuration group 'PlatformSupport'
- Configuration group 'Podule'
- Configuration group 'Pointer'
- Configuration group 'PowerControl'
- Configuration group 'ProgEnv'
- Configuration group 'Pyro'
- Configuration group 'PyromaniacModule'
- Configuration group 'ROMInformation'
- Configuration group 'Resolver'
- Configuration group 'Sound'
- Configuration group 'SysLog'
- Configuration group 'SystemBell'
- Configuration group 'SystemInformation'
- Configuration group 'TaskManager'
- Configuration group 'TaskWindow'
- Configuration group 'Territory'
- Configuration group 'Throwback'
- Configuration group 'Time'
- Configuration group 'Timings'
- Configuration group 'Trace'
- Configuration group 'Twin'
- Configuration group 'URI'
- Configuration group 'UniqueId'
- Configuration group 'UserV'
- Configuration group 'VDU'
- Configuration group 'VDUANSIText'
- Configuration group 'WX'
- Configuration group 'WimpReportErrorBox'
Obtaining help
The help for all configuration options for RISC OS Pyromaniac can be obtained by running:
python pyro.py --help-config --load-internal-modules
Within RISC OS help can be obtained with:
*PyromaniacConfig -help
Configuration group 'APIWarnings'
APIWarnings.enterleaveos
Value: no
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether the OS_EnterOS/OS_LeaveOS SWIs warn about their use. These calls should generally not be used in applications.
APIWarnings.intonoff
Value: no
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether the OS_IntOn/OS_IntOff SWIs warn about their use. These calls should generally not be used in applications.
APIWarnings.synchronisecodeareas
Value: no
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether the OS_SynchroniseCodeAreas SWI warns about efficient unbounded synchronise requests.
Configuration group 'Buffers'
The Buffers configuration group configures how large the buffers are for the standard RISC OS buffers. Most of these buffers are actually not used, and have not been used since the BBC.
Buffers.keyboard_size
Value: 255
Type: int
Configures the number of bytes available in the keyboard input buffer.
Buffers.mouse_size
Value: 63
Type: int
Configures the number of bytes available in the mouse input buffer.
Buffers.printer_size
Value: 1023
Type: int
Configures the number of bytes available in the printer buffer.
Buffers.serialinput_size
Value: 255
Type: int
Configures the number of bytes available in the serial input buffer.
Buffers.serialoutput_size
Value: 191
Type: int
Configures the number of bytes available in the serial output buffer.
Buffers.soundchannel0_size
Value: 3
Type: int
Configures the number of bytes available in the sound buffer for channel 0 (not used by RISC OS).
Buffers.soundchannel1_size
Value: 3
Type: int
Configures the number of bytes available in the sound buffer for channel 1 (not used by RISC OS).
Buffers.soundchannel2_size
Value: 3
Type: int
Configures the number of bytes available in the sound buffer for channel 2 (not used by RISC OS).
Buffers.soundchannel3_size
Value: 3
Type: int
Configures the number of bytes available in the sound buffer for channel 3 (not used by RISC OS).
Buffers.speech_size
Value: 3
Type: int
Configures the number of bytes available in the speech buffer (not used by RISC OS).
Configuration group 'CLI'
CLI.module_hash_enable
Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether the CLI commands prefixed by Module#<name>
are directed to the
named module or not.
RISC OS classic supports this syntax, but it is obscure and almost never used. It can
be helpful in explicitly directing a command to a module, but might preclude the use of
a filesystem called Module
that supported special fields.
Configuration group 'ClipboardHolder'
ClipboardHolder.enable
Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether the ClipboardHolder module is able to function. If this is disabled, the ClipboardHolder SWIs will return errors.
ClipboardHolder.implementation
Value: pyperclip
Type: str
Configures which implementation will be used for the clipboard. The following implementations are provided:
static
- holds the clipboard in Pyromaniac memory only.- 'pyperclip' - uses the Python 'pyperclip' package to transfer the clipboard to and from the host system.
- 'posturl' - uses a HTTP POST to submit the clipboard data to a remote server. No mechanism it provided to receive clipboard data.
ClipboardHolder.post_url
Value: http://localhost:8080/
Type: str
Configures the URL to use when the 'posturl' implementation is selected.
The posted data is contained within the body of the request. The media type supplied will be an 'application/riscos' type, with the name of the file containing the filetype number.
ClipboardHolder.scrap_file
Value: <Wimp$ScrapDir>.Clipboard
Type: str
Configures the file that the clipboard will be transferred through when it must be transferred by a file.
Configuration group 'Console'
Console.input_escapes
Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether terminal escapes for function keys, cursor keys and other input, are processed by the input system. If this option is disabled, the escape codes (and therefore cursor keys and function keys) will be passed through verbatim. If this option is enabled, the escape codes will be processed into RISC OS keys, and cursor keys will be seen by RISC OS as expected.
Console.input_escapes_timeout
Value: 0.2
Type: float
Configures how many seconds will be waited before cancelling a terminal escape sequence. Usually this causes the physical escape key to be reported as a key press. It is usually a fraction of a second, in order that the terminal be responsive, but delays in buffering do not cause the escape to be misidentified.
Console.input_utf8
Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether characters input are treated as UTF-8 and converted to the current alphabet. If this option is disabled, input is passed through unmodified.
Configuration group 'Debugger'
Debugger.hide_topbitset
Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether characters with the top bit set will be shown as a '.' character, or displayed directly.
Debugger.memory_bytesperrow
Value: 16
Type: int
Configures the width of the *Memory command's output in bytes.
Debugger.memory_defaultsize
Value: 256
Type: int
Configures the amount of memory which is displayed when *Memory is used without an end address.
Debugger.memoryi_defaultsize
Value: 24
Type: int
Configures the amount of memory which is displayed when *MemoryI is used without an end address.
Debugger.showregs_context
Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether the *ShowRegs command includes context information from the registers which are stored in the exception areas.
Configuration group 'Documentation'
Documentation.enable_launch
Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0
Configuration group 'DynamicArea'
DynamicArea.area_base
Value: &5000000
Type: Hexadecimal value, optionally prefixed by '&'.
Controls where in memory the OS_DynamicArea calls to create new areas with auto-allocated base addresses will start.
DynamicArea.clamp_machinesize
Value: 64 M
Type: Size as a number which may be suffixed by 'K', 'M' or 'G', and '-1'
Configures the default clamp for dynamic areas which request an area which is as large as possible (max size -1).
DynamicArea.clamp_maxsize
Value: 1024 M
Type: Size as a number which may be suffixed by 'K', 'M' or 'G', and '-1'
Configures the default clamp for dynamic areas which request an area with an explicit maximum size (max size not -1).
DynamicArea.clamp_sparsesize
Value: 3072 M
Type: Size as a number which may be suffixed by 'K', 'M' or 'G', and '-1'
Configures the default clamp for dynamic areas which are sparse mapped. Sparse mapping is not currently supported.
Configuration group 'Emulation'
Emulation.disable_interrupt
Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether timers are enabled or not. There may be underlying bugs with the timer implementation that mean that code will execute out of turn - ie be completely fatal. Because of this, timers are disabled by default.
Emulation.internal_backtrace
Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether, when a Python exception occurs during the processing of a SWI, callback, interrupt or other event, a backtrace is produced. The backtrace will not be sent through the RISC OS VDU system, as this may be the reason for the backtrace.
Emulation.internal_recursion_limit
Value: 0
Type: int
Controls the recursion depth for internal python functions. By default, Python uses a limit of 1000-deep function calls (implementation-specific), which may limit some calls in the RISC OS environment which are inherently deeply nested. This option allows the recursion limit to be explicitly raised. If the value is set to 0, no limit raising is performed.
Emulation.kernel_shutdown
Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether, when the OS terminates the Kernel is shut down. The Kernel shutdown means that Service_PreReset is issued and other clean up activities may be performed. Disabling this may ensure that the system terminates cleanly, even when modules may be acting badly.
Emulation.runtime_limit
Value: 0s
Type: Time in the form: {<number>{s|m|h|d|w|y}}*
Configures the maximum runtime that the system may execute for. After this time, the system will be terminated. A value of 0 disables any limits.
Configuration group 'Error'
Error.invalid_effect
Value: message
Type: One of the strings 'message', 'passthrough'
Controls the handling of returns from SWIs with V set and R0 pointing to invalid memory.
message
will replace the error with a message reporting the address.passthrough
will leave the error block pointing to invalid memory.
Error.nullpointer_effect
Value: ofla
Type: One of the strings 'ofla', 'message', 'passthrough'
Controls the handling of returns from SWIs with V set and R0 = 0.
ofla
will replace the error with a message of 'ofla' (although not the original 'ofla' message).message
will replace the error with a message reporting that a null pointer was used.passthrough
will leave the error block as a null pointer.
Error.unaligned_effect
Value: message
Type: One of the strings 'message', 'passthrough'
Controls the handling of returns from SWIs with V set and R0 pointing to a non-word aligned address.
message
will replace the error with a message reporting the address.passthrough
will leave the error block pointing to invalid memory.
Configuration group 'Execute'
Execute.error_template
Value: Error: %0 (Error number &%1)
Type: str
Configures the template that will be used when the system exits with an error.
The message will be written to the destination set by the output
option.
The template substitutes values from the error:
%1
will be replaced by the error number as a hexadecimal string.%0
will be replaced by the error message.
Execute.exit_template
Value: `
Type:
str`
Configures the template that will be used when the system exits normally.
The message will be written to the destination set by the output
option.
The template substitutes values from the error:
%0
will be replaced by the return code.
Execute.output
Value: stdout
Type: One of the strings 'stdout', 'stderr', 'riscos'
Configures where the messages produced on system exit are sent. The destination can be one of the following values:
stdout
- the host stdout.stderr
- the host stderr.riscos
- the RISC OS VDU stream.
Execute.reset_template
Value: RISC OS Reset requested
Type: str
Configures the template that will be used when the system is reset.
The message will be written to the destination set by the output
option.
Although described as a template, there are currently no substitutions performed.
Configuration group 'Filesystem'
The Filesystem configuration group currently covers two parts of the configuration - that for the file system as a whole (what would be FileSwitch in RISC OS Classic), and the native filesystem (which would be a separate file system).
The native filesystem provides an interface to the host disc, rooted at a location
defined by native_directory
. The files within this directory use the RISC OS
storage convention of appending ,xxx
for filetypes, or ,llllllll,xxxxxxxx
for
fully specified load and exec addresses.
Filesystem.filehandle_max
Value: 255
Type: int
Configures the highest file handle that will be used. File handle usage goes down from the highest file handle. Using file handles greater than 255 may result in some interfaces not working as expected.
Filesystem.filehandle_min
Value: 1
Type: int
Configures the lowest file handle that will be used.
Filesystem.info_use_sysdateformat
Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether *Info
(and *Ex
) use the Sys$DateFormat
variable, (as is documented
in the PRMs), or use a hard-coded date format (as it implemented in RISC OS Classic).
The default in Pyromaniac is to use the variable, as this gives the greatest
flexibility, and produces the same output by default.
Filesystem.mask_timestamp
Value: none
Type: Date time in the form YYYY-MM-DD[THH:MM:SS[.CC]], or a hex string or 'none'
Configures what, if any, timestamp will be used for files on the filesystem. When this
is set a value other than none
, all files will return the timestamp supplied. This can
ensure that tests are consistent.
Filesystem.native_boot_option
Value: run
Type: One of the strings 'none', 'load', 'run', 'exec'
Configures the native filesystem's boot option, which would normally be set with
*OPT 4, <opt>
.
Filesystem.native_directory
Value: .
Type: ValidDirectory
Controls where the native fileystem reads as the root of the disc.
Filesystem.native_freespace
Value: host
Type: 'host', 'error' or Size as a number which may be suffixed by 'K', 'M', 'G', 'T', 'P', or 'E', and '-1'
Configures what should be returned for the free space of the native filesystem. This can be configured to:
- Report a fixed size.
- Report the host system's free space (if possible).
- Raise an error.
Configuration group 'GTK'
GTK.maximum_redraw_rate
Value: 20
Type: int
Configures the maximum rate at which the GTK window will be updated. If this is set too high, the system may spend more time redrawing than executing code. If this is set too low, output may not refresh in a timely manner as it is generated.
GTK.open_at_front
Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether the GTK window will be opened at the front of the stack. By default on some systems the window is opened behind the terminal that launched it. When this option is set, the window should be raised to the front on opening.
Configuration group 'Graphics'
Graphics.implementation
Value: null
Type: str
Configures which implementation will be used for the clipboard. The following implementations are provided:
gtk
- a GTK based application, using cairo graphics as the back end.wxwidgets
- a WxWidgets based application, using cairo graphics as the back end.cairo
- a cario based in-memory graphics system.
Graphics.pointer_off_shape
Value: cross
Type: One of the strings 'default', 'cross', 'none'
Configures the UI pointer shape to use when the RISC OS pointer has been turned off. It can take one of the following values:
default
: Leaves the standard pointer alone.cross
: A system cross pointer shape.none
: No pointer shape will be shown.
Graphics.pointer_on_shape
Value: riscos
Type: One of the strings 'default', 'cross', 'riscos', 'none'
Configures the UI pointer shape to use when the RISC OS pointer has been turned on. It can take one of the following values:
default
: Leaves the standard pointer alone.cross
: A system cross pointer shape.riscos
: The RISC OS pointer shape.none
: No pointer shape will be shown.
Graphics.screen_banks
Value: 2
Type: int
Configures the number of screen banks available for the the display.
Graphics.vsync_rate
Value: 20
Type: float
Configures how regularly the vysnc event is triggered.
Configuration group 'GraphicsCairo'
GraphicsCairo.antialias
Value: no
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether anti-aliasing (smoother lines) are enabled within Cairo. As RISC OS does not expect this, it is disabled by default.
GraphicsCairo.bitmap_font
Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether the RISC OS bitmap font will be used, or a native system font. As RISC OS expects the bitmap font, that is the default.
GraphicsCairo.save_filename
Value: image.png
Type: Regular expression matching: ^.*\.(png|svg|pbm)$
Configures the native filename to which the graphics screen will be saved on exit.
It may be suffixed by .png or .svg to determine the format. The screen is only
saved if the save_on_exit
is enabled.
GraphicsCairo.save_on_exit
Value: no
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether the contents of the screen are saved when the system exits. The
screen will be saved to the filename specified by save_filename
.
GraphicsCairo.video_directory
Value: video
Type: str
Configures the directory into which frames from the graphics system will be
saved. This is only used when video_enable
is set.
GraphicsCairo.video_enable
Value: no
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether each 'frame' of the screen is saved to a file, together with a
script to join them to make a video. The frames will be stored in the directory
specified by video_directory
. The file 'ffmpeg_concat.txt' is also written,
which contains the script necessary to create a video from these images. The
command necessary to create an MP4 video from these files can be found
at the head of the file.
Configuration group 'GraphicsUI'
GraphicsUI.border_colour
Value: &222222
Type: Hexadecimal value, optionally prefixed by '&'.
Configures the colour of the border around the RISC OS screen, between the screen and the window frame. This is a dark grey by default, to differentiate it from the usual black background, but be clearly not part of the screen. Colours are specified in the form '&RRGGBB'.
GraphicsUI.border_size
Value: 4
Type: int
Configures the size of the border around the RISC OS screen, between the screen and the window frame. This is a small value by default, to ensure that curved window borders do not obscure the RISC OS screen content.
GraphicsUI.min_width
Value: 1024
Type: int
GraphicsUI.scale
Value: 1.0
Type: float
Configures the scale factor applied to the Graphics UI as a floating point value. Values larger than 1 will scale the display up. Values smaller than 1 will scale the dispay down.
GraphicsUI.title
Value: RISC OS Pyromaniac
Type: str
Configures the title of the Graphics UI window. Eventually this will include template strings, but currently this is just a bare string.
Configuration group 'Heap'
Heap.clear_alloc_enable
Value: no
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether allocated blocks are cleared by writing a value (clear_value
)
over them. This can help to identify memory that has not been initialised.
Heap.clear_alloc_value
Value: &a110ced3
Type: Hexadecimal value, optionally prefixed by '&'.
Configures the value which will be used to overwrite allocated values when the
clear_alloc_enable
option is set.
Heap.clear_free_enable
Value: no
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether freed blocks are cleared by writing a value (clear_value
)
over them. This can help to identify memory reuse problems.
Heap.clear_free_value
Value: &f0f1f2f3
Type: Hexadecimal value, optionally prefixed by '&'.
Configures the value which will be used to overwrite freed values when the
clear_free_enable
option is set.
Heap.extend_to_nothing_is_error
Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether resizing a heap to nothing is considered to be an error or not. On RISC OS classic this returns a value of -1 for the block pointer. This is not documented, and it's surprising, as it may result in aborts. Pyromaniac defaults to reporting an error, as this may be a bad effect - if you know you're freeing a block, you should really free it.
Heap.maximum_heap_size
Value: 512 M
Type: Size as a number which may be suffixed by 'K', 'M' or 'G', and '-1'
Configures the largest that a heap can be. This limit ensures that we can detect some corruptions, and may detect oversized initialisations.
Heap.minimum_allocation
Value: 12
Type: int
Configures the smallest memory allocation supported by the heap system. Requests for heap blocks will be limited to this minimum size. RISC OS Classic has a minimum of 12.
Configuration group 'Hourglass'
Hourglass.implementation
Value: console
Type: str
Configures the implementation to use for the hourglass. The following implementations are provided:
- 'console' - displays the hourglass status on the console.
- 'vdu' - displays the hourglass status to the VDU stream.
- 'pointer' - displays a hourglass using the graphics pointer.
- 'null' - has no effect for the hourglass.
Configuration group 'Input'
Input.eof_effect
Value: error
Type: One of the strings 'none', 'error', 'escape', 'exit', 'reset'
Configures the effect that EOF (usually ctrl-d) from the terminal has on the system. The effects can be:
none
- EOF is ignored.error
- An error is generated, indicating that EOF was received.escape
- The same effect as pressing the Escape key.exit
- OS_Exit is called, which may exit the current application.reset
- OS_Reset is called,which may exit the system.
Input.flush_output_on_read
Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether the VDU output is explicitly flushed when a character is read from the input stream. This ensures that prompts which do not end in a newline are displayed before input is waited on. Together with the VDU options for flushing, this ensures that the experience of using RISC OS is similar to that of other non-RISC OS applications.
Input.keypress_enable
Value: True
Type: One of the strings 'auto', 'force', 'no'
Controls whether key press events are handled by the system. The key presses events handled by KeyV can be enabled or disabled as needed. When enabled they install a ticker which runs every centisecond, which will slow the system.
Options are:
no
- disables the keypress handlingauto
- enables the keypress handling when the UI requests itforce
- enables the keypress handling even when the UI does not request it
Input.readline_native
Value: no
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether the OS_ReadLine interfaces are passed through the native readline (either GNU or BSD).
If this is enabled, the line input will take the same features as the native readline, such as editing and history. However, whilst line editing is in use, RISC OS will be suspended. No interrupts, callbacks or other events will be passed through the system until the line input is complete. This includes the escape key (usually ctrl-c) which will only take effect after the line has been entered.
If this is disabled, the line input will be handled by the RISC OS key input.
Input.readline_native_history_file
Value: ~/.pyromaniac_history
Type: str
Configures where the native readline system stores the history.
Input.readline_native_history_length
Value: 1000
Type: int
Configures how many lines the native readline system will store in the history file.
Input.readline_native_prompt
Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether the VDU output is tracked to produce a native readline prompt that
matches the output from RISC OS. For example, the *
prompt (CLI$Prompt
) from
the Supervisor or the >
prompt from BASIC will be used as the readline prompt.
If this is disabled, any readline operations which require the whole line to be redrawn will lose the original prompt.
Configuration group 'Internet'
Internet.enable
Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether the Internet module is enabled. If this is disabled, the Socket SWI calls will report errors.
Internet.gifconf_ignore_unknown
Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether SIOCGIFCONF/SIOCOGIFCONF return no information for host interfaces which contain no RISC OS supported address formats. If this is disabled, such interfaces will return their name in the response but with the af_family field set to 0 (which is invalid).
Internet.gifconf_truncate_osockaddr
Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether SIOCGIFCONF truncates interfaces which would not fit into the old sockaddr buffer. Under Internet 5, over long sockaddrs would be truncated (which includes AF_LINK) when they were requested with the SIOCGIFCONF ioctl call. If this is disabled, such over long sockaddrs will instead be omitted from the response.
Internet.tablesize
Value: 128
Type: int
Configures the size of the socket table. This controls how many sockets can be open simultaneously across the whole system. Increasing the size of this may cause problems for clients using Socket_Select, as they may not allocate enough space for the additional bit fields.
Configuration group 'Kernel'
Kernel.boot_fallback
Value: gos
Type: One of the strings 'exit', 'gos', 'bootmenu'
Controls the second operation after booting from the filesystem fails. The options are:
exit
- no further operation.bootmenu
- attempt to boot from the boot menu (and fall back to the supervisor)gos
- start the supervisor
Kernel.boot_from_fs
Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether, after reset, the system will attempt to boot from the filesystem. If booting from the filesystem fails, the configuration option boot_fallback determines what the next operation will be.
Kernel.boot_menu
Value: Resources:$.Resources.BootMenu.BootMenu
Type: str
Controls what path is used to execute the boot menu.
Kernel.da_highvectors
Value: 49
Type: int
Controls the dynamic area number for the high CPU vector area. By default this is the registered dynamic area number.
Kernel.da_zeropage
Value: 48
Type: int
Controls the dynamic area number for zero page. By default this is the registered dynamic area number.
Kernel.interrupt_control_swis
Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether the OS_IntOn and OS_IntOff SWIs are effective or not. If this is disabled, the SWIs will have no effect.
Kernel.reset_banner
Value: no
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether, on a reset, the service for the banner will be issued. If this is disabled, no banner will be shown.
Kernel.reset_bell
Value: no
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether, on a reset, the BEL will be issued. When set, the service for the the bell will be issued, which will result in a sound being issued through either the Sound system or the console bell.
Kernel.reset_modechange
Value: no
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether, on a reset, a mode change will be issued. If this is disabled, the mode change is not issued which has effects for the ANSIText VDU implementation which will not clear the screen.
Kernel.swi_recursion_limit
Value: 0
Type: int
Controls the recursion depth for SWI calls. It is possible for SWI calls to recurse until the SVC stack is exhausted. However, this can be artificially forced to fail at an earlier point by setting this limit. If the value is set to 0, no SWI recursion limitting is performed.
Kernel.swimisuse_omit_swis
Value:
Type: Comma separated list of SWI numbers or names
Configures which SWIs we will never warn about if the debug option 'swimisuse' is enabled.
It is common to find that modules and interrupt handlers use some SWI calls without the X-bit. SWIs such as OS_ReadMonotonicTime, for example, would never be expected to report an error - or if they did, you have much bigger problems. Thus, these might be used in privileged modes without fear that bad effects will happen.
This list controls which SWI numbers will be ignored if a warning would be generated.
Kernel.trace_ignores_write_swis
Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether the OS_Write* SWIs will be ignored by the tracing of SWIs.
Configuration group 'LegacyBBC'
LegacyBBC.envelope_stub
Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether we provide a stub for ENVELOPE (OS_Word 8) which does nothing. When this option is enabled, the ENVELOPE command will do nothing. When it is disabled, the ENVELOPE command will give an error.
By default this option is enabled to make it easier to port programs from the BBC - on RISC OS Classic, unknown OS_Word calls would not generate errors.
Configuration group 'MAC'
The MAC group allows the ethernet MAC address to be configured. The ethernet MAC address is returned by OS_ReadSysInfo 4.
MAC.high
Value: &0
Type: Hexadecimal value, optionally prefixed by '&'.
MAC.low
Value: &0
Type: Hexadecimal value, optionally prefixed by '&'.
Configuration group 'MMIO'
MMIO.enabled
Value: no
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether the memory mapped I/O is able to be used within Pyromaniac. MMIO is very expensive in processing time. It is not currently used within the current implementation of Pyromaniac.
Configuration group 'Memory'
Memory.statistics
Value: no
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether the statistics for the internal Memory objects are collected during execution. These statistics show how much the Memory object is used, and the distribution of the operations performed by the Pyromaniac system. Whilst largely for debugging, this provides information on how the OS itself is accessing memory and may indicate bottlenecks.
Configuration group 'MemoryMap'
The MemoryMap configuration group controls the locations and sizes of memory areas within the Pyromaniac system. Each memory area has 3 settings:
base
, which defines the low address for the memory areasize
, which defines how large the area is on bootmaxsize
, which defines the largest size the area may grow to be.
MemoryMap.appspace_base
Value: &8000
Type: Hexadecimal value, optionally prefixed by '&'.
Configures the base address for application space. Setting this to anything other than &8000 is unlikely to work.
MemoryMap.appspace_maxsize
Value: 48 M
Type: Size as a number which may be suffixed by 'K', 'M' or 'G', and '-1'
Configures the maximum size of the application space.
MemoryMap.appspace_size
Value: 1024 K
Type: Size as a number which may be suffixed by 'K', 'M' or 'G', and '-1'
Configures the initial size of the application space.
MemoryMap.irqstack_base
Value: &4000000
Type: Hexadecimal value, optionally prefixed by '&'.
Configures the base address of the IRQ stack area. The stack must have its base at a megabyte boundary.
MemoryMap.irqstack_maxsize
Value: 16 K
Type: Size as a number which may be suffixed by 'K', 'M' or 'G', and '-1'
Configures the maximum size of the SVC stack area. It is unlikely that resizing the IRQ stack at runtime will function well.
MemoryMap.irqstack_size
Value: 16 K
Type: Size as a number which may be suffixed by 'K', 'M' or 'G', and '-1'
Configures the initial size of the SVC stack area.
MemoryMap.rma_base
Value: &7000000
Type: Hexadecimal value, optionally prefixed by '&'.
Configures the base address of the module area.
MemoryMap.rma_maxsize
Value: 15 M
Type: Size as a number which may be suffixed by 'K', 'M' or 'G', and '-1'
Configures the maximum size of the module area.
MemoryMap.rma_size
Value: 1024 K
Type: Size as a number which may be suffixed by 'K', 'M' or 'G', and '-1'
Configures the initial size of the module area.
MemoryMap.rom_base
Value: &3800000
Type: Hexadecimal value, optionally prefixed by '&'.
Configures the base address of the ROM area.
MemoryMap.rom_maxsize
Value: 8 M
Type: Size as a number which may be suffixed by 'K', 'M' or 'G', and '-1'
Configures the maximum size of the ROM area.
MemoryMap.rom_size
Value: 1024 K
Type: Size as a number which may be suffixed by 'K', 'M' or 'G', and '-1'
Configures the initial size of the ROM area.
MemoryMap.svcstack_base
Value: &4100000
Type: Hexadecimal value, optionally prefixed by '&'.
Configures the base address of the SVC stack area. The stack must have its base at a megabyte boundary.
MemoryMap.svcstack_maxsize
Value: 32 K
Type: Size as a number which may be suffixed by 'K', 'M' or 'G', and '-1'
Configures the maximum size of the SVC stack area. It is unlikely that resizing the SVC stack at runtime will function well.
MemoryMap.svcstack_size
Value: 32 K
Type: Size as a number which may be suffixed by 'K', 'M' or 'G', and '-1'
Configures the initial size of the SVC stack area.
MemoryMap.sysheap_base
Value: &4109000
Type: Hexadecimal value, optionally prefixed by '&'.
Configures the base address of the system heap area. The system heap is used for all internal Pyromaniac allocations.
MemoryMap.sysheap_maxsize
Value: 3040 K
Type: Size as a number which may be suffixed by 'K', 'M' or 'G', and '-1'
Configures the maximum size of the system heap area. The system heap is used for all internal Pyromaniac allocations.
MemoryMap.sysheap_size
Value: 128 K
Type: Size as a number which may be suffixed by 'K', 'M' or 'G', and '-1'
Configures the initial size of the system heap area. The system heap is used for all internal Pyromaniac allocations.
MemoryMap.undstack_base
Value: &8400000
Type: Hexadecimal value, optionally prefixed by '&'.
Configures the base address of the UND stack area. The stack must have its base at a megabyte boundary.
MemoryMap.undstack_maxsize
Value: 16 K
Type: Size as a number which may be suffixed by 'K', 'M' or 'G', and '-1'
Configures the maximum size of the UND stack area. It is unlikely that resizing the UND stack at runtime will function well.
MemoryMap.undstack_size
Value: 16 K
Type: Size as a number which may be suffixed by 'K', 'M' or 'G', and '-1'
Configures the initial size of the UND stack area.
MemoryMap.zeropage_enable
Value: no
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether zero page is given memory or not. If this is disabled, access to zero page will cause an abort.
Configuration group 'MessageTrans'
MessageTrans.support
Value: simple
Type: One of the strings 'none', 'simple', 'full'
Controls how the MessageTrans module functions. It can operate with different levels of support, where to make the system faster, or less encumbered by parts of the OS that do not exist.
none
: Makes all file open requests fail.simple
: Makes all file open requests succeed, but the actual files will never be used, and the response will be the tokens, or the default values.full
: Provides as much functionality of MessageTrans as is possible.
Configuration group 'Modules'
Modules.default_postfix
Value: Base
Type: str
Configures what the default module postfix should be for the base instance.
Modules.rominit_errors_fatal
Value: no
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether, during initialisation the ROM modules which produce errors are fatal for the system.
Modules.rominit_noisy
Value: no
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether, during initialisation the ROM module names and any errors are displayed. Mirrors a similar option in the classic Kernel.
Modules.unplug
Value: ROM:
Type: UnplugList
Configures which modules will not be initialised from the internal ROM, or any extension ROMs. This is distinct from the NVRAM configuration which unplugs modules (which is not currently implemented).
The configuration is supplied as a list of ROM sections and module
names to be unplugged. The ROM sections and modules are listed in a ;
separated list, in the form <section-name>:<modules>
, where <modules>
is a ,
separated list.
Valid section names are:
rom
- the system ROM populated by Pyromaniacextrom-<number>
- a numbered extension ROM.card-<number>
- a numbered expansion card.nic
- the network expansion card.
For example:
rom:ddeutils
- would unplug DDEUtils from the system ROM.extrom-1:Podule
- would unplug the podule manager from extension ROM 1.extrom-1:Podule;rom:ddeutils
- would unplug both the modules named in the prior examples.rom:ddeutils,taskwindow
- would unplug DDEUtils and TaskWindow from the system ROM.
Configuration group 'NVRAM'
NVRAM.backingfile
Value: none
Type: str
Configures the backing file used for the NVRAM configuration data, or 'none' to disable reading and writing the configuration data. When set, the backing file will be loaded on boot, and written out whenever the configuration is changed.
NVRAM.format
Value: auto
Type: One of the strings 'auto', 'bytes', 'keyvalue'
Configures how the configuration backing file will be read and written. The format of the backing file can be:
auto
- decide on the format based on the size of the file.bytes
- a file containing 240 bytes.keyvalue
- a file containing colon separated byte: value format lines.
Configuration group 'OSConfirm'
OSConfirm.keys_no
Value: n
Type: str
Configures the characters which will be displayed as a 'no' response to the confirmation
request. Actually, any key other than those defined in keys_yes
will be treated as a
'no' response.
OSConfirm.keys_yes
Value: y
Type: str
Configures the characters which will be displayed and accepted as a 'yes' response to the confirmation request. Lower case versions of this character will also be accepted.
OSConfirm.shape
Value: alternate
Type: One of the strings 'classic', 'alternate'
Configures the shape used for the pointer which is displayed when the OS_Confirm call is made:
- classic: RISC OS Classic confirm pointer.
- alternate: Alternate form.
RISC OS Classic form uses a 'Y' to indicate the key for a positive response. RISC OS Pyromaniac defaults to an alternate form which uses a check mark to indicate a positive response.
A check mark is recognised in more countries as a positive response than the 'Y' character (and we don't have any Internationalisation in Pyromaniac yet).
OSConfirm.show_message
Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether a message is displayed when the OS_Confirm call is made.
OSConfirm.show_pointer
Value: if-active
Type: One of the strings 'never', 'always', 'if-active'
Configures how the pointer will be displayed when the OS_Confirm call is made:
- never: Never changes the pointer shape.
- always: Always changes the pointer shape.
- if-active: Changes the pointer shape if the pointer is already active.
RISC OS Classic uses the behaviour 'if-active', so Pyromaniac defaults to this.
Configuration group 'OSMemory'
The OSMemory configuration group controls the size reported for the memory areas from OS_Memory 8 (read memory amounts). Some of the areas are able to be calculated dynamically, whilst other areas have no meaning and can be configured to fake values.
OSMemory.amount_dram
Value: dynamic
Type: Size suffixed by 'K', 'M' or 'G', or 'dynamic' to calculate at runtime
Configures the amount of memory reported by OS_Memory 8 for the DRAM. The value may be calculated dynamically by setting the value to 'dynamic'.
OSMemory.amount_iospace
Value: 0
Type: Size as a number which may be suffixed by 'K', 'M' or 'G', and '-1'
Configures the amount of memory reported by OS_Memory 8 for the I/O space. As there is no concept of I/O in Pyromaniac, this defaults to 0.
OSMemory.amount_rom
Value: dynamic
Type: Size suffixed by 'K', 'M' or 'G', or 'dynamic' to calculate at runtime
Configures the amount of memory reported by OS_Memory 8 for the ROM. The value may be calculated dynamically by setting the value to 'dynamic'.
OSMemory.amount_softrom
Value: dynamic
Type: Size suffixed by 'K', 'M' or 'G', or 'dynamic' to calculate at runtime
Configures the amount of memory reported by OS_Memory 8 for the soft ROM. The value may be
calculated dynamically by setting the value to 'dynamic'. The dynamic value depends on
whether we claim that the ROM is softloaded in the platformsupport.os_rom
configuration
setting.
OSMemory.amount_vram
Value: 0
Type: Size as a number which may be suffixed by 'K', 'M' or 'G', and '-1'
Configures the amount of memory reported by OS_Memory 8 for the VARM. As there is no concept of VRAM in Pyromaniac, this defaults to 0.
Configuration group 'PlatformSupport'
The PlatformSupport configuration group controls the response from OS_ReadSysInfo 8.
PlatformSupport.additional_processor
Value: no
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether the flag for supporting the second processor will be set.
PlatformSupport.os_ram
Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether the flag for the OS being RAM loaded will be set. It defaults to enabled, because the OS is effectively RAM loaded (and isn't protected either).
PlatformSupport.os_rotated_loads
Value: no
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether the flag for whether the OS uses rotated loads will be set. It defaults to disabled, because the 'OS' doesn't actually do any ARM-based load operations, rotated or not.
PlatformSupport.os_unaligned_access
Value: no
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether the flag for whether the OS uses unaligned memory accesses will be set. It defaults to disabled, because the 'OS' doesn't actually do any unaligned memory accesses, or any ARM-based memory accesses at all for that matter.
PlatformSupport.pci
Value: no
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether the flag for supporting PCI cards will be set.
PlatformSupport.podules
Value: no
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether the flag for supporting podules will be set.
Configuration group 'Podule'
Podule.extensionrom1
Value: `
Type:
str`
Configures the filename of the ROM image to load into Extension ROM 1. The file should be a ROM image suitable for use with a 32bit operating system. Any recognised modules will be provided through the Podule system, but the Kernel will not be present.
For the loading to work, the linkage address of the ROM must be available in memory. This
may mean that the Pyromaniac ROM memory needs to be moved away by changing the
memorymap.rom_base
option to a different base (0x8800000 may be a suitable location).
It is likely that modules in the ROM will need to be unplugged with the modules.unplug
option.
At present, only Select-style 32 bit ROMs will function with the loader provided.
Configuration group 'Pointer'
Pointer.colours
Value: wimp
Type: One of the strings 'black', 'wimp'
Configures the colours that are used for the pointer by default. RISC OS Classic defaults to all the pointer colours being black. However, most uses will expect the colours to be those used by the Wimp, so this is what RISC OS Pyromaniac selects by default.
Pointer.enable
Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether the pointer is polled for events from the UI. When enabled, UI clicks will be passed to the mouse buffer and movements will move the mouse.
Pointer.max_height
Value: 32
Type: int
Configures the maximum height of the pointer allowed by the system. RISC OS Classic only allows a pointer 32 pixels high. RISC OS Pyromaniac allows larger pointers, but by default we set the same limits as RISC OS Classic.
Pointer.max_width
Value: 32
Type: int
Configures the maximum width of the pointer allowed by the system. RISC OS Classic only allows a pointer 32 pixels wide. RISC OS Pyromaniac allows larger pointers, but by default we set the same limits as RISC OS Classic.
Configuration group 'PowerControl'
PowerControl.poweroff_support
Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether the power control operations (OS_Reset &OFF and Portable) are supported.
Configuration group 'ProgEnv'
ProgEnv.cli_size
Value: 1024
Type: Size as a number which may be suffixed by 'K', 'M' or 'G', and '-1'
Configures the default length of the CLI supported by the environment. On early RISC OS versions this was 256. With RISC OS 4, it was increased to 1024. Lengths longer than 256 are commonly not supported by BASIC tools, and many other tools may fail with longer strings.
ProgEnv.exception_errors_show_region
Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0
Control whether, on an exception, the error that is generated includes information about the region of the aborts. This was not available in RISC OS classic, but is very useful for debugging.
ProgEnv.exception_show_registers
Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0
Control whether, on an exception, the register dump is written out to the VDU output stream. This may aid in debugging, especially in the case where error handlers themselves are faulty.
Configuration group 'Pyro'
Pyro.reset_effect
Value: reboot
Type: One of the strings 'exit', 'reboot'
Configures how pyro deals with a request to reset the system:
exit
- always caauses the system to exitreboot
- boot the statem again
Pyro.return_rc
Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether the tool will return the Sys$ReturnCode from the last run process or not. When this option is enabled, the command return code will be set to the value of the Sys$ReturnCode on return from the last command. When this option is disabled, the command return code will be 0 unless an error occurred.
Pyro.stop_on_failing_rc
Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether the execution of actions by the tool will check the Sys$ReturnCode variable for non-0 values. When this option is enabled, a non-0 return code is given, command execution will stop and the system will exit. When this option is disabled, a non-0 return code is ignored. The Obey module's execution of files is closesr to the effect of this option being disabled.
Pyro.system_boot
Value: no
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether the system will go through the normal system boot sequence (filesystem boot, bootmenu, supervisor, as configured) or not.
Configuration group 'PyromaniacModule'
PyromaniacModule.config_allow
Value: `
Type:
listlower`
Configures which configuration groups are allowed to be configured by the *PyromanicConfig command. The group names are given in a comma-separated list. If this list is empty, all groups are allowed. If groups are listed, then any configuration which is not named in those groups will give an error.
PyromaniacModule.config_deny
Value: `
Type:
listlower`
Configures which configuration groups are not allowed to be configured by the *PyromanicConfig command. The group names are given in a comma-separated list. If this list is empty, all groups are allowed. If groups are listed, then any configuration which is named in those groups will give an error.
PyromaniacModule.config_enable
Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether the *PyromaniacConfig command is allowed to be used. If this is disabled, the command will return an error.
PyromaniacModule.debug_enable
Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether the *PyromaniacDebug command is allowed to be used. If this is disabled, the command will return an error.
PyromaniacModule.enable
Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether the Pyromaniac module is able to function. If this is disabled, the Pyromaniac commands will return errors.
PyromaniacModule.hostcommand_ansiescapes
Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether the *PyromanicHostCommand output is converted from ANSI control codes to RISC OS control codes. Only a very limited subset of the terminal controls are supported. If this is disabled, the output from the host command will be passed directly to the RISC OS VDU stream.
PyromaniacModule.hostcommand_cwd_riscos
Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether the *PyromaniacHostCommand executes within the native working directory, if there is one. When enabled, the commands will run with the working directory set to the equivalent location on the native filesystem. When disabled, the working directory will be unaffected.
PyromaniacModule.hostcommand_enable
Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether the *PyromanicHostCommand is allowed to be used. If this is disabled, the command will return an error.
PyromaniacModule.hostcommand_output_encoding
Value: utf-8
Type: str
Configures what encoding the output from *PyromanicHostCommand is reported in. Most host system tools use UTF-8 as their encoding. This means that to be rendered correctly in RISC OS, the UTF-8 characters must be re-encoded to the current alphabet. This option controls whether the characters from the host command are treated as UTF-8, or some other encoding. Encoding names are those used by Python (not the alphabets used by RISC OS).
The configuration may also use 'identity' to pass through characters directly to the RISC OS system.
PyromaniacModule.hostcommand_print_rc
Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether the *PyromanicHostCommand reports the return code from the host command by printing to the VDU stream at the end of its execution. If this is disabled, no message will be printed.
Whether this option is enabled or not, the Sys$ReturnCode variable will be updated.
PyromaniacModule.timing_enable
Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether the *PyromaniacTiming command is allowed to be used. If this is disabled, the command will return an error.
PyromaniacModule.watchpoint_enable
Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether the *PyromaniacWatchpoint command is allowed to be used. If this is disabled, the command will return an error.
Configuration group 'ROMInformation'
The ROMInformation configuration group controls the values returned by OS_ReadSysInfo 9. Normally these values would be encoded in the end of the ROM image. However, there is no fixed ROM for Pyromaniac, so these may be configured here.
Any of the ROMInformation strings may contain a '\n' sequence to embed a newline in the information string.
ROMInformation.builddate
Value: Tue,17 Nov 2020.23:33:21
Configures the build date for the system. The build date was recorded with each image to ensure that if a ROM was rebuilt from an earlier part number, it would be distinguishable. In Pyromaniac this defaults to the current date and time at the time of execution. The string is intended to be human readable.
ROMInformation.dealername
Value: Gerph
Configures the dealer name for the system. The dealer name was intended to be used for ROMs customised by dealers, to ensure that they were distinguishable from the others. The intent was that the part number was only interpretable together with the dealer name.
ROMInformation.hardwareplatformname
Value: Darwin/x86_64
ROMInformation.osdescription
Value: RISC OS Pyromaniac
Configures the printable OS description for the system.
ROMInformation.osname
Value: RISC OS Pyromaniac
Configures the name of the Operating System, usually in the form:
RISC OS [<variant>] [Select] [\[Beta\]]
ROMInformation.partnumber
Value: None
Configures the part number of the system. The part number was used by RISCOS Ltd to track releases through their artifact repository, with each released build being tracked and both reproducible and recorded. Usually the part numbers took the form:
YYYYMMDD-XXX
or YYYYMMDD-iii-system
ROMInformation.useraddress
Value: None
Configures the address of the user who registered the system. The address would be displayed on startup, to give a little more customisation to the ROM images.
ROMInformation.username
Value: None
Configures the user name who registered the system. The user name would be displayed on startup, to give a little more customisation to the ROM images.
Configuration group 'Resolver'
Resolver.enable
Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether the Resolver module is able to function. If this is disabled, the Resolver SWIs will return errors.
Configuration group 'Sound'
The Sound configuration group controls the way in which the SoundChannels module plays sounds. The SoundChannels module uses the host MIDI functions to provide audible effects. The sound channel is mapped to the MIDI channel (although only 8 channels are supported, like RISC OS). The RISC OS voices are mapped to MIDI instruments, with a default set of instruments selected to sound close to the originals.
The voice_*
configuration options all have the same configuration format:
default
- never configure anything (leaves the channel configuration alone)
<program-number>
- set a program number (1-128) within bank 121 (GM1 Sound Set)
<program-number>:<msb>
- set a program number (1-128) within a bank, given the MSB (1-128)
<program-number>:<msb>:<lsb>
- set a program number (1-128) within a bank, given the MSB (1-128) and LSB (1-128)
<name>
- set a program number to a given instrument in the GM1 Sound Set
<name>:<lsb>
- set a program number to a given instrument in the GM1 Sound Set, with LSB
Sound.bbc_style
Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether the SoundChannels module functions like RISC OS, or like the BBC. The difference is in how sounds are queued and where the flags are defined.
BBC style:
- Sounds are queued, and on completion of one note, the next note on the channel is played.
- Flags are present in the channel.
RISC OS style:
- Sounds are played immediately, replacing any currently playing notes.
- Flags are present in the amplitude.
Sound.enable_midi
Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether the SoundChannels module uses the MIDI system for its sound. When disabled, the sound system will go through the motions but will not actually generate sounds.
Sound.voice_percussion_medium
Value: Melodic Tom
Type: Voice configuration, such as GM1 instrument name
Sound.voice_percussion_noise
Value: Bagpipe
Type: Voice configuration, such as GM1 instrument name
Sound.voice_percussion_snare
Value: Synth Drum
Type: Voice configuration, such as GM1 instrument name
Sound.voice_percussion_soft
Value: Woodblock
Type: Voice configuration, such as GM1 instrument name
Sound.voice_stringlib_hard
Value: Electric Guitar (Clean)
Type: Voice configuration, such as GM1 instrument name
Sound.voice_stringlib_pluck
Value: Acoustic Guitar (Nylon)
Type: Voice configuration, such as GM1 instrument name
Sound.voice_stringlib_soft
Value: Violin
Type: Voice configuration, such as GM1 instrument name
Sound.voice_stringlib_steel
Value: Acoustic Guitar (Steel)
Type: Voice configuration, such as GM1 instrument name
Sound.voice_wavesynth_beep
Value: Electric Piano 1
Type: Voice configuration, such as GM1 instrument name
Configuration group 'SysLog'
SysLog.default_flush
Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether reports to SysLog are written out immediately, or only written out on an explicit flush.
In the original module, and the reimplementation, the output would be buffered and written out on a delay in the background. This is not currently implemented.
SysLog.default_loglevel
Value: 125
Type: int
Configures the default log level which is set on log files. This is 125 by convention with the original module.
SysLog.log_directory
Value: $.Logs
Type: str
Configures the directory to which log files will be written. As no boot sequence will commonly have been used, this defaults to '$.Logs'.
SysLog.timestamp_format
Value: %b %d %H:%M:%S
Type: str
Configures the format used by the timestamps in the SysLog file output. This defaults to the same format as the orignal module. The format string is in the strftime style.
Configuration group 'SystemBell'
SystemBell.bell_type
Value: sound
Type: One of the strings 'sound', 'console', 'message'
Configures how the External Bell service should be handled. This service is issued for VDU 7, and can be configured to operate in different manners on different systems. The types of bell supported are:
sound
- call Sound_Control, with the configured sound parameters from OS_Byte. This is how RISC OS usually handles the VDU 7 bell.console
- writes a BEL to the console, which will perform its own handling of the bell.message
- write a message to the VDU output stream.
Configuration group 'SystemInformation'
The SystemInformation configuration controls the information returned about the system through a few of the core SWI calls.
SystemInformation.osbyte0_machinetype
Value: 6
Type: int
Configures the value used for the machine type returned by OS_Byte 0. The default value is a machine type for ARM based systems.
SystemInformation.osbyte129_osversion
Value: &ae
Type: Hexadecimal value, optionally prefixed by '&'.
Configures the value used for the OS version returned by OS_Byte 129 (INKEY(-256)). The default value is a version allocated to Pyromaniac.
SystemInformation.platform_class
Value: 16
Type: int
Configures the value used for the platform class returned by OS_ReadSysInfo 8. The default value is the class allocated to Pyromaniac.
Configuration group 'TaskManager'
TaskManager.taskmanager_task
Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether the TaskManager lists itself as a task in the enumeration given by TaskManager_EnumerateTasks.
Configuration group 'TaskWindow'
TaskWindow.in_taskwindow
Value: no
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether the TaskWindow module reports that we are in a TaskWindow or not.
Configuration group 'Territory'
Territory.write_direction
Value: ltr-ttb-horizontal
Type: Regular expression matching: (ltr|rtl)-(ttb|btt)-(horizontal|vertical)
Configures the flags returned from Territory_WriteDirection.
The values take the form:
* ltr
or rtl
for left-to-right or right-to-left
* ttb
or btt
for top-to-bottom or bottom-to-top
* horizontal
or vertical
for the direction that is used primarily.
Configuration group 'Throwback'
Throwback.console_colour
Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether colour is used in the output in the 'console' implementation.
Throwback.implementation
Value: console
Type: str
Configures the implementation to use for throwback reported through the DDEUtils module. The following implementations are provided:
console
- displays the throwback reports on the console.null
- has no effect for the throwback reports.posturl
- posts throwback reports to theurl
.
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 numberreason_name
- the reason name ('Processing', 'Error', 'Info')filename
- the RISC OS filename being reportedurl' - 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 'Time'
Time.offset
Value: 0s
Type: Time in the form: [+|-]{<number>{s|m|h|d|w|y}}*
Configures the time offset applied to the current host clock within RISC OS. The offset is a string which contains the offset in the form of a decimal followed by the single character units, repeated, optionally preceded by a '-' sign. Units supported are:
s
- secondsm
- minutesh
- hoursd
- daysw
- weeksy
- years
For example:
1h 15m
- would add 1 hour and 15 minutes to the current time.-1w
- would subtract 1 week from the current time.
Configuration group 'Timings'
The Timings configuration group manages the data collected about the time spent in different areas, and the number of times those areas are entered. The data is reported when the system is exited. The data which is recorded falls into the following groups:
- SWI execution - times each SWI's total execution time. This may include the time spent within the dispatch to executed code, and calls to other SWIs.
- Emulated ARM execution - times the execution of the ARM code. This only includes the ARM code, and not any SWIs that it might call.
- Timer execution - times the execution of calls to timer routines registered with OS_CallEvery/OS_CallAfter.
- Callback execution - times the execution of calls to the transient callback routines registered wtih OS_AddCallBack.
- Non-emulation execution - times the internal overhead of the time not spent executing ARM code. Because of reentrancy, this might include calls into the ARM execution as well.
Timings.execute
Value: no
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether non-SWI timings are collected during execution and reported when the system exits.
Timings.swi
Value: no
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether SWIs counts and timings are collected during execution and reported when the system exits.
Configuration group 'Trace'
Trace.function_registers
Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether when the execution enters a function, the trace will report the registers.
Trace.output
Value: stderr
Type: One of the strings 'stdout', 'stderr', 'riscos'
Configure where the trace output will be send. The output configuration can be:
stdout
- trace to stdoutstderr
- trace to stderrfile:...
- trace to a named file
Trace.recent_blocks_count
Value: 10
Type: int
Configures how many blocks of recent execution will be reported in exceptions.
Trace.report_python_traceback
Value: no
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether reports such as exceptions will include the traceback within the Python code as well as within the emulated system. This may be useful when the location is passing through a Pyromaniac interface which does not otherwise appear in the traceback.
Trace.report_relative_instructions
Value: 15
Type: int
Controls whether reports such as exceptions will include details of the recent blocks that were executed if that information is available.
Trace.show_disassembled_word
Value: no
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether disassembly during a trace will include the instruction word that was executed. Normally this is omitted.
Trace.show_referenced_pointers
Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether disassembly during a trace will include details of the pointer values in registers.
Trace.show_referenced_registers
Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether disassembly during a trace will include details of the registers which are referenced in the instruction. The registers reported are the values before the instruction is executed.
Trace.stack_depth_indicator
Value: no
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether trace lines include a stack indicator using '|' markers to show how deep the stack is at a given point.
Trace.stack_depth_width
Value: 24
Type: int
Configures how many characters are used for the stack indicator when it is in use. If the stack markers exceed this width, it will be made longer.
Trace.stack_value
Value: no
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether trace lines include the value of the stack pointer.
Trace.switraps
Value:
Type: Comma separated list of hexadecimal SWI numbers, or names
Configures the list of SWIs numbers, names or prefixes which will be trapped. When the SWIs listed are executed, the details of that execution will be recorded to the trace output.
Trace.tracepoints
Value:
Type: Comma separated list of hexadecimal addresses, or function names
Configures the list of addresses which will be watched for execution. When the address is executed, the details of that execution will be recorded to the trace output.
Trace.watch_lowvectors
Value: yes
Type: One of the strings 'no', 'read', 'write', 'yes'
Controls whether the low CPU vector region is implicitly registered as a watchpoint.
Trace.watchpoints
Value:
Type: Comma separated list of hexadecimal addresses
Configures the list of addresses which will be watched for changes. When the address is accessed, the details of that access will be recorded to the trace output.
Configuration group 'Twin'
Twin.command
Value: nano -R
Type: str
Configures the command that will be invoked to edit the source. This command will be passed the name of the temporary file which should be edited. After the command returns, the file will be loaded and returned to BASIC.
Twin.enable
Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether the Twin module is able to function. If this is disabled, the Twin commands will return errors.
Configuration group 'URI'
URI.acceptable_schemes
Value: http,https,ftp
Type: listlower
Configures which schemes are able to be launched in the host system by the URI module.
URI.enable
Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether the URI module is able to function. If this is disabled, the URI SWIs will return errors.
Configuration group 'UniqueId'
The UniqueID configuration group allows the machine unique ID to be configured. The UniqueID is returned by OS_ReadSysInfo 2 and 5.
UniqueId.high
Value: &decade
Type: Hexadecimal value, optionally prefixed by '&'.
UniqueId.low
Value: &da2ed
Type: Hexadecimal value, optionally prefixed by '&'.
Configuration group 'UserV'
UserV.effect
Value: message
Type: One of the strings 'null', 'message', 'error', 'warning'
Configures how the UserV handler should function when it is called. By default on RISC OS it does nothing, and it is discouraged from being used. However, it may be useful for certain debugging actions. In particular, being able to trigger a warning through the trace system may help to diagnose issues dynamically.
Effects available are:
null
- Do nothingmessage
- Displays a message to the VDU streamerror
- Raises an errorwarning
- Reports a warning through the trace system
Configuration group 'VDU'
VDU.alphabet
Value: Latin1
Type: str
Configure the RISC OS alphabet used for the VDU output. The alphabet can be one of the alphabets used by RISC OS which are supported by Pyromaniac. Use the *Alphabets command to list these. The output from the VDU system (either through the graphics system or the console) will be converted from this alphabet to the output_encoding. Usually this is set to 'Latin1'.
VDU.flush
Value: position
Type: One of the strings 'line', 'char', 'position'
Controls when console output is flushed. On RISC OS Classic, output would always appear when it is written. This isn't how most unix-like tools function. They usually buffer output when they're run in a pipe, either with lines or larger chunks. This is more efficient as the number of system calls are reduced and the user mode process can do more work. Because RISC OS does not have this concept, this setting tries to balance the efficiency with responsiveness.
-
position
will flushes output at the end of a line or when the cursor is explicitly moved. This is a good compromise most of the time. -
line
will flush only at the end of the line. -
char
will cause a flush for every character, which is the least efficient but most consistent with RISC OS Classic.
The default setting is 'position'. Regardless of the setting, the output will be flushed if input is requested.
VDU.implementation
Value: plain
Type: str
Configures the implementation used for the VDU system. This controls where the
VDU system sends its output (in addition to the graphics system). Use
--list-implementations
to show the VDU implementations.
VDU.mode
Value: 27
Type: int
Configures the RISC OS mode to be selected on boot. Only mode numbers can be supplied.
VDU.newline_format
Value: LF
Type: One of the strings 'lf', 'lfcr', 'crlf', 'cr'
Controls what SWI OS_NewLine will generate - line feeds, carriage return, both
or none. By default, this is configured to just LF
, which differs from the
RISC OS default. This is, however, the expected output for most unix-like tools,
so should produce comparable results to other native tools. RISC OS Classic
would use LFCR
.
VDU.output_encoding
Value: utf-8
Type: str
Configure the Python encoding that will be used for the console output. Usually this is set to 'UTF-8', but it can also be configured to 'identity' to pass through the VDU output without an encoding translation.
VDU.paging
Value: none
Type: One of the strings 'none', 'console', 'shift'
Controls how paged mode (VDU 14) is handled. The following configurations are available: * 'console': A prompt will appear for a key press to continue to the next page. * 'none': Paged mode will still be counted, but it will be as if the paging was always continued immediately. * 'shift': The 'shift' keys will continue paged output, as under RISC OS Classic. This will only be effective when the input system can detect the shift key (such as in the graphics UIs).
VDU.show_controls
Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether unrecognised control codes will be displayed as
[<control sequence>]
. When disabled, no output will occur for unrecognised
control codes.
Configuration group 'VDUANSIText'
VDUANSIText.change_terminal_size
Value: no
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether the terminal size will be changed on a mode change.
VDUANSIText.closest_match
Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether failing to match the primary colours or 8 bit colour matching exactly falls back to finding a closest of those colours. This would not be used if the 24 bit matching was enabled.
VDUANSIText.support_24bit
Value: no
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether 24 bit ANSI colour selection using the 38;2m and 48;2m codes is used. These 24 bit codes will only be used when the primary colours and the 8bit colour codes do not match.
VDUANSIText.support_8bit
Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether 8 bit ANSI colour selection using the 38;5m and 48;5m codes is used. These 8bit codes will only be used when the primary colours do not match.
VDUANSIText.support_primary
Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether the primary colour selection using 30-7m and 40-7m codes is used. These codes are used with support_primarybold to select bold foreground colours.
VDUANSIText.support_primarybold
Value: yes
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether the primary colour selection for foreground colours also uses bold colour selection. Without this, the primary colour will be used for the full intensity colours.
Configuration group 'WX'
WX.maximum_redraw_rate
Value: 20
Type: int
Configures the maximum rate at which the wxWidgets window will be updated. If this is set too high, the system may spend more time redrawing than executing code. If this is set too low, output may not refresh in a timely manner as it is generated.
Configuration group 'WimpReportErrorBox'
WimpReportErrorBox.disable_beep
Value: no
Type: Boolean state in the form true/false, yes/no, or 1/0
Controls whether the Wimp_ReportError beeps (when not disabled in the call). If enabled, the beep will be issued through the System Bell interface (VDU 7, Service_SystemBell))
WimpReportErrorBox.implementation
Value: vdu
Type: str
Configures the implementation to use for the Wimp_ReportError system. This allows the type of error reports to be controlled. The current implementations that are provided are:
null
- always reports the cancel operation.vdu
- reports messages to the RISC OS VDU stream, and accepts input from the input stream.easygui
- uses the EasyGUI python package to provide a host interface. This implementation cannot be used in conjunction with other UI interfaces.