libcm is a C development framework with an emphasis on audio signal processing applications.
Du kan inte välja fler än 25 ämnen Ämnen måste starta med en bokstav eller siffra, kan innehålla bindestreck ('-') och vara max 35 tecken långa.

cmRtSys.h 15KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335
  1. //( { file_desc:"Improved real-time audio processing engine." kw:[rtsys] }
  2. //
  3. // The audio system is composed a collection of independent sub-systems.
  4. // Each sub-system maintains a thread which runs asynchrounsly
  5. // from the application, the MIDI devices, and the audio devices.
  6. // To faciliate communication between these components each sub-system maintains
  7. // two thread-safe data buffers one for control information and a second
  8. // for audio data.
  9. //
  10. // The audio devices are the primary driver for the system.
  11. // Callbacks from the audio devices (See #cmApCallbackPtr_t)
  12. // inserts incoming audio samples into the audio
  13. // record buffers and extracts samples from the playback buffer.
  14. // When sufficient incoming samples and outgoing empty buffer space exists
  15. // a sub-system thread is waken up by the callback. This triggers a DSP audio
  16. // processing cycle which empties/fills the audio buffers. During a DSP
  17. // processing cycle control messages from the application and MIDI are blocked and
  18. // buffered. Upon completetion of the DSP cycle a control message
  19. // transfer cycles occurs - buffered incoming messages are passed to
  20. // the DSP system and messages originating in the DSP system are
  21. // buffered by the audio system for later pickup by the application
  22. // or MIDI system.
  23. //
  24. // Note that control messages that arrive when the DSP cycle is not
  25. // occurring can pass directly through to the DSP system.
  26. //
  27. // The DSP system sends messages back to the host by calling
  28. // cmRtDspToHostFunc_t provided by cmRtSysCtx_t. These
  29. // calls are always made from within an audio system call to
  30. // audio or control update within cmRtCallback_t. cmRtDspToHostFunc_t
  31. // simply stores the message in a message buffer. The host picks
  32. // up the message at some later time when it notices that messages
  33. // are waiting via polling cmRtSysIsMsgWaiting().
  34. //
  35. // Implementation: \n
  36. // The audio sub-systems work by maintaining an internal thread
  37. // which blocks on a mutex condition variable.
  38. // While the thread is blocked the mutex is unlocked allowing messages
  39. // to pass directly through to the DSP procedure via cmRtCallback().
  40. //
  41. // Periodic calls from running audio devices update the audio buffer.
  42. // When the audio buffer has input samples waiting and output space
  43. // available the condition variable is signaled, the mutex is
  44. // then automatically locked by the system, and the DSP execution
  45. // procedure is called via cmRtCallback().
  46. //
  47. // Messages arriving while the mutex is locked are queued and
  48. // delivered to the DSP procedure at the end of the DSP execution
  49. // procedure.
  50. //)
  51. #ifndef cmRtSys_h
  52. #define cmRtSys_h
  53. #ifdef __cplusplus
  54. extern "C" {
  55. #endif
  56. //(
  57. // Audio system result codes
  58. enum
  59. {
  60. kOkRtRC = cmOkRC,
  61. kThreadErrRtRC,
  62. kMutexErrRtRC,
  63. kTsQueueErrRtRC,
  64. kMsgEnqueueFailRtRC,
  65. kAudioDevSetupErrRtRC,
  66. kAudioBufSetupErrRtRC,
  67. kAudioDevStartFailRtRC,
  68. kAudioDevStopFailRtRC,
  69. kBufTooSmallRtRC,
  70. kNoMsgWaitingRtRC,
  71. kMidiSysFailRtRC,
  72. kMsgSerializeFailRtRC,
  73. kStateBufFailRtRC,
  74. kInvalidArgRtRC,
  75. kNotInitRtRC,
  76. kTimeOutErrRtRC,
  77. kNetErrRtRC
  78. };
  79. enum
  80. {
  81. kAsDfltMsgQueueByteCnt = 0xffff,
  82. kAsDfltDevFramesPerCycle = 512,
  83. kAsDfltDspFramesPerCycle = 64,
  84. kAsDfltBufCnt = 3,
  85. kAsDfltSrate = 44100,
  86. kAsDfltSyncToInputFl = 1,
  87. kAsDfltMinMeterMs = 10,
  88. kAsDfltMeterMs = 50,
  89. kAsDfltMaxMeterMs = 1000
  90. };
  91. typedef cmHandle_t cmRtSysH_t; //< Audio system handle type
  92. typedef unsigned cmRtRC_t; //< Audio system result code
  93. struct cmRtSysCtx_str;
  94. //
  95. // DSP system callback function.
  96. //
  97. // This is the sole point of entry into the DSP system while the audio system is running.
  98. //
  99. // ctxPtr is pointer to a cmRtSysCtx_t record.
  100. //
  101. // This function is called under two circumstances:
  102. //
  103. // 1) To notify the DSP system that the audio input/output buffers need to be serviced.
  104. // This is a perioidic request which the DSP system uses as its execution trigger.
  105. // cmRtSysCtx_t.audioRateFl is set to true to indicate this type of callback.
  106. //
  107. // 2) To pass messages from the host application to the DSP system.
  108. // The DSP system is asyncronous with the host because it executes in the
  109. // audio system thread rather than the host thread. The cmRtSysDeliverMsg()
  110. // function synchronizes incoming messages with the internal audio system
  111. // thread to prevent thread collisions.
  112. //
  113. // Notes:
  114. // This callback is always made with the internal audio system mutex locked.
  115. //
  116. // The signal time covered by the callback is from
  117. // ctx->begSmpIdx to ctx->begSmpIdx+cfg->dspFramesPerCycle.
  118. //
  119. // The return value is currently not used.
  120. typedef cmRC_t (*cmRtCallback_t)(void* ctxPtr, unsigned msgByteCnt, const void* msgDataPtr );
  121. // Network nodes
  122. typedef struct
  123. {
  124. const cmChar_t* label; // Remote node label or NULL if this is the local node.
  125. const cmChar_t* ipAddr; // IP address in xxx.xxx.xxx.xxx form or NULL for 'localhost'.
  126. cmUdpPort_t ipPort; // IP port
  127. } cmRtSysNetNode_t;
  128. // Local endpoints.
  129. typedef struct
  130. {
  131. const cmChar_t* label; // Local endpoint label
  132. unsigned id; // Local endpoint id
  133. } cmRtSysNetEndpt_t;
  134. // Audio device sub-sytem configuration record
  135. typedef struct cmRtSysArgs_str
  136. {
  137. cmRpt_t* rpt; // system console object
  138. unsigned inDevIdx; // input audio device
  139. unsigned outDevIdx; // output audio device
  140. bool syncInputFl; // true/false sync the DSP update callbacks with audio input/output
  141. unsigned msgQueueByteCnt; // Size of the internal msg queue used to buffer msgs arriving via cmRtSysDeliverMsg().
  142. unsigned devFramesPerCycle; // (512) Audio device samples per channel per device update buffer.
  143. unsigned dspFramesPerCycle; // (64) Audio samples per channel per DSP cycle.
  144. unsigned audioBufCnt; // (3) Audio device buffers.
  145. double srate; // Audio sample rate.
  146. } cmRtSysArgs_t;
  147. // Audio sub-system configuration record.
  148. // This record is provided by the host to configure the audio system
  149. // via cmRtSystemAllocate() or cmRtSystemInitialize().
  150. typedef struct cmRtSysSubSys_str
  151. {
  152. cmRtSysArgs_t args; // Audio device configuration
  153. cmRtCallback_t cbFunc; // DSP system entry point function.
  154. void* cbDataPtr; // Host provided data for the DSP system callback.
  155. const cmChar_t* bcastAddr; // Network broadcast address.
  156. const cmChar_t* localNodeLabel; // Network local node address.
  157. const cmChar_t* localIpAddr; // Network local IP address (default:NULL to use any available address)
  158. cmUdpPort_t localIpPort; // Network local socket port address
  159. cmRtSysNetEndpt_t* endptArray; // Local end points
  160. unsigned endptCnt; // Count of local endpoints.
  161. } cmRtSysSubSys_t;
  162. // Signature of a callback function provided by the audio system to receive messages
  163. // from the DSP system for later dispatch to the host application.
  164. // This declaration is used by the DSP system implementation and the audio system.
  165. // Note that this function is intended to convey one message broken into multiple parts.
  166. // See cmTsQueueEnqueueSegMsg() for the equivalent interface.
  167. typedef cmRtRC_t (*cmRtDspToHostFunc_t)(struct cmRtSysCtx_str* p, const void* msgDataPtrArray[], unsigned msgByteCntArray[], unsigned msgSegCnt);
  168. // Record passed with each call to the DSP callback function cmRtCallback_t
  169. typedef struct cmRtSysCtx_str
  170. {
  171. void* reserved; // used internally by the audio system
  172. bool audioRateFl; // true if this is an audio update callback
  173. unsigned srcNetNodeId; // Source net node if this is a msg callback originating from a remote network node.
  174. unsigned rtSubIdx; // index of the sub-system this DSP process is serving
  175. cmRtSysSubSys_t* ss; // ptr to a copy of the cfg recd used to initialize the audio system
  176. unsigned begSmpIdx; // gives signal time as a sample count
  177. cmRtDspToHostFunc_t dspToHostFunc; // Callback used by the DSP process to send messages to the host
  178. // via the audio system. Returns a cmRtRC_t result code.
  179. // output (playback) buffers
  180. cmSample_t** oChArray; // each ele is a ptr to buffer with cfg.dspFramesPerCycle samples
  181. unsigned oChCnt; // count of output channels (ele's in oChArray[])
  182. cmTimeSpec_t oTimeStamp;
  183. // input (recording) buffers
  184. cmSample_t** iChArray; // each ele is a ptr to buffer with cfg.dspFramesPerCycle samples
  185. unsigned iChCnt; // count of input channels (ele's in iChArray[])
  186. cmTimeSpec_t iTimeStamp;
  187. } cmRtSysCtx_t;
  188. extern cmRtSysH_t cmRtSysNullHandle;
  189. // Allocate and initialize an audio system as a collection of 'cfgCnt' sub-systems.
  190. // Prior to call this function the audio audio ports system must be initalized
  191. // (via cmApInitialize()) and the MIDI port system must be initialized
  192. // (via cmMpInitialize()). Note also that cmApFinalize() and cmMpFinalize()
  193. // cannot be called prior to cmRtSysFree().
  194. // See cmRtSystemTest() for a complete example.
  195. cmRtRC_t cmRtSysAllocate( cmRtSysH_t* hp, cmCtx_t* ctx );
  196. // Finalize and release any resources held by the audio system.
  197. cmRtRC_t cmRtSysFree( cmRtSysH_t* hp );
  198. // Returns true if 'h' is a handle which was successfully allocated by
  199. // cmRtSysAllocate().
  200. bool cmRtSysHandleIsValid( cmRtSysH_t h );
  201. // clientCbFunc is Called by cmRtSysReceiveMsg() to deliver internally generated msg's to the host.
  202. // Set to NULL if msg's will be directly returned by buffers passed to cmRtSysReceiveMsg().
  203. cmRtRC_t cmRtSysBeginCfg( cmRtSysH_t h, cmTsQueueCb_t clientCbFunc, void* clientCbArg, unsigned meterMs, unsigned ssCnt );
  204. // Reinitialize a previously allocated audio system. This function
  205. // begins with a call to cmRtSysFinalize().
  206. // Use cmRtSysEnable(h,true) to begin processing audio following this call.
  207. cmRtRC_t cmRtSysCfg( cmRtSysH_t h, const cmRtSysSubSys_t* ss, unsigned rtSubIdx );
  208. cmRtRC_t cmRtSysEndCfg( cmRtSysH_t h );
  209. // Complements cmRtSysInitialize(). In general there is no need to call this function
  210. // since calls to cmRtSysInitialize() and cmRtSysFree() automaticatically call it.
  211. cmRtRC_t cmRtSysFinalize( cmRtSysH_t h );
  212. // Returns true if the audio system has been successfully initialized.
  213. bool cmRtSysIsInitialized( cmRtSysH_t );
  214. // Returns true if the audio system is enabled.
  215. bool cmRtSysIsEnabled( cmRtSysH_t h );
  216. // Enable/disable the audio system. Enabling the starts audio stream
  217. // in/out of the system.
  218. cmRtRC_t cmRtSysEnable( cmRtSysH_t h, bool enableFl );
  219. //
  220. // DSP to Host delivery function
  221. //
  222. // This function is used to pass messages from a DSP process to the HOST it
  223. // is always called from within the real-time thread.
  224. cmRtRC_t cmRtSysDspToHostSegMsg( cmRtSysH_t h, const void* msgDataPtrArray[], unsigned msgByteCntArray[], unsigned msgSegCnt);
  225. cmRtRC_t cmRtSysDspToHost( cmRtSysH_t h, const void* msgDataPtr, unsigned msgByteCnt);
  226. //
  227. // Host to DSP delivery functions
  228. //
  229. // Deliver a message from the host application to the DSP process. (host -> DSP);
  230. // The message is formed as a concatenation of the bytes in each of the segments
  231. // pointed to by 'msgDataPtrArrary[segCnt][msgByteCntArray[segCnt]'.
  232. // This is the canonical msg delivery function in so far as the other host->DSP
  233. // msg delivery function are written in terms of this function.
  234. // The first 4 bytes in the first segment must contain the index of the audio sub-system
  235. // which is to receive the message.
  236. cmRtRC_t cmRtSysDeliverSegMsg( cmRtSysH_t h, const void* msgDataPtrArray[], unsigned msgByteCntArray[], unsigned msgSegCnt, unsigned srcNetNodeId );
  237. // Deliver a single message from the host to the DSP system.
  238. cmRtRC_t cmRtSysDeliverMsg( cmRtSysH_t h, const void* msgPtr, unsigned msgByteCnt, unsigned srcNetNodeId );
  239. // Deliver a single message from the host to the DSP system.
  240. // Prior to delivery the 'id' is prepended to the message.
  241. cmRtRC_t cmRtSysDeliverIdMsg( cmRtSysH_t h, unsigned rtSubIdx, unsigned id, const void* msgPtr, unsigned msgByteCnt, unsigned srcNetNodeId );
  242. //
  243. // DSP to Host message functions
  244. //
  245. // Is a msg from the DSP waiting to be picked up by the host? (host <- DSP)
  246. // 0 = no msgs are waiting or the msg queue is locked by the DSP process.
  247. // >0 = the size of the buffer required to hold the next msg returned via
  248. // cmRtSysReceiveMsg().
  249. unsigned cmRtSysIsMsgWaiting( cmRtSysH_t h );
  250. // Copy the next available msg sent from the DSP process to the host into the host supplied msg buffer
  251. // pointed to by 'msgBufPtr'. Set 'msgDataPtr' to NULL to receive msg by callback from cmRtSysCfg_t.clientCbFunc.
  252. // Returns kBufTooSmallRtRC if msgDataPtr[msgByteCnt] is too small to hold the msg.
  253. // Returns kNoMsgWaitingRtRC if no messages are waiting for delivery or the msg queue is locked by the DSP process.
  254. // Returns kOkRtRC if a msg was delivered.
  255. // Call cmRtSysIsMsgWaiting() prior to calling this function to get
  256. // the size of the data buffer required to hold the next message.
  257. cmRtRC_t cmRtSysReceiveMsg( cmRtSysH_t h, void* msgDataPtr, unsigned msgByteCnt );
  258. // Fill an audio system status record.
  259. void cmRtSysStatus( cmRtSysH_t h, unsigned rtSubIdx, cmRtSysStatus_t* statusPtr );
  260. // Enable cmRtSysStatus_t notifications to be sent periodically to the host.
  261. // Set rtSubIdx to cmInvalidIdx to enable/disable all sub-systems.
  262. // The notifications occur approximately every cmRtSysCfg_t.meterMs milliseconds.
  263. void cmRtSysStatusNotifyEnable( cmRtSysH_t, unsigned rtSubIdx, bool enableFl );
  264. // Return a pointer the context record associated with a sub-system
  265. cmRtSysCtx_t* cmRtSysContext( cmRtSysH_t h, unsigned rtSubIdx );
  266. // Enable non-block mode. In this mode audio I/O is disabled
  267. // and the DSP callback is made every noBlockSleepMs milliseconds.
  268. cmRtRC_t cmRtSysEnableNoBlockMode( cmRtSysH_t h, unsigned rtSubIdx, bool enaFl, unsigned noBlockSleepMs );
  269. // Return the count of audio sub-systems.
  270. // This is the same as the count of cfg recds passed to cmRtSystemInitialize().
  271. unsigned cmRtSysSubSystemCount( cmRtSysH_t h );
  272. // Audio system test and example function.
  273. void cmRtSysTest( cmCtx_t* ctx, int argc, const char* argv[] );
  274. bool cmRtSysNetIsInitialized( cmRtSysH_t h );
  275. cmRtRC_t cmRtSysNetDoSync( cmRtSysH_t h );
  276. cmRtRC_t cmRtSysNetReport( cmRtSysH_t h );
  277. cmRtRC_t cmRtSysNetReportSyncEnable( cmRtSysH_t h, bool enableFl );
  278. cmRtRC_t cmRtSysNetGetHandle( cmRtSysH_t h, unsigned rtSubIdx, cmRtNetH_t* hp );
  279. //)
  280. #ifdef __cplusplus
  281. }
  282. #endif
  283. #endif