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