#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