MusicKit  0.0.0
DSPControl.h
00001 #ifndef __MK_DSPControl_H___
00002 #define __MK_DSPControl_H___
00003 /* DSPControl.h - Functions in libdsp_s.a having to do with DSP control.
00004  * Copyright 1988-1992, NeXT Inc.  All rights reserved.
00005  * Author: Julius O. Smith III
00006  */
00007 
00008 /* Control functions are also in DSPObject.h */
00009 
00010 #include "MKDSPDefines.h"
00011 
00012 /********************** READING/WRITING DSP HOST FLAGS ***********************/
00013 
00014 MKDSP_API int DSPSetHF0(void);
00015 /*
00016  * Set bit HF0 in the DSP host interface.
00017  * In the context of the music kit or array processing kit, HF0 is set 
00018  * by the driver to indicate that the host interface is initialized in DMA
00019  * mode.
00020  */
00021 
00022 
00023 MKDSP_API int DSPClearHF0(void);
00024 /*
00025  * Clear bit HF0 in the DSP host interface.
00026  */
00027 
00028 
00029 MKDSP_API int DSPGetHF0(void);
00030 /* 
00031  * Read state of HF0 flag of ICR in DSP host interface.
00032  */
00033 
00034 
00035 MKDSP_API int DSPSetHF1(void);
00036 /*
00037  * Set bit HF1 in the DSP host interface.
00038  * In the context of the music kit or array processing kit, HF1 is not used.
00039  */
00040 
00041 
00042 MKDSP_API int DSPClearHF1(void);
00043 /*
00044  * Clear bit HF1 in the DSP host interface.
00045  */
00046 
00047 
00048 MKDSP_API int DSPGetHF1(void);
00049 /* 
00050  * Read state of HF1 flag of ICR in DSP host interface.
00051  */
00052 
00053 
00054 MKDSP_API int DSPGetHF2(void);
00055 /*
00056  * Return nonzero if bit HF2 in the DSP host interface is set, otherwise FALSE.
00057  * In the context of the music kit or array processing kit, HF2 is set during 
00058  * the execution of a host message.
00059  */
00060 
00061 
00062 MKDSP_API int DSPGetHF3(void);
00063 /*
00064  * Return nonzero if bit HF3 in the DSP host interface is set, otherwise FALSE.
00065  * HF3 set in the context of the music kit implies the Timed Message Queue
00066  * in the DSP is full.  For array processing, it means the AP program is still
00067  * executing on the DSP.
00068  */
00069 
00070 
00071 MKDSP_API int DSPGetHF2AndHF3(void);
00072 /*
00073  * Return nonzero if bits HF2 and HF3 in the DSP host interface are set, 
00074  * otherwise FALSE.  The Music Kit and array processing monitors set
00075  * both bits to indicate that the DSP has aborted.
00076  */
00077 
00078 /*************************** DSP SYNCHRONIZATION ***************************/
00079 
00080 
00081 MKDSP_API int DSPAwaitCondition(int mask, int value, int msTimeLimit);
00082 /*
00083  * Await specified condition in the DSP host interface.
00084  * The DSP registers ICR,CVR,ISR,IVR are concatenated to form a 32-bit word.
00085  * Call this word dspregs.  Then the awaited condition is
00086  *
00087  *  dspregs & mask == value
00088  *
00089  * If the condition is true by msTimeLimit (millisecond time-limit),
00090  * 0 is returned. Otherwise, DSP_ETIMEOUT is returned.  An msTimeLimit of 0
00091  * means wait forever.  Note that the time-out is only for the function 
00092  * call. The awaited condition is still pending in the DSP driver, and 
00093  * there is presently no way to cancel it or give it a time-out in the driver.
00094  * If the condition hangs, all DSP commands at the same or lower
00095  * Mach message priority will be blocked. Higher priority messages can
00096  * still get through.
00097  */
00098 
00099 
00100 MKDSP_API int DSPResumeAwaitingCondition(int msTimeLimit);
00101 /*
00102  * If DSPAwaitCondition() returns nonzero, you can call this function to
00103  * resume waiting for a specified interval.  You should also call
00104  * DSPAwakenDriver() (see below) before calling this one to make sure
00105  * the driver rechecks the awaited condition in the DSP.  By doing this
00106  * in a loop at regular intervals you can set up a polling loop for the
00107  * awaited condition.   The polling is efficient if
00108  * msTimeLimit is reasonably large because during that time
00109  * the calling thread is sleeping in msg_receive().
00110  * Returns 0 if the condition comes true, nonzero if it times out.
00111  */
00112 
00113 
00114 MKDSP_API int DSPAwaitConditionNoBlock(
00115     int mask,           /* mask to block on as bits in (ICR,CVR,ISR,IVR) */
00116     int value);         /* 1 or 0 as desired for each 1 mask bit */
00117 /*
00118  * Same as DSPAwaitCondition() except the function returns immediately.
00119  * The condition serves as a possible block for the DSP command queue
00120  * within the driver, but not for the calling program.
00121  */
00122 
00123 
00124 MKDSP_API int DSPAwaitHC(int msTimeLimit);
00125 /*
00126  * Wait for "HC bit" to clear. 
00127  * The HC clears when the next instruction to be executed in the DSP
00128  * is the first word of the host command interrupt vector.
00129  * Equivalent to "DSPAwaitCondition(0x00800000,0x00000000,msTimeLimit);"
00130  */
00131 
00132 
00133 MKDSP_API int DSPAwaitTRDY(int msTimeLimit);
00134 /*
00135  * Wait for "TRDY bit" to set. 
00136  * Equivalent to "DSPAwaitCondition(0x00040000,0x00040000,msTimeLimit);"
00137  */
00138 
00139 
00140 MKDSP_API int DSPAwaitHF3Clear(int msTimeLimit);
00141 /*
00142  * Wait for HF3 = "MK TMQ full" or "AP Program Busy" bit to clear. 
00143  * Equivalent to "DSPAwaitCondition(0x00100000,0x00100000,msTimeLimit);"
00144  */
00145 
00146 
00147 MKDSP_API int DSPAwaitHostMessage(int msTimeLimit);
00148 /*
00149  * Wait for currently executing host message to finish.
00150  */
00151 
00152 
00153 int DSPAwakenDriver(void);
00154 /* 
00155  * Send empty message to DSP at priority DSP_MSG_HIGH to wake up the driver. 
00156  * When the DSP driver is awaiting a condition, such as is done by
00157  * DSPAwaitCondition(), there no automatic polling that is done by the system.
00158  * Instead, it is up to the programmer to ensure that some event, such
00159  * as a Mach message to the Sound/DSP driver, a DMA-completion interrupt 
00160  * involving the DSP, or a DSP interrupt, will cause the driver to run and 
00161  * check the awaited condition.  See DSPResumeAwaitingCondition().
00162  */
00163 
00164 /**************************** DSP Program Execution ********************************/
00165 
00166 MKDSP_API int DSPSetStart(DSPAddress startAddress);
00167 /*
00168  * Set default DSP start address for user program.
00169  */
00170 
00171 
00172 MKDSP_API int DSPStart(void);
00173 /*
00174  * Initiate execution of currently loaded DSP user program at current
00175  * default DSP start address.
00176  */
00177 
00178 
00179 MKDSP_API int DSPStartAtAddress(DSPAddress startAddress);
00180 /*
00181  * Equivalent to DSPSetStart(startAddress) followed by DSPStart().
00182  */
00183 
00184 /********************** Querying the DSP MK or AP Monitor  **************************/
00185 
00186 MKDSP_API int DSPPingVersionTimeOut(
00187     int *verrevP,
00188     int msTimeLimit);
00189 /* 
00190  * Like DSPPingVersion but allowing specification of a time-out in
00191  * milliseconds.
00192  */
00193 
00194 
00195 MKDSP_API int DSPPingVersion(int *verrevP);
00196 /* 
00197  * "Ping" the DSP.  The DSP responds with an "I am alive" message
00198  * containing the system version and revision.
00199  * Returns 0 if this reply is received, nonzero otherwise.
00200  * (version<<8 | revision) is returned in *verrevP.
00201  */
00202 
00203 
00204 MKDSP_API int DSPPingTimeOut(int msTimeLimit);
00205 /* 
00206  * Like DSPPing but allowing specification of a time-out in
00207  * milliseconds.
00208  */
00209 
00210 
00211 MKDSP_API int DSPPing(void);
00212 /* 
00213  * "Ping" the DSP.  The DSP responds with an "I am alive" message.
00214  * Returns 0 if this reply is received, nonzero otherwise.
00215  */
00216 
00217 
00218 MKDSP_API int DSPCheckVersion(
00219     int *sysver,           /* system version running on DSP (returned) */
00220     int *sysrev);          /* system revision running on DSP (returned) */
00221 /* 
00222  * "Ping" the DSP.  The DSP responds with an "I am alive" message
00223  * containing the DSP system version and revision as an argument.
00224  * For extra safety, two more messages are sent to the DSP asking for the
00225  * address boundaries of the DSP host-message dispatch table.  These
00226  * are compared to the values compiled into the program. 
00227  * A nonzero return value indicates a version mismatch or a hung DSP.
00228  * The exact nature of the error will appear in the error log file, if enabled.
00229  */
00230 
00231 
00232 MKDSP_API int DSPIsAlive(void);
00233 /*
00234  * Ask DSP monitor if it's alive, ignoring system version and revision.
00235  * "Alive" means anything but hung.  System version compatibility is
00236  * immaterial.  Use DSPCheckVersion() to check for compatibility between 
00237  * the loaded DSP system and your compilation.
00238  */
00239 
00240 
00241 MKDSP_API int DSPMKIsAlive(void);
00242 /*
00243  * Ask DSP monitor if it's alive, and if it's the Music Kit monitor.
00244  */
00245 
00246 /***************************** Untimed Control  *******************************/
00247 
00248 MKDSP_API int DSPMKFreezeOrchestra(void);
00249 /*
00250  * Place the DSP orchestra into the "frozen" state.  The orchestra loop enters
00251  * this state when it finishes computing the current "tick" of sound and jumps
00252  * back to the loop top.  It busy-waits there until DSPMKThawOrchestra() is
00253  * called.  In the frozen state, DSP device interrupts remain enabled, but no
00254  * new sound is computed.  Thus, if sound-out is flowing, it will soon
00255  * under-run.
00256  */
00257 
00258 
00259 MKDSP_API int DSPMKThawOrchestra(void);
00260 /*
00261  * Release the DSP orchestra from the frozen state.
00262  */
00263 
00264 
00265 MKDSP_API int DSPMKPauseOrchestra(void);
00266 /*
00267  * Place the DSP orchestra into the paused state.  In this type of pause, the
00268  * orchestra loop continues to run, emitting sound, but time does not advance.
00269  * Thus, a better name would be DSPMKPauseTimedMessages().
00270  */
00271 
00272 
00273 MKDSP_API int DSPMKResumeOrchestra(void);
00274 /*
00275  * Release the DSP orchestra from the paused state.
00276  */
00277 
00278 
00279 MKDSP_API int DSPSetDMAReadMReg(DSPAddress M);
00280 /* 
00281  * Set the M index register used in DMA reads from DSP to host to M.
00282  * The default is M = -1 which means linear addressing.
00283  * The value M = 0 implies bit-reverse addressing, and
00284  * positive M is one less than the size of the modulo buffer used.
00285  */
00286 
00287 
00288 MKDSP_API int DSPSetDMAWriteMReg(DSPAddress M);
00289 /* 
00290  * Set the M index register used in DMA writes from host to DSP to M.
00291  * The default is M = -1 which means linear addressing.
00292  * The value M = 0 implies bit-reverse addressing, and
00293  * positive M is one less than the size of the modulo buffer used.
00294  */
00295 
00296 
00297 MKDSP_API int DSPAbort(void);
00298 /* 
00299  * Tell the DSP to abort.
00300  */
00301 
00302 
00303 /******************************** TIMED CONTROL ******************************/
00304 /* 
00305    Timed messages are used by the music kit.  Time is maintained in the DSP.
00306    The current time (in samples) is incremented by the tick size DSPMK_I_NTICK
00307    once each iteration of the orchestra loop on the DSP.  When the orchestra
00308    loop is initially loaded and started, the time increment is zero so that
00309    time does not advance.  This is the "paused" state for the DSP orchestra
00310    (to be distinguished from the "frozen" state in which everything suspends).
00311 */
00312 
00313 MKDSP_API int DSPMKSetTime(DSPFix48 *aTimeStampP);
00314 /*
00315  * Set DSP sample time to that contained in *aTimeStampP.
00316  */
00317 
00318 
00319 MKDSP_API int DSPMKClearTime(void);
00320 /*
00321  * Set DSP sample time to zero.
00322  */
00323 
00324 
00325 MKDSP_API int DSPReadLong(DSPFix48 *longValue,DSPAddress address);
00326 /*
00327  * Read a 48-bit value from DSP l memory.
00328  */
00329 
00330 
00331 DSPFix48 *DSPGetLong(DSPAddress address);
00332 /*
00333  * Read a 48-bit value from DSP l memory.
00334  * Pointer returned is to freshly allocated DSPFix48.
00335  */
00336 
00337 
00338 MKDSP_API int DSPMKReadTime(DSPFix48 *dspTime);
00339 /*
00340  * Read DSP sample time.
00341  * Equivalent to DSPReadLong(dspTime,DSP_L_TICK);
00342  */
00343 
00344 
00345 MKDSP_API DSPFix48 *DSPMKGetTime(void);
00346 /*
00347  * Read DSP sample time.  Returns NULL on error instead of error code.
00348  * Pointer returned is to freshly allocated DSPFix48.
00349  */
00350 
00351 
00352 MKDSP_API int DSPMKEnableAtomicTimed(DSPFix48 *aTimeStampP);
00353 /* 
00354  * Tell the DSP to begin an atomic block of timed messages.
00355  */
00356 
00357 
00358 MKDSP_API int DSPMKDisableAtomicTimed(DSPFix48 *aTimeStampP);
00359 /* 
00360  * Terminate an atomic block of timed messages in the DSP TMQ.
00361  */
00362 
00363 
00364 MKDSP_API int DSPMKPauseOrchestraTimed(DSPFix48 *aTimeStampP);
00365 /*
00366  * Place the orchestra into the paused state at the requested DSP sample time.
00367  */
00368 
00369 #endif