midimonster.h

#ifndef MIDIMONSTER_HEADER
#define MIDIMONSTER_HEADER
#include <stdio.h>
#include <stdlib.h>
#include <stdint.h>
#include <inttypes.h>

/* Core version unless set by the build process */
#ifndef MIDIMONSTER_VERSION
	#define MIDIMONSTER_VERSION "v0.7-dist"
#endif

/* Set backend name if unset */
#ifndef BACKEND_NAME
	#define BACKEND_NAME "unspec"
#endif

/* API call attributes and visibilities */
#ifndef MM_API
	#ifdef _WIN32
		#define MM_API __attribute__((dllimport))
	#else
		#define MM_API
	#endif
#endif

/* Some build systems may apply the -fvisibility=hidden parameter from the core build to the backends, so mark the init function visible */
#ifndef MM_PLUGIN_API
	#ifdef _WIN32
		#define MM_PLUGIN_API __attribute__((dllexport))
	#else
		#define MM_PLUGIN_API __attribute__((visibility ("default")))
	#endif
#endif

/* Straight-forward min / max macros */
#define max(a,b) (((a) > (b)) ? (a) : (b))
#define min(a,b) (((a) < (b)) ? (a) : (b))

/* Clamp a value to a range */
#define clamp(val,max,min) (((val) > (max)) ? (max) : (((val) < (min)) ? (min) : (val)))

/* Log function prototype - do not use directly. Use the LOG/LOGPF/DBGPF macros below instead */
MM_API __attribute__((format(printf, 3, 4))) int log_printf(int level, char* module, char* fmt, ...);

/* Debug messages only compile in when DEBUG is set */
#ifdef DEBUG
	#define DBGPF(format, ...) log_printf(1, (BACKEND_NAME), format "\n", __VA_ARGS__)
#else
	#define DBGPF(format, ...)
#endif

/* Log messages should be routed through these macros to ensure interoperability with different core implementations */
#define LOGPF(format, ...) log_printf(0, (BACKEND_NAME), format "\n", __VA_ARGS__)
#define LOG(message) log_printf(0, (BACKEND_NAME), message "\n")

/* Stop compilation if the build system reports an error */
#ifdef BUILD_ERROR
	#error The build system reported an error, compilation stopped. Refer to the invocation for this compilation unit for more information.
#endif

/* Pull in additional defines for non-linux platforms */
#include "portability.h"

/* Default configuration file name to read when no other is specified */
#ifndef DEFAULT_CFG
	#define DEFAULT_CFG "monster.cfg"
#endif

/* Default backend plugin location */
#ifndef PLUGINS
	#ifndef _WIN32
		#define PLUGINS "./backends/"
	#else
		#define PLUGINS "backends\\"
	#endif
#endif

/* Forward declare some of the structs so we can use them in each other */
struct _channel_value;
struct _backend_channel;
struct _backend_instance;
struct _managed_fd;

/*
 * Backend module callback defines
 *
 * The lifecycle of a backend module is as follows
 * 	* int init()
 * 		The only function that should be exported by the shared object.
 * 		Called when the shared object is attached. Should register
 * 		a backend structure containing callable entry points with the core.
 * 		Returning anything other than zero causes midimonster to fail the
 * 		startup checks.
 * 	* mmbackend_configure
 * 		Parse backend-global configuration options from the user-supplied
 * 		configuration file. Returning a non-zero value fails config parsing.
 * 	* mmbackend_instance
 * 		Allocate the backend-specific data parts of the supplied instance
 * 		structure. Returning non-zero signals an error condition and
 * 		terminates the program.
 * 	* mmbackend_configure_instance
 * 		Parse instance configuration from the user-supplied configuration
 * 		file. Returning a non-zero value fails config parsing.
 * 	* mmbackend_channel
 * 		Parse a channel-spec to be mapped to/from. The `flags` parameter supplies
 * 		additional information to the parser, such as whether the channel is being
 * 		queried for use as input (to the MIDIMonster core) and/or output
 * 		(from the MIDIMonster core) channel (on a per-query basis).
 * 		Returning NULL signals an out-of-memory condition and terminates the program.
 * 	* mmbackend_start
 * 		Called after all instances have been created and all mappings
 * 		have been set up. Only backends for which instances have been configured
 * 		receive the start call. May be used to connect to backing hardware
 * 		or to update runtime-specific data in the various data structures.
 * 		Returning a non-zero value signals an error starting the backend
 * 		and stops further progress.
 * 	* Normal processing loop starts here
 * 		* mmbackend_process_fd
 * 			Handle data from signaled fds registered via mm_manage_fd.
 * 			Push generated events to the core with mm_channel_event.
 * 			All registered fds that are ready to read are pushed at once.
 * 			Backends that have not registered any fds are still called with
 * 			nfds set to 0 in order to support polling backends.
 * 			Returning a non-zero value signals an error and gracefully terminates
 * 			the program.
 *		* mmbackend_handle_event
 *			An event resulted in a channel for an instance being set.
 *			Called once per changed instance with all updated channels for that
 *			specific instance.
 *			Returning a non-zero value terminates the program.
 *		* (optional) mmbackend_interval
 *			Return the maximum sleep interval for this backend in milliseconds.
 *			If not implemented, a maximum interval of one second is used.
 *			Returning 0 signals that the backend does not have a minimum
 *			interval.
 *	* mmbackend_shutdown
 *		Clean up all allocations, finalize all hardware connections. All registered
 *		backends receive the shutdown call, regardless of whether they have been
 *		started previously.
 *		Return value is currently ignored.
 */
typedef int (*mmbackend_handle_event)(struct _backend_instance* inst, size_t channels, struct _backend_channel** c, struct _channel_value* v);
typedef int (*mmbackend_create_instance)(struct _backend_instance* inst);
typedef struct _backend_channel* (*mmbackend_parse_channel)(struct _backend_instance* instance, char* spec, uint8_t flags);
typedef void (*mmbackend_free_channel)(struct _backend_channel* c);
typedef int (*mmbackend_configure)(char* option, char* value);
typedef int (*mmbackend_configure_instance)(struct _backend_instance* instance, char* option, char* value);
typedef int (*mmbackend_process_fd)(size_t nfds, struct _managed_fd* fds);
typedef int (*mmbackend_start)(size_t ninstances, struct _backend_instance** inst);
typedef uint32_t (*mmbackend_interval)();
typedef int (*mmbackend_shutdown)(size_t ninstances, struct _backend_instance** inst);

/* Bit masks for the `flags` parameter to mmbackend_parse_channel */
typedef enum {
	mmchannel_input = 0x1,
	mmchannel_output = 0x2
} mmbe_channel_flags;

/* Channel event value, .normalised is used by backends to determine channel values */
typedef struct _channel_value {
	union {
		double dbl;
		uint64_t u64;
	} raw;
	double normalised;
} channel_value;

/* 
 * Backend callback structure
 * Used to register a backend with the core using mm_backend_register()
 */
typedef struct /*_mm_backend*/ {
	char* name;
	mmbackend_configure conf;
	mmbackend_create_instance create;
	mmbackend_configure_instance conf_instance;
	mmbackend_parse_channel channel;
	mmbackend_handle_event handle;
	mmbackend_process_fd process;
	mmbackend_start start;
	mmbackend_shutdown shutdown;
	mmbackend_free_channel channel_free;
	mmbackend_interval interval;
} backend;

/* 
 * Backend instance structure - do not allocate directly!
 * Use the memory returned by mm_instance()
 */
typedef struct _backend_instance {
	backend* backend;
	uint64_t ident;
	void* impl;
	char* name;
} instance;

/* 
 * Instance channel structure
 * Backends may either manage their own channel registry or use the global
 * channel store via the mm_channel() API
 */
typedef struct _backend_channel {
	instance* instance;
	uint64_t ident;
	void* impl;
} channel;

/*
 * File descriptor structure passed for backend handling
 * Register for the core event loop using mm_manage_fd()
 */
typedef struct _managed_fd {
	int fd;
	backend* backend;
	void* impl;
} managed_fd;

/*
 * Register a new backend.
 */
MM_API int mm_backend_register(backend b);

/*
 * Finds an instance matching the specified backend and identifier.
 * Since setting an identifier for an instance is optional, this may not work
 * depending on the backend. Instance identifiers may for example be set in the
 * backends mmbackend_start call.
 */
MM_API instance* mm_instance_find(char* backend, uint64_t ident);

/*
 * This function is the main interface to the core-provided channel registry.
 * This API is just a convenience function. Creating and managing a
 * backend-internal channel store is possible (and encouraged for performance
 * reasons).
 *
 * Channels are identified by the (instance, ident) tuple within the registry.
 *
 * This API provides a pointer to a channel structure, pre-filled with the
 * provided instance reference and identifier.
 * The `create` parameter is a boolean flag indicating whether a channel
 * matching the `ident` parameter should be created in the global channel store
 * if none exists yet. If the instance already registered a channel matching
 * `ident`, a pointer to the existing channel is returned.
 * 
 * When returning pointers from a backend-local channel store, the
 * returned pointers must stay valid over the lifetime of the instance and
 * provide valid `instance` members, as they are used for callbacks.
 * For each channel with a non-NULL `impl` field registered using
 * this function, the backend will receive a call to its channel_free
 * function (if it exists).
 */
MM_API channel* mm_channel(instance* i, uint64_t ident, uint8_t create);

/*
 * When using the core-provided channel registry, the identification
 * member of the structure must only be updated using this API.
 * The tuple of (instance, ident) is used as key to the backing
 * storage of the channel registry, thus the registry must be notified
 * of changes.
 */
MM_API void mm_channel_update(channel* c, uint64_t ident);

/*
 * Register (manage = 1) or unregister (manage = 0) a file descriptor to be
 * selected on. The backend will be notified when the descriptor becomes ready
 * to read via its registered mmbackend_process_fd call. The `impl` argument
 * will be provided within the corresponding managed_fd structure upon callback.
 */
MM_API int mm_manage_fd(int fd, char* backend, int manage, void* impl);

/*
 * Notifies the core of a channel event. Called by backends to inject events
 * gathered from their backing implementation.
 */
MM_API int mm_channel_event(channel* c, channel_value v);

/*
 * Query all active instances for a given backend.
 * *i will need to be freed by the caller.
 */
MM_API int mm_backend_instances(char* backend, size_t* n, instance*** i);

/*
 * Query an internal timestamp, which is updated every core iteration.
 * This timestamp should not be used as a performance counter, but can be used
 * for timeouting. Resolution is milliseconds.
 */
MM_API uint64_t mm_timestamp();

/*
 * Create a channel-to-channel mapping. This API should not be used by backends.
 * It is only exported for core modules.
 */
int mm_map_channel(channel* from, channel* to);
#endif