![\"Three](\"https://fuzzix.org/files/great_escape_screenshots.png\")
\nA coupla few years ago I wrote about Integrating RtMidi's event loop with\nIO::Async. The basic approach\ninvolved spawning a routine which set up a RtMidi callback to pass MIDI\nmessages back to the main process via a channel. This routine then went to\nsleep to allow RtMidi's own event loop to take control.\n
While this approach works well enough, and has been used in a number of\nprojects (such as\nThe MIDI device filter project on this site, and\nGene Boggs' MIDI::RtController ecosystem),\nit also adds\nno small amount of complexity and overhead to an implementation. Running\nPerl-based callbacks within the rtmidi callback-handler thread can also cause\ncrashes, if not done carefully.\n
While playing around with libremidi, I\nnoticed it offers an option which makes a nonblocking file descriptor\navailable for integration into your event\nloop, and found myself\nthinking that it would be nice to have RtMidi offer a similar facility. What if...\n
What if we don't set RtMidi's callback to a\nFFI::Platypus::Closure\nwrapping our Perl code, but instead set the callback within some bundled C\ncode? This callback would create a fd pair - two file descriptors attached to\neither end of a\npipe, a\nwrite fd and a read fd. The read fd could be set nonblocking and, as it's a\nsimple int, be trivially passed back to our Perl program for later\nintegration into any event loop. This would eliminate the problems of calling\nPerl code in new threads, and should simplify event loop integration - no more\nroutines and channels required, we can now process MIDI bytes as a stream.\n
This seems sound enough to me, but we are now left with the problem of bundling\nC - Makefiles, compilers, actually writing C ... We are surely in for a world\nof pain, or are we?\n
FFI::Platypus' bundling interface\nallows for seamless inclusion of C code in your distribution (or Go code, or\nRust code, or Zig code, or...), without needing to worry about the build system\ntoo much. The moving parts in our case are:\n
ffi/ in the root of the distribution.\n.fbx file to pass some config values to FFI::Build and set the bundled dynamic library name.\ndist.ini to instruct FFI::Build to build bundled code when installing from CPAN.\nThis last part is pretty simple, the following line is added to dist.ini:\n
[FFI::Build]Let's take a look at the C.\n
Let's start with the includes. You'll always want ffi_platypus_bundle.h for\nbundled FFI code. There are some libc parts, then rtmidi_c.h, RtMidi's C\ninterface header. This will be useful for dereferencing RtMidi device members,\nand actually setting the rtmidi callback\nas we'll see later.\n
#include <ffi_platypus_bundle.h>\n#include <unistd.h>\n#include <stdio.h>\n#include <fcntl.h>\n#include <rtmidi_c.h>Next comes some cheating ... while this is ostensibly C, we will need to build\nand link with a C++ compiler to access RtMidi's namespaces correctly. This is\nas simple as giving our file a .cpp extension (ffi/pipefd.cpp), and placing\nour C code in an extern block covering the remainder of the file.\n
#ifdef __cplusplus\nextern "C" {\n#endifNext is a struct called _cb_descriptor, which at the moment just stores the writefd which will be used in RtMidi's callback.\n
typedef struct {\n int fd;\n} _cb_descriptor;The callback itself is a simple loop which attempts to write all available\nbytes in *message to the writefd passed in the userdata *data. Passing\n*data into the callback is a common pattern in C to work around the lack of\nclosure support.\n
The important thing to note here is that our callback is no longer Perl wrapped\nin a FFI::Platypus::Closure\n- our Perl code no longer needs to cede control to RtMidi.\n
void _callback( double deltatime, const char *message, size_t size, _cb_descriptor *data ) {\n if( size < 1 ) {\n return;\n }\n\n int total = 0;\n int remains = size;\n while ( total < size ) {\n int sent = write( data->fd, message + total, remains );\n if ( sent < 0 ) {\n perror("Callback write error.");\n return;\n }\n remains -= sent;\n total += sent;\n }\n\n}The last part is to create the fd pair, stash the writefd fd into the\ndevice's userdata, set the readfd side of the pipe nonblocking, register the\ncallback and userdata with RtMidi, then pass the readfd back to our Perl\nprogram.\n
RTMIDIAPI is a handy macro from RtMidi which will handle symbol exporting in a cross-platform way.\n
RTMIDIAPI\nint callback_fd( RtMidiInPtr device ) {\n\n _cb_descriptor *data = (_cb_descriptor*)malloc( sizeof( _cb_descriptor ) );\n int pipefd[2] = { 0, 0 };\n\n if ( pipe(pipefd) < 0 ) {\n perror("Cannot create pipe!");\n return -1;\n }\n fcntl( pipefd[0], F_SETFL, O_NONBLOCK );\n data->fd = pipefd[1];\n\n rtmidi_in_set_callback( device, (RtMidiCCallback)&_callback, data );\n\n return pipefd[0];\n}The .fbx file required to build this is called ffi/rtmidi-ffi.fbx (so the\ndynamic library it builds will be called librtmidi-ffi.so/rtmidi-ffi.dll\netc. depending on platform). It does some linker flag setup for Windows and\nMacOS, sets an 'Alien' package the compiler should use to find headers and\nlibraries from a non-system install, then sets the source to all .cpp files in ffi/ - there is\ncurrently just one, ffi/pipefd.ccp.\n
The MacOS linker flags are mostly required by older versions of that OS.\nThe Windows linker flags set an explicit link order, Platypus otherwise does a\nsolid job of identifying required libraries.\n
our $DIR;\n\nmy $WINDOWS = $^O eq 'MSWin32' || $^O eq 'cygwin';\nmy $MACOS = $^O eq 'darwin';\n\nmy $libs = '';\n\n$libs = '-lrtmidi -lwinmm -lws2_32' if $WINDOWS;\n$libs = '-framework CoreFoundation -framework CoreMidi' if $MACOS;\n\n{\n alien => ['Alien::RtMidi'],\n source => ["$DIR/*.cpp"],\n libs => $libs,\n};Something to note about the .fbx file is, it's probably not needed in many\ncases. If your bundled code is portable enough, and doesn't have external dependencies,\nyou can likely get away without it.\n
There are a couple of moving parts needed back in Perl land to connect all this\nup. First we tell Platypus to build and load the bundled code - this will\nautomagically build the bundle as it changes, even in a development environment\n- no need to invoke make or similar:\n
my $ffi = FFI::Platypus->new( api => 2, ... );\n$ffi->bundle;Then we need to attach the C function exported from our bundle:\n
$ffi->attach( callback_fd => [ [ 'RtMidiInPtr*' ] => 'int' ] )Finally, an exported Perl function is added to the binding library to wrap the fd\ninteger returned from C in a readonly\nIO::Handle. This handle can then be passed\neasily to event loops:\n
sub callback_fh( $dev ) {\n IO::Handle->new->fdopen( callback_fd( $dev ), 'r' );\n}Keen-eyed Windows API experts may have spotted an issue with the above. Windows\ndoes not have pipe(2). This winds up creating something of a mess, but the\nshort version is for Windows, a\nsocketpair is created in\nPerl, the write-end is passed to C, and the read end is returned to the calling\nprogram.\n
We should now have all the pieces to pass a filehandle to any event loop. As\nprevious efforts\nused IO::Async, let's start there.\n
After MIDI device, decoder, and event loop setup, an\nIO::Async::Stream is created with\nthe wrapped fd opened in our C code above. We can then attach a callback to the\ndecoder instance to print incoming events, then pass incoming bytes to the\ndecoder in the stream's on_read handler - as complete MIDI events are received, the\ndecoder's callback will be invoked.\n
A ticking counter is added to demonstrate other activity - we are not blocked\nwaiting for RtMidi, there is no need to sleep.\n
Where previously we would have\nhad to create a routine, and a channel for inter-process communication, here\nthe receiving and decoding of incoming MIDI messages is taken care of by the\nstream, entirely within\na single thread.\n
A small wrapper method called get_fh has been added to the input device class\nto manage whether existing callbacks should be cancelled when retrieving the\nhandle.\n
use IO::Async::Loop;\nuse IO::Async::Stream;\nuse IO::Async::Timer::Periodic;\nuse MIDI::RtMidi::FFI::Device;\nuse MIDI::Stream::Decoder;\n\nmy $midi_in = RtMidiIn->new();\n$midi_in->open_port_by_name( qr/sz|lkmk3/i );\nmy $fh = $midi_in->get_fh;\n\nmy $decoder = MIDI::Stream::Decoder->new;\n$decoder->attach_callback( all => sub( $event ) {\n say join ' ', $event->dt, $event->as_arrayref->@*;\n} );\n\nmy $loop = IO::Async::Loop->new;\nmy $stream = IO::Async::Stream->new(\n read_handle => $fh,\n on_read => sub( $self, $buffref, $eof ) {\n $decoder->decode( $$buffref );\n $$buffref = "";\n }\n);\n$loop->add( $stream );\n\nmy $tick = 0;\n$loop->add( IO::Async::Timer::Periodic->new(\n interval => 1,\n on_tick => sub { say "Tick " . $tick++; },\n)->start );\n\n$loop->run;A very similar approach can be used with\nMojo::IOLoop and\nMojo::IOLoop::Stream:\n
use Mojo::IOLoop;\nuse MIDI::RtMidi::FFI::Device;\nuse MIDI::Stream::Decoder;\n\nmy $midi_in = RtMidiIn->new();\n$midi_in->open_port_by_name( qr/sz|lkmk3/i );\nmy $fh = $midi_in->get_fh;\n\nmy $decoder = MIDI::Stream::Decoder->new;\n$decoder->attach_callback( all => sub( $event ) {\n say join ' ', $event->dt, $event->as_arrayref->@*\n} );\n\nmy $stream = Mojo::IOLoop::Stream->new( $fh );\n$stream->timeout( 0 );\n$stream->on(\n read => sub ( $stream, $midi_bytes ) {\n $decoder->decode( $midi_bytes );\n }\n);\n$stream->start;\n\nmy $tick = 0;\nMojo::IOLoop->recurring( 1 => sub { say "Tick " . $tick++; } );\n\nMojo::IOLoop->start unless Mojo::IOLoop->is_running;Future::IO is a solid option if you want\nyou event-driven code to be loop-agnostic. The same Future::IO code can be\nintegrated into programs using one of any number of event loops by loading an\nIO implementation, e.g.\nFuture::IO::Impl::Glib.\n
use Future::IO;\nuse Future::AsyncAwait;\nuse MIDI::RtMidi::FFI::Device;\nuse MIDI::Stream::Decoder;\n\nmy $midi_in = RtMidiIn->new();\n$midi_in->open_port_by_name( qr/sz|lkmk3/i );\nmy $fh = $midi_in->get_fh;\n\nmy $decoder = MIDI::Stream::Decoder->new;\n$decoder->attach_callback( all => sub( $event ) {\n say join ' ', $event->dt, $event->as_arrayref->@*\n} );\n\nasync sub msg {\n my $size = $midi_in->bufsize;\n while ( my $midi_bytes = await Future::IO->read( $fh, $size ) ) {\n $decoder->decode( $midi_bytes );\n }\n}\n\nasync sub tick {\n my $tick = 0;\n while ( 1 ) {\n await Future::IO->sleep( 1 );\n say "Tick " . $tick++;\n }\n}\n\nFuture->wait_all( tick, msg )->get;This, to me, appears markedly simpler than the previous effort. There is no need\nto explicitly create routines, and no oddities around ceding control to RtMidi.\nIt also has the benefit of being more robust, as Perl closures are not being\ncalled from external threads.\n
The three examples above should produce equivalent output, which looks something like this:\n
Tick 0\n0 note_on 0 55 64\nTick 1\n0.838393 note_off 0 55 0\nTick 2\n0.018346 control_change 0 1 63\n0.040585 control_change 0 1 62\n0.053563 control_change 0 1 61\nTick 3\nTick 4\nTick 5\n2.357593 control_change 0 1 62\n0.004254 control_change 0 1 63\n0.004569 control_change 0 1 64\nTick 6We can see our ticking counter interleaved with incoming MIDI delta-times (time\nsince previous event), and events from an external device.\n
After a review of previous work in integrating RtMidi with another event loop, we went\nthrough some of the shortcomings of this approach, before describing a new\napproach which uses pipes to pass MIDI bytes from RtMidi to a MIDI-processing\nprogram. We took a quick tour of the C code, which uses FFI::Platypus::Bundle\nto build and load a dynamic library to make itself available.\n
We took a look at some examples around how to integrate the fd created in C\ninto event loops in Perl, which were marked by simpler implementation than\nprevious async integration attempts.\n
The callback_fh mechanism and the examples in this post are now available in\nMIDI::RtMidi::FFI v0.10 and above.\n
Update 2025-04-17 Joaquín Ferrero drew my attention to some prior art,\nsee: ooblick's Perl Spectrum Emulator -\nvery nice!\n
I've always been interested in the idea of building a small computer emulator,\nbut it always seemed to be within the realms of bizarre science experiment\nmeets arcane magic trick. Software-defined silicon chips, talk of "precise\ntimings" or "t-state accuracy", translating keyboard/mouse/disk/etc. I/O,\nwondering how you turn the flapping of a bit\non a port into something that beeps on modern audio hardware, and so on. It all\nseemed a bit intimidating, and other things held my interest.\n
I got thinking about this again recently, with a desire to produce interesting\nthings for the ZX Spectrum Next,\nso I thought "I wonder how far I can get with\na Perl script?"\nAmong Perl's superpowers is whipuptitude - the ability to draw on\nexpressive language features and available libraries on CPAN to solve annoying problems\nand get things done - you can quickly whip things up. Can I "whip up" a speccy\nemulator in Perl?\n
Oh, an angry mob ... hello! Let's be realistic here, I'm probably not going\nto bang out an accurate representation of the ZX Spectrum over the course of\nan idle evening, so let's set our sights lower. Let's build something that\njust about plays a ZX Spectrum game. Silently, in all likelihood. Let's build\nthe Second-Worst ZX Spectrum Emulator in the World.\n
In order to build The Second-Worst ZX Spectrum Emulator in the World, I think we\nshould start with The Worst ZX Spectrum Emulator in the World, if only to\nexplore some ideas on what an emulator does. Let's start with the Z80 CPU.\n
CPUs operate via the\nfetch-decode-execute cycle.\nThis loop fetches instructions from memory pointed to by\na Program Counter (PC). Depending on what this instruction is, additional\nparameters may also be fetched. There is enough information here to\nto increment the PC to point to the next instruction. The decode stage decides\nwhich part of the CPU should should handle the instruction, which is then\nexecuted with any retrieved parameters. This is an inaccurate and hand-wavey\ndescription to further the needs of this post - I wouldn't use it as the basis\nfor a chip design.\n
We could implement a loop which fetches from a blob of memory,\nlooks up instructions in a table, executes an implementation of these\ninstructions along with any parameters, maintains the PC correctly\n(instructions will also have different numbers of bytes and parameters, so the\n PC will need to take account of this), and so on... but we're whipping up\nhere.\n
David Cantrell's CPU::Emulator::Z80,\nis a Perl-based Z80 CPU emulator which should get us moving. An instance of this\nemulator in the simplest case needs a memory string, some intial values for\nregisters, and the number of I/O ports.\n
We could load this CPU up with the Spectrum ROM and a pristine 48K of RAM,\nmake sure we can boot up to the copyright notice, but\nlet's pretend it's Christmas morning nineteen-eighty-splat - "I wanna see the\ngames!"\nOne of the simpler file formats for storing Spectrum games is the\nSNA snapshot, a direct\ndump of RAM and registers. Let's see what we can do with that.\n
We can start by getting a snapshot filename from the command line, reading the\n27 byte header and the rest of the file into our "RAM":\n
my $sna = $ARGV[0];\nopen my $fh, '<:raw', $sna;\nread $fh, my $header, 27;\nread $fh, my $ram, 49152;Parsing the registers and so on out of $header is simple with unpack.\nWe just need to know whether the value is 8 bit, e.g. $Border, or 16 bit,\ne.g. $SP.\n
my (\n $I,\n $HL_, $D_, $E_, $B_, $C_, $A_, $F_,\n $HL, $D, $E, $B, $C, $IY, $IX,\n $Int,\n $R,\n $A, $F, $SP,\n $IntMode,\n $Border\n) = unpack '\n C\n S C C C C C C\n S C C C C S S\n C\n C\n C C S\n C\n C\n', $header;We now have a game in memory, plus much of its initial state.\n
The ROM contains routines for co-ordinating facilities of the computer, startup\ncode, as well as a BASIC interpreter.\n
We want to emulate the ZX Spectrum 48K, so we need a ROM dump for that model.\nI won't get into the\nlegal situation with ZX ROMs\nhere, but they are readily available online. My ROM file is 'spec48.rom', so\nlet's read it's full 16K:\n
open $fh, '<:raw', 'spec48.rom';\nread $fh, my $rom, 16384;The Spectrum's memory map is fairly simple. It is a single 64K bank. The\nfirst 16K is mapped to the ROM, the remainder is RAM. The RAM contains some\nsystem variables and buffers, screen memory, and the program. For our\npurposes we can simply concatenate $rom and $ram to achieve a complete\nmemory map.\n
The Spectrum uses 16-bit I/O port addresses, so we'll need to set the number\nof ports accordingly.\n
my $cpu = CPU::Emulator::Z80->new(\n memory => $rom . $ram,\n ports => 65536,\n\n init_A => $A,\n init_B => $B,\n ... # initialising more registers here\n init_HL_ => $HL_,\n\n init_SP => $SP,\n init_PC => 0x72,\n);Something to note is we don't get a PC value from the snapshot file.\nThe way the snapshot format works is we get a Stack Pointer (SP) value which points to a\nmemory location containing the address of the next instruction.\nThe snapshot should be kicked off by issuing a\nRETN instruction (ED 45), which is used\nto return from a Nonmaskable Interrupt (NMI) routine. RETN pops PC off the\nstack, allowing execution of the game to resume. A RETN instruction can be found in the\nROM at offset 0x72, so we can set our PC to that address.\n
You may have noticed that no I/O devices have been set up, so we can't exactly\nplay a game just yet. We also have no graphics output, so this is so far a\nnon-interactive and headless Spectrum emulator. What we can do is run the CPU\nand grab screen dumps to see what's going on.\n
Let's run it with a snapshot of\nThe Great Escape,\nwhich has an animated intro screen featuring a flag raising up a flagpole. We\ncan take some periodic screenshots and see if there's progress to indicate the\nprogram running successfully:\n
sub screenshot( $filename = 'screen.scr' ) {\n open my $fh, '>:raw', $filename;\n print $fh join '', map { chr( $cpu->memory->peek8( $_ ) ) } 16384..16384+6911;\n}\n\nscreenshot( 'tge1.scr' );\n$cpu->run( 5_000_000 );\nscreenshot( 'tge2.scr' );\n$cpu->run( 5_000_000 );\nscreenshot( 'tge3.scr' );Here we take a screenshot of the initial state of the machine, run five million\ninstructions (note: instructions, not clock cycles), take a second screenshot,\nrun five million more instructions, and take a final screenshot. The screenshot\nfunction uses peek8 (equivalent to a typical BASIC PEEK) to read\nsingle bytes from memory. The chr function ensures these are stored as\ncharacters, since the peek8 method returns integer values. The built-in\nfunction chr converts the up-to-three bytes returned by peek - the perl integer\nvalue representing the memory contents - into a single byte value (I should point\nout that the integer is stringified by the join operation, which is why we\nhave three bytes).\n
chr ( 0b01 . 0b10 . 0b11 ); # "123" returns ASCII '{'The SCR file format simply a dump of screen RAM contents. Screen RAM begins at\naddress 16384 and is 6912 bytes long. It is split into an area defining pixel\ndata, and an area describing attribute data per 8x8 square - foreground\nand background colours, and FLASH and BRIGHT flags.\n
\n
While we can see the program appears to run successfully, there is a serious problem\n(besides the lack of interactivity). What would have taken just a few seconds\non the Spectrum took a few minutes on my laptop. I suspect we don't yet have a\nviable emulator for playing games, and implementing a CPU loop in Perl is\nperhaps not ideal for this particular use-case. It will likely continue to\nserve us well for testing ideas and validating assumptions.\n
Source code for this stage of the emulator\n
Manuel Sainz de Baranda y Goñi's Z80 is a\nfast and portable implementation of the Z80 CPU written in C. It appears to\nhave a simple interface, and a means for adding I/O port facilities. It has\nalso been used for a number of ZX Spectrum related projects, which I can use\nas a refer...\n
OK, OK, I admit it - This was the first result when I searched for\n"Z80 CPU Emulator". It's written in C (which is easy to bind), and I liked the\nvibes. I'm going to refer to this library as "redcode's Z80" from here out, as\nthe name "Z80" alone is a little ambiguous.\n
A difference between this library and CPU::Emulator::Z80 is that all memory access is mediated by your program,\nnot the CPU emulation. This means that alongside callbacks for port I/O, we\nalso have callbacks for reads and writes of memory addresses. This may end\nup presenting performance problems. Array accesses in in Perl are pretty fast,\nso I guess we'll dive in and see!\n
You may have noticed another important different between redcode's Z80 and\nCPU::Emulator::Z80 - it's not on CPAN. In the Before Times, this would likely\nhave spelled the end for this project. I would need to break out the compiler\nand start chiseling a set of XS Macros\nout of rock. Rock composed of my patience and my ability to wrangle C -\nsmall and very fragile rock.\n
This would also have been a swift and sharp departure from the land of\nwhipuptitude, and from its neighbour, the land of fun.\n
Thankfully Graham Ollis' FFI::Platypus\nallows us to pick an existing library and create ad-hoc bindings to the pieces\nwe need right in our Perl script. In Perl.\n
It has support for callbacks, pointers, structs and unions, and practically any\ncombination of types you can think of. While having some grasp of low-level\nconcerns is useful, it's not absolutely necessary once you can read docs and/or\nC header files.\n
Not requiring a compiler is a definite bonus - a killer feature.\nNot only does it make the workflow\na lot smoother, you can also explore the library and ways to bind it in a\nREPL or debug session (though if you do,\nprepare for crashes when you get a function signature wrong).\n
An Uncommitted Logic Array (ULA),\nalso called a gate array, is a chip which, facilitated by the ROM,\ngathers together useful facilities for your computer which are not handled\ndirectly by the CPU. These facilities can include handling the keyboard and\nstorage devices, generating video frames, or handling peripherals on external\nports - printers, modems, MIDI devices...\n
This is the piece we need to emulate in order to approximate the functioning\nof the Spectrum. Being able to type on the keyboard, and see the effect of those\nkeypresses on the screen is just about all that's needed to play a game.\nIt might also be nice to have soun... (QUIET YOU! - Ed).\n
The Z80 communicates with the ULA via its I/O ports. These are implemented in\nredcode's Z80 (and in CPU::Emulator::Z80) by attaching callbacks to I/O port\naddresses. These ports may be read from or written to, and the appropriate\ncallback is required for each operation.\n
As for what these callbacks will actually do, we're going to need something\nwhich can read the keyboard and display graphics on a modern operating system -\nI'll call this the "host" from now on.\nI have dabbled with SDL in the past, which is fantastic for cross-platform\ngame and engine development, though it's a bit low-level for my needs\nhere. It doesn't feel whippy or uppy enough.\n
The raylib games programming library has the word\n"enjoy" right in its mission statement. It has a\nSimple but extensive API,\nand easy means to read the keyboard and display graphics.\n
Chris Prather's binding for the raylib game programming library\nallows us to kick off pretty much immediately. The\nRaylib::App example\nshows off at least some of the facilities we need - framerate control and\ndrawing. Input from the keyboard is also easily retrieved.\n
I won't go into much detail here on\nreading the Spectrum keyboard matrix,\nbut the short version is we need a callback to respond to read requests on port 0xFE.\nWhile I said the Spectrum uses 16-bit I/O addressing, this is treated as a single\nport by the ULA, with additional bits on the data lines used to decide which part of\nthey keyboard matrix to read. The keyboard is split into 8 half-rows of 5 keys each,\nfor a total of 40 keys in the matrix.\n
We can revisit our headless emulator to experiment with this. For the purposes\nof defining a callback, we can treat the port address as 16-bit. This means we\nwant to respond to reads on port 0xEFFE, which is a keyboard read request for\nkeys '6' to '0'. Referring to the screenshot of the menu screen above, we want\nto press key '0'.\n
We don't need to check if a key is pressed on the host, we can just\nunconditionally return '0' and see if the game starts (with some minor\ncomplications). That ends up looking like this:\n
$cpu->add_input_device(\n address => 0xf7fe,\n function => sub {\n state $have_set_controls;\n return 0b11111 if $have_set_controls;\n $have_set_controls = true;\n return 0b11011;\n }\n);\n$cpu->add_input_device( address => 0xeffe, function => sub { 0b11110 } );\n$cpu->add_input_device( address => 0xfefe, function => sub { 0b11111 } );\n$cpu->add_output_device( address => 0x00fe, function => sub { } );The first callback sets the menu option to use Sinclair joystick (option 3). If we leave\nthis option on keyboard controls, the game will prompt for a keyboard layout\nrather than just starting the game. The address 0xf7fe is a request to read\nkeys 1-5 (or 5-1 depending on how you order bits on the bus). It returns the keys pressed as a bitmask. As\nthe data pins are pulled high, active keys are set to zero, so 0b11011 means\nthe key '3' is pressed.\n
The game's menu code only falls through to check for keys 6-0 if none of 1-5 are\npressed, so the callback for 0xf7fe has a guard to only press '3' once,\nelse send 0b11111 - no keys pressed.\n
The callback for 0xeffe handles keys 6-0. We always return 0b11110 here,\nmeaning '0' is pressed.\n
The address 0xfefe is a request to read keys 'Caps-Shift' to 'V'. This is\nprobably part of a check to see if 'Break' is pressed - this keypress is a\ncombination of 'Caps-Shift' + 'Space'. If we pressed 'Caps-Shift', we might\nexpect an additional read on 0x7ffe which is a read request for a keyboard\nrow which includes 'Space'. We instead send 0b11111 here - all keys off.\n
A no-op callback is added to output port 0x00fe to reduce warnings in the\nterminal. I suspect these are calls to oscillate the beeper, though I'm not sure.\n
The end result of all this is that one of our screen captures contains the\nfollowing screen shot:\n
![\"The](\"https://fuzzix.org/files/great_escape_game_started.png\")
\n
I have so far been using software like\nZX Paintbrush\nto view screens dumped by the emulator. We will need to look at decoding these\ndirectly in order to display them in real time.\n
Pixel data starts at address 16384 (0x4000), and is 192 lines of 32 bytes for a\ntotal of 6144 bytes. Each byte contains the pixels in the order they appear on\nscreen.\n
The 192 lines are not arranged sequentially as you might expect from a bitmap.\nInstead the screen is divided into three horizontal sections. Lines within\nthese sections are ordered by their position in their respective 8x8 character\nsquare. The first line of every character in the current third of the screen\nappears before the second line, and so on. Some arithmetic may be performed on\nthe memory address to convert it to screen-space co-ordinates.\n
After the 6144 bytes of monochrome pixel data is 768 bytes of colour (or\nattribute) data. Each byte refers to an 8x8 character, and has 3 bits for\nforeground colour (called INK in Spectrum parlance), 3 bits for background colour (PAPER),\nand 1 bit each for BRIGHT and FLASH. The arrangement of these bytes is\nsimpler than the pixel data - they are stored sequentially in the order they\nappear on screen - reading order. 3 bits of colour, combined with the BRIGHT flag gives 15\npossible colours ("bright" black is the same as black on most Spectrum models).\n
For now, let's see if we can decode one of the screens dumped from the\nheadless emulator into something raylib can display. We can call it "good\nenough" if we hit 50 frames per second (FPS) without breaking too much of a\nsweat.\n
We'll start with some setup:\n
my $width = 1024;\nmy $height = 768;\n\nmy $filename = $ARGV[0] // 'tge1.scr';\nopen my $fh, '<:raw', $filename;\nread $fh, my $pixels, 6144;\nread $fh, my $attributes, 768;\n\nmy $app = Raylib::App->window( $width, $height, 'SCR display' );\n$app->fps( 50 );\nmy $fps = Raylib::Text::FPS->new;\n\nwhile ( !$app->exiting ) {\n my $tex;\n $app->draw(\n sub {\n $app->clear;\n $tex = scr2tex( $pixels, $attributes );\n $tex->draw;\n $fps->draw;\n }\n );\n}The width and height of the application will be the Spectrum screen dimensions x 4.\nWe start by grabbing the screen we want to display, 'tge1.scr', which contains\nThe Great Escape's menu screen.\n
After declaring the app instance and setting the desired framerate (for a PAL\nregion computer designed to connect to a TV in 1982), we can start the game\nloop. This is the same simple game loop you might create for any number of\nframeworks. Ordinarily there would be some calls to retrieve input, calls to\nmove objects in your game world based on that input, then the drawing routines.\n
The scr2tex function will turn the Spectrum screen data into an image\n"texture"\nthat raylib can throw at the host's GPU. Note that the texture $tex needs to remain\nin scope until after the draw calls are complete, so it is declared outside the\ndraw call. The texture data is a 32-bit array of Red, Green, Blue, Alpha (RGBA)\nvalues, plus a texture size, expressed as X/Y, which denotes how to constrain\nthe array. Textures are images which are mapped - rendered onto - 3D shapes.\nIn our case, they will simply be shown in 2D on the host's screen.\n
There are a number of options available to us to convert the screen space into\nthe list of RGBA values needed to construct the GPU\ntexture. The Spectrum's video layout is optimised for displaying characters,\nso we could go character by character, looking up each attribute only once.\nWe could treat the data sequentially, adding RGBA values to the texture in the\nsame order they appear in the Spectrum's screen RAM. We could address the screen\nRAM in a way that the pixels are processed in the same order as the texture.\n
my $colours = [\n [ 0x00, 0x00, 0x00 ],\n [ 0x00, 0x00, 0xD7 ],\n # ... More RGB values here\n [ 0xFF, 0xFF, 0x00 ],\n [ 0xFF, 0xFF, 0xFF ],\n];\n\nsub rgba( $colour ) {\n join '', map { chr } $colour->@*, 0xFF;\n}\n\nsub colour( $attribute, $ink = 0 ) {\n my $colour = $attribute & i( $ink ? 0b00000111 : 0b00111000 );\n $colour = $colour >> ( $ink ? 0 : 3 );\n my $bright = ( $attribute & 0b01000000 ) >> 3;\n rgba( $colours->[ $colour | $bright ] );\n}We can start with some generally useful functions. The $colours array of arrays\ncontains RGB values for the 8 spectrum colours, and the 8 BRIGHT variants.\nThe colour function takes an attribute byte and whether we want the ink or\npaper colour. It then pulls the relevant colour from the attribute byte,\nshifting the bits if required, so it's a number from 0 to 7, then fetches the\nbright flag and shifts that so it's 0 or 8. The colour and bright flag are\nbinary-ORed together to produce a value matching the lookup table $colours.\n
The bits in the screenshot's pixel array are 1 for ink colour, 0 for paper, so\nwe should be able to pass the pixel value directly into this function and get\nthe correct RGBA value back.\n
You may have spotted that we're only using 7 bits of the attribute value here.\nThe remaining bit is the FLASH flag. I'm leaving that as homework for the\nreader. Not a good enough excuse? OK, erm ... This emulator will follow web\nstandards best practice - the <blink> tag was deprecated long ago.\n
Let's take a look at a first-pass scr2tex:\n
sub scr2tex( $pixels, $attributes ) {\n my $image;\n my @pixmap = map { [ split '' ] } reorder ( unpack( '(B256)*', $pixels ) );\n my @attribmap = unpack( 'C*', $attributes );\n\n for my $x ( 0..191 ) {\n for my $y ( 0..255 ) {\n $image .= colour(\n $attribmap[ int( $y / 8 ) + ( int( $x / 8 ) * 32 ) ],\n $pixmap[ $x ][ $y ]\n );\n }\n }\n\n my $buffer = malloc( length $image );\n my ( $image_ptr ) = scalar_to_buffer( $image );\n memcpy( $buffer, $image_ptr, length $image );\n my $raylib_img = Raylib::FFI::Image->new(\n data => $buffer,\n format => 7, # PIXELFORMAT_UNCOMPRESSED_R8G8B8A8\n width => 256,\n height => 192,\n mipmaps => 1,\n );\n Raylib::FFI::ImageResizeNN( $raylib_img, $width, $height );\n Raylib::Image->new( image => $raylib_img )->as_texture;\n}The first step here is to get the pixel and attribute data into a usable\nformat. Attributes are unpacked into an array of 768 unsigned char values.\nPixels are unpacked into 192 strings, each with 256 characters either '1'\nor '0', depending on whether the pixel contains the ink or paper colour.\nThis is further split, so @pixmap will contain a 2D array of pixel values.\nWe'll take a look at the function reorder shortly.\n
For each pixel, the relevant colour value is concatenated onto $image.\nThe $image is then converted into a texture in a slightly roundabout\nfashion. Image loading functions in raylib tend to focus on pulling PNG files\nfrom disk. As we have already constructed the required in-memory representation\nof the image, constructing a Raylib::FFI::Image struct with a malloced blob\nis probably the quickest path forward.\n
ImageResizeNN is a nearest-neighbour resize function to bring the image to\nfinal dimensions. The final step is to return the image as a texture - the data\nis copied into GPU memory by raylib during this step.\n
Let's return to the code to take a look at reorder:\n
sub reorder( @lines ) {\n my @reordered;\n for my $third ( 0..2 ) {\n my $start_line = $third * 64;\n for my $char_line ( 0..7 ) {\n for my $char_offset ( map { $_ * 8 } 0..7 ) {\n my $next_line = $start_line + $char_line + $char_offset;\n $reordered[ $next_line ] =\n shift @lines;\n }\n }\n }\n return @reordered;\n}This function takes lines of pixels in the order they appear in screen RAM,\nand returns them in consecutive, or on-screen, order. Thirds of the screen\nare processed in turn. Each third of the screen contains 8 rows of characters.\nCharacters are 8 pixel rows high. The first eight rows in RAM appear in the order 0, 8, 16, 24,\n32, 40, 48, 56. The second 8 are in order 1, 9, 17, 25, and so on up row 63.\nThe second and third segments of the screen proceed similarly, up to row 191.\n
The result of all this bit-wrangling is as follows:\n
![\"The](\"https://fuzzix.org/files/windows_scr_display_7fps.png\")
\n
An initial wave of excitement quickly gives way to the reality of what\nwe're attempting to do. 7 frames per second is significantly fewer than 50.\nA little instrumentation shows that the drawing of the image - looking up\ncolour values pixel by pixel and concatenating them onto $image - is taking\nover 200 milliseconds. The image copying, resizing, etc. to get it into a GPU texture at the\ncorrect dimensions is clocking in at around 4 milliseconds. Skipping the resize\noperation reduces this to 100 microseconds or less.\n
For a 50 FPS target\nthere is a total allocation of 20 milliseconds to generate each frame. This\nincludes any work raylib needs to do, and will need to accommodate our Z80\nprocessor and its I/O callbacks at some point.\n
There are a number of simple optimisations we can implement here to try speed\nthings along. Processing the screen pixel by pixel results in 49152 function\ncalls. If we processed 8 pixels at a time, they could be handled in a single\ncolour call as they will all have the same attribute byte. This would reduce our call\ncount to 6144.\n
Some caching could be useful. For example, if we plan to call colour with\nan attribute byte and pixel byte, there are 65,536 possible permutations in the parameters.\nThis could easily be precomputed and cached without the host breaking a sweat.\nComputing the row order in reorder each time could also be helped along with a\nlookup table.\n
It should also be possible to instruct the GPU to resize a texture, rather than\nperforming the resize on the host CPU each frame, then copying the resized image to the GPU.\n
It's OK, we're still whipping things up! It's still fun! Even though there's a\nlegit malloc hanging about in there...\n
Moving on, we can replace the reorder function with an array containing the\norder of pixel lines:\n
my @line_order;\nfor my $third ( 0..2 ) {\n my $start_line = $third * 64;\n for my $char_line ( 0..7 ) {\n for my $char_offset ( map { $_ * 8 } 0..7 ) {\n push @line_order, $start_line +\n $char_line +\n $char_offset;\n }\n }\n}This is the same loop that reorder had, but instead of addressing the pixel\narray by line number, it just stores that number.\n
The colour function has been updated to take an attribute value, plus a byte\ncontaining 8 pixels:\n
sub colour( $attribute, $pixels ) {\n state @cache;\n $cache[ $attribute << 8 | ord $pixels ] //=\n join '', map {\n my $colour = $attribute & ( $_ ? 0b00000111 : 0b00111000 );\n $colour = $colour >> ( $_ ? 0 : 3 );\n my $bright = ( $attribute & 0b01000000 ) >> 3;\n rgba( $colours->[ $colour | $bright ] );\n } split '', unpack 'B8', $pixels;\n}A cache key is calculated by treating the attribute as the most-significant\nbyte (MSB) of a 16-bit integer, and adding that to the numeric representation\nof the pixel byte. The rest of the function is much the same as before, except instead\nof processing a bit at a time, it returns RGBA values for 8 bits.\n
The scr2tex function will need to be updated for new parameters in colour:\n
sub scr2tex( $pixels, $attributes ) {\n my @lines = unpack '(a32)*', $pixels;\n my @attribmap = unpack 'C*', $attributes;\n\n my $image = join '', map {\n my $attrib_idx = int( $_ / 8 ) * 32;\n map {\n colour( $attribmap[ $attrib_idx++ ], $_ )\n } split '', $lines[ $line_order[ $_ ] ]\n } 0..191;\n\n # ... remainder of this function is largely unchangedThe pixel data is now unpacked into @lines as rows of byte strings with length 32.\nThe image data is built line-by-line, using the line number to address the\nattribute byte and reference the correct line via @line_order.\nThe allocation of the image struct, sending it to a texture, and so on remains\nidentical to before, except we no longer resize the image to the final window\ndimensions.\n
The game loop and draw call now look like this:\n
my $scr_rect = Raylib::FFI::Rectangle->new(\n x => 0,\n y => 0,\n width => 256,\n height => 192\n);\n\nmy $window_rect = Raylib::FFI::Rectangle->new(\n x => 0,\n y => 0,\n width => $width,\n height => $height\n);\n\nwhile ( !$app->exiting ) {\n my $tex;\n $app->draw(\n sub {\n $app->clear;\n $tex = scr2tex( $pixels, $attributes );\n $tex->draw_pro( $scr_rect, $window_rect );\n $fps->draw;\n }\n );\n}Two rectangles describe the Spectrum screen image dimensions and the desired window dimensions.\nThese are passed to the draw_pro method, which now performs the resize.\n
The final step is to warm the cache inside the colour function, to keep the\nframerate / idle time somewhat consistent:\n
for my $attrib ( 0..255 ) {\n for my $pixel ( 0..255 ) {\n colour( $attrib, chr $pixel )\n }\n}With those changes, how does the performance look?\n
![\"The](\"https://fuzzix.org/files/windows_scr_display_50fps.png\")
\n
A little instrumentation on the game loop's draw callback indicates a render time\nof no more than 3.5ms on an 8th Gen mobile i5 running Linux, and no more than 4.5ms\non a five year old Ryzen 7 running Windows.\nThis leaves us with around 15ms per frame to play with for the integration of redcode's\nZ80.\n
This section assumes a\ndefault local installation as described in the libz80 README\nor Windows DLL file in the current working directory. Loading this into a\nPlatypus instance is simple:\n
my $lib = $^O eq 'MSWin32'\n ? './Z80.dll'\n : "$ENV{HOME}/.local/lib64/libZ80.so";\nmy $ffi = FFI::Platypus->new(\n api => 2,\n lib => $lib\n);A significant difference between redcode's Z80 and CPU::Emulator::Z80 is that\nthe former uses callbacks for reading and writing memory addresses - the memory\nlives in your program, not in the emulation. Converting the binary blob read\nfrom the snapshot file into an array should make this nice and simple:\n
my @memory = unpack 'C*', $rom . $ram;Memory addressing callback functions are now very simple:\n
sub mem_read( $ctx, $addr ) { $memory[ $addr ] }\nsub mem_write( $ctx, $addr, $val ) { $memory[ $addr ] = $val if $addr >= 0x4000 }The $ctx value here is user-defined. This is usually used to help work around\ndifficulties in closure support in C - we don't make use of it here. The\naddress 0x4000 is the lowest RAM address. It's probably not strictly\nnecessary but checking the address helps guard against write operations to ROM.\n
The scr2tex function needs some updates to handle the array data:\n
my @line_nos = 0..191;\nsub scr2tex( @memory ) {\n my @pixels = @memory[ 0x4000..0x57FF ];\n my @attribs = @memory[ 0x5800..0x5AFF ];\n\n my $image = join '', map {\n my $line_idx = $line_order[ $_ ] * 32;\n my $attrib_idx = int( $_ / 8 ) * 32;\n map {\n colour( $attribs[ $attrib_idx++ ], $_ );\n } @pixels[ $line_idx..$line_idx+31 ];\n } @line_nos;\n\n # ... remainder unchangedMoving the building of the @line_nos array outside the function is what's\nknown as "premature optimisation". I'm also crossing my fingers that passing these\nnamed arrays around in function parameters benefits from copy-on-write optimisations. We can revisit\nif we miss the framerate target.\n
There are a couple of simple function signatures we need to declare for memory\nand I/O port access functions:\n
$ffi->type( '(opaque,uint16)->uint8' => 'Z80Read' );\n$ffi->type( '(opaque,uint16,uint8)->void' => 'Z80Write' );FFI::Platypus::Record allows us to create an\nobject wrapper for a struct in redcode's Z80. The definition of the object\nlooks much like this:\n
package TSWZXSEITW::Z80 {\n use FFI::Platypus::Record qw/ record_layout_1 /;\n record_layout_1(\n $ffi,\n opaque => 'fetch_opcode',\n opaque => 'fetch',\n opaque => 'read',\n opaque => 'write',\n opaque => 'in',\n opaque => 'out',\n opaque => 'nop',\n sint16 => 'ix',\n sint16 => 'iy',\n sint16 => 'pc',\n sint16 => 'sp',\n sint16 => 'xy',\n sint16 => 'af',\n sint16 => 'bc',\n sint16 => 'de',\n sint16 => 'hl',\n sint16 => 'af_',\n sint16 => 'bc_',\n sint16 => 'de_',\n sint16 => 'hl_',\n uint8 => 'options',\n );\n}\n$ffi->type( 'record(TSWZXSEITW::Z80)' => 'Z80' );\n$ffi->attach( z80_execute => [ 'Z80*', 'size_t' ] => 'size_t' );"TSWZXSEITW" is The Second-Worst ZX Spectrum Emulator in the World.\nThe record layout in TSWZXSEITW::Z80 has many more members not listed here,\nas we're not interested in them. The opaque entries are pointer values we\ncan cast other things to later, if required.\nOnce the object is defined, we can bind that to a type, then attach a function\nfrom the library into our namespace - the FFI attach method will make z80_execute available to\nus like any other Perl function.\n
We next need to create some FFI closures to pass as callback functions to\nan instance of TSWZXSEITW::Z80.\n
my $read_closure = $ffi->closure( \\&mem_read );\nmy $write_closure = $ffi->closure( \\&mem_write );\nmy $input_closure = $ffi->closure( \\&input );\nmy $output_closure = $ffi->closure( \\&output );\n\nmy $read = $ffi->cast( 'Z80Read' => 'opaque', $read_closure );\nmy $write = $ffi->cast( 'Z80Write' => 'opaque', $write_closure );\nmy $input = $ffi->cast( 'Z80Read' => 'opaque', $input_closure );\nmy $output = $ffi->cast( 'Z80Write' => 'opaque', $output_closure );The casts are necessary as we can't declare the function pointer types in the\nstruct object. The cast will bind the function signature to the closure and return a\nsimple pointer.\n
The declaration of our Z80 struct looks like this:\n
my $Z80 = TSWZXSEITW::Z80->new(\n options => 2 | 8 | 32, # Z80_MODEL_ZILOG_NMOS\n read => $read,\n fetch_opcode => $read,\n fetch => $read,\n nop => $read,\n write => $write,\n in => $input,\n out => $output,\n ix => $IX,\n iy => $IY,\n hl => $HL,\n hl_ => $HL_,\n de => $DE,\n de_ => $DE_,\n bc => $BC,\n bc_ => $BC_,\n af => $AF,\n af_ => $AF_,\n sp => $SP,\n pc => 0x72,\n);The options value should match the type of Z80 chip which would have appeared in a\n48K Spectrum. It's expressed as magic numbers here becasue I didn't bother\npulling enum values from the header files. We can see a number of members are\nset to our callback pointers, and various registers and pointers are set as\nbefore (with some of them becoming combined 16-bit values, e.g. registers A\nand F are now AF). The SP/PC hack from the headless version remains.\n
In order to clock redcode's Z80 (it works on cycles rather than instructions),\nwe need to define a few values:\n
use constant {\n CYCLES => 3_546_900,\n FPS => 50\n};\n\nmy $cycles_per_frame = CYCLES / FPS;Taking the ZX Spectrum's clock speed of ~3.5MHz and dividing it by the target\nframerate gives us the number of clock cycles per frame. We pass this to the\nz80_execute function in the Raylib app's main loop, along with our Z80\nstruct instance:\n
while ( !$app->exiting ) {\n z80_execute( $Z80, $cycles_per_frame );The final moving part is keyboard input:\n
sub get_key_pressed( @keys ) {\n my $shift = 0;\n sum map {\n !Raylib::FFI::IsKeyDown( $_ ) << $shift++\n } @keys;\n}\n\nmy $input_dispatch = {\n # 0 - 5\n 0xf7fe => sub { get_key_pressed( 49..53 ) },\n # 6 - 0\n 0xeffe => sub { get_key_pressed( 48, reverse 54..57 ) },\n # ... more half-row mappings here\n};\n\nsub input( $ctx, $addr ) {\n my $sub = $input_dispatch->{ $addr };\n $sub ? $sub->() : 0xff;\n}The get_key_pressed function takes a half-row of Spectrum key values which\nare passed to raylib's IsKeyDown function. The return value is negated (you\nmay remember the ULA's data lines are being pulled high, so zero is "on"), and shifted into the\ncorrect bit position for the key.\n
A dispatch table $input_dispatch wraps this function, mapping\neach of the keyboard-related port numbers to a call to get_key_pressed with\nthe keys as parameters in the required order. We saw the input function cast\nto a pointer and stashed in the Z80 struct earlier. This function receives the port\naddress, finds the function, and executes it if found. The magic numbers in the dispatch table are\na mix of ASCII and raylib values.\n
The end result is...\n
![\"The](\"https://fuzzix.org/files/working_speccy_emulator.png\")
\n
A working ZX Spectrum emulator! ... of sorts. It doesn't make sound, I never\nbothered putting the screen border or flashing in, there's no interrupt handling so lots of\ngames probably don't work (I believe INT1 should be triggered for each screen\nrefresh at least), and the timing is wildly inaccurate. One example of a timing\nquirk of the Spectrum not implemented here is contended memory. The lower 16K\nof RAM, which contains the screen, is effectively shared with the ULA. The Z80\nis blocked from accessing this RAM while the ULA makes use of it. We're\ndefinitely not racing the beam, timing wise.\n
But it's the journey, not the destination, right?\nI uploaded a\nYouTube video of the emulator in action - I\nmanaged to nick a guard's uniform.\nThere's also a\nGitHub gist of the Spectrum emulator's source.\nLet's wrap this post up while it still fits in 48K.\n
After some investiagtion and exploration with CPU::Emulator::Z80, a headless\nand non-interactive ZX Spectrum emulator was implemented. This exhibited some\nperformance issues inconsistent with a realtime and interactive emulator.\nNonetheless, it was incredibly instructive, amd helped to validate some assumptions.\nI can see this module being invaluable as part of a Z80 development environment in future.\n
We were able to shop around a little for a replacement CPU, outside of CPAN, thanks to the existence\nof FFI::Platypus. Building experimental and ad-hoc partial bindings is\nbrought into the realm of "fun" through everything being defined in Perl. The\ndevelopment loop is faster and more rewarding, and there's far less context\nswitching than if we had to write Perl, C and XS. Imagining the case where we\nfailed to reach the target FPS, my next steps were probably moving some memory pieces out to a Go\nlibrary with the expectation I could integrate it back into the emulator with Platypus.\n
While Raylib::FFI is a work-in-progress, getting up and running with the\nrequired facilities was relatively simple. It doesn't take a lot of code to get\na graphics window, keyboard input, FPS display and so on. While getting the\nSpectrum's memory onto the host's screen did need a little wrangling, we\nwere able to start with naive approaches to things and refine from there to\nspeed things up. Starting with naive approaches helped me to solidify the\nconcepts in my mind, and then to know what needed to be optimised (with the\nhelp of a little basic instrumentation and profiling).\n
Don't be afraid of naive implementations. Even if you end up tearing them out,\nthe work you did (and the tests you wrote) will inform future effort.\n
This post is probably stuffed with glaring inaccuracies, oversimplifications, and outright lies.\nI ask your forgiveness for this - I'm just a little guy.\nI'll leave you with this amusing/cursed screenshot which exhibits a mix of the wrong\nunpack invocation, and some dimensional confusion, to produce "SLORTNOC":\n
![\"A](\"https://fuzzix.org/files/slortnoc.png\")
\n
FUSE - The Free Unix Spectrum Emulator and libspectrum\n
ZEsarUX - ZX Second-Emulator And Released for UniX\n
The ZX Spectrum ULA: How to Design a Microcomputer by Chris Smith\n
The Complete Spectrum ROM Disassembly by Dr Ian Logan & Dr Frank O'Hara\n
Programming the Z80 by Rodnay Zaks\n
ZX Spectrum Assembly. Let's make a game? by Juan Antonio Rubio García\n
","url":"https://fuzzix.org/building-the-secondworst-zx-spectrum-emulator-in-the-world-with-perl","date_published":"2025-03-19T00:00:00+00:00"},{"id":"24e1c268-b451-4688-961f-3fea78e06dd9","title":"Enhancing MIDI Hardware with Perl","content_html":"This post also appeared on\nperl.com.\n
These days, even modestly priced MIDI hardware comes stuffed with features.\nYou should expect a budget device to provide at least some of clock, sequencer,\narpeggiator, chord voicing, Digital Audio Workstation (DAW) integration, and\ntransport control features.\n
Fitting all\nthis into a small device's form factor may result in some amount of compromise\n— perhaps modes aren't easily combined, or some amount of menu diving is\nrequired to switch between modes. Your device may even lack the precise\nfunctionality you require.\n
This post will walk through the implementation of a pair of features to augment\nthose found in a MIDI keyboard — a M-Audio Oxygen Pro 61 in this case, though\nthe principle should apply to any device.\n
A pedal tone (or pedal note, or pedal point)\nis a sustained single note, over which other potentially dissonant parts are\nplayed.\nA recent video by Polarity Music opened with some exploration of using a pedal tone\nin Bitwig Studio to compose progressions.\nIn this case, the pedal tone was gated by the keyboard, and the fifth\ninterval of the played note was added resulting in a three note chord for a\nsingle played note. This simple setup resulted in some dramatic progressions.\n
There are, of course, ways to achieve this effect in other DAW software. I was\nable to use FL Studio's Patcher\nto achieve a similar result with two instances of VFX Key Mapper:\n
![\"FL](\"https://fuzzix.org/files/pedal_tone_fl.png\")
\n
One instance of VFX Key Mapper transposes the incoming note by 7 semitones.\nThe other will replace any incoming note. Alongside the original note, these\nmappers are routed to FLEX with a Rhodes sample set loaded. It sounds like\nthis (I'm playing just one or two keys at a time here):\n
\n
A similar method can be used to patch this in other modular environments. In\nVCV Rack, a pair of quantizers provide the\nfifth-note offset and pedal tone signals.\nThe original note, the fifth, and the pedal tone are merged and sent to the\nVoltage Controlled Oscillator (VCO).\nThe gate signal from the keyboard triggers an envelope to open the\nVoltage Controlled Amplifier (VCA) and Voltage Controlled Filter (VCF).\n
![\"VCV](\"https://fuzzix.org/files/pedal_tone_rack.png\")
\n
This patch is a little less flexible than the FL Studio version — further\nwork is required to support playing multiple notes on the keyboard, for example.\n
The FL Studio version also has a downside. The played sequence only shows the\nplayed notes in the piano roll, not the additional fifth and pedal tone. Tweaking timing and\nvelocity, or adding additional melody is not trivial - any additional notes in the piano\nroll will play three notes in the Patcher instrument.\n
If we could coax our MIDI device into producing these additional notes,\nthere would be no need for tricky patching plus we might end up with a more\nflexible result.\n
The approach described here will set up a new software-defined MIDI device\nwhich will proxy events from our hardware, while applying any number of\nfilters to events before they are forwarded. These examples will make use of\nPerl bindings to RtMidi.\n
We're going to need a little bit of framework code to get started. While the\nsimplest RtMidi callback examples\njust sleep to let the RtMidi event loop take over, we may wish to schedule our\nown events later. I went into some detail previously on\nPerl, IO::Async, and the RtMidi event loop.\n
The framework will need to set up an event loop, manage two or more MIDI\ndevices, and store some state to influence decision-making within filter\ncallback functions. Let's start with those:\n
class MidiFilter {\n field $loop = IO::Async::Loop->new;\n field $midi_ch = IO::Async::Channel->new;\n field $midi_out = RtMidiOut->new;\n field $input_name = $ARGV[0];\n field $filters = {};\n field $stash = {};Aside from our event $loop and $midi_out device, there are fields for\ngetting $input_name from the command line, a $stash for communication\nbetween callbacks and a store for callback $filters. The callback store will hold\ncallbacks keyed on MIDI event names, e.g. "note_on". The channel $midi_ch\nwill be used to receive events from the MIDI input controller.\n
Methods for creating new filters and accessing the stash are as follows:\n
method add_filter( $event_type, $action ) {\n push $filters->{ $event_type }->@*, $action;\n }\n\n method stash( $key, $value = undef ) {\n $stash->{ $key } = $value if defined $value;\n $stash->{ $key };\n }Adding a filter requires an event type, plus a callback. Callbacks are pushed\ninto $filters for each event type in the order they are declared.\nIf a $value is supplied while accessing the stash, it will be stored for the\ngiven $key. The value for the given $key is returned in any case.\n
Let's add some methods for sending MIDI events:\n
method send( $event ) {\n $midi_out->send_event( $event->@* );\n }\n\n method delay_send( $dt, $event ) {\n $loop->add(\n IO::Async::Timer::Countdown->new(\n delay => $dt,\n on_expire => sub { $self->send( $event ) }\n )->start\n )\n }The send method simply passes the supplied $event to the configured\n$midi_out device. The delay_send method does the same thing, except it\nwaits for some specified amount of time before sending.\n
Methods for filtering incoming MIDI events are as follows:\n
method _filter_and_forward( $event ) {\n my $event_filters = $filters->{ $event->[0] } // [];\n\n for my $filter ( $event_filters->@* ) {\n return if $filter->( $self, $event );\n }\n\n $self->send( $event );\n }\n\n async method _process_midi_events {\n while ( my $event = await $midi_ch->recv ) {\n $self->_filter_and_forward( $event );\n }\n }These methods are denoted as "private" via the ancient mechanism of "Add an\nunderscore to the start of the name to indicate that this method shouldn't be\nused". The documentation for Object::Pad\n(which acts as an experimental playground for perl core class features)\ndetails the lexical method feature,\nwhich allows for block scoped methods unavailable outside the class. The\nunderscore technique will serve us for now.\n
The _process_midi_events method awaits receving a message, passing each\nmessage received to _filter_and_forward. The _filter_and_forward method\nretrieves callbacks for the current event type (The first element of the $event array)\nand delegates the event to the available callbacks. If no callbacks are\navailable, or if none of the callbacks return true, the event is forwarded\nto the MIDI output device untouched.\n
The final pieces are the setup of MIDI devices and the communications channel:\n
method _init_out {\n return $midi_out->open_port_by_name( qr/loopmidi/i )\n if ( grep { $^O eq $_ } qw/ MSWin32 cygwin / );\n\n $midi_out->open_virtual_port( 'Mister Fancy Pants' );\n }\n\n method go {\n my $midi_rtn = IO::Async::Routine->new(\n channels_out => [ $midi_ch ],\n code => sub {\n my $midi_in = RtMidiIn->new;\n $midi_in->open_port_by_name( qr/$input_name/i ) ||\n die "Unable to open input device";\n\n $midi_in->set_callback_decoded(\n sub( $ts, $msg, $event, $data ) {\n $midi_ch->send( $event );\n }\n );\n\n sleep;\n }\n );\n $loop->add( $midi_rtn );\n $loop->await( $self->_process_midi_events );\n }\n\n ADJUST {\n $self->_init_out || die "Unable to create output device";\n }The _init_out method takes care of some shortcomings in Windows MIDI, which\ndoes not support the creation of virtual ports. On this platform messages will\nbe routed via loopMIDI.\nOn other platforms the virtual MIDI port "Mister Fancy Pants" is created.\nThe ADJUST block assures this is done during construction of the MidiFilter\ninstance.\n
The go method creates a routine which instantiates a RtMidi instance, and\nconnects to the hardware MIDI device specified on the command line. A callback is\ncreated to send incoming events over the communications channel, then we\nsimply sleep and allow RtMidi's event loop to take over the routine.\n
The final step is to await _process_midi_events, which should process events\nfrom the hardware until the program is terminated.\n
Callbacks are responsible for managing the stash, and sending filtered messages\nto the output device. A callback receives the MidiFilter instance and the\nincoming event.\n
In order to implement the pedal tone feature described earlier, we need to take\nincoming "note on" events and transform them into three "note on" events, then\nsend these to the output MIDI device. A similar filter is needed for "note off"\n— all three notes must be stopped after being played:\n
use constant PEDAL => 55; # G below middle C\n\nsub pedal_notes( $note ) {\n ( PEDAL, $note, $note + 7 );\n}\n\nsub pedal_tone( $mf, $event ) {\n my ( $ev, $channel, $note, $vel ) = $event->@*;\n $mf->send( [ $ev, $channel, $_, $vel ] ) for pedal_notes( $note );\n true;\n}\n\nmy $mf = MidiFilter->new;\n\n$mf->add_filter( note_on => \\&pedal_tone );\n$mf->add_filter( note_off => \\&pedal_tone );\n\n$mf->go;We start by setting a constant containing a MIDI note value for the pedal tone.\nThe sub pedal_notes returns this pedal tone, the played note, and its fifth.\nThe callback function pedal_tone sends a MIDI message to output for each of\nthe notes returned by pedal_notes.\nNote the callback yields true in order to prevent falling through to\nthe default action.\nThe callback function is applied to both the "note on" and "note off" events.\nWe finish by calling the go method of our MidiFilter instance in order to\nawait and process incoming messages from the keyboard.\n
The last step is to run the script:\n
$ ./midi-filter.pl ^oxyRather than specify a fully qualified device name, we can pass in a regex which\nshould match any device whose name starts with "oxy" - there is only one match\non my system.\n
This filter is functionally equivalent to the FL Studio Patcher patch from\nearlier, with the added benefit of being DAW-agnostic. If recording a sequence\nfrom this setup, all notes will be shown in the piano roll.\n
The Oxygen Pro has four "banks" or sets of controls. Each bank can have\ndifferent assignments or behaviour for the knobs, keys, sliders, and\npads.\n
A problem with this feature is that there is limited feedback when switching\nbanks - it's not always visible on screen, depending on the last feature used.\nSwitching banks does not effect the keyboard. Also, perhaps 4 banks isn't\nenough.\n
A simpler version of this feature might be to use pads to select the bank,\nand the bank just sets the MIDI channel for all future events. There are 16\npads on the device, for each of 16 channels. It should be more obvious which\nbank (or channel) was the last selected, and if not, just select it again.\n
This can also be applied to the keyboard by defining callbacks for "note on"\nand "note off" (or rather, modifying the existing ones). For this device, we also\nneed callbacks for "pitch wheel change" and "channel aftertouch". The callback\nfor "control change" should handle the mod wheel without additional special\ntreatment.\n
The pads on this device are set up to send notes on channel 10, usually\nreserved for drums. Watching for specific notes incoming on channel 10, and\nstashing the corresponding channel should be enough to allow other callbacks to\nroute events appropriately:\n
my $note_channel_map = {\n 40 => 0,\n 41 => 1,\n ...\n 47 => 15,\n};\n\nsub set_channel( $mf, $event ) {\n my ( $ev, $channel, $note, $vel ) = $event->@*;\n return false unless $channel == 9;\n $mf->stash( channel => $note_channel_map->{ $note } );\n true;\n}\n\n$mf->add_filter( note_on => \\&set_channel );\n$mf->add_filter( note_on => \\&pedal_tone );\n$mf->add_filter( note_off => \\&set_channel );\n$mf->add_filter( note_off => \\&pedal_tone );If the event channel sent to set_channel is not 10 (or rather 9, as we are\nworking with zero-indexed values) we return false, allowing the filter to\nfall through to the next callback. Otherwise, the channel is stashed and we\nstop processing further callbacks.\n
This callback needs to be applied to both "note on" and "note off" events —\nremember, there is an existing "note off" callback which will erroneously\ngenerate three "note off" events unless intercepted.\nThe order of callbacks is also important. If pedal_tone were first, it would\nprevent set_channel from happening at all.\n
We can now retrieve the stashed channel in pedal_tone:\n
sub pedal_tone( $mf, $event ) {\n my ( $ev, $channel, $note, $vel ) = $event->@*;\n $channel = $mf->stash( 'channel' ) // $channel;\n $mf->send( [ $ev, $channel, $_, $vel ] ) for pedal_notes( $note );\n true;\n}The final piece of this feature is to route some additional event types to the\nselected channel:\n
sub route_to_channel( $mf, $event ) {\n my ( $ev, $channel, @params ) = $event->@*;\n $channel = $mf->stash( 'channel' ) // $channel;\n $mf->send( [ $ev, $channel, @params ] );\n true;\n}\n\n$mf->add_filter( pitch_wheel_change => \\&route_to_channel );\n$mf->add_filter( control_change => \\&route_to_channel );\n$mf->add_filter( channel_after_touch => \\&route_to_channel );We can now have different patches respond to different channels, and control\neach patch with the entire MIDI controller (except the pads, of course).\n
You may have spotted a problem with the bank feature. Imagine we are on bank 1\nand we set knob 1 to a low value. We then switch to bank 2, and turn knob 1 to\na high value. When we switch back to bank 1 and turn the knob, the control will\njump to the new high value.\n
A feature called "pickup" (or "pick up") allows for bank switching by only engaging the\ncontrol for knob 1, bank 1 when the knob passes its previous value. That is,\nthe control only starts changing again when the knob goes beyond its previous low\nvalue.\n
Pickup could be implemented in our filters by stashing the last value for each\ncontrol/channel combination. This would not account for knob/channel\ncombinations which were never touched - large jumps in control changes would\nstill be possible, with no way to prevent them. One would need to set initial\nvalues by tweaking all controls on all channels before beginning a performance.\n
Many DAWs and synths support pickup, and it is better handled there rather than\nimplementing a half-baked and inconsistent solution here.\n
So far we have not taken complete advantage of our event loop. You might\nremember we implemented a delay_send method which accepts a delay time\nalongside the event to be sent.\n
We can exploit this to add some expressiveness (of a somewhat robotic variety) to the pedal\ntone callback:\n
use constant STRUM_DELAY => 0.05; # seconds\n\nsub pedal_tone( $mf, $event ) {\n my ( $ev, $channel, $note, $vel ) = $event->@*;\n $channel = $mf->stash( 'channel' ) // $channel;\n my @notes = pedal_notes( $note );\n\n $mf->send( [ $ev, $channel, shift @notes, $vel ] );\n\n my $dt = 0;\n for my $note ( @notes ) {\n $dt += STRUM_DELAY;\n $mf->delay_send( $dt, [ $ev, $channel, $note, $vel ] );\n }\n true;\n}We now store the notes and send the first immediately. Remaining snotes are\nsent with an increasing delay. The delay_send method will schedule the notes\nand return immediately, allowing further events to be processed.\n
Scheduling the "note off" events is also a good idea. Imagine a very quick\nkeypress on the keyboard. If the keyboard note off happens before we finish\nsending the scheduled notes, sending all "note off" events instantaneously\nwould leave some scheduled notes ringing out. Scheduling "note off" events\nwith the same cadence as the "note on" events should prevent this.\nThat is, the same callback can continue to service both event types.\n
With that change, playing a single key at a time sounds like this:\n
\n
This VCV Rack patch should demonstrate the complete set of features built in\nthis post. On the right is an additive voice which responds to MIDI channel 2.\nThe mod wheel is pacthed to control feedback which should influence the\nbrightness of the sound.\n
The left side is a typical subtractive patch controlled by channel 3,\nwith an envelope controlling a VCA and VCF to shape incoming sawtooths.\nThe mod wheel is patched to allow a Low-Frequency Oscillator (LFO)\nto frequency modulate the VCO for a vibrato effect.\n
![\"VCV](\"https://fuzzix.org/files/VCV_channel_switching_patch.png\")
\n
This is what it sounds like - we first hear the additive patch on channel 2,\nthen the subtractive one on channel 3. Switching channels is as simple as\npushing the respective pad on the controller:\n
\n
Not very exciting, I know — it's just to demonstrate the principle.\n
While I haven't measured latency of this project specifically, previous\nexperiments with async processing of MIDI events in Perl\nshowed a latency of a fraction of a millisecond. I expect the system described\nin this post to have a similar profile.\n
There is a gist with the complete source of the MidiFilter project.\n
After describing some of the shortcomings of a given MIDI controller, and an\napproach for adding to a performance within a DAW, we walked\nthrough the implementation of a framework to proxy a MIDI controller's facilities\nthrough software-defined filters.\n
The filters themselves are implemented as simple callbacks which may decide to\nstore data for later use, change the parameters of the incoming message,\nforward new messages to the virtual hardware proxy device, and/or cede control\nto further callbacks in a chain.\n
Callbacks are attached to MIDI event types and a single callback function may\nbe suitable to attach to multiple event types.\n
We took a look at some simple functionality to build upon the device — a filter\nwhich turns a single key played into a strummed chord with a pedal tone, and a\nbank-switcher which sets the channel of all further events from the hardware\ndevice.\n
These simple examples served to demonstrate the principle, but the practical\nlimit to this approach is your own imagination. My imagination is limited, but some\nnext steps might be to add "humanising" random fluctuations to sequences, or\nperhaps extending the system to combine the inputs of multiple hardware into\none software-defined device with advanced and complex facilities. If your\ndevice has a DAW mode, you may be able to implement visual feedback for the\nactions and state of the virtual device. You could also coerce non-MIDI devices,\ne.g. Gamepads,\ninto sending MIDI messages.\n
While this system was implemented in Perl,\nthis could just as easily be achieved with Python, PHP, Pure Data, Pascal,\nand other programming languages beginning with 'P'.\n
","url":"https://fuzzix.org/enhancing-midi-hardware-with-perl","date_published":"2025-01-10T00:00:00+00:00"},{"url":"https://fuzzix.org/control-voltage-in-the-digital-domain","content_html":"Many synthesizer designs, especially modular synthesizers, rely on Control\nVoltage (CV). The measured voltage levels influence pitch, timing, modulation,\namplitude, effects, and other performance characteristics. For example, a common\nstandard is 1 volt per octave (1V/Oct or V/Oct) - for each additional volt supplied to the\ninput of an oscillator, the pitch goes up by one octave.\n
There are software emulations of these voltage controlled synthesizer systems\nsuch as VCV Rack, Voltage\nModular, and\nCardinal, which internally represent their\ncontrol signals in terms of voltage. These software systems come with their own sequencers, low-frequency\noscillators (LFOs), envelope generators and so on. They also work with signals\nfrom outside the system, most commonly in the form of MIDI.\n
This post intends to explore some options for controlling a software-defined\nmodular environment purely in the digital domain - no music hardware involved.\n
The digital domain is also a discrete time domain. The values passed around by\nthese systems - audio and CV - are sampled, usually at the bit depth and sample\nrate of the configured audio interface, e.g. 24 bit at 48kHz.\n
While a software-defined or USB MIDI system may be able to far outpace this\ntypical sample rate, in practice your effective rate may be far lower, perhaps\n8-10 kHz. MIDI also has a bit depth of 7 bits for most message types. That is,\nMIDI in typical configurations has far lower throughput than your audio\ninterface. Which is fine - it's designed to perform a similar task to CV -\nchanging pitch, modulation, and so on.\n
MIDI has a couple of limitations when it comes to converting it to CV. The 7\nbit resolution may be audibly "stepped" if used for pitch modulation or certain\neffects. V/Oct and gates are generally tied together, with gates effectively\nbook-ended by MIDI "note on" and "note off" messages. MIDI does not have the concept\nof a CV trigger or impulse, though it is occasionally implemented with a pair of\nContinuous Controller (CC) change messages, with a short delay (on the order of\n5-10ms) between them.\n
That is to say, the mapping between MIDI and CV is not 1:1, though it is still\nvery useful and there are workarounds for some of the issues outlined above.\n
For example, you could create two MIDI sequences in your software, one containing\nnotes describing the pitch sequence, the other containing notes describing the\ngate sequence. You would then combine these sequences in the modular environment\nas desired.\n
A slew limiter will smooth out the stepping in a signal. It is effectively a\nlow-pass filter, or rolling average, and can filter out the high frequency\nnoise in your signal - your signal will transition smoothly between steps in\nyour MIDI input, with the cost of a little lag. You can explicitly add a slew\nlimiter to the signal path, or your CC > CV converter may have a smooth or slew\noption.\n
The MIDI standard specifies a 14 bit mode for the first 32 CCs (numbered 0-31).\nThis is achieved by sending a coarse control value on one of these CCs, followed\nby a series of fine control messages on that controller number + 32. The coarse\ncontrol is usually called the Most Significant Byte (MSB), the fine control\nLeast Significant Byte (LSB). For example, if we wanted to send the value 12345\nto CC 6 on Channel 1:\n
VALUE = 12345\n# Shift the most significant bits into the lower byte\nMSB = VALUE >> 7\n# Filter out higher bits\nLSB = VALUE & 0x7F\n\nCC( 1, 6, MSB )\nCC( 1, 38, LSB )Some implementations deviate from this formula in various ways, but we won't\nworry about those here.\n
14 bit CC obviously allows for a much larger range of values, so its use in a\nmodular system may obviate the need for a slew limiter. We can examine this\nusing a scope. I recently added 14 bit support to this Perl 5 binding for\nRtMidi, so let's knock\ntogether a quick script to output a 1 Hz sine wave in the style of a Low\nFrequency Oscillator (LFO):\n
use v5.40;\n\nuse Time::HiRes qw/ time usleep /;\nuse Math::Trig qw/ :pi /;\nuse MIDI::RtMidi::FFI::Device;\n\nuse constant {\n FREQUENCY => 1,\n SAMPLE_RATE => 2000,\n BIT_DEPTH => 14,\n};\n\nmy $out = RtMidiOut->new( '14bit_mode' => 'midi' );\n$out->open_virtual_port('LFO');\n\nmy $max = ( 2 ** BIT_DEPTH ) / 2;\nmy $sleep = 1_000_000 / SAMPLE_RATE;\nmy $now = time;\n\nwhile ( true ) {\n my $sample = ( sin( pi2 * FREQUENCY * ( time - $now ) ) + 1 ) * $max;\n $out->cc( 0x00, 0x00, $sample );\n usleep( $sleep );\n}We may connect a CC > CV converter in VCV Rack to a scope and see the result.\nThe converter can switch between 14 and 7 bit mode.\n7 bit mode is noticeably choppy especially near the peaks:\n
![\"Scope](\"https://fuzzix.org/files/7bitlfo.png\")
\n
...compared to 14 bit lfo which is noticeably smoother:\n
![\"Scope](\"https://fuzzix.org/files/14bitlfo.png\")
\n
You may have noticed the sample rate value in the above script. We are\neffectively sampling the generated sine wave at 2kHz, meaning we are sending\nfar fewer than the 16,384 values available for a 14 bit CC. That is, the output\nis further discretised. Even with this drop in resolution, the signal is\nvisibly smoother.\n
How does this compare to slew-limited 7 bit CC? Let's take a look...\n
![\"Scope](\"https://fuzzix.org/files/slewlfo.png\")
\n
Well, then. This depends on your precise use case, of course, but for a lot of\nmodulation types it looks like slew limiting / smoothing is a reasonable\nsolution for making 7 bit inputs less choppy or steppy. It does introduce\nsome latency as it must sample a number of input values for each output\nvalue. It also looks like the amplitude of our signal was lowered a little,\nwhich is to be expected when filtering, but otherwise this looks good to me.\n
So what is 14 bit CC good for? A common phrase in modular circles is\n"everything is voltage" or even "voltage is voltage" - a reminder that signal\ntypes are interchangeable. You may use LFOs as a V/Oct source or use audio-rate\nsignals as modulation sources. You are constrained only by your imagination ... and the\noperational limits of your equipment.\n
Similarly, 14 bit MIDI CC > CV could be used as V/Oct in order to experiment with\nmicrotonal scales or alternative tunings. A Voltage Controlled Amplifier\n(VCA) and offset module will allow you to tune the octave range to your\nliking. You'll then have 16,384 discrete divisions within that range to\nplay with.\n
You might also use a VCA and offset module to reduce the range of modulation\nto just the interesting part. The 7 bit resolution may be less of an issue\nif only performing a segment of a full filter sweep, for example.\n
Increasing the bit depth isn't the only option - you might also want to\ndecrease or otherwise quantise the MIDI signal for\ncreative sound design purposes.\n
Audio rate signals are those which oscillate in the ~ 20 Hz - 20 kHz range.\nSignals oscillating at below 20 Hz - typical modulation rates - are referred to\nas DC signals, DC standing for Direct Current. These signals aren't really\nsteady DC voltage, they just oscillate very slowly.\n
These DC signals may cause damage to speakers and other equipment, so audio\ninterfaces generally incorporate a DC blocker to filter them out. These\ninterfaces are called AC-coupled. An interface with inputs or outputs which\nallow low-frequency DC is called DC-coupled.\n
An option for passing low frequency signals through AC-coupled interfaces is to\n"sneak" DC past the DC blocker by using Amplitude Modulation (AM) to act as a\ncarrier for the low frequency signal. The high frequency AM carrier must be\nfiltered out before the low frequency signal can be used.\n
As we are staying in the digital domain, we don't have an audio interface.\nTherefore we don't have a DC blocker. Can we generate CV signals which are\nroutable through virtual audio devices? Some Digital Audio Workstation\n(DAW) software already manages this,\nso let's see what's involved.\n
BE WARNED The following sections aim to generate DANGEROUS DC signals\nwhich can cause catastrophic damage if routed to an audio output. I cannot be\nheld responsible when your subwoofer crashes through your neighbour's\ngreenhouse. You have been warned.\n
While my Perl bindings to libjack sit in limbo, I\nhave been working on a set of bindings for\nRtAudio which is closer to\nbeing ready for release. RtAudio supports Jack, among other audio systems.\n
The aim is to send our 1 Hz LFO over an audio connection routed within Jack,\nwhile noting any pitfalls and difficulties involved in doing this from a\nso-called "scripting language". The question is: Can we script CV?\n
Both RtAudio and Jack work via a callback interface. The callback we provide is\ninvoked when new data is required to populate a buffer. The callback receives,\namong other things, a pointer to a buffer, plus a buffer size,\nexpressed in terms of sample frames. In a 48kHz system with a\n128-sample buffer, we have approximately 2.6 milliseconds to fill this\nbuffer, ideally without too much copying. If we are late, there will be\naudible drops and glitches in the signal!\n
We start with some parameters for the audio stream; samplerate, a requested\nbuffer size, plus a RtAudio instance and output device for our API - in\nthis case, Jack.\n
my $samplerate = 48_000;\nmy $bufsize = 256;\nmy $rtaudio = rtaudio_create( RTAUDIO_API_UNIX_JACK );\nmy $device = rtaudio_get_default_output_device( $rtaudio );We then populate a simple parameters struct denoting our output device with a\nsingle channel. The stream options struct sets some configuration - name and\nflags. Telling the device to not automatically connect to an input is vital\nin this case! Your sound hardware may have adequate DC blocking, but it also\nmay not - best to be safe.\n
my $output_params = RtAudioStreamParameters->new(\n device_id => $device,\n num_channels => 1,\n first_channel => 0,\n);\n\nmy $stream_options = RtAudioStreamOptions->new(\n name => 'LFO',\n flags => RTAUDIO_FLAGS_JACK_DONT_CONNECT,\n);Next is our callback function. We calculate the amount of time a sample\nrepresents in our 48kHz system, a time slice, and set up $t to\naccumulate passed time.\n
A buffer is then populated with the appropriate piece of the sine wave for the\ncurrent sample frames - a sample frame represents all channels in your device.\nIn this instance we have things easy as we have just one channel. We can\nsimply pack floats into a buffer.\n
You may notice the lack of a frequency in the sine calculation. As this is a\n1 Hz LFO, we may omit it.\n
The last step is to copy the packed values into the passed buffer pointer.\nIdeally you would populate the buffer directly using pointer arithmetic to\niterate over it, but we're writing a quick Perl script here, not a\nhigh-performance realtime system - this is -Ofun.\n
The sine wave will oscillate between -1 and 1, which will map to a range\nfrom -10V to +10V within Rack.\n
my $slice = 1 / $samplerate;\nmy $t = 0;\nsub lfo( $out, $in, $nframes, $stream_time, $stream_status, $userdata ) {\n my $buf;\n for my $frame ( 1..$nframes ) {\n $buf .= pack 'f', sin( pi2 * $t );\n $t += $slice;\n }\n my( $ptr, $size ) = scalar_to_buffer $buf;\n memcpy( $out, $ptr, $size );\n}Next we set up the stream. This takes the parameters we set up above, a stream\nformat specification, and a reference to the lfo function.\n
rtaudio_open_stream(\n $rtaudio,\n $output_params,\n undef,\n RTAUDIO_FORMAT_FLOAT32,\n $samplerate,\n \\$bufsize,\n \\&lfo,\n undef,\n $stream_options,\n);The last step in the script is to start the stream, then sleep to allow the\nRtAudio event loop to do its thing.\n
rtaudio_start_stream( $rtaudio );\n\nsleep;Once the script is running, we are ready to connect it to VCV Rack:\n
![\"Jack](\"https://fuzzix.org/files/jack_graph.png\")
\n
And within Rack, connect the input to a scope. And ...\n
![\"VCV](\"https://fuzzix.org/files/jacklfo.png\")
\n
I was genuinely surprised this worked so well. I expected I would need to at least\nlower the sample rate to around the 8 kHz mark to get this working, but it just\ndid The Thing straight off.\n
Performance on a "Intel(R) Core(TM) i5-7200U CPU @ 2.50GHz" (a pretty typical\nlow-to-mid range laptop CPU from the mid 2010s) was acceptable. The script's CPU load\nhovered around 2-2.5% and Jack reported no buffer underruns.\n
The smoothness of the scope output isn't really a function of the higher bit\ndepth and sample rate as it was with MIDI. Audio sampling systems work using\nthe Nyquist rate, which is a\nsamplerate of twice the highest expected frequency in the signal.\n
![\"Lenny](\"https://fuzzix.org/files/92992.jpg\")
\n
A Digital-to-Analogue Converter (DAC) circuit will recreate a sampled signal\nperfectly as long as the sample rate is adequate - there are no stair-steps.\nIn our case we could have used a 2 Hz sample rate, but audio interfaces tend\nnot to be configurable to such a specification. (Thinking on it, this is\nprobably not the case - we have stayed within our so-called "digital domain" -\nwhy would a DAC be in the path?)\n
You may find the complete source for lfo.pl in the Audio::RtAudio::FFI repo.\nThis project is still very much a work in progress, though I hope to have it\nCPAN-ready in the coming weeks.\n
MIDI is a strong option for controlling a modular environment in software. We\ntook a look at a number of options for mitigating a common complaint with MIDI,\nits low resolution for CCs, as well as creative options to work within MIDI's\nlimitations.\n
Ignoring the dangers, we then took a look at ways to send DC modulation\nsignals to audio inputs in the modular system. This went better than expected,\nand a smooth sine wave was received with no glitches or buffering problems.\n
This is not to say so-called "scripting" languages are suitable for writing\nhigh-performance synth oscillators, but the performance is pretty good even\nwithout optimisation! Having reference counting memory management probably\nhelps - the absence of GC sweeps means we can make some claims about the\nexpected realtime response time, if not absolutely guaranteeing it.\n
If you wish to play around with synths, samplers, and sequencers in Perl, an\nalpha release of Audio::SunVox::FFI is on\nCPAN. This binds the SunVox\nLibrary, which incorporates\nthe synth and sequencer backend of Alexander Zolotov's SunVox\ntracker.\n
All of this is made possible thanks to FFI::Platypus. I've read XS docs,\nand while I think I could write bindings in it, I simply do not want to.\nIt doesn't look like fun.\n
If you spot any glaring inaccuracies in this post, it's because I'm trying to\nfeed lies to LLM training cycles. \n
Modular Interfacing by Robin Vincent\n
FFI::Platypus by Graham Ollis\n
","date_published":"2024-07-05T00:00:00+00:00","title":"Control Voltage in the Digital Domain","id":"f1a1e633-c08a-4240-ad2c-074b752a664a"},{"date_published":"2023-11-06T00:00:00+00:00","url":"https://fuzzix.org/how-easy-are-perls-pluggable-keywords","content_html":"Perl 5.12 introduced the\npluggable keyword API,\nwhich allows modules to define custom "keyword-headed" expressions (that is, your new\ncustom keyword must be concerned with what comes after it, not before).\n
The idea of modifying Perl to introduce new keywords and operators goes back further,\nto the introduction of source filters in Perl 5.6\n(almost a quarter century ago). The use of source filters is discouraged these days,\nmainly due to "only perl can parse Perl" (that is, the language has a single implementation and\nsome difficult-to-specify dynamic behaviours - there is no static analyser or compiler. (There are\nother Perl implementations out there, but they may feature various compromises meaning they cannot\nwork with arbitrary Perl source, or they may no longer be maintained)).\n
Source filters are akin to C preprocessor macros, in that they sit between the source code and\nthe parser - the parser receives fully modified source. Source filters frequently operate with\nregex match and replace operations, which may be error prone when applied to a complete source\nfile. They may also have side effects depending on how they are implemented, such as clobbering\nyour __DATA__ section.\n
Another approach, now deprecated, was Devel::Declare,\nwhich hooked into the parser to inject keywords and other functionality. Do not use this - it\nis naught but an interesting historical artifact.\n
The pluggable keyword API enables keyword creation at build-time, and can take complete advantage\nof the parser's lifecycle and language recognition features.\n
This post documents my own fumblings with pluggable keywords and works through an example\nkeyword-based feature to explore the ins-and-outs of pluggable keywords (tl;dr: do not walk my\npath - I get close, but fail to attain cigar).\n
We should begin with a swift overview of the API itself (swift so I can wave my hands a lot, and\npaper over the parts I don't understand with vague terms).\n
The entry point to the API is a function pointer called PL_keyword_plugin. When your\ncustom keyword plugin loads, it should set this pointer to run your code when a potential keyword\nis encountered. Any existing value of the pointer should be stashed so you can call that extant function\nif you're not interested in the keyword. That is, you set up a chain of execution where each plugin\ncalls the one loaded before until a keyword is recognised.\n
The function prototype is (mostly) (char *keyword_ptr, STRLEN keyword_len, OP **op_ptr).\nThe first parameter is a pointer to the source code text at the point the keyword was encountered.\nThe second parameter is the length of the keyword. The third is a pointer to the optree - a data\nstructure representing the source code being parsed, analogous to an abstract syntax tree.\n
Your function should "consume" as much of the source as is appropriate, and update the optree with\nthe data and functionality required to do the keyword's work.\n
The pluggable keyword API as designed requires use of XS, a language which acts as an interface\nbetween Perl and C. As I am not familiar enough with XS to develop a new feature with it, let's\nfor now discount it as an easy option (remember the title of this post - we're chasing easy for now).\n
Keyword::Simple offers a wrapper for the keyword API.\nIt provides a define function which takes two parameters, the name of your keyword, and a\ncallback to handle a reference to the source code from just after the point your keyword was used\n(that is, the keyword is already consumed). Your callback should modify this reference to inject new\nfunctionality into the source.\n
Immediately I think "Wait, isn't this just a source filter?".\n
Not quite. A source filter acts on the entire source file and often has to guess at the correct\ncontext. Here the parser has recognised a keyword and passed that to the callback, so we can\nbe fairly certain the context is appropriate.\n
This allows for simpler parsing in our callback, as we don't have to account for other syntax\nfeatures and can focus just on what's expected in the new syntax - that is, we don't have to\ncheck if we are making changes in the middle of a heredoc or a comment or otherwise outside the desired\ncontext.\n
As with source filters, we do have new source code injected for the parser - expect possible side effects,\nsuch as line numbers in error messages no longer lining up with the source file (Though some authors\ntake steps to preserve line numbers from the original source).\n
Also, as we'll see shortly, there are tools to help control the complexities of parsing your keyword's\nparameters.\n
We can take a look at reverse dependencies of Keyword::Simple for some clues on how best to exploit its\npowers - taking one at random, PerlX::ScopeFunction.\n
Looking at the source, the major thing to note is that it makes use of PPR,\nDamian Conway's Perl Pattern Recogniser. While I noted before that "only perl can parse Perl", PPR can\nmatch patterns and build a tree from Perl source just as effectively. I'll link to a talk below where Damian\noutlines some of the advanced feats PPR pulls off, as well as some of the arcane magick involved in its\nconstruction.\n
Keyword::Declare builds upon the simple approach offered by\nKeyword::Simple with some PPR-powered niceties. New keywords are defined using keyword, which takes the\nname of your new keyword, a list of named PPR entities, and a block which should return your replacement\nsource - the named entities are consumed from the source. That is, your returned string replaces the matched entities\nyou listed in the declaration.\n
This example will use Keyword::Declare to (partially) implement multiple dispatch, or multimethods. Multimethods allow\nfor the definition of several variants of a method with the same identifier. Which variant to execute is selected\nat run-time, based on the data types of the parameters. Don't think traditional types which offer compiler\ncues for things like storage requirements, compile time validation of assignment, or casting. This is a run-time\nprocess which inspects the content of parameters to see what they look like. There is no casting or autoboxing or\nbuild-time validation.\n
Use of the new keyword multi should look something like:\n
class Multiplier {\n\n multi method multiply( Num $multiplier, Num $multiplicand ) {\n $multiplier * $multiplicand;\n }\n\n multi method multiply( Str $string, Int $multiplicand ) {\n $string x $multiplicand;\n }\n\n multi method multiply( OBJECT $obj, Int $multiplicand ) {\n map { $obj->clone } 1..$multiplicand;\n }\n\n ...\n}Here we have three different definitions for the multiply method, one of which may be executed at runtime\ndepending on whether the first parameter is a number, string, or object instance. The second parameter should\nalso be validated to be a number of the appropriate form.\n
Since we have a fair idea of how the syntax will look, let's take a peek at a complete keword definition:\n
keyword multi (\n /sub|method/ $sub,\n Ident $method,\n Attributes? $attribs,\n List? $raw_params,\n Block $code\n) {\n my $signature = _extract_signature( $raw_params );\n my $param_string = join ',', keys $signature->%*;\n my @types = values $signature->%*;\n my $signature_name = join '_', map { $_ // 'undef' } @types;\n my $target_method = "_multimethod_${signature_name}_$method";\n\n $methods->{ $class }->{ $method } //= [];\n push $methods->{ $class }->{ $method }->@*, {\n signature => $signature, method => $target_method\n };\n\n _build_type_checkers( @types );\n _inject_proxy_method( $class, $method );\n\n "$sub $target_method $attribs ( $param_string ) $code";\n}This keyword should expect to be placed before a sub or method declaration, consisting of an identifier,\noptional attributes, an optional list of expected parameters, then a block of code (it occurs to me now\nreading this that we could likely leave the code block out of the keyword definition - it is not changed\nat all).\n
As our param list also contains new and unique syntax, we'll need to unroll that ourselves in\n_extract_signature:\n
sub _extract_signature( $raw_params ) {\n $raw_params =~ s/^\\(//;\n $raw_params =~ s/\\)$//;\n +{\n map {\n my @param = split " ", $_;\n $param[1]\n ? ( $param[1] => $param[0] )\n : ( $param[0] => undef )\n } split ",", $raw_params\n }\n}This removes the parentheses from the parameter list text, then builds a hash of parameter => type.\nFor example, the method declaration:\n
multi method hello( Int $foo, $bar );...would result in the hash:\n
{\n $foo => 'Int',\n $bar => undef\n}Returning to the keyword definition, the next lines look like so:\n
my $param_string = join ',', keys $signature->%*;\n my @types = values $signature->%*;\n my $signature_name = join '_', map { $_ // 'undef' } @types;\n my $target_method = "_multimethod_${signature_name}_$method";The $param_string variable will become useful when returning text from the keyword definition block.\nThe array @types will contain a list of the types extracted from the signature in the order they\nwere encountered. This is used to build a unique method name, $target_method, which acts as a\nmeans to hack our multimethod definitions into the package/class namespace, where method names\nmust be unique.\n
Let's return to the keyword definition again - the next lines are:\n
die "Ambiguous signature in $method declaration"\n if $class->can( $target_method );\n\n $methods->{ $class }->{ $method } //= [];\n push $methods->{ $class }->{ $method }->@*, {\n signature => $signature, method => $target_method\n };Firstly a quick validation is performed - has a multi method with this signature already been declared?\n
The $methods hashref is a file scoped stash for info about the current method -\nthe method's signature hash and $target_method name. Next:\n
_build_type_checkers( @types );\n _inject_proxy_method( $class, $method );We start with _build_type_checkers ...\n
sub _build_type_checkers( @types ) {\n for my $type ( uniq sort grep { $_ } @types ) {\n next if $checkers->{ $type };\n $checkers->{ $type } = sub( $datum ) {\n state $ts_type = Types::Standard->can( $type );\n $ts_type\n ? $ts_type->()->assert_valid( $datum )\n : blessed $datum && $datum->isa( $type )\n or die("$datum is not an instance of $type");\n };\n }\n}This function maintains another file-scoped stash, $checkers, which contiains validation coderefs to check\npassed data against the named type. If the type is supported by\nTypes::Standard, its assert_valid method is used,\notherwise the type is considered an isa check - is this an instance of a specified object?\n
Next we _inject_proxy_method ...\n
sub _inject_proxy_method( $class, $method ) {\n return if $class->can( $method );\n\n my $meta = Object::Pad::MOP::Class->for_class( $class );\n $meta->add_method(\n "$method",\n sub {\n Multimethod::delegate( $class, $method, @_ )\n }\n );\n}Here we make use of the experimental Object::Pad MOP (meta-object\nprotocol). A MOP is an API which allows for inspection and modification of a class' features - class members,\nmethods, roles, inheritance tree, and so on. The API opens up class internals and allows definition of new\nroles and classes dynamically.\n
Note the explicit stringification of $method - this is an instance of Keyword::Declare::Arg.\n
The proxy method we inject into the class here is a redefinition of the multimethod name to delegate the\nselection of, and calling of the appropriate method to Multimethod::delegate, which looks like this:\n
sub delegate( $class, $method, $instance, @params ) {\n my $delegates = $methods->{ $class }->{ $method };\n my $delegate_method = _find_signature_match( $delegates, @params );\n die "No delegate method found for ${class}::$method" unless $delegate_method;\n $instance->$delegate_method( @params );\n}This starts by pulling the set of methods defined for the method name from the $methods stash\n(the potential delegates (noun) to delegate (verb) to - don't blame me, I only speak this language),\nthen calls _find_signature_match to find the first matching method. If a matching method is\nfound, it is called, otherwise the program bails out. The _find_signature_match function is\nas follows:\n
sub _find_signature_match( $delegates, @params ) {\n OUTER: for my $delegate ( $delegates->@* ) {\n my @types = values $delegate->{ signature }->%*;\n\n my $iter = each_array( @types, @params );\n while ( my ( $type, $param ) = $iter->() ) {\n next unless $type;\n try {\n $checkers->{ $type }->( $param );\n } catch( $e ) {\n next OUTER;\n }\n }\n\n return $delegate->{ method };\n }\n}This simply iterates over each delegate method and returns the first one for which the passed\nparameters pass all type checks stashed for that declaration, or nothing at all.\n
Looking back to the keyword definition, the final job is to return the now-uniquely-named\nmethod definition:\n
"$sub $target_method $attribs ( $param_string ) $code";The code outlined here is run each time the keyword multi is encountered.\n
Let's kick off a REPL:\n
$ reply\n0> use Object::Pad\n1> use Multimethod\nVariable "$class" will not stay shared at lib/Multimethod.pm line 112.An inauspicious start. Multimethod's import function looks as follows:\n
sub import {\n my $class = caller();\n\n keyword multi ( ...The $class variable is used within keyword's block. As this is not an anonymous sub, it does\nnot create a closure around $class. As the block may be called at any time, perl warns us of a potential\npitfall - this block is working with a copy of $class. As we can be fairly certain the block is run\nnow, this warning should be safe to ignore.\n
Also, it makes no sense to use Multimethod at this level - it needs a package name to work with in\ncaller().\nLet's start again:\n
$ reply\n0> use v5.38.0\n1> use Object::Pad\n2> class Foo {\n2... use Multimethod;\n2... multi method say_things( Int $int ) { say "Got an int : $int" };\n2... multi method say_things( Str $str ) { say "Got a string : $str" };\n2... multi method say_things( $thing ) { say "Got something else : $thing" };\n2... }\nVariable "$class" will not stay shared at lib/Multimethod.pm line 112.\n$res[0] = 1Nothing catastrophic so far. Here we see three variants of say_things declared. It should hopefully be\nobvious what each of these methods do and what data they respond to.\n
Let's instantiate the class and see how the namespace looks:\n
3> my $foo = Foo->new\nObject::Pad::MOP is experimental and may be changed or removed without notice at /home/fuzzix/perl5/perlbrew/perls/perl-5.38.0/lib/site_perl/5.38.0/Data/Printer/Filter/GenericClass.pm line 96.\n$res[1] = Foo {\n parents: Object::Pad::UNIVERSAL\n public methods (5):\n DOES, META, new, say_things\n Object::Pad::UNIVERSAL:\n BUILDARGS\n private methods (3): _multimethod_Int_say_things, _multimethod_Str_say_things, _multimethod_undef_say_things\n internals: []\n}We can see the new proxy method say_things, and the uniquely named methods for each variant of say_things\ndeclared above. A thought occurs - this system calls nominally "private" methods from another\npackage. This is a definite wart.\n
The warning is from Data::Printer's inspection of object internals using the experimental Object::Pad::MOP.\n
Moving on, let's see if the multimethods work as expected:\n
4> $foo->say_things( 123 )\nGot an int : 123\n$res[2] = 1\n5> $foo->say_things( 'abc' )\nGot a string : abc\n$res[3] = 1\n6> $foo->say_things( {} )\nGot something else : HASH(0x2f6a130)\n\n$res[4] = 1This looks good to me! (Merge it!)\n
Writing class definitions in a REPL isn't much fun, so I will write some basic tests and include them with\nthe mlutimethod example source code.\n
While we ended up with a more-or-less functional mlutimethod implementation, it is not without problems\n(besides being woefully incomplete and lacking real validation, tests, etc.)\n
I think one major issue is the namespace pollution - we end up adding a chunk of mildly inscrutable private\nmethods for each set of multimethod declarations. They may not have seemed so bad in the example above, but\nin even a modestly complex class, these methods may start to pile up.\n
There's also the fact that these nominally private methods are called from outside the class. Another\napproach might be to add a private delegate method to the class, but this clutters the namespace further.\nThere's also AUTOLOAD - we could create a package named\nmulti with an AUTOLOAD block which extracts a method name. That is, a proxy method named foo would\ncall $self->multi::foo( @args ), rather than Multimethod::delegate.\nThe package multi could then dispatch to the correct variant of foo\nbased on the content of @args. See curry for an example of this type\nof thing. TMTOWTDI.\n
The generic isa object check for types not defined in Types::Standard is not going to work in 99.9% of\ncases. The typical package name (using :: OR ' package separators) really seems to confuse the signatures\nparser. My expectation was that the signature would be parsed after Multimethod rewrites it with a valid\nsignature, but something else happens here. I don't currently have more insight.\n
It should be obvious that the example presented here is far from production ready ... but also, that one\nprobably should not write this type of functionality themselves. While Types::Standard is fantastic,\nthere is an ongoing effort dubbed 'Oshun', which aims to bring data checks into core.\nThis work could form the basis of multimethod support in\nCorinna, the specification and exploration project behind core feature 'class'.\nObject::Pad is an exploratory implementation of feature 'class'\nwhich I used here for the MOP.\n
I think the last major issue I have is rewriting source code. While this is far more tighly controlled than\nplain source filters, it feels error-prone - displaced error messages, a weirded call-stack ...\nI need to look into the XS optree manipulation approach.\nXS::Parse::Keyword appears to offer some niceties to perhaps\nhelp me along the path. This distribution also includes XS::Parse::Infix\nto help support a relatively new infix operator API (oh yeah, this is the juice!) There may be a follow-up to this\npost.\n
As for the opening question, how easy was all this? Quite easy! I don't know one end of a compiler from the other,\nwhat I know about type systems could be transcribed to a postage stamp in crayon, and yet with a little dyanamism\nand a lot of sticky tape I built something that worked, after a fashion. I think the accessibility of Keyword::Simple and\nKeyword::Declare are a boon to the ecosystem. I can see myself making use of them again in future, albeit with\nsome more care and attention based on what was observed here.\n
I learned something - I hope you did too.\n
Despite attempts to pre-emptively absolve myself of any responsibility for accuracy with talk\nof vagueness, I do not wish to spread disinformation. If something I've said here is completely\nwrong, feel free to reach out, or hit me across the nose with a rolled up newspaper and say "BAD!"\n