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