diff include/BeagleRT.h @ 47:643cbee74eda newapi

First draft of Doxygen documentation

--- a/include/BeagleRT.h	Thu May 28 14:38:00 2015 -0400
+++ b/include/BeagleRT.h	Thu May 28 17:06:03 2015 -0400
@@ -1,12 +1,13 @@
-/*
- *  RTAudio.h
+/**
+ *  @file
+ *  @brief Main BeagleRT public API
  *
  *  Central control code for hard real-time audio on BeagleBone Black
  *  using PRU and Xenomai Linux extensions. This code began as part
  *  of the Hackable Instruments project (EPSRC) at Queen Mary University
  *  of London, 2013-14.
  *
- *  (c) 2014 Victor Zappi and Andrew McPherson
+ *  (c) 2014-15 Andrew McPherson, Victor Zappi and Giulio Moro,
  *  Queen Mary University of London
  */
 
@@ -18,33 +19,63 @@
 #include "digital_gpio_mapping.h"
 
 // Useful constants
+
+/** \cond PRIVATE */
 #define DBOX_CAPE					// New custom cape
-
 #ifdef DBOX_CAPE
 #define CODEC_I2C_ADDRESS  0x18		// Address of TLV320AIC3104 codec
 #else
 #define CODEC_I2C_ADDRESS  0x1B		// Address of TLV320AIC3106 codec
 #endif
 
-// Default volume levels
-#define DEFAULT_DAC_LEVEL	0.0
-#define DEFAULT_ADC_LEVEL	-6.0
-#define DEFAULT_HP_LEVEL	-6.0
-
 #define MAX_PRU_FILENAME_LENGTH 256
 #define MAX_SERVERNAME_LENGTH 256
+/** \endcond */
 
-// Priority at which BeagleRT audio code runs
-// Higher numbers preempt the audio; lower numbers are preempted by it
+/**
+ * \ingroup auxtask
+ *
+ * Xenomai priority level for audio processing. Maximum possible priority is 99.
+ * In general, all auxiliary tasks should have a level lower than this unless for\
+ * special purposes where the task needs to interrupt audio processing.
+ */
 #define BEAGLERT_AUDIO_PRIORITY		95
 
-// Flags for BeagleRTContext data structure
+// Default volume levels
+
+/**
+ * \addtogroup levels
+ *
+ * @{
+ */
+
+/**
+ * Default level of the audio DAC in decibels. See BeagleRT_setDACLevel().
+ */
+#define DEFAULT_DAC_LEVEL	0.0
+
+/**
+ * Default level of the audio ADC in decibels. See BeagleRT_setADCLevel().
+ */
+#define DEFAULT_ADC_LEVEL	-6.0
+
+/**
+ * Default level of the headphone output in decibels. See BeagleRT_setHeadphoneLevel().
+ */
+#define DEFAULT_HP_LEVEL	-6.0
+/** @} */
+
+/**
+ * Flag for BeagleRTContext. If set, indicates the audio and analog buffers are interleaved.
+ */
 #define BEAGLERT_FLAG_INTERLEAVED				(1 << 0)	// Set if buffers are interleaved
+/**
+ * Flag for BeagleRTContext. If set, indicates analog outputs persist for future frames.
+ */
 #define BEAGLERT_FLAG_ANALOG_OUTPUTS_PERSIST	(1 << 1)	// Set if analog/digital outputs persist for future buffers
 
 // Mappings from pin numbers on PCB to actual DAC channels
 // This gives the DAC and ADC connectors the same effective pinout
-
 #define DAC_PIN0	6
 #define DAC_PIN1	4
 #define DAC_PIN2	2
@@ -63,79 +94,194 @@
 #define ADC_PIN6	6
 #define ADC_PIN7	7
 
-// Structure which contains initialisation parameters for the
-// real-time audio system
+/**
+ * \ingroup control
+ * \brief Structure containing initialisation parameters for the real-time
+ * audio control system.
+ *
+ * This structure is initialised using BeagleRT_defaultSettings(). Its contents
+ * are used up through the point of calling
+ * BeagleRT_initAudio() at which point it is no longer needed.
+ */
 typedef struct {
 	// These items might be adjusted by the user:
-	int periodSize;			// Number of (analog) frames per period; audio is twice this
-	int useAnalog;			// Whether to use the analog
-	int useDigital;			// Whether to use the 16 programmable GPIOs
-	int numAnalogChannels;	// How many channels for the ADC and DAC
-	int numDigitalChannels;	// How many channels for the GPIOs
 
-	int beginMuted;			// Whether to begin with the speakers muted
-	float dacLevel;			// Level for the audio DAC output
-	float adcLevel;			// Level for the audio ADC input
-	float headphoneLevel;	// Level for the headphone output
+	/// \brief Number of (analog) frames per period.
+	///
+	/// Number of audio frames depends on relative sample rates of the two. By default,
+	/// audio is twice the sample rate, so has twice the period size.
+	int periodSize;
+	/// Whether to use the analog input and output
+	int useAnalog;
+	/// Whether to use the 16 programmable GPIOs
+	int useDigital;
+	/// How many channels for the ADC and DAC
+	int numAnalogChannels;
+	/// How many channels for the GPIOs
+	int numDigitalChannels;
 
-	char pruFilename[MAX_PRU_FILENAME_LENGTH]; // The external .bin file to load. If empty will use PRU code from pru_rtaudio_bin.h
-	int verbose;			// Whether to use verbose logging
+	/// Whether to begin with the speakers muted
+	int beginMuted;
+	/// Level for the audio DAC output
+	float dacLevel;
+	/// Level for the audio ADC input
+	float adcLevel;
+	/// Level for the headphone output
+	float headphoneLevel;
+
+	/// The external .bin file to load. If empty will use PRU code from pru_rtaudio_bin.h
+	char pruFilename[MAX_PRU_FILENAME_LENGTH];
+	/// Whether to use verbose logging
+	int verbose;
 
 	// These items are application-dependent but should probably be
 	// determined by the programmer rather than the user
-	int interleave;			// Whether audio/analog data should be interleaved
-	int analogOutputsPersist; // Whether analog outputs should persist to future frames
-							  // n.b. digital pins always persist, audio never does
+
+	/// Whether audio/analog data should be interleaved
+	int interleave;
+	/// \brief Whether analog outputs should persist to future frames.
+	///
+	/// n.b. digital pins always persist, audio never does
+	int analogOutputsPersist;
 
 	// These items are hardware-dependent and should only be changed
 	// to run on different hardware
-	int codecI2CAddress;	  // Where the codec can be found on the I2C bus
-	int ampMutePin;			  // Pin where amplifier mute can be found
-	int receivePort;          // Port where the UDP server will listen
-	int transmitPort;         // Port where the UDP client will transmit
+
+	/// Where the codec can be found on the I2C bus
+	int codecI2CAddress;
+	/// Pin where amplifier mute can be found
+	int ampMutePin;
+	/// Port where the UDP server will listen
+	int receivePort;
+	/// Port where the UDP client will transmit
+	int transmitPort;
 	char serverName[MAX_SERVERNAME_LENGTH];
 } BeagleRTInitSettings;
 
-// BeagleRTContext data structure
-// Holds information passed to the render() function and related calls
-// Contains the current audio and sensor settings and pointers to the data buffers
 
+/**
+ * \ingroup render
+ * \brief Structure holding current audio and sensor settings and pointers to data buffers.
+ *
+ * This structure is passed to initialise_render(), render() and cleanup_render(). It is
+ * initialised in BeagleRT_initAudio() based on the contents of the BeagleRTInitSettings
+ * structure.
+ */
 typedef struct {
+	/// \brief Buffer holding audio input samples
+	///
+	/// This buffer may be in either interleaved or non-interleaved format,
+	/// depending on the contents of the BeagleRTInitSettings structure.
+	/// \b Note: this element is available in render() only.
 	float *audioIn;
+
+	/// \brief Buffer holding audio output samples
+	///
+	/// This buffer may be in either interleaved or non-interleaved format,
+	/// depending on the contents of the BeagleRTInitSettings structure.
+	/// \b Note: this element is available in render() only.
 	float *audioOut;
+
+	/// \brief Buffer holding analog input samples
+	///
+	/// This buffer may be in either interleaved or non-interleaved format,
+	/// depending on the contents of the BeagleRTInitSettings structure.
+	/// \b Note: this element is available in render() only.
 	float *analogIn;
+
+	/// \brief Buffer holding analog output samples
+	///
+	/// This buffer may be in either interleaved or non-interleaved format,
+	/// depending on the contents of the BeagleRTInitSettings structure.
+	/// \b Note: this element is available in render() only.
 	float *analogOut;
+
+	/// \brief Buffer holding digital input/output samples
+	///
+	/// \b Note: this element is available in render() only.
 	uint32_t *digital;
 
+	/// Number of audio frames per period
 	uint32_t audioFrames;
+	/// Number of audio channels (currently always 2)
 	uint32_t audioChannels;
+	/// Audio sample rate in Hz (currently always 44100.0)
 	float audioSampleRate;
 
+	/// \brief Number of analog frames per period
+	///
+	/// This will be 0 if analog I/O is disabled.
 	uint32_t analogFrames;
+
+	/// \brief Number of analog channels
+	///
+	/// This could take a value of 8, 4 or 2. This will be 0 if analog I/O is disabled.
 	uint32_t analogChannels;
+
+	/// \brief Analog sample rate in Hz
+	///
+	/// The analog sample rate depends on the number of analog channels used. If
+	/// 8 channels are used, the sample rate is 22050. If 4 channels are used, the sample
+	/// rate is 44100. If 2 channels are used, the sample rate is 88200. If analog I/O
+	/// is disabled, the sample rate is 0.
 	float analogSampleRate;
 
+	/// Number of digital frames per period
 	uint32_t digitalFrames;
+	/// \brief Number of digital channels
+	///
+	/// Currently this will always be 16, unless digital I/O is disabled, in which case it will be 0.
 	uint32_t digitalChannels;
+	/// Digital sample rate in Hz (currently always 44100.0)
 	float digitalSampleRate;
 
+	/// \brief Number of elapsed audio samples since the start of rendering.
+	///
+	/// This holds the total number of audio samples as of the beginning of the current period. To
+	/// find the current number of analog or digital samples elapsed, multiply by the ratio of the
+	/// sample rates (e.g. half the number of analog samples will have elapsed if the analog sample
+	/// rate is 22050).
 	uint64_t audioSampleCount;
+
+	/// \brief Other audio/sensor settings
+	///
+	/// Binary combination of flags including:
+	///
+	/// BEAGLERT_FLAG_INTERLEAVED: indicates the audio and analog buffers are interleaved
+	///
+	/// BEAGLERT_FLAG_ANALOG_OUTPUTS_PERSIST: indicates that writes to the analog outputs will
+	/// persist for future frames. If not set, writes affect one frame only.
 	uint32_t flags;
 } BeagleRTContext;
 
-enum {
-	kAmplifierMutePin = 61	// P8-26 controls amplifier mute
-};
-
+/** \ingroup auxtask
+ *
+ * Auxiliary task variable. Auxiliary tasks are created using createAuxiliaryTask() and
+ * automatically cleaned up after cleanup_render() finishes.
+ */
 typedef void* AuxiliaryTask;	// Opaque data type to keep track of aux tasks
 
-// Flag that indicates when the audio will stop; can be read or
-// set by other components which should end at the same time as the audio
+/** \ingroup render
+ *
+ * Flag that indicates when the audio will stop. Threads can poll this variable to indicate when
+ * they should stop. Additionally, a program can set this to \c true
+ * to indicate that audio processing should terminate. Calling BeagleRT_stopAudio()
+ * has the effect of setting this to \c true.
+ */
 extern bool gShouldStop;
 
 // *** User-defined render functions ***
 
 /**
+ * \defgroup render User-defined render functions
+ *
+ * These three functions must be implemented by the developer in every BeagleRT program.
+ * Typically they appear in their own .cpp source file.
+ *
+ * @{
+ */
+
+/**
  * \brief User-defined initialisation function which runs before audio rendering begins.
  *
  * This function runs once at the beginning of the program, after most of the system
@@ -187,6 +333,17 @@
  */
 void cleanup_render(BeagleRTContext *context, void *userData);
 
+/** @} */
+
+/**
+ * \defgroup control Control and command line functions
+ *
+ * These functions are used to initialise the BeagleRT settings, process arguments
+ * from the command line, and start/stop the audio and sensor system.
+ *
+ * @{
+ */
+
 // *** Command-line settings ***
 
 /**
@@ -241,6 +398,7 @@
  */
 void BeagleRT_setVerboseLevel(int level);
 
+
 // *** Audio control functions ***
 
 /**
@@ -287,8 +445,16 @@
  */
 void BeagleRT_cleanupAudio();
 
-// Volume/level controls
-// These return 0 on success
+/** @} */
+
+/**
+ * \defgroup levels Audio level controls
+ *
+ * These functions control the input and output levels for the audio codec. If a BeagleRT program
+ * does not call these functions, sensible default levels will be used.
+ *
+ * @{
+ */
 
 // *** Volume and level controls ***
 
@@ -356,6 +522,22 @@
  */
 int BeagleRT_muteSpeakers(int mute);
 
+/** @} */
+
+/**
+ * \defgroup auxtask Auxiliary task support
+ *
+ * These functions are used to create separate real-time tasks (threads) which run at lower
+ * priority than the audio processing. They can be used, for example, for large time-consuming
+ * calculations which would take more than one audio frame length to process, or they could be
+ * used to communicate with external hardware when that communication might block or be delayed.
+ *
+ * All auxiliary tasks used by the program should be created in initialise_render(). The tasks
+ * can then be scheduled at will within the render() function.
+ *
+ * @{
+ */
+
 // *** Functions for creating auxiliary tasks ***
 
 /**
@@ -366,14 +548,14 @@
  * Auxiliary tasks should be created in initialise_render() and never in render() itself.
  *
  * The second argument specifies the real-time priority. Valid values are between 0
- * and 99, and usually should be lower than BEAGLERT_AUDIO_PRIORITY. Tasks with higher priority always
+ * and 99, and usually should be lower than \ref BEAGLERT_AUDIO_PRIORITY. Tasks with higher priority always
  * preempt tasks with lower priority.
  *
  * \param functionToCall Function which will run each time the auxiliary task is scheduled.
  * \param priority Xenomai priority level at which the task should run.
- * \param Name for this task, which should be unique system-wide (no other running program should use this name).
+ * \param name Name for this task, which should be unique system-wide (no other running program should use this name).
  */
-AuxiliaryTask createAuxiliaryTaskLoop(void (*functionToCall)(void), int priority, const char *name);
+AuxiliaryTask BeagleRT_createAuxiliaryTask(void (*functionToCall)(void), int priority, const char *name);
 
 /**
  * \brief Run an auxiliary task which has previously been created.
@@ -386,6 +568,8 @@
  *
  * \param task Task to schedule for running.
  */
-void scheduleAuxiliaryTask(AuxiliaryTask task);
+void BeagleRT_scheduleAuxiliaryTask(AuxiliaryTask task);
+
+/** @} */
 
 #endif /* BEAGLERT_H_ */