Add support for a peripheral attached to the user port

README.md

@@ -128,6 +128,7 @@ When starting `x16emu` without arguments, it will pick up the system ROM (`rom.b
 * `-sound <device>` can be used to specify the output sound device. If 'none', no audio is generated.
 * `-abufs` can be used to specify the number of audio buffers (defaults to 8 when using the SD card, 32 when using HostFS). If you're experiencing stuttering in the audio, try increasing this number. This will result in additional audio latency though.
 * `-via2` installs the second VIA chip expansion at $9F10.
+* `-user-peripheral <my_peripheral.{so|dll|dylib}>` connects an emulated user peripheral built as a dynamically linked library. implies `-via2`
 * `-midline-effects` enables mid-scanline raster effects at the cost of vastly increased host CPU usage.
 * `-mhz <integer>` sets the emulated CPU's speed. Range is from 1-40. This option is mainly for testing and benchmarking.
 * `-enable-ym2151-irq` connects the YM2151's IRQ pin to the system's IRQ line with a modest increase in host CPU usage.

src/dylib.h

@@ -0,0 +1,17 @@
+#pragma once
+
+#ifdef _WIN32
+    #include <windows.h>
+    #define LIBRARY_TYPE HMODULE
+    #define LOAD_LIBRARY(name) LoadLibrary(name)
+    #define GET_FUNCTION(lib, name) (void *)GetProcAddress(lib, name)
+    #define CLOSE_LIBRARY(lib) FreeLibrary(lib)
+    #define LIBRARY_ERROR() "[ unknown error ]"
+#else
+    #include <dlfcn.h>
+    #define LIBRARY_TYPE void*
+    #define LOAD_LIBRARY(name) dlopen(name, RTLD_LAZY)
+    #define GET_FUNCTION(lib, name) dlsym(lib, name)
+    #define CLOSE_LIBRARY(lib) dlclose(lib)
+    #define LIBRARY_ERROR() dlerror()
+#endif

src/main.c

@@ -132,6 +132,7 @@ bool testbench = false;
 bool enable_midline = false;
 bool ym2151_irq_support = false;
 char *cartridge_path = NULL;
+char *user_peripheral_plugin_path = NULL;
 
 bool has_midi_card = false;
 uint16_t midi_card_addr;
@@ -334,7 +335,7 @@ machine_reset()
 	vera_spi_init();
 	via1_init();
 	if (has_via2) {
-		via2_init();
+		via2_init(user_peripheral_plugin_path);
 	}
 	video_reset();
 	mouse_state_init();
@@ -514,6 +515,9 @@ usage()
 	printf("\tSet the real-time-clock to the current system time and date.\n");
 	printf("-via2\n");
 	printf("\tInstall the second VIA chip expansion at $9F10\n");
+	printf("-user-peripheral <peripheral lib>\n");
+	printf("\tUse the provided shared library to drive user peripherals.\n");
+	printf("\tImplies -via2\n");
 	printf("-testbench\n");
 	printf("\tHeadless mode for unit testing with an external test runner\n");
 	printf("-mhz <integer>\n");
@@ -1088,6 +1092,16 @@ main(int argc, char **argv)
 			argc--;
 			argv++;
 			has_via2 = true;
+		} else if (!strcmp(argv[0], "-user-peripheral")) {
+			argc--;
+			argv++;
+			if (!argc || argv[0][0] == '-') {
+				usage();
+			}
+			has_via2 = true;
+			user_peripheral_plugin_path = argv[0];
+			argc--;
+			argv++;
 		} else if (!strcmp(argv[0], "-version")){
 			printf("%s", VER_INFO);
 #ifdef GIT_REV
@@ -1309,6 +1323,7 @@ void main_shutdown() {
 		cartridge_save_nvram();
 		cartridge_unload();
 	}
+	via2_shutdown();
 	files_shutdown();
 
 #ifdef PERFSTAT

src/midi.c

@@ -8,20 +8,7 @@
 #include "midi.h"
 #include "audio.h"
 #include "endian.h"
-
-#ifdef _WIN32
-    #include <windows.h>
-    #define LIBRARY_TYPE HMODULE
-    #define LOAD_LIBRARY(name) LoadLibrary(name)
-    #define GET_FUNCTION(lib, name) (void *)GetProcAddress(lib, name)
-    #define CLOSE_LIBRARY(lib) FreeLibrary(lib)
-#else
-    #include <dlfcn.h>
-    #define LIBRARY_TYPE void*
-    #define LOAD_LIBRARY(name) dlopen(name, RTLD_LAZY)
-    #define GET_FUNCTION(lib, name) dlsym(lib, name)
-    #define CLOSE_LIBRARY(lib) dlclose(lib)
-#endif
+#include "dylib.h"
 
 #define ASSIGN_FUNCTION(lib, var, name) {\
     var = GET_FUNCTION(lib, name);\

src/user_pins.h

@@ -0,0 +1,121 @@
+#pragma once
+
+// Include this header in a user peripheral library.
+//
+// A user peripheral library must export a [user_port_init_t x16_user_port_init] to be
+// called at runtime by the emulator during initialization of via2. [x16_user_port_init]
+// should return 0 on success, and -1 on error.
+
+#include <stdint.h>
+
+// This must be assigned to the [api_version] field of [user_port_t] by the peripheral
+// library so that version mismatches can be detected.
+#define X16_USER_PORT_API_VERSION 1
+
+// Bit assignments for each 65C22 pin exposed to the user port, for use with
+// [user_pin_t]. For convenience, all Port A pins are in the low byte, in bit order, and
+// Port B pins are likewise in the second byte.
+
+#define PA0_PIN (1 << 0)
+#define PA1_PIN (1 << 1)
+#define PA2_PIN (1 << 2)
+#define PA3_PIN (1 << 3)
+#define PA4_PIN (1 << 4)
+#define PA5_PIN (1 << 5)
+#define PA6_PIN (1 << 6)
+#define PA7_PIN (1 << 7)
+#define PB0_PIN (1 << 8)
+#define PB1_PIN (1 << 9)
+#define PB2_PIN (1 << 10)
+#define PB3_PIN (1 << 11)
+#define PB4_PIN (1 << 12)
+#define PB5_PIN (1 << 13)
+#define PB6_PIN (1 << 14)
+#define PB7_PIN (1 << 15)
+#define CA1_PIN (1 << 16)
+#define CA2_PIN PB3_PIN
+#define CB1_PIN PB6_PIN
+#define CB2_PIN PB7_PIN
+
+// USER_PINn macros map the 65C22 pins (above) to the exposed pins on the X16's user port.
+
+// Left column
+#define USER_PIN1 PB0_PIN
+#define USER_PIN3 PA0_PIN
+#define USER_PIN5 PA1_PIN
+#define USER_PIN7 PA2_PIN
+#define USER_PIN9 PA3_PIN
+#define USER_PIN11 PA4_PIN
+#define USER_PIN13 PA5_PIN
+#define USER_PIN15 PA6_PIN
+#define USER_PIN17 PA7_PIN
+#define USER_PIN19 CA1_PIN
+#define USER_PIN21 PB1_PIN
+#define USER_PIN23 PB2_PIN
+#define USER_PIN25 PB3_PIN
+
+// Right Column
+#define USER_PIN2 PB4_PIN
+#define USER_PIN4 PB5_PIN
+#define USER_PIN6 PB6_PIN
+#define USER_PIN8 PB7_PIN
+// 10-24 (even) are GND, 26 is VCC
+
+// [user_pin_t] is a bitmask of pin values. Port A is the first byte, Port B is the second
+// byte, and CA1 is bit 16. Bits above 16 must always be 0. The above *_PIN macros define
+// the appropriate bits to use with [user_pin_t].
+//
+// Note that in this implementation, all pins are either high (1) or low (0). If your
+// device uses pull-up/down, you'll need to factor that into [read] or [step] pin values
+// manually. However, unless the data direction of the pins on the via stays constant it
+// will be quite difficult to keep the via's and peripheral's states in sync, since there
+// is no signal that a via pin has switched from being actively driven to hi-Z, or vice
+// versa.
+typedef uint32_t user_pin_t;
+
+typedef struct user_port_t {
+	// Must be set to X16_USER_PORT_API_VERSION
+	int api_version;
+
+	// A mask of pins actually connected to the user peripheral.
+	user_pin_t connected_pins;
+
+	// Arbitrary user data which is passed to the various callbacks.
+	void *userdata;
+
+	// Return the values of the connected pins based on the peripheral's internal
+	// state. Any pin values not in [connected_pins] will be ignored.
+	user_pin_t (*read)(void *userdata);
+
+	// New pin values pushed from the via to the peripheral. Pins not in the
+	// [connected_pins] mask will be zeroes, but that does not imply those pins are low
+	void (*write)(user_pin_t pins, void *userdata);
+
+	// Step the state machine of the connected peripheral. [nanos] is the number of
+	// nanoseconds which has passed since the last step. Returns the pin state so that any
+	// interrupts based on CA1 and CB1 can be triggered. CA2 and CB2 are not presently
+	// implemented in the via code.
+	user_pin_t (*step)(double nanos, void *userdata);
+
+	// Called on reset and shutdown. is_poweroff is true for final shutdown, to
+	// differentiate from a reset
+	void (*cleanup)(bool is_poweroff, void *userdata);
+} user_port_t;
+
+// Extensible init args struct. Includes api_version so perhipheral libraries can abort or
+// downgrade, if necessary.
+typedef struct __attribute__((aligned(sizeof(void *)))) user_port_init_args_t {
+	int api_version;
+
+	// Callback for setting an error message from the plugin
+	// Errors longer than 256 chars (including null) will be truncated
+	void (*set_error)(char const *);
+} user_port_init_args_t;
+
+// Populates the provided [user_port_t *]. If any of [read], [write] or [step] is NULL, it
+// will be ignored.
+//
+// A peripheral library's exposed [user_port_init_t] function MUST be named "x16_user_port_init".
+//
+// Returns 0 on success and -1 on error.
+typedef int (*user_port_init_t)(user_port_init_args_t *, user_port_t *);