Resources

Documentation
Diagrams
Example code

Documentation

2022Pyromaniac documentation

Download

Documentation for the Pyromaniac system is available as links on this site, but can also be downloaded here in a zip.

Updated for 2022.

2022API documentation

Download

A few of the API changes are documented. Mostly the OS works as you would expect, so there's little need to provide additional documentation.

Updated for 2022.

Diagrams

A number of diagrams were created about Pyromaniac and for use with it. Some of these diagrams are included here.

2020Architecture diagram

(Full size image)

Architecture diagram of the Pyromaniac system.

2020Execution flow chart

(Full size image)

Simple flow chart showing the core of the execution within Pyromaniac. The actual processing of SWI calls is significantly more complex, but the model used at the core has not really changed since the early versions of Pyromaniac.

2020Key reading flow chart

(Full size image)

The operation of reading a key is quite involved because the key could come from many locations. This flow chart shows the operations performed in RISC OS Classic. It is not the manner in which RISC OS Pyromaniac handles key input - it's slightly different because interrupts mean that keys don't enter the buffer in the same way, and there is a slightly different order of operations. However it is useful to understand what the behaviour was in the reference implementation.

2020Input buffer reading flow chart

(Full size image)

In the prior diagram, there is a 'Read byte from input buffer' step, which is highlighted. The reading of a byte from the input buffer is actually quite complex, and is described in this flow chart. Most of the behaviour in this diagram is handled in some form by the input system in RISC OS Pyromaniac, though it may not be in quite the steps that are described here.

2020Escape key handling flow chart

(Full size image)

The Escape key (or its programatic equivalent) is actually quite complex. There are a lot of things that the escape key can do, and ways in which that can be modified. Again, these are largely covered by RISC OS Pyromaniac. Some operations like the 'Escape effects' are only partially followed, because the parts of the system that need to be notified (like the VDU system and the sound system) are more involved to coordinate. The Break key is also described in passing in this diagram.

2020Docker image layering

(Full size image)

Pyromaniac has been built into a number of Docker containers. These containers are built upon one another so that they can share content (which is more efficient) and be understandable. The base 'pyromaniac' image just includes Pyromaniac and a few core modules. Then the 'pyromaniac-build' image adds build tools to that. There are 3 images which are based on that - the 'pyromaniac-robuild' image (which provides the build service), the 'pyromaniac-demo' image (which provides the shell.riscos.online site). and the 'pyromaniac-vncserver' image (which allows manual testing of WxWidgets without leaving the comfort of macOS).

2022Graphics implementation layering

(Full size image)

Pyromaniac can use different graphics implementations. Although they do not have to be, they are largely built upon the Cairo graphics implementation, as it provides most of the functionality that is needed by other parts of the system. There are a few user interfaces that allow interaction (the WxWidgets, GTK and VNC implementations), and there are a few that use real hardware to display the output.

2022PyromaniacGit basic implementation

(Full size image)

The PyromaniacGit module interfaces with the host git tool. To do so, it uses the ANSI output translation provided by the HostCommand used by TWIN. The command arguments are translated from RISC OS format to host format, and the command is run on the host. The output is streamed through the ANSI parser and RISC OS codes are generated and the alphabet applied to it. If the user presses escape, the process is sent an interrupt.

2022PyromaniacGit authentication implementation

(Full size image)

To perform the authentication we need to provide a tool that can obtain the user name and password from the user. This 'askpass' tool communicates back to Pyromaniac to request the details. Pyromaniac provides a server which takes the request and passes it to the 'UserInput' system, which asks the user.

The default implemenation prints messages to the VDU stream and reads with OS_ReadLine, but the request can be passed to the UI. The WxWidgets interface provides a dialogue box to request the input from the user.

The basic PyromaniacGit flow is used for printing the output.

Example code

There are a few examples of code from within Pyromaniac here, to show how it's structured and what it looks like.

2020TWIN module

Download code

This is the actual implementation of TWIN inside Pyromaniac. TWIN is a module which provides an editor for BASIC programs. There's really no point in implementing a whole other editor, when an existing editor will do as well - so that's all that this implementation does. It is configured to just invoke another tool on the in-memory data.

[Show/hide source]

2020IIC module

Download code

The I²C bus is a hardware bus that allows you to communicate with addressable devices. On the RiscPC this was used to communicate with the hardware clock and provide some non-volatile memory, used for configuration. Clients should communicate with it through the IIC module.

This is the Pyromaniac implementation of the IIC module and the PCF8583 chip which provided the NVRAM and clock functions. It's one of the earliest modules I implemented, but it's actually about right. The I²C bus is implemented as a set of registered handlers which can be dispatched to - creating a new I²C device is a simple matter of registering a function to handle an address with a decorator. Other I²C devices could be registered in other files, and would appear on the bus when queried.

The PCF8583 is actually implemented inside a resource, because then it can hold state - which is what you'd expect from a piece of hardware - and can be located easily.

[Show/hide source]

2020SoundSystem prototype

(Asciinema)

Jason Tribbeck did a presentation in October 2020 for the work his was doing on the audio APIs. During the talk, I had a look at the documentation and - to help myself understand it - started writing a simple implementation using it. This gave me a better understanding of what was intended, and some (hopefully) useful freeback on the design.

I sent this short recording of the SoundSystem and SoundPyromaniac modules initialising and registering to Jason. Debug has been enabled for both the SoundSystem and services, so that it's easy to see the initialisation process and the services that are issued and responded to as a part of that.

Download code

I only spent about 3 hours on it, so all I managed to get done was a registration interface and a module that would use it - there's actually no sound handling going on at all. But this was part of the reason for building Pyromaniac. It allows a rapid prototype to be built to see how things would fit together.

The code here shows some of what you can do in a few hours.

[Show/hide source]

2021VNC graphics implementation

Download code

This is the actual implementation of the VNC graphics implementation inside Pyromaniac. The VNC implementation is based on the supplied Cairo implementation, and uses the cairo-vnc modules I created and open sourced separately. The code is only about 300 lines long - that's all you need to provide a variant of an existing graphics implementation.

[Show/hide source]