MusicKit  0.0.0
monitor_independent.h
00001 #ifndef __MK_monitor_independent_H___
00002 #define __MK_monitor_independent_H___
00003 /* monitor_independent.h - libdsp functions independent of the DSP monitor used
00004  * Copyright 1988-1992, NeXT Inc.  All rights reserved.
00005  * Author: Julius O. Smith III
00006  */
00007 
00008 /* 
00009  * This header file contains procedure prototypes for the monitor-independent
00010  * subset of the functions in libdsp_s.a.  Its main purpose is to "document"
00011  * which functions can be used independently of the Music Kit and array
00012  * processing DSP monitors.  Only the host interface of the DSP is
00013  * touched (via the Sound/DSP driver) by the functions. The functions can 
00014  * be considered higher level alternatives to the snddriver_*() functions
00015  * in libsys_s.a, and direct Mach messaging.  The functions which set up
00016  * open modes assumed DSPOpenNoBoot() or variant will be called.
00017  */     
00018 
00019 /*
00020 
00021 #import "DSPStructMisc.h"
00022 #import "DSPConversion.h"
00023 #import "DSPSymbols.h"
00024 #import "DSPError.h"
00025 
00026 /*
00027     Not monitor-independent:
00028         #import "DSPControl.h"
00029         #import "DSPMessage.h"
00030         #import "DSPTransfer.h"
00031 */
00032 
00033 /* ============================= DSPReadFile.c ============================= */
00034 int DSPReadFile(DSPLoadSpec **dsppp, const char *fn);
00035 /*
00036  * Read in a DSP file (as produced by the assembler in absolute mode).
00037  * It looks in the system-wide .dsp directory for the given file if 
00038  * the user's working directory does not contain a readable version of 
00039  * the file (.lnk, .lod, or .dsp).
00040  */
00041 
00042 /* =============================== DSPBoot.h =============================== */
00043 
00044 int DSPBootFile(char *fn);
00045 /*
00046  * Boot DSP from the file specified.
00047  * Equivalent to DSPReadFile followed by DSPBoot.
00048  */
00049 
00050 
00051 int DSPBoot(DSPLoadSpec *system);
00052 /* 
00053  * Load DSP bootstrap program.
00054  * DSPBoot closes the DSP if it is open, resets it, and feeds the
00055  * resident monitor supplied in the struct 'system' to the bootstrapping DSP.
00056  * If system is NULL, the default resident monitor is supplied to the DSP.
00057  * On return, the DSP is open.
00058  */
00059 
00060 /* =============================== DSPObject.h ============================= */
00061 /* 
00062  * Excerpt - Low level DSP access and control.
00063  */
00064 
00065 /*
00066  * These functions are organized logically with respect to the DSP open
00067  * routines in that functions apearing before the open routines must be called
00068  * before the DSP is opened (or any time), and functions apearing after the
00069  * open routines must be (or typically are) called after the DSP is opened.
00070  */
00071 
00072 extern int DSPGetHostTime(void);
00073 /*
00074  * Returns the time in microseconds since it was last called.
00075  */
00076 
00077 
00078 /*********** Utilities global with respect to all DSP instances **************/
00079 
00080 
00081 extern int DSPGetDSPCount(void);
00082 /* 
00083  * Return number of DSPs in current system.
00084  */
00085 
00086 
00087 extern int DSPSetHostName(char *newHost);
00088 /*
00089  * Set name of host on which to open the DSP.  
00090  * The default is NULL which means that of the local processor.
00091  * Currently, only one DSP can be open at a time.
00092  */
00093 
00094 extern char *DSPGetHostName(void);
00095 /*
00096  * Get name of host on which the DSP is being or will be used.
00097  * NULL means that of the local processor.
00098  * Use gethostname(2) to retrieve the local processor's host name.
00099  */
00100 
00101 extern int DSPSetCurrentDSP(int newidsp);
00102 /* 
00103  * Set DSP number.  Calls to functions in this file will act on that DSP.
00104  * Release 2.0 supports only one DSP: "DSP 0".
00105  */
00106 
00107 extern int DSPGetCurrentDSP(void);
00108 /* 
00109  * Returns currently selected DSP number.
00110  */
00111 
00112 /*************** Getting and setting "DSP instance variables" ****************/
00113 
00114 /*
00115  * DSP "get" functions do not follow the convention of returning an error code.
00116  * Instead (because there can be no error), they return the requested value.
00117  * Each functions in this class has a name beginning with "DSPGet".
00118  */
00119 
00120 
00121 extern int DSPGetMessagePriority(void);
00122 /*
00123  * Return DSP Mach message priority:
00124  *
00125  *       DSP_MSG_HIGH           0
00126  *       DSP_MSG_MED            1
00127  *       DSP_MSG_LOW            2
00128  *
00129  * Only medium and low priorities are used by user-initiated messages.
00130  * Normally, low priority should be used, and high priority messages
00131  * will bypass low priority messages enqueued in the driver.  Note,
00132  * however, that a multi-component message cannot be interrupted once it 
00133  * has begun.  The Music Kit uses low priority for all timed messages
00134  * and high priority for all untimed messages (so that untimed messages
00135  * may bypass any enqueued timed messages).
00136  *
00137  */
00138 
00139 
00140 extern int DSPSetMessagePriority(int pri);
00141 /*
00142  * Set DSP message priority for future messages sent to the kernel.
00143  * Can be called before or after DSP is opened.
00144  */
00145 
00146 /*********** Enable/Disable/Query for DSP open-state variables ************/
00147 
00148 /* 
00149  * In general, the enable/disable functions must be called BEFORE the DSP
00150  * is opened.  They have the effect of selecting various open
00151  * modes for the DSP.  The function which ultimately acts on them is
00152  * DSPOpenNoBoot() (which is called by the DSP init and boot functions).
00153  */
00154 
00155 
00156 extern int DSPGetOpenPriority(void);
00157 /*
00158  * Return DSP open priority.
00159  *      0 = low priority (default).
00160  *      1 = high priority (used by DSP debugger, for example)
00161  * If the open priority is high when DSPOpenNoBoot is called,
00162  * the open will proceed in spite of the DSP already being in use.
00163  * In this case, a new pointer to the DSP owner port is returned.
00164  * Typically, the task already in control of the DSP is frozen and
00165  * the newly opening task is a DSP debugger stepping in to look around.
00166  * Otherwise, the two tasks may confuse the DSP with interleaved commands.
00167  * Note that deallocating the owner port will give up ownership capability
00168  * for all owners.
00169  */
00170 
00171 
00172 extern int DSPSetOpenPriority(int pri);
00173 /*
00174  * Set DSP open priority.
00175  * The new priority has effect when DSPOpenNoBoot is next called.
00176  *      0 = low priority (default).
00177  *      1 = high priority (used by DSP debugger, for example)
00178  */
00179 
00180 
00181 extern int DSPEnableHostMsg(void);
00182 /* 
00183  * Enable DSP host message protocol.
00184  * This has the side effect that all unsolicited "DSP messages"
00185  * (writes from the DSP to the host) are split into two streams.
00186  * All 24-bit words from the DSP with the most significant bit set
00187  * are interpreted as error messages and split off to an error port.
00188  * On the host side, a thread is spawned which sits in msg_receive()
00189  * waiting for DSP error messages, and it forwards then to the DSP 
00190  * error log, if enabled.  Finally, the DSP can signal an abort by
00191  * setting both HF2 and HF3. In the driver, the protocol bits set by
00192  * enabling this mode are (cf. <sound/sounddriver.h>):
00193  * SND_DSP_PROTO_{DSPMSG|DSPERR|HFABORT|RAW}.
00194  */
00195 
00196 
00197 extern int DSPDisableHostMsg(void);
00198 /* 
00199  * Disable DSP host message protocol.
00200  * All writes from the DSP come in on the "DSP message" port.
00201  * The "DSP errors" port will remain silent.
00202  * This corresponds to setting the DSP protocol int to 0 in
00203  * the DSP driver.  (cf. snddriver_dsp_protocol().)
00204  */
00205 
00206 
00207 extern int DSPHostMsgIsEnabled(void);
00208 /* 
00209  * Return state of HostMsg enable flag.
00210  */
00211 
00212 
00213 /*********************** OPENING AND CLOSING THE DSP ***********************/
00214 
00215 
00216 extern int DSPOpenNoBootHighPriority(void);
00217 /*
00218  * Open the DSP at highest priority.
00219  * This will normally only be called by a debugger trying to obtain
00220  * ownership of the DSP when another task has ownership already.
00221  */ 
00222 
00223 
00224 extern int DSPOpenNoBoot(void);
00225 /*
00226  * Open the DSP in the state implied by the DSP state variables.
00227  * If the open is successful or DSP is already open, 0 is returned.
00228  * After DSPOpenNoBoot, the DSP is open in the reset state awaiting
00229  * a bootstrap program download.  Normally, only DSPBoot or a debugger
00230  * will ever call this routine.  More typically, DSPInit() is called 
00231  * to open and reboot the DSP.
00232  */
00233 
00234 
00235 extern int DSPIsOpen(void);
00236 /* 
00237  * Returns nonzero if the DSP is open.
00238  */
00239 
00240 extern int DSPClose(void);
00241 /*
00242  * Close the DSP device (if open). If sound-out DMA is in progress, 
00243  * it is first turned off which leaves the DSP in a better state.
00244  * Similarly, SSI sound-out from the DSP, if running, is halted.
00245  */
00246 
00247 
00248 extern int DSPCloseSaveState(void);
00249 /*
00250  * Same as DSPClose(), but retains all enabled features such that
00251  * a subsequent DSPBoot() or DSPOpenNoBoot() will come up in the same mode.
00252  * If sound-out DMA is in progress, it is first turned off.
00253  * If SSI sound-out is running, it is halted.
00254  */
00255 
00256 
00257 extern int DSPRawCloseSaveState(void);
00258 /*
00259  * Close the DSP device without trying to clean up things in the DSP,
00260  * and without clearing the open state (so that a subsequent open
00261  * will be with the same modes).
00262  * This function is normally only called by DSPCloseSaveState, but it is nice
00263  * to have interactively from gdb when the DSP is wedged.
00264  */
00265 
00266 
00267 extern int DSPRawClose(void);
00268 /*
00269  * Close the DSP device without trying to clean up things in the DSP.
00270  * This function is normally only called by DSPClose, but it is nice
00271  * to have interactively from gdb when the DSP is known to be hosed.
00272  */
00273 
00274 
00275 extern int DSPOpenWhoFile(void);
00276 /*
00277  * Open DSP "who file" (unless already open) and log PID and time of open.
00278  * This file is read to find out who has the DSP when an attempt to
00279  * access the DSP fails because another task has ownership of the DSP
00280  * device port.  The file is removed by DSPClose().  If a task is
00281  * killed before it can delete the who file, nothing bad will happen.
00282  * It will simply be overwritten by the next open.
00283  */
00284 
00285 
00286 extern int DSPCloseWhoFile(void);
00287 /*
00288  * Close and delete the DSP lock file.
00289  */
00290 
00291 
00292 char *DSPGetOwnerString(void);
00293 /*
00294  * Return string containing information about the current task owning
00295  * the DSP.  An example of the returned string is as follows:
00296  * 
00297  *      DSP opened in PID 351 by me on Sun Jun 18 17:50:46 1989
00298  *
00299  * The string is obtained from the file /tmp/dsp_lock and was written
00300  * when the DSP was initialized.  If the DSP is not in use, or if there
00301  * was a problem reading the lock file, NULL is returned.
00302  * The owner string is returned without a newline.
00303  */
00304 
00305 
00306 extern int DSPReset(void);
00307 /* 
00308  * Reset the DSP.
00309  * The DSP must be open.
00310  * On return, the DSP should be awaiting a 512-word bootstrap program.
00311  */
00312 
00313 
00314 /********************** READING/WRITING DSP HOST FLAGS ***********************/
00315 
00316 extern int DSPSetHF0(void);
00317 /*
00318  * Set bit HF0 in the DSP host interface.
00319  */
00320 
00321 
00322 extern int DSPClearHF0(void);
00323 /*
00324  * Clear bit HF0 in the DSP host interface.
00325  */
00326 
00327 
00328 extern int DSPGetHF0(void);
00329 /* 
00330  * Read state of HF0 flag of ICR in DSP host interface.
00331  */
00332 
00333 
00334 extern int DSPSetHF1(void);
00335 /*
00336  * Set bit HF1 in the DSP host interface.
00337  */
00338 
00339 
00340 extern int DSPClearHF1(void);
00341 /*
00342  * Clear bit HF1 in the DSP host interface.
00343  */
00344 
00345 
00346 extern int DSPGetHF1(void);
00347 /* 
00348  * Read state of HF1 flag of ICR in DSP host interface.
00349  */
00350 
00351 
00352 extern int DSPGetHF2(void);
00353 /*
00354  * Return nonzero if bit HF2 in the DSP host interface is set, otherwise FALSE.
00355  */
00356 
00357 
00358 extern int DSPGetHF3(void);
00359 /*
00360  * Return nonzero if bit HF3 in the DSP host interface is set, otherwise FALSE.
00361  */
00362 
00363 
00364 extern int DSPGetHF2AndHF3(void);
00365 /*
00366  * Return nonzero if bits HF2 and HF3 in the DSP host interface are set, 
00367  * otherwise FALSE.  A driver DSP protocol mode bit can be set such
00368  * that both bits indicate the DSP has aborted.
00369  */
00370 
00371 /****************** READING/WRITING HOST-INTERFACE REGISTERS *****************/
00372 
00373 
00374 extern int DSPReadRegs(unsigned int *regsP);
00375 /* 
00376  * Read DSP Interrupt Control Register (ICR), 
00377  * Command Vector Register (CVR),
00378  * Interrupt Status Register (ISR), and
00379  * Interrupt Vector Register (IVR),
00380  * in that order, concatenated to form
00381  * a single 32-bit word.
00382  */
00383 
00384 
00385 extern unsigned int DSPGetRegs(void);
00386 /*
00387  * Same as DSPReadRegs() but returns regs as function value.
00388  */
00389 
00390 
00391 extern int DSPWriteRegs(
00392     int mask,                   /* bit mask in (ICR,CVR,ISR,IVR) longword */
00393     int value);                 /* bit values in (ICR,CVR,ISR,IVR) longword */
00394 /*
00395  * Set DSP host-interface bits to given value.
00396  * Returns 0 for success, nonzero on error.
00397  * Example:
00398  *      DSPWriteRegs(DSP_ICR_HF0_REGS_MASK,DSP_ICR_HF0_REGS_MASK),
00399  * sets host flag 0 to 1 and 
00400  *      DSPWriteRegs(DSP_ICR_HF0_REGS_MASK,0));
00401  * clears it.
00402  */
00403 
00404 
00405 extern int DSPReadICR(int *icrP);               
00406 /* 
00407  * Read DSP Interrupt Control Register (ICR).
00408  * value returned in *icrP is 8 bits, right justified.
00409  */
00410 
00411 
00412 extern int DSPGetICR(void);
00413 /*
00414  * Return ICR register of the DSP host interface.
00415  */
00416 
00417 
00418 extern int DSPReadCVR(int *cvrP);
00419 /* 
00420  * Read DSP Command Vector Register (CVR).
00421  * value returned in *cvrP is 8 bits, right justified.
00422  */
00423 
00424 
00425 extern int DSPGetCVR(void);
00426 /*
00427  * Return CVR register of the DSP host interface.
00428  */
00429 
00430 
00431 extern int DSPHostCommand(int cmd);
00432 /*
00433  * Issue DSP "host command". The low-order 5 bits of cmd are sent.
00434  * There are 32 possible host commands, with 18 predefined by Motorola.
00435  * Others are used by the DSP driver for DMA control. See
00436  * <sound/sounddriver.h> for their definitions.
00437  */
00438 
00439 
00440 extern int DSPReadISR(int *isrP);
00441 /*
00442  * Read DSP Interrupt Status Register (ISR).
00443  * value returned in *isrP is 8 bits, right justified.
00444  */
00445 
00446 
00447 extern int DSPGetISR(void);
00448 /*
00449  * Return ISR register of the DSP host interface.
00450  */
00451 
00452 
00453 extern int DSPGetRX(void);
00454 /*
00455  * Return RX register of the DSP host interface.
00456  * Equivalent to "DSPReadRX(&tmp); return tmp;".
00457  */
00458 
00459 
00460 extern int DSPReadDataArrayMode(DSPFix24 *data, int nwords, int mode);
00461 /*
00462  * Read nwords words from DSP Receive Byte Registers (RX) in "DMA mode" mode.
00463  * The mode is DSP_MODE<n> where <n> = 8,16,24,32, (using the defines in 
00464  * <sound/sounddriver.h>) and the modes are described under the function
00465  * DSPReadArraySkipMode() (which requires the MK or AP DSP monitor).
00466  * RXDF must be true for each word before it is read.  
00467  * Note that it is an "error" for RXDF not to come true.  
00468  * Call DSPAwaitData(msTimeLimit) before calling
00469  * DSPReadRX() in order to await RXDF indefinitely.  
00470  * The default time-out used here may change in the future, and it is 
00471  * currently infinity.
00472  * This function is for simple non-DMA data reads from the DSP.
00473  * The only protocol used with the DSP is that HF1 is set during the read.
00474  */
00475 
00476 
00477 extern int DSPReadMessageArrayMode(DSPFix24 *data, int nwords, int mode);
00478 /*
00479  * Like DSPReadDataArrayMode() except for DSP messages.
00480  * Only useable in "host message protocol" mode, i.e., the driver takes
00481  * DSP interrupts and places words from the DSP into a "message buffer".
00482  * Return value is 0 for success, nonzero if an element could not be read
00483  * after trying for DSPDefaultTimeLimit seconds.
00484  * If the read could not finish, the number of elements successfully 
00485  * read + 1 is returned.
00486  * The mode specifies the data mode as in DSPReadDataArrayMode().
00487  */
00488 
00489 
00490 extern int DSPReadRXArrayMode(DSPFix24 *data, int nwords, int mode);
00491 /*
00492  * Equivalent to 
00493  *
00494  *      if (DSPHostMsgIsEnabled())
00495  *              return DSPReadMessageArrayMode();
00496  *       else 
00497  *              return DSPReadDataArrayMode();
00498  */
00499 
00500 
00501 extern int DSPAwaitRX(int msTimeLimit);
00502 /*
00503  * Equivalent to 
00504  *
00505  *      if (DSPHostMsgIsEnabled())
00506  *              return DSPAwaitMessages(msTimeLimit);
00507  *       else 
00508  *              return DSPAwaitData(msTimeLimit);
00509  */
00510 
00511 
00512 extern int DSPReadRXArray(DSPFix24 *data, int nwords);
00513 /*
00514  * Equivalent to DSPReadRXArrayMode(data,nwords,DSP_MODE32);
00515  * Each value is returned as 24 bits, right justified in 32.
00516  */
00517 
00518 
00519 extern int DSPReadRX(DSPFix24 *wordp);
00520 /*
00521  * Equivalent to DSPReadRXArrayMode(data,1,DSP_MODE32);
00522  * Value returned in *wordp is 24 bits, right justified.
00523  * after waiting DSPDefaultTimeLimit.  
00524  */
00525 
00526 
00527 extern int DSPWriteTX(DSPFix24 word);
00528 /*
00529  * Write word into DSP transmit byte registers.
00530  * Low-order 24 bits are written from word.
00531  */
00532 
00533 
00534 extern int DSPWriteTXArray(
00535     DSPFix24 *data,
00536     int nwords);
00537 /* 
00538  * Feed array to DSP transmit register.
00539  */
00540 
00541 
00542 extern int DSPWriteTXArrayB(
00543     DSPFix24 *data,
00544     int nwords);
00545 /*
00546  * Feed array *backwards* to DSP TX register 
00547  */
00548 
00549 
00550 /***************** READ/WRITE ARRAY FROM/TO DSP HOST INTERFACE ***************/
00551 
00552 /* 
00553         For DMA array transfers to/from DSP, use the "snddriver" functions.
00554         They are prototyped in <sound/sound_client.h>.
00555         See /NextDeveloper/Examples/DSP/SoundDSPDriver/* for examples of 
00556                 using them.
00557  */
00558 
00559 
00560 /*************************** DSP SYNCHRONIZATION ***************************/
00561 
00562 
00563 extern int DSPAwaitCondition(int mask, int value, int msTimeLimit);
00564 /*
00565  * Await specified condition in the DSP host interface.
00566  * The DSP registers ICR,CVR,ISR,IVR are concatenated to form a 32-bit word.
00567  * Call this word dspregs.  Then the awaited condition is
00568  *
00569  *  dspregs & mask == value
00570  *
00571  * If the condition is true by msTimeLimit (millisecond time-limit),
00572  * 0 is returned. Otherwise, DSP_ETIMEOUT is returned.  An msTimeLimit of 0
00573  * means wait forever.  Note that the time-out is only for the function 
00574  * call. The awaited condition is still pending in the DSP driver, and 
00575  * there is presently no way to cancel it or give it a time-out in the driver.
00576  * If the condition hangs, all DSP commands at the same or lower
00577  * Mach message priority will be blocked. Higher priority messages can
00578  * still get through.
00579  */
00580 
00581 
00582 extern int DSPResumeAwaitingCondition(int msTimeLimit);
00583 /*
00584  * If DSPAwaitCondition() returns nonzero, you can call this function to
00585  * resume waiting for a specified interval.  You should also call
00586  * DSPAwakenDriver() (see below) before calling this one to make sure
00587  * the driver rechecks the awaited condition in the DSP.  By doing this
00588  * in a loop at regular intervals you can set up a polling loop for the
00589  * awaited condition.   The polling is efficient if
00590  * msTimeLimit is reasonably large because during that time
00591  * the calling thread is sleeping in msg_receive().
00592  * Returns 0 if the condition comes true, nonzero if it times out.
00593  */
00594 
00595 
00596 extern int DSPAwaitConditionNoBlock(
00597     int mask,           /* mask to block on as bits in (ICR,CVR,ISR,IVR) */
00598     int value);         /* 1 or 0 as desired for each 1 mask bit */
00599 /*
00600  * Same as DSPAwaitCondition() except the function returns immediately.
00601  * The condition serves as a possible block for the DSP command queue
00602  * within the driver, but not for the calling program.
00603  */
00604 
00605 
00606 extern int DSPAwaitHC(int msTimeLimit);
00607 /*
00608  * Wait for "HC bit" to clear. 
00609  * The HC clears when the next instruction to be executed in the DSP
00610  * is the first word of the host command interrupt vector.
00611  * Equivalent to "DSPAwaitCondition(0x00800000,0x00000000,msTimeLimit);"
00612  */
00613 
00614 
00615 extern int DSPAwaitTRDY(int msTimeLimit);
00616 /*
00617  * Wait for "TRDY bit" to set. 
00618  * Equivalent to "DSPAwaitCondition(0x00040000,0x00040000,msTimeLimit);"
00619  */
00620 
00621 
00622 extern int DSPAwaitHF3Clear(int msTimeLimit);
00623 /*
00624  * Wait for HF3 = "MK TMQ full" or "AP Program Busy" bit to clear. 
00625  * Equivalent to "DSPAwaitCondition(0x00100000,0x00100000,msTimeLimit);"
00626  */
00627 
00628 
00629 extern int DSPAwaitHostMessage(int msTimeLimit);
00630 /*
00631  * Wait for currently executing host message to finish.
00632  */
00633 
00634 
00635 int DSPAwakenDriver(void);
00636 /* 
00637  * Send empty message to DSP at priority DSP_MSG_HIGH to wake up the driver. 
00638  * When the DSP driver is awaiting a condition, such as is done by
00639  * DSPAwaitCondition(), there no automatic polling that is done by the system.
00640  * Instead, it is up to the programmer to ensure that some event, such
00641  * as a Mach message to the Sound/DSP driver, a DMA-completion interrupt 
00642  * involving the DSP, or a DSP interrupt, will cause the driver to run and 
00643  * check the awaited condition.  See DSPResumeAwaitingCondition().
00644  */
00645 
00646 
00647 /******************************** DSP MESSAGES *******************************/
00648 
00649 /* 
00650  * Any unsolicited single word written by the DSP to the host (via RX) 
00651  * is defined as a "DSP Message".  This 24-bit message consist of a high-order
00652  * "opcode" byte, and two low-order "data" bytes. 
00653  *
00654  * If  "DSPEnableHostMsg()" is called before opening the DSP, 
00655  * "Host Message protocol" is used by the DSP driver.  
00656  * In this mode, RREQ is kept on in the DSP interface,
00657  * and each "DSP message" causes an interrupt in the host.  The DSP messages 
00658  * are buffered up by the driver.  When not using host message protocol,
00659  * RXDF is ignored, and only "data" is assumed to come from the DSP.
00660  * The data does not go into a driver buffer.  Instead, there are driver
00661  * calls to explicitly read data from the RX register.
00662  *
00663  * Note that "complex DMA mode" also
00664  * forces the driver to "listen" to the DSP.  In that case, if an 
00665  * unrecognized DSP message comes in (anything other than a DMA request)
00666  * the message goes to the DSP message buffer as in host message protocol
00667  * mode.
00668  */
00669 
00670 extern int DSPDataIsAvailable(void);
00671 /*
00672  * Return nonzero if RXDF is set.
00673  */
00674 
00675 
00676 extern int DSPAwaitData(int msTimeLimit);
00677 /*
00678  * Block until RXDF is set in the DSP host interface.
00679  * An msTimeLimit of zero means wait forever.
00680  * Returns 0 when data available, nonzero if
00681  * no data available before time-out.
00682  */
00683 
00684 extern int DSPMessageIsAvailable(void);
00685 /*
00686  * Return nonzero if DSP has one or more pending DSP messages waiting in the
00687  * DSP host interface.  
00688  * Only useable in host message protocol mode or to look for unrecognized
00689  * messages in complex DMA mode.
00690  */
00691 
00692 extern int DSPAwaitMessages(int msTimeLimit);
00693 /*
00694  * Block until DSPMessageIsAvailable() will return nonzero.
00695  * An msTimeLimit of zero means wait forever.
00696  * Returns 0 when a message is available, nonzero on time-out.
00697  * Only useable in host message protocol mode.
00698  */
00699 
00700 extern int DSPReadMessages(int msTimeLimit);
00701 /*
00702  * Read messages from DSP into internal buffers.
00703  * Returns 0 if DSP messages were read by msTimeLimit milliseconds.
00704  * A 0 msTimeLimit means DON'T WAIT if there are no messages waiting
00705  * from the DSP.  See DSPMessage.h for functions which process the messages.
00706  * Only useable in host message protocol mode or to look for unrecognized
00707  * messages in complex DMA mode.
00708  */
00709 
00710 extern int DSPMessageGet(int *msgp);
00711 /*
00712  * Return a single DSP message in *msgp, if one is waiting,
00713  * otherwise wait DSPDefaultTimeLimit for it (0 => wait forever). 
00714  * On time-out, returns the DSP error code DSP_ENOMSG.
00715  * The DSP message returned in *msgp is 24 bits, right justified.
00716  * Only called when a message is really expected.
00717  * Use DSPAwaitMessages(msTimeLimit) to obtain a precise time-limit.
00718  * Use DSPMessageIsAvailable() to determine if a message is waiting.
00719  */
00720 
00721 extern int DSPFlushMessages(void);
00722 /*
00723  * Flush any unread messages from the DSP.
00724  */
00725 
00726 extern int DSPFlushMessageBuffer(void);
00727 /*
00728  * Flush any DSP messages cached internally in libdsp.
00729  * Same as DSPFlushMessages() except that the DSP
00730  * is not checked for more messages.  Anything
00731  * queued up in the driver buffer will stay there.
00732  * Use DSPFlushMessages() to flush the driver's message queue.
00733  * Note: since there is no input-data buffer in the driver,
00734  * there is no DSPFlushDataBuffer() function.
00735  */
00736 
00737 
00738 /******************************* DSP Negotiation Port ************************/
00739 
00740 int DSPSetNegotiationPort(mach_port_t neg_port);
00741 /* 
00742  * Set port given to anyone attempting to open the DSP.
00743  */
00744 
00745 mach_port_t DSPGetNegotiationPort(void);
00746 /* 
00747  * Get port set by DSPSetNegotiationPort().
00748  */
00749 
00750 /******************************* Port fetching *******************************/
00751 
00752 /*
00753  * In all these routines for obtaining Mach ports,
00754  * the DSP must be opened before asking for the ports.
00755  */
00756 
00757 mach_port_t DSPGetOwnerPort(void);
00758 /* 
00759  * Get port conveying DSP and sound-out ownership capability.
00760  */
00761 
00762 
00763 mach_port_t DSPGetHostMessagePort(void);
00764 /* 
00765  * Get port used to send "host messages" to the DSP.
00766  * Also called the "command port" in other contexts.
00767  */
00768 
00769 
00770 mach_port_t DSPGetDSPMessagePort(void);
00771 /* 
00772  * Get port used to send "DSP messages" from the DSP to the host.
00773  * Messages on this port are enabled by DSPEnableHostMsg().
00774  */
00775 
00776 
00777 mach_port_t DSPGetErrorPort(void);
00778 /* 
00779  * Get port used to send "DSP error messages" from the DSP to the host.
00780  * Error messages on this port are enabled by DSPEnableHostMsg().
00781  */
00782 
00783 
00784 mach_port_t DSPMKGetSoundPort(void);
00785 /* 
00786  * Get sound device port.
00787  */
00788 
00789 
00790 mach_port_t DSPMKGetSoundOutStreamPort(void);
00791 /* 
00792  * Get stream port used to convey "sound out" buffers from the DSP
00793  * to the stereo DAC.
00794  */
00795 
00796 /************************ SIMULATOR FILE MANAGEMENT **************************/
00797 
00798 extern int DSPIsSimulated(void);
00799 /* 
00800  * Returns nonzero if the DSP is simulated.
00801  */
00802 
00803 
00804 extern int DSPIsSimulatedOnly(void);
00805 /* 
00806  * Returns nonzero if the DSP simulator output is open but the DSP device 
00807  * is not open.  This would happen if DSPOpenSimulatorFile() were called
00808  * without opening the DSP.
00809  */
00810 
00811 
00812 FILE *DSPGetSimulatorFP(void);
00813 /*
00814  * Returns file pointer used for the simulator output file, if any.
00815  */
00816 
00817 
00818 extern int DSPOpenSimulatorFile(char *fn);                      
00819 /* 
00820  * Open simulator output file fn.
00821  */
00822 
00823 
00824 extern int DSPStartSimulator(void);
00825 /*
00826  * Initiate simulation mode, copying DSP commumications to the simulator
00827  * file pointer.
00828  */
00829 
00830 
00831 extern int DSPStartSimulatorFP(FILE *fp);
00832 /*
00833  * Initiate simulation mode, copying DSP commumications to the file pointer fp.
00834  * If fp is NULL, the previously set fp, if any, will be used.
00835  */
00836 
00837 
00838 extern int DSPStopSimulator(void);
00839 /*
00840  * Clear simulation bit, halting DSP command output to the simulator file.
00841  */
00842 
00843 
00844 extern int DSPCloseSimulatorFile(void);
00845 /* 
00846  * Close simulator output file.
00847  */
00848 
00849 
00850 /*********************** DSP COMMANDS FILE MANAGEMENT ************************/
00851 
00852 /*
00853  * DSP commands are saved only for libdsp functions, not snddriver functions 
00854  * and not direct Mach messaging.
00855  */
00856 
00857 extern int DSPIsSavingCommands(void);
00858 /* 
00859  * Returns nonzero if a "DSP commands file" is open.
00860  */
00861 
00862 extern int DSPIsSavingCommandsOnly(void);
00863 /* 
00864  * Returns nonzero if the DSP commands file is open but the DSP device 
00865  * is not open.  This would happen if DSPOpenCommandsFile() were called
00866  * without opening the DSP.
00867  */
00868 
00869 extern int DSPOpenCommandsFile(const char *fn);
00870 /*
00871  * Opens a "DSP Commands file" which will receive all Mach messages
00872  * to the DSP.  The filename suffix should be ".snd".  This pseudo-
00873  * sound file can be played by the sound library.
00874  */
00875 
00876 /******************************* Miscellaneous *******************************/
00877 
00878 /******************************* Miscellaneous *******************************/
00879 
00880 int DSPGetProtocol(void);
00881 /*
00882  * Returns the DSP protocol int in effect.  Some of the relevant bits are
00883  *
00884  *   SNDDRIVER_DSP_PROTO_RAW     - disable all DSP interrupts
00885  *   SNDDRIVER_DSP_PROTO_DSPMSG  - enable DSP messages (via intrpt)
00886  *   SNDDRIVER_DSP_PROTO_DSPERR  - enable DSP error messages (hi bit on)
00887  *   SNDDRIVER_DSP_PROTO_C_DMA   - enable "complex DMA mode"
00888  *   SNDDRIVER_DSP_PROTO_HFABORT - recognize HF2&HF3 as "DSP aborted"
00889  *
00890  * See the snddriver function documentation for more information (e.g.
00891  * snddriver_dsp_protocol()).
00892  */
00893 
00894 int DSPSetProtocol(int newProto);
00895 /*
00896  * Sets the protocol used by the DSP driver.
00897  * This function logically calls snddriver_dsp_proto(), but it's faster
00898  * inside libdsp optimization blocks.  (As many Mach messages as possible are 
00899  * combined into a single message to maximize performance.)
00900  */
00901 
00902 extern int DSPSetComplexDMAModeBit(int bit);
00903 /*
00904  * Set or clear the bit "SNDDRIVER_DSP_PROTO_CDMA" in the DSP driver protocol.
00905  */
00906 
00907 extern int DSPSetHostMessageMode(void);
00908 /*
00909  * Set "Host Message" protocol.  This is the dynamic version of DSPEnableHostMsg()
00910  * followed by a form of DSPOpen().  It can be called after the DSP is already open.
00911  * Host message mode consists of the driver protocol flags 
00912  * SNDDRIVER_DSP_PROTO_{DSPMSG|DSPERR} in addition to the flags enabled by libdsp
00913  * when not in host message mode, which are SNDDRIVER_DSP_PROTO_{RAW|HFABORT}.
00914  */
00915 
00916 extern int DSPClearHostMessageMode(void);
00917 /*
00918  * Clear "Host Message" protocol.  This is the dynamic version of DSPDisableHostMsg()
00919  * followed by a form of DSPOpen().  It can be called after the DSP is already open.
00920  * Clearing host message mode means clearing the driver protocol flags 
00921  * SNDDRIVER_DSP_PROTO_{DSPMSG|DSPERR}.  The usual protocol bits
00922  * SNDDRIVER_DSP_PROTO_{RAW|HFABORT} are left on.  
00923  * 
00924  * Note that the "complex DMA mode bit " bit is not touched.  
00925  * If you have enabled the SNDDRIVER_DSP_PROTO_C_DMA protocol bit,
00926  * clearing host message mode will probably not do what you want (prevent the driver
00927  * from taking DSP interrupts and filling the message buffer with whatever the
00928  * DSP has to send).  In general, the driver is taking DSP interrupts whenever
00929  * SNDDRIVER_DSP_PROTO_RAW is off and when any of
00930  * SNDDRIVER_DSP_PROTO_{DSPMSG|DSPERR|C_DMA} are set.  
00931  * 
00932  * When the "RAW" mode bit is off, you can think of it as "release 1.0 mode", 
00933  * where you get DSPERR mode by default, even with no other protocol bits enabled.
00934  * Consult the snddriver function documentation for more details
00935  * of this complicated protocol business.  Yes, there's actually documentation.
00936  * ("Inside every mode, there is a simpler mode struggling to get out.")
00937  */
00938 
00939 extern int DSPCloseCommandsFile(DSPFix48 *endTimeStamp);
00940 /*
00941  * Closes a "DSP Commands file".  The endTimeStamp is used by the
00942  * sound library to terminate the DSP-sound playback thread.
00943  */
00944 
00945 extern int DSPGetMessageAtomicity(void);
00946 /*
00947  * Returns nonzero if libdsp Mach messages are atomic, zero otherwise.
00948  */
00949 
00950 extern int DSPSetMessageAtomicity(int atomicity);
00951 /*
00952  * If atomicity is nonzero, future libdsp Mach messages will be atomic.
00953  * Otherwise they will not be atomic.  If not atomic, DMA complete interrupts,
00954  * and DSP DMA requests, for example, can get in between message components,
00955  * unless they are at priority DSP_MSG_HIGH.
00956  * (DMA related messages queued by the driver in response to DSP or user
00957  * DMA initiation are at priority DSP_MSG_HIGH, while libdsp uses 
00958  * DSP_MSG_LOW for timed messages and DSP_MSG_MED for untimed messages to
00959  * the DSP.
00960  */
00961 
00962 extern int DSPCloseCommandsFile(DSPFix48 *endTimeStamp);
00963 /*
00964  * Closes a "DSP Commands file".  The endTimeStamp is used by the
00965  * sound library to terminate the DSP-sound playback thread.
00966  */
00967 
00968 extern int DSPGetMessageAtomicity(void);
00969 /*
00970  * Returns nonzero if libdsp Mach messages are atomic, zero otherwise.
00971  */
00972 
00973 extern int DSPSetMessageAtomicity(int atomicity);
00974 /*
00975  * If atomicity is nonzero, future libdsp Mach messages will be atomic.
00976  * Otherwise they will not be atomic.  If not atomic, DMA complete interrupts,
00977  * and DSP DMA requests, for example, can get in between message components,
00978  * unless they are at priority DSP_MSG_HIGH.
00979  * (DMA related messages queued by the driver in response to DSP or user
00980  * DMA initiation are at priority DSP_MSG_HIGH, while libdsp uses 
00981  * DSP_MSG_LOW for timed messages and DSP_MSG_MED for untimed messages to
00982  * the DSP.
00983  */
00984 
00985 /******************************  DSP Symbols *********************************/
00986 
00987 /*
00988  * DSP symbols are produced by asm56000, the DSP56000/1 assembler.
00989  * They are written into either a .lnk or .lod file, depending on 
00990  * whether the assembly was "relative" or "absolute", respectively.
00991  * When DSPReadFile() reads one of these files (ASCII), or their .dsp file
00992  * counterparts (binary), all symbols are loaded as well into the
00993  * structs described in /usr/include/dsp/dsp_structs.h.  The functions
00994  * below support finding these symbols and their values.  Because the
00995  * assembler does not fully support mixed case, all symbol names are 
00996  * converted to upper case when read in, and any name to be searched for
00997  * in the symbol table is converted to upper case before the search.
00998  */
00999 
01000 
01001 extern int DSPSymbolIsFloat(DSPSymbol *sym);
01002 /* 
01003  * Returns TRUE if the DSP assembler symbol is type 'F'.
01004  */
01005 
01006 
01007 extern DSPSymbol *DSPGetSectionSymbol(char *name, DSPSection *sec);
01008 /*
01009  * Find symbol within the given DSPSection with the given name. 
01010  * See "/LocalDeveloper/Headers/dsp/dsp_structs.h" for the definition of a 
01011  * DSPSection. Equivalent to trying DSPGetSectionSymbolInLC() for each of 
01012  * the 12 DSP location counters.
01013  */
01014 
01015 
01016 extern DSPSymbol *DSPGetSectionSymbolInLC(char *name, DSPSection *sec, 
01017                                    DSPLocationCounter lc);
01018 /*
01019  * Find symbol within the given DSPSection and location counter
01020  * with the given name.  See "/LocalDeveloper/Headers/dsp/dsp_structs.h" 
01021  * for an lc list.
01022  */
01023 
01024 
01025 extern int DSPReadSectionSymbolAddress(DSPMemorySpace *spacep,
01026                                        DSPAddress *addressp,
01027                                        char *name,
01028                                        DSPSection *sec);
01029 /*
01030  * Returns the space and address of symbol with the given name in the 
01031  * given DSP section.  Note that there is no "Get" version because
01032  * both space and address need to be returned.
01033  */
01034 
01035 extern int DSPGetSystemSymbolValue(char *name);
01036 /*
01037  * Returns the value of the symbol "name" in the DSP system image, or -1 if
01038  * the symbol is not found or the DSP is not opened.  
01039  *
01040  * The "system image" is that of the currently loaded monitor in the currently
01041  * selected DSP.  The current DSP must be open so for this monitor image to
01042  * be available.
01043  * 
01044  * The requested symbol
01045  * is assumed to be type "I" and residing in the GLOBAL section under location
01046  * counter "DSP_LC_N" (i.e., no memory space is associated with the symbol).
01047  * No fixups are performed, i.e., the symbol is assumed to belong to an 
01048  * absolute (non-relocatable) section.  
01049  * See /usr/local/lib/dsp/monitor/apmon_8k.lod and mkmon_8k.lod for example 
01050  * system files which compatibly define system symbols.
01051  *
01052  * Equivalent to
01053  *  DSPGetSectionSymbol(name,DSPGetUserSection(DSPGetSystemImage()));
01054  * (because the DSP system is assembled in absolute mode, and there
01055  * is only one section, the global section, for absolute assemblies).
01056  */
01057 
01058 extern int DSPGetSystemSymbolValueInLC(char *name, DSPLocationCounter lc);
01059 /*
01060  * Same as DSPGetSystemSymbolValue() except faster because the location 
01061  * counter is known, and the rest are not searched.
01062  */
01063 
01064 int DSPReadSystemSymbolAddress(DSPMemorySpace *spacep, DSPAddress *addressp,
01065                                char *name);
01066 /*
01067  * Same as DSPReadSectionSymbolAddress() except it knows to look in the
01068  * system section (GLOBAL).
01069  */
01070 
01071 #endif