PiTrex Wiki

Linux_Configuration

This page describes details of how Linux can be configured to best work with the PiTrex software. These steps are not required for running only Bare-Metal programs.

Installation Directories

PiTrex software installs within the "/opt/pitrex" directory. Binaries are in "/opt/pitrex/bin", and "/opt/pitrex/lib" or "/opt/pitrex/share" may be added if programs require them.

Some files also need to be used by Bare-Metal programs, which can only access the first partition of the SD card, mounted in Linux as "/boot". As such, "/opt/pitrex/ini", "/opt/pitrex/settings", and "/opt/pitrex/roms" are symlinks to "/boot/ini", "/boot/settings", and "/boot/roms". Note that storage in these directories is therefore limited by the size of the first SD card partition. Root access is also required to modify all files in /boot (though as PiTrex software currently needs root permissions anyway, this isn't much inconvenience).

Avoiding Glitches

The Raspberry Pi needs to turn off the vector beam at a specific time after a draw operation begins (the scale time, plus a delay to account for other delays in the Vectrex circuitry). Linux has various ways of delaying the operation to turn off the beam, and so needs to be configured with various work-arounds in order to allow reliable display on the Vectrex.

Interrupt Disabling

Currently all Linux interrupts are disabled for the duration of each draw operation. This means that other Linux processes can't jump in and do something else while we're supposed to be stopping and turning off the Vectrex display's electron beam (see Interrupts for more details). Unfortunately this upsets (the latest versions of) the Raspberry Pi Foundation's custom USB driver "dwc-otg", and can lead to a system crash when a USB device is connected.

Luckily the standard Linux "dwc2" USB driver does also work on the Raspberry Pi, and isn't upset by the interrupt disabling. So this line needs to be added to config.txt (/boot/config.txt when running on the Pi) so that the dwc2 driver is used:

#Use alternative Linux USB driver (no FIQ)
#Modes: "host", "peripheral" or "otg"
dtoverlay=dwc2,dr_mode=host

Alternative settings for "dr_mode" are "peripheral" and "otg", required for OTG/Gadget mode.

This is automatically added by the pitrex-config.sh script.

Constant CPU Clock Speed

By default the Pi's CPU clock speed is adjusted automatically to minimise power consumption. This was found to disrupt the Vectrex Interface library's draw operations. By putting it into "performance" mode, the clock speed is constant:

echo -n performance | sudo tee /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor

You can check the current setting with this command ("performance" = good, "ondemand" = bad):

cat /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor

The pitrex-config.sh script sets this command to run at the end of the boot sequence. Alternatively the PLAY script changes it only during execution of the PiTrex program that you run.

Disable video output

For reasons not entirely clear, video output causes glitches too. It's not certain whether this is due to hardware interrupts that can't be disabled, or the clock speed being adjusted somehow.

Disable video output with this command:

sudo tvservice -o

The pitrex-config.sh script sets this command to run at the end of the boot sequence. Alternatively the PLAY script disables video output only during execution of the PiTrex program that you run.

Running as Root

PiTrex programs currently need root permissions in order to run. This can be done with the sudo command:

sudo ./< program name >

Or you can "suid root" the program, so that it runs with root permissions without needing to use sudo (this should also be done by "install" rules in program makefiles):

sudo chown root < program name >
sudo chmod u+s < program name >

./< program name >

Enabling Sound

Sound from the Vectrex works fine without any more configuration, but if you want to use a USB or Bluetooth (Pi0 W) audio adapter, these can allow modern sampled sound effects to be output from games and emulators that haven't been converted to use the Vectrex sound generator.

So far only the USB adapters have been tested (EDIT: Bluetooth audio has been successfully tested now too, see Linux_Example for instructions), note that you must have access to the USB port in order to connect them while the cartridge is inserted in the Vectrex (see Mechanical_Description).

The Pi defaults to trying to output audio via the integrated sound output on other Pi models (even if the driver for this is disabled by commenting out "dtparam=audio=on" in /boot/config.txt). To make the USB adapter default first check the device number that is assigned to the USB adutio adapter using this command:

cat /proc/asound/cards

Then create the file /etc/asound.conf containing:

defaults.pcm.card < device number >
defaults.ctl.card < device number >

Where "< device number >" is the number that you read from /proc/asound/cards.

You can check that it worked by running the commadn "speaker-test"

Future Plans

Linux support is still not ideally implemented, and some decisions during software development were targeted more towards the Bare-Metal environment where glitch-free display was working first

Kernel Driver

By implementing the drawing code from the Vectrex Interface library as a Linux kernel driver, the above configuration steps for preventing glitches should not be required. Root permissions also shouldn't be required to run the PiTrex software, and the Vectrex controller could appear as a HID controller to Linux software. This will also prevent screen updates from messing with the USB/Bluetooth audio output.

The efficiency of the software should also be increased by implementing an interrupt-driven vector drawing system.

Update:

It turns out the Linux kernel driver does still need system interrupts disabled in places, so the above configuration steps would still be required. The increase in software efficiency is now the main cause for development (and still a significant advantage).

Work on the kernel driver module is currently suspended, but the incomplete code can be viewed , and advice/contributions from people who know about Linux kernel module programming would be very welcome.

Work on supporting the Vectrex controller in a kernel driver has not been begun, and this may be best implemented as a separate driver to the display

A summary of conclusions from work on the Linux kernel driver.

Enabling Pi-Connected Controllers

This is not yet supported in the PiTrex software, but we hope that in addition to the Vectrex controller, some/all software will support control from USB and Bluetooth (Pi0 W) controllers and joysticks connected to the Pi.

To best accomodate this, the Vectrex controller should appear within Linux as a controller device the same as USB and bluetooth controllers (see Kernel Driver).

Web Interface

A web interface to the Pi0, allowing games to be managed and loaded from a smart phone or other computer, has been proposed. This would normally be used with a Pi0 W, which has built-in WiFi.