Bela.h

Go to the documentation of this file.

#ifndef BELA_H_
#define BELA_H_
#define BELA_MAJOR_VERSION 1
#define BELA_MINOR_VERSION 13
#define BELA_BUGFIX_VERSION 0

// Version history / changelog:
// 1.14.0
// - added disabledDigitalChannels to BelaInitSettings and corresponding command-line
// 1.13.0
// - added Bela_setLineOutLevel() which replaces Bela_setDacLevel() (though
// with different semantics).
// - in BelaInitSettings, dacGains is _replaced_ by lineOutGains
// - replaced --dac-level with --line-out-level, -D now means --line-out-level
// - replaced DEFAULT_DAC_LEVEL with DEFAULT_LINE_OUT_LEVEL
// - removed setAdcLevel(): use setAudioInputGain() instead
// - removed -A/--adc-gain, now ignored (non-bw-compatible)
// - removed DEFAULT_ADC_LEVEL
// - deprecated Bela_setDacLevel()
// 1.12.0
// - added Bela_cpuTic(), Bela_cpuToc(), Bela_cpuMonitoringInit(),
// Bela_cpuMonitoringGet() and BelaCpuData.
// 1.11.0
// - added BelaChannelGain and BelaChannelGainArray
// - added setHpLevel(), setAudioInputGain(), setAdcLevel(), setDacLevel(),
// deprecated the functions they are intended to replace
// - added the corresponding fields in BelaInitSettings: headphoneGains,
// audioInputGains, adcGains, dacGains
// 1.10.0
// - added parameter to Bela_detectHw(), and associated typedef
// - added more values to the BelaHw enum
// - added codecMode to BelaInitSettings
// 1.9.0
// - added Bela_HwConfig_{new,delete}
// 1.8.0
// - added callback for when the audio thread is done: settings->audioThreadDone
// 1.7.0
// - Bela_getopt_long takes a char* const []
// - added the functions and definitions from Utilities.h
// - INPUT and OUTPUT are now an enum
// 1.6.0
// - added Bela_setUserData(), Bela_requestStop(), Bela_stopRequested()
// 1.5.1
// - in BelaInitSettings, renamed unused members, preserving binary compatibility
// 1.5.0
// - in BelaInitSettings, board becomes BelaHw
// - added to BelaInitSettings char* projectName
// - added to BelaContext char* projectName
// 1.4.0
// - added allocator/de-allocator for BelaInitSettings
// - added char board field to BelaInitSettings
// 1.3.0
// - removed define for I2C codec address
// - removed user option in settings for I2C address
// 1.2.0
// - renames and re-ordered BelaHw enum
// 1.1.0
// - adds BelaHw, Bela_detectHw()
// - removes digital_gpio_mapping.h

#ifdef __cplusplus
extern "C"
{
#endif

#include <stdint.h>
#include <unistd.h>
#include <stdbool.h>
#include <stdio.h>
// these functions are currently provided by xenomai.
// We put these declarations here so we do not have to include
// Xenomai specific files
int rt_printf(const char *format, ...);
int rt_fprintf(FILE *stream, const char *format, ...);
int rt_vprintf(const char *format, va_list ap);
int rt_vfprintf(FILE *stream, const char *format, va_list ap);

typedef enum
{
        BelaHw_NoHw = -1, 
        BelaHw_Bela, 
        BelaHw_BelaMini, 
        BelaHw_Salt, 
        BelaHw_CtagFace, 
        BelaHw_CtagBeast, 
        BelaHw_CtagFaceBela, 
        BelaHw_CtagBeastBela, 
        BelaHw_BelaMiniMultiAudio, 
        BelaHw_BelaMiniMultiTdm, 
        BelaHw_BelaMultiTdm, 
        BelaHw_BelaMiniMultiI2s, 
        BelaHw_BelaEs9080, 
        BelaHw_BelaRevC, 
        BelaHw_Batch, 
} BelaHw;

typedef struct _BelaHwConfig
{
        float audioSampleRate;
        unsigned int audioInChannels;
        unsigned int audioOutChannels;
        unsigned int analogInChannels;
        unsigned int analogOutChannels;
        unsigned int digitalChannels;
} BelaHwConfig;

BelaHwConfig* Bela_HwConfig_new(BelaHw hw);

void Bela_HwConfig_delete(BelaHwConfig* cfg);

typedef enum
{
        BelaHwDetectMode_Scan, 
        BelaHwDetectMode_Cache, 
        BelaHwDetectMode_CacheOnly, 
        BelaHwDetectMode_User, 
        BelaHwDetectMode_UserOnly, 
} BelaHwDetectMode;

#include <GPIOcontrol.h>

// Useful constants

#define MAX_PRU_FILENAME_LENGTH 256
#define MAX_UNUSED_LENGTH 220
#define MAX_PROJECTNAME_LENGTH 256

#define BELA_AUDIO_PRIORITY             95

// Default volume levels

#define DEFAULT_LINE_OUT_LEVEL  0.0

#define DEFAULT_PGA_GAIN 16

#define DEFAULT_HP_LEVEL        -6.0

#define BELA_FLAG_INTERLEAVED                           (1 << 0)        // Set if buffers are interleaved

#define BELA_FLAG_ANALOG_OUTPUTS_PERSIST        (1 << 1)        // Set if analog/digital outputs persist for future buffers

#define BELA_FLAG_DETECT_UNDERRUNS      (1 << 2)        // Set if the user will be displayed a message when an underrun occurs

#define BELA_FLAG_OFFLINE (1 << 3)

struct option;

typedef struct {
        const float * const audioIn;

        float * const audioOut;

        const float * const analogIn;

        float * const analogOut;

        uint32_t * const digital;

        const uint32_t audioFrames;
        const uint32_t audioInChannels;
        const uint32_t audioOutChannels;
        const float audioSampleRate;

        const uint32_t analogFrames;

        const uint32_t analogInChannels;

        const uint32_t analogOutChannels;

        const float analogSampleRate;

        const uint32_t digitalFrames;
        const uint32_t digitalChannels;
        const float digitalSampleRate;

        const uint64_t audioFramesElapsed;

        const uint32_t multiplexerChannels;

        const uint32_t multiplexerStartingChannel;

        const float * const multiplexerAnalogIn;

        const uint32_t audioExpanderEnabled;

        const uint32_t flags;

        char projectName[MAX_PROJECTNAME_LENGTH];

        const unsigned int underrunCount;
} BelaContext;

struct BelaChannelGain {
        int channel; 
        float gain; 
};

struct BelaChannelGainArray {
        unsigned int length;
        struct BelaChannelGain* data;
};
typedef struct {
        // These items might be adjusted by the user:

        int periodSize;
        int useAnalog;
        int useDigital;
        int numAudioInChannels;
        int numAudioOutChannels;
        int numAnalogInChannels;
        int numAnalogOutChannels;
        int numDigitalChannels;

        int beginMuted;
        float dacLevel;
        float adcLevel;
        float pgaGain[2];
        float headphoneLevel;
        int numMuxChannels;
        unsigned int audioExpanderInputs;
        unsigned int audioExpanderOutputs;

        int pruNumber;
        char pruFilename[MAX_PRU_FILENAME_LENGTH];
        int detectUnderruns;
        int verbose;
        int enableLED;
        int stopButtonPin;
        int highPerformanceMode;

        // These items are application-dependent but should probably be
        // determined by the programmer rather than the user

        int interleave;
        int analogOutputsPersist;
        int uniformSampleRate;
        // to 128KiB
        unsigned int audioThreadStackSize;
        // to 128KiB
        unsigned int auxiliaryTaskStackSize;

        // Pointers to the user-defined functions
        bool (*setup)(BelaContext*, void*);
        void (*render)(BelaContext*, void*);
        void (*cleanup)(BelaContext*, void*);
        // These items are hardware-dependent and should only be changed
        // to run on different hardware

        int ampMutePin;

        void (*audioThreadDone)(BelaContext*, void*);
        char* codecMode;
        struct BelaChannelGainArray audioInputGains;
        struct BelaChannelGainArray headphoneGains;
        struct BelaChannelGainArray adcGains;
        struct BelaChannelGainArray lineOutGains;
        uint32_t disabledDigitalChannels;

        char unused[MAX_UNUSED_LENGTH];

        BelaHw board;

        char* projectName;

} BelaInitSettings;

typedef void* AuxiliaryTask;    // Opaque data type to keep track of aux tasks

extern int volatile gShouldStop;

// *** User-defined render functions ***

bool setup(BelaContext *context, void *userData);

void render(BelaContext *context, void *userData);

void cleanup(BelaContext *context, void *userData);

// *** Command-line settings ***


BelaInitSettings* Bela_InitSettings_alloc();

void Bela_InitSettings_free(BelaInitSettings* settings);

void Bela_defaultSettings(BelaInitSettings *settings);

#pragma weak Bela_userSettings

void Bela_userSettings(BelaInitSettings *settings);

int Bela_getopt_long(int argc, char * const argv[], const char *customShortOptions,
                                   const struct option *customLongOptions, BelaInitSettings *settings);

void Bela_usage();

void Bela_getVersion(int* major, int* minor, int* bugfix);

void Bela_setVerboseLevel(int level);


BelaHw Bela_detectHw(BelaHwDetectMode mode);

// *** Audio control functions ***

int Bela_initAudio(BelaInitSettings *settings, void *userData);

int Bela_startAudio();

int Bela_runInSameThread();

void Bela_stopAudio();

void Bela_cleanupAudio();

void Bela_setUserData(void* newUserData);

void Bela_requestStop();

int Bela_stopRequested();

#ifndef BELA_DISABLE_CPU_TIME

#include <time.h>
typedef struct {
        int count; 
        unsigned int currentCount; 
        long long unsigned int busy; 
        long long unsigned int total; 
        struct timespec tic; 
        struct timespec toc; 
        float percentage; 
} BelaCpuData;
int Bela_cpuMonitoringInit(int count);
BelaCpuData* Bela_cpuMonitoringGet();
void Bela_cpuTic(BelaCpuData* data);
void Bela_cpuToc(BelaCpuData* data);

#endif // BELA_DISABLE_CPU_TIME

// *** Volume and level controls ***

int Bela_setLineOutLevel(int channel, float decibel);

int Bela_setDacLevel(int channel, float decibels);

int Bela_setDACLevel(float decibels);

int Bela_setAdcLevel(int channel, float decibels);

int Bela_setADCLevel(float decibels);


int Bela_setAudioInputGain(int channel, float decibels);

int Bela_setPgaGain(float decibels, int channel);

int Bela_setHpLevel(int channel, float decibels);
int Bela_setHeadphoneLevel(float decibels);

int Bela_muteSpeakers(int mute);

// *** Functions for creating auxiliary tasks ***

AuxiliaryTask Bela_createAuxiliaryTask(void (*callback)(void*), int priority, const char *name, void* arg
#ifdef __cplusplus
= NULL
#endif /* __cplusplus */
);

int Bela_scheduleAuxiliaryTask(AuxiliaryTask task);

#ifdef __cplusplus
AuxiliaryTask Bela_runAuxiliaryTask(void (*callback)(void*), int priority = 0, void* arg = nullptr);
#endif // __cplusplus

int Bela_startAuxiliaryTask(AuxiliaryTask task);
int Bela_startAllAuxiliaryTasks();
void Bela_stopAllAuxiliaryTasks();
void Bela_deleteAllAuxiliaryTasks();

// You may want to define the macro below in case `Utilities.h` causes namespace conflicts
#ifndef BELA_DONT_INCLUDE_UTILITIES
#include <Utilities.h>
#endif // BELA_DONT_INCLUDE_UTILITIES

enum {
        INPUT = 0,
        OUTPUT = 1,
};
#define Bela_setBit(word,bit)                   ((word) | (1 << (bit)))

#define Bela_clearBit(word,bit)                         ((word) &~ (1 << (bit)))

#define Bela_getBit(word,bit)                   (((word) >> (bit)) & 1)

#define Bela_changeBit(word,bit,value)  ((Bela_clearBit((word),(bit))) | ((value) << (bit)))

// Note: pinMode(), analogWrite() and digitalWrite() should be able to be called from setup()
// Likewise, thread launch should be able to be called from setup()
// Also, make volume change functions callable from render() thread -- as an aux task?

static inline float audioRead(BelaContext *context, int frame, int channel);

static inline float audioReadNI(BelaContext *context, int frame, int channel);

static inline void audioWrite(BelaContext *context, int frame, int channel, float value);

static inline void audioWriteNI(BelaContext *context, int frame, int channel, float value);

static inline float analogRead(BelaContext *context, int frame, int channel);

static inline float analogReadNI(BelaContext *context, int frame, int channel);

static inline void analogWrite(BelaContext *context, int frame, int channel, float value);

static inline void analogWriteNI(BelaContext *context, int frame, int channel, float value);

static inline void analogWriteOnce(BelaContext *context, int frame, int channel, float value);

static inline void analogWriteOnceNI(BelaContext *context, int frame, int channel, float value);

static inline int digitalRead(BelaContext *context, int frame, int channel);

static inline void digitalWrite(BelaContext *context, int frame, int channel, int value);

static inline void digitalWriteOnce(BelaContext *context, int frame, int channel, int value);

static inline void pinMode(BelaContext *context, int frame, int channel, int mode);

static inline void pinModeOnce(BelaContext *context, int frame, int channel, int mode);

/*
 * \brief Returns the value of the given multiplexer channel for the given analog input.
 *
 * This function reads an input from the Multiplexer Capelet hardware, which needs to be
 * attached and enabled by selecting 16, 32 or 64 analog input channels in the command line
 * arguments. With the Multiplexer Capelet, each analog input can be connected to one of 8
 * multiplexer channels. This function will return a particular multiplexer channel for a
 * particular input, with the returned valued being the most recent sample taken from that pin.
 *
 * Depending on the block size, it may take longer than a single block to scan all multiplexer
 * channels. For this reason, successive calls to multiplexerAnalogRead() may return the same
 * sample. If you want precise timing control on when a multiplexer input was sampled, use
 * multiplexerChannelForFrame() instead to determine which multiplexer channels were sampled
 * in a particular block.
 *
 * \param context The I/O data structure which is passed by Bela to render().
 * \param input The analog input to read, i.e. what would be passed as \c channel to analogRead().
 * Valid values are 0 to (context->analogInChannels - 1).
 * \param muxChannel Which multiplexer channel to read. Valid values are 0 to
 * (context->multiplexerChannels - 1).
 * \return Value of the analog input from the Multiplexer Capelet.
 */

static inline float multiplexerAnalogRead(BelaContext *context, int input, int muxChannel);

/*
 * \brief Returns which multiplexer channel the given analog frame was taken from.
 *
 * This function indicates what the multiplexer setting was for a given analog input frame.
 * This can be used to work out which pin on the Multiplexer Capelet a given analog input sample
 * was taken from. For this function to have any meaning, the Multiplexer Capelet hardware must
 * be attached and it should be enabled by selecting 16, 32 or 64 analog input channels in the
 * command line arguments.
 *
 * Depending on the block size, it may take longer than a single block to scan all multiplexer
 * channels. For this reason, each call to render() may contain only a subset of the available
 * multiplexer channels. This function allows you timing precision by knowing at what frame each
 * multiplexer reading was taken, but it does not guarantee that all channels can be read in
 * any given callback. If you need access to all the multiplexer inputs in every call to render(),
 * use multiplexerAnalogRead() instead.
 *
 * \param context The I/O data structure which is passed by Bela to render().
 * \param frame The analog frame (i.e. the time) whose multiplexer setting should be queried.
 * \return Multiplexer channel setting at the given frame.
 */

static inline unsigned int multiplexerChannelForFrame(BelaContext *context, int frame);

// audioRead()
//
// Returns the value of the given audio input at the given frame number.
static inline float audioRead(BelaContext *context, int frame, int channel) {
        return context->audioIn[frame * context->audioInChannels + channel];
}

static inline float audioReadNI(BelaContext *context, int frame, int channel) {
        return context->audioIn[channel * context->audioFrames + frame];
}

// audioWrite()
//
// Sets a given audio output channel to a value for the current frame
static inline void audioWrite(BelaContext *context, int frame, int channel, float value) {
        context->audioOut[frame * context->audioOutChannels + channel] = value;
}

static inline void audioWriteNI(BelaContext *context, int frame, int channel, float value) {
        context->audioOut[channel * context->audioFrames + frame] = value;
}

// analogRead()
//
// Returns the value of the given analog input at the given frame number.
static inline float analogRead(BelaContext *context, int frame, int channel) {
        return context->analogIn[frame * context->analogInChannels + channel];
}

static inline float analogReadNI(BelaContext *context, int frame, int channel) {
        return context->analogIn[channel * context->analogFrames + frame];
}

// analogWriteOnce()
//
// Sets a given channel to a value for only the current frame
static inline void analogWriteOnce(BelaContext *context, int frame, int channel, float value) {
        context->analogOut[frame * context->analogOutChannels + channel] = value;
}

static inline void analogWriteOnceNI(BelaContext *context, int frame, int channel, float value) {
        context->analogOut[channel * context->analogFrames + frame] = value;
}

// analogWrite()
//
// Sets a given analog output channel to a value for the current frame and, if persistent outputs are
// enabled, for all subsequent frames
static inline void analogWrite(BelaContext *context, int frame, int channel, float value) {
        unsigned int f;
        for(f = frame; f < context->analogFrames; f++)
                analogWriteOnce(context, f, channel, value);
}

static inline void analogWriteNI(BelaContext *context, int frame, int channel, float value) {
        unsigned int f;
        for(f = frame; f < context->analogFrames; f++)
                analogWriteOnceNI(context, f, channel, value);
}

// digitalRead()
//
// Returns the value of a given digital input at the given frame number
static inline int digitalRead(BelaContext *context, int frame, int channel) {
        return Bela_getBit(context->digital[frame], channel + 16);
}

// digitalWrite()
//
// Sets a given digital output channel to a value for the current frame and all subsequent frames
static inline void digitalWrite(BelaContext *context, int frame, int channel, int value) {
        unsigned int f;
        for(f = frame; f < context->digitalFrames; f++) {
                if(value)
                        context->digital[f] |= 1 << (channel + 16);
                else
                        context->digital[f] &= ~(1 << (channel + 16));
        }
}

// digitalWriteOnce()
//
// Sets a given digital output channel to a value for the current frame only
static inline void digitalWriteOnce(BelaContext *context, int frame, int channel, int value) {
        if(value)
                context->digital[frame] |= 1 << (channel + 16);
        else
                context->digital[frame] &= ~(1 << (channel + 16));
}

// pinMode()
//
// Sets the direction of a digital pin for the current frame and all subsequent frames
static inline void pinMode(BelaContext *context, int frame, int channel, int mode) {
        unsigned int f;
        for(f = frame; f < context->digitalFrames; f++) {
                if(mode == INPUT)
                        context->digital[f] |= (1 << channel);
                else
                        context->digital[f] &= ~(1 << channel);
        }
}

// pinModeOnce()
//
// Sets the direction of a digital pin for the current frame only
static inline void pinModeOnce(BelaContext *context, int frame, int channel, int mode) {
        if(mode == INPUT)
                context->digital[frame] |= (1 << channel);
        else
                context->digital[frame] &= ~(1 << channel);
}

// multiplexerAnalogRead()
//
// Returns the value of the given multiplexer channel for the given analog input.
static inline float multiplexerAnalogRead(BelaContext *context, int input, int muxChannel) {
        return context->multiplexerAnalogIn[muxChannel * context->analogInChannels + input];
}

// multiplexerChannelForFrame()
//
// Returns which multiplexer channel the given analog frame was taken from.
static inline unsigned int multiplexerChannelForFrame(BelaContext *context, int frame) {
        if(context->multiplexerChannels <= 1)
                return 1;
        return (context->multiplexerStartingChannel + frame) % context->multiplexerChannels;
}

#ifdef __cplusplus
}
#endif

#endif /* BELA_H_ */