Pyromaniac

Resources

Resources

Documentation

API documentation

[zip]
Download

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

Pyromaniac documentation

[zip]
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.

Diagrams

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

Architecture diagram

[Image]
(Full size image)

Architecture diagram of the Pyromaniac system.

Execution flow chart

[Image]
(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.

Key reading flow chart

[Image]
(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.

Input buffer reading flow chart

[Image]
(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.

Escape key handling flow chart

[Image]
(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.

Docker image layering

[Image]
(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).

Example code

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

TWIN module

[python]
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]

IIC module

[python]
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]

SoundSystem prototype

[Asciinema!]
(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.

[python]
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]