MusicKit  0.0.0
DSPObject.h
00001 #ifndef __MK_DSPObject_H___
00002 #define __MK_DSPObject_H___
00003 /* $Id$
00004  * Low level DSP access and control functions.
00005  * Copyright 1988-1992, NeXT Inc.  All rights reserved.
00006  * Author: Julius O. Smith III
00007  *
00008  * Intel and QuintProcessor support copyright CCRMA, Stanford University, 
00009  * 1992. Added by David Jaffe
00010  */
00011 
00012 /*
00013  * This file is organized logically with respect to the DSPOpen*()
00014  * routines in that functions apearing before the open routines must be
00015  * called before the DSP is opened (or any time), and functions apearing 
00016  * after the open routines must be (or are typically) called after the 
00017  * DSP is opened.
00018  *
00019  * The functions which depend on the Music Kit DSP monitor have the
00020  * prefix "DSPMK".  The prefix "DSP" may either be independent of the
00021  * monitor used, or require the array processing monitor.  Generally,
00022  * functions with prefix "DSP are monitor-independent unless they involve
00023  * input/output to or from private DSP memory, i.e., unless they require
00024  * services of a DSP monitor to carry out their function.
00025  * To upgrade your own DSP monitor to support these DSP functions, lift
00026  * out the I/O support in the array processing monitor.  The sources are
00027  * distributed online in /usr/local/lib/dsp/smsrc (system monitor source).
00028  */
00029 
00030 #import <stdio.h>
00031 #import "dsp_types.h"
00032 #import "dsp_structs.h"
00033 
00034 extern int DSPGetHostTime(void);
00035 /*
00036  * Returns the time in microseconds since it was last called.
00037  */
00038 
00039 
00040 /*********** Utilities global with respect to all DSP instances **************/
00041 
00042 /* WARNING: The following must be kept in synch with dspdriverAccess.h */
00043 #ifndef DSP_MAXDSPS
00044 #define DSP_MAXDSPS 32 /* DSP31 is the highest */
00045 #define DSPDRIVER_PAR_MONITOR "Monitor"
00046 #define DSPDRIVER_PAR_MONITOR_4_2 "Monitor_4_2"
00047 #define DSPDRIVER_PAR_SERIALPORTDEVICE "SerialPortDevice"
00048 #define DSPDRIVER_PAR_ORCHESTRA "Orchestra"
00049 #define DSPDRIVER_PAR_WAITSTATES "WaitStates"
00050 #define DSPDRIVER_PAR_SUBUNITS "SubUnits"
00051 #define DSPDRIVER_PAR_CLOCKRATE "ClockRate"
00052 #endif
00053 /* End of "Warning" section */
00054 
00055 /********** Intel utilities ***************************/
00056 char *DSPGetDriverParameter(const char *parameterName);
00057 /* Returns the specified driver parameter of the current DSP.  
00058    This value can be overridden by the user's defaults data base.
00059    The returned value is an NXAtom and should not be freed. 
00060  */
00061 
00062 int DSPGetDriverCount(void);
00063 /* Returns the total number of DSP drivers that have been installed/added to 
00064  * the system.  This is the size of the arrays returned by DSPGetDriverNames()
00065  * and DSPGetDriverUnits().
00066  */
00067 
00068 char **DSPGetDriverNames(void);
00069 int *DSPGetDriverUnits(void);
00070 int *DSPGetDriverSubUnits(void);
00071 unsigned long *DSPGetDriverSUVects(void);
00072 /* Return the names and units of all the DSP drivers. The size of these arrays
00073  * is DSPGetDriverCount(). */
00074 
00075 char **DSPGetInUseDriverNames(void);
00076 int *DSPGetInUseDriverUnits(void);
00077 int *DSPGetInUseDriverSubUnits(void);
00078 /* Return the names and units of the drivers in use.  The size of these arrays
00079  * is DSP_MAXDSPS
00080  */
00081 /********** end of Intel utilities ***************************/
00082 
00083 
00084 extern int DSPGetDSPCount(void);
00085 /* 
00086  * Returns the number of actual DSPs on NeXT hardware systems.
00087  * On all other architectures, returns the value DSP_MAXDSPS,
00088  * which is the maximum possible number of DSPs.
00089  */
00090 
00091 extern int DSPSetHostName(char *newHost);
00092 /*
00093  * Set name of host on which to open the DSP.  
00094  * The default is NULL which means that of the local processor.
00095  * Currently, only one DSP can be open at a time.
00096  */
00097 
00098 extern char *DSPGetHostName(void);
00099 /*
00100  * Get name of host on which the DSP is being or will be used.
00101  * NULL means that of the local processor.
00102  * Use gethostname(2) to retrieve the local processor's host name.
00103  */
00104 
00105 extern int DSPSetCurrentDSP(int newidsp);
00106 /* 
00107  * Set DSP number.  Calls to functions in this file will act on that DSP.
00108  */
00109 
00110 extern int DSPGetCurrentDSP(void);
00111 /* 
00112  * Returns currently selected DSP number.
00113  */
00114 
00115 /*************** Getting and setting "DSP instance variables" ****************/
00116 
00117 /*
00118  * DSP "get" functions do not follow the convention of returning an error code.
00119  * Instead (because there can be no error), they return the requested value.
00120  * Each functions in this class has a name beginning with "DSPGet".
00121  */
00122 
00123 
00124 extern int DSPGetMessagePriority(void);
00125 /*
00126  * Return DSP Mach message priority:
00127  *
00128  *       DSP_MSG_HIGH           0
00129  *       DSP_MSG_MED            1
00130  *       DSP_MSG_LOW            2
00131  *
00132  * Only medium and low priorities are used by user-initiated messages.
00133  * Normally, low priority should be used, and high priority messages
00134  * will bypass low priority messages enqueued in the driver.  Note,
00135  * however, that a multi-component message cannot be interrupted once it 
00136  * has begun.  The Music Kit uses low priority for all timed messages
00137  * and high priority for all untimed messages (so that untimed messages
00138  * may bypass any enqueued timed messages).
00139  *
00140  */
00141 
00142 
00143 extern int DSPSetMessagePriority(int pri);
00144 /*
00145  * Set DSP message priority for future messages sent to the kernel.
00146  * Can be called before or after DSP is opened.
00147  */
00148 
00149 
00150 extern double DSPMKGetSamplingRate(void);
00151 /*
00152  * Returns sampling rate assumed by DSP software in Hz.
00153  */
00154 
00155 
00156 extern int DSPMKSetSamplingRate(double srate);
00157 /*
00158  * Set sampling rate assumed by DSP software to rate in samples per
00159  * second (Hz).  Note that only sampling rates 22050.0 and 44100.0 
00160  * are supported for real time digital audio output.  Use of other sampling
00161  * rates implies non-real-time processing or sound-out through the DSP serial
00162  * port to external hardware.
00163  */
00164 
00165 
00166 extern int DSPEnableMachMessageOptimization(void);
00167 extern int DSPDisableMachMessageOptimization(void);
00168 /*
00169  * By default, optimization is enabled.  In this mode, as many Mach
00170  * message components as possible are combined into a single, multicomponent
00171  * message.  This minimizes context-switching between the application and
00172  * the kernel.  The ability to turn it off exists solely to provide a 
00173  * workaround in the event a bug turns up in it.  We know there is a problem
00174  * with non-dma 16-bit and 8-bit data messages which are not at the beginning
00175  * of the message, and in these cases optimization is always disabled.
00176  */
00177 
00178 
00179 /*********** Enable/Disable/Query for DSP open-state variables ************/
00180 
00181 /* 
00182  * In general, the enable/disable functions must be called BEFORE the DSP
00183  * is "opened" via DSPInit(), DSPAPInit(), DSPMKInit(), DSPBoot(), or one of
00184  * the DSPOpen*() functions.  They have the effect of selecting various open
00185  * modes for the DSP.  The function which ultimately acts on them is
00186  * DSPOpenNoBoot() (which is called by the Init and Boot functions above).
00187  */
00188 
00189 
00190 extern int DSPGetOpenPriority(void);
00191 /*
00192  * Return DSP open priority.
00193  *      0 = low priority (default).
00194  *      1 = high priority (used by DSP debugger, for example)
00195  * If the open priority is high when DSPOpenNoBoot is called,
00196  * the open will proceed in spite of the DSP already being in use.
00197  * In this case, a new pointer to the DSP owner port is returned.
00198  * Typically, the task already in control of the DSP is frozen and
00199  * the newly opening task is a DSP debugger stepping in to look around.
00200  * Otherwise, the two tasks may confuse the DSP with interleaved commands.
00201  * Note that deallocating the owner port will give up ownership capability
00202  * for all owners.
00203  */
00204 
00205 
00206 extern int DSPSetOpenPriority(int pri);
00207 /*
00208  * Set DSP open priority.
00209  * The new priority has effect when DSPOpenNoBoot is next called.
00210  *      0 = low priority (default).
00211  *      1 = high priority (used by DSP debugger, for example)
00212  */
00213 
00214 
00215 extern int DSPGetMessageAtomicity(void);
00216 /*
00217  * Returns nonzero if libdsp Mach messages are atomic, zero otherwise.
00218  */
00219 
00220 
00221 extern int DSPSetMessageAtomicity(int atomicity);
00222 /*
00223  * If atomicity is nonzero, future libdsp Mach messages will be atomic.
00224  * Otherwise they will not be atomic.  If not atomic, DMA complete interrupts,
00225  * and DSP DMA requests, for example, can get in between message components,
00226  * unless they are at priority DSP_MSG_HIGH.
00227  * (DMA related messages queued by the driver in response to DSP or user
00228  * DMA initiation are at priority DSP_MSG_HIGH, while libdsp uses 
00229  * DSP_MSG_LOW for timed messages and DSP_MSG_MED for untimed messages to
00230  * the DSP.
00231  */
00232 
00233 
00234 int DSPEnableHostMsg(void);
00235 /* 
00236  * Enable DSP host message protocol.
00237  * This has the side effect that all unsolicited "DSP messages"
00238  * (writes from the DSP to the host) are split into two streams.
00239  * All 24-bit words from the DSP with the most significant bit set
00240  * are interpreted as error messages and split off to an error port.
00241  * On the host side, a thread is spawned which sits in msg_receive()
00242  * waiting for DSP error messages, and it forwards then to the DSP 
00243  * error log, if enabled.  Finally, the DSP can signal an abort by
00244  * setting both HF2 and HF3. In the driver, the protocol bits set by
00245  * enabling this mode are (cf. <sound/sounddriver.h>):
00246  * SND_DSP_PROTO_{DSPMSG|DSPERR|HFABORT|RAW}.
00247  */
00248 
00249 
00250 int DSPDisableHostMsg(void);
00251 /* 
00252  * Disable DSP host message protocol.
00253  * All writes from the DSP come in on the "DSP message" port.
00254  * The "DSP errors" port will remain silent.
00255  * This corresponds to setting the DSP protocol int to 0 in
00256  * the DSP driver.  (cf. snddriver_dsp_protocol().)
00257  */
00258 
00259 
00260 extern int DSPHostMsgIsEnabled(void);
00261 /* 
00262  * Return state of HostMsg enable flag.
00263  */
00264 
00265 
00266 extern int DSPMKIsWithSoundOut(void);
00267 /* 
00268  * Returns nonzero if the DSP is linked to sound out.
00269  */
00270 
00271 
00272 extern int DSPMKEnableSoundOut(void);
00273 /* 
00274  * Enable DSP linkage to sound out.
00275  * When DSP is next opened, it will be linked to sound out.
00276  */
00277 
00278 
00279 extern int DSPMKDisableSoundOut(void);
00280 /* 
00281  * Disable DSP linkage to sound out.
00282  * When DSP is next opened, it will not be linked to sound out.
00283  */
00284 
00285 
00286 extern int DSPMKSoundOutIsEnabled(void);
00287 /* 
00288  * Return state of SoundOut enable flag.
00289  */
00290 
00291 
00292 /* Sound out to the serial port */
00293 
00294 extern int DSPMKEnableSSISoundOut(void);
00295 /* 
00296  * Enable DSP serial port sound out.
00297  * When DSP is next opened with a Music Kit DSP system, it will be 
00298  * configured to have SSI sound out. 
00299  */
00300 
00301 
00302 extern int DSPMKDisableSSISoundOut(void);
00303 /* 
00304  * Disable DSP serial port sound out.
00305  * When DSP is next opened with a Music Kit DSP system, the SSI
00306  * port of the DSP will not be used.
00307  */
00308 
00309 
00310 extern int DSPMKSSISoundOutIsEnabled(void);
00311 /* 
00312  * Return state of serial port SoundOut enable flag.
00313  */
00314 
00315 
00316 extern int DSPMKStartSSISoundOut(void);
00317 /*
00318  * Tell DSP to send sound-out data to the SSI serial port in the DSP.
00319  * The DSP will block until the SSI port has read the current sound-out
00320  * buffer.  SSI sound-out to the SSI can not occur simultaneously with 
00321  * sound-out to the host.
00322  */
00323 
00324 
00325 extern int DSPMKStopSSISoundOut(void);
00326 /*
00327  * Tell DSP not to send sound-out data to the SSI serial port.
00328  */
00329 
00330 
00331 /* Sound in from the serial port */
00332 
00333 extern int DSPMKEnableSSIReadData(void);
00334 /* 
00335  * Enable DSP serial port sound in.
00336  * When DSP is next opened with a Music Kit DSP system, it will be 
00337  * configured to have SSI sound in.
00338  */
00339 
00340 
00341 extern int DSPMKDisableSSIReadData(void);
00342 /* 
00343  * Disable DSP serial port sound in.
00344  * When DSP is next opened with a Music Kit DSP system, the SSI
00345  * port of the DSP will not be used.
00346  */
00347 
00348 
00349 extern int DSPMKSSIReadDataIsEnabled(void);
00350 /* 
00351  * Return state of serial port ReadData enable flag.
00352  */
00353 
00354 
00355 extern int DSPMKStartSSIReadData(void);
00356 /*
00357  * Tell DSP to read sound-in data from the SSI serial port in the DSP.
00358  * The DSP will block until the SSI port has written the current sound-in
00359  * buffer.  Sound-in from the SSI can occur simultaneously with SSI sound-out
00360  */
00361 
00362 
00363 extern int DSPMKStopSSIReadData(void);
00364 /*
00365  * Tell DSP not to take sound-in data from the SSI serial port.
00366  */
00367 
00368 
00369 extern int DSPMKEnableSmallBuffers(void);
00370 /* 
00371  * Enable use of small buffers for DSP sound-out.
00372  * This is something worth doing when real-time response
00373  * is desired.  Normally, the sound-out driver uses
00374  * four 8K byte buffers.  With small buffers enabled,
00375  * four 1K byte buffers are used.
00376  */
00377 
00378 
00379 extern int DSPMKDisableSmallBuffers(void);
00380 /* 
00381  * Disable use of small buffers for DSP sound-out.
00382  */
00383 
00384 
00385 extern int DSPMKSmallBuffersIsEnabled(void);
00386 /* 
00387  * Return true if small sound-out buffers are enabled.
00388  */
00389 
00390 
00391 extern int DSPMKEnableTMFlush(void);
00392 /* 
00393  * Enable flushing timed messages every message.
00394  * This is for debugging so it is easy to see each message go by.
00395  * It also can be tried if a bug is suspected in the timed message
00396  * optimization.
00397  */
00398 
00399 
00400 extern int DSPMKDisableTMFlush(void);
00401 /* 
00402  * Disable auto-flushing timed messages.
00403  */
00404 
00405 
00406 extern int DSPMKTMFlushIsEnabled(void);
00407 /* 
00408  * Return true if auto-flushing timed messages is enabled.
00409  */
00410 
00411 extern int DSPSetTimedZeroNoFlush(int yesOrNo);
00412 
00413 extern int DSPMKEnableBlockingOnTMQEmptyTimed(DSPFix48 *aTimeStampP);
00414 /* 
00415  * Tell the DSP to block when the Timed Message Queue is empty.
00416  * This prevents the possibility of late score information.
00417  * It is necessary to call DSPMKDisableBlockingOnTMQEmptyTimed()
00418  * after the last time message is sent to the DSP to enable the 
00419  * computing of all sound after the time of the last message.
00420  */
00421 
00422 
00423 extern int DSPMKDisableBlockingOnTMQEmptyTimed(DSPFix48 *aTimeStampP);
00424 /* 
00425  * Tell the DSP to NOT block when the Timed Message Queue is empty.
00426  */
00427 
00428 /****************** Getting and setting DSP system files *********************/
00429 
00430 /*
00431  * Get/set various DSP system file names.
00432  * The default filenames are defined in dsp.h.
00433  * The "get" versions return an absolute path.
00434  * The "set" versions take a relative path.
00435  * The environment variable $DSP must be overwritten appropriately
00436  * before a "get" version will return what the "set" version set.
00437  * Or, one could place custom system files in the $DSP directory.
00438  */
00439 
00440 
00441 /* Misc. routines for getting various directories. */
00442 const char *DSPGetDSPDirectory(void);    /* DSP_SYSTEM_DIRECTORY or $DSP if set */
00443 char *DSPGetSystemDirectory(void); /* <DSPDirectory>/monitor */
00444 char *DSPGetAPDirectory(void);     /* <DSPDirectory>/DSP_AP_BIN_DIRECTORY */
00445 
00446 extern int DSPSetSystem(DSPLoadSpec *system);
00447 /* 
00448  * Set the DSP system image (called by DSPBoot.c) 
00449  * If the system name begins with "MKMON" or "APMON",
00450  * all system filenames (binary, link, and map) are set accordingly.
00451  */
00452 
00453 
00454 char *DSPGetSystemBinaryFile(void);
00455 /* 
00456  * Get system binary filename.
00457  * Used by DSPBoot.c.
00458  */
00459 
00460 
00461 char *DSPGetSystemLinkFile(void);
00462 /* 
00463  * Get system linkfile name.
00464  * Used by _DSPMakeMusicIncludeFiles.c.
00465  */
00466 
00467 
00468 char *DSPGetSystemMapFile(void);
00469 /* 
00470  * Get system linkfile name.
00471  * Used by _DSPRelocateUser.c.
00472  */
00473 
00474 
00475 extern int DSPMonitorIsMK(void);
00476 /*
00477  * Returns true if the currently set DSP system is of the
00478  * for "mkmon*.dsp", otherwise false.
00479  */
00480 
00481 
00482 extern int DSPSetMKSystemFiles(void);
00483 /*
00484  * Set the system binary, link, and map files to the MK world.
00485  */
00486 
00487 
00488 extern int DSPMonitorIsAP(void);
00489 /*
00490  * Returns true if the currently set DSP system is of the
00491  * form "apmon*.dsp", otherwise false.
00492  */
00493 
00494 
00495 extern int DSPSetAPSystemFiles(void);
00496 /*
00497  * Set the system binary, link, and map files to the AP world.
00498  */
00499 
00500 
00501 /***************************** WriteData Setup *******************************/
00502 
00503 /*
00504  * "Write data" is DSP sound data which is being recorded to disk.
00505  */
00506 
00507 
00508 extern int DSPMKSetWriteDataFile(const char *fn);
00509 /* 
00510  * Set the file-name for DSP write-data to fn.
00511  */
00512 
00513 
00514 char *DSPMKGetWriteDataFile(void);
00515 /* 
00516  * Read the file-name being used for DSP write-data.
00517  */
00518 
00519 
00520 extern int DSPMKEnableWriteData(void);
00521 /* 
00522  * Enable DSP write data.
00523  * When DSP is next opened, stream ports will be set up between the
00524  * DSP, host, and sound-out such that write-data can be used.
00525  * 
00526  * After opening the DSP with DSPMKInit(), call DSPMKStartWriteDataTimed() 
00527  * (described below) to spawn the thread which reads DSP data to disk.
00528  *
00529  *  Bug: Audible sound-out is disabled during write data.
00530  */
00531 
00532 
00533 extern int DSPMKDisableWriteData(void);
00534 /* 
00535  * Disable DSP write data (default).
00536  */
00537 
00538 
00539 extern int DSPMKWriteDataIsEnabled(void);
00540 /* 
00541  * Return state of DSP write-data enable flag.
00542  */
00543 
00544 
00545 extern int DSPMKWriteDataIsRunning(void);
00546 /* 
00547  * Return nonzero if DSP write data thread is still running.
00548  */
00549 
00550 
00551 /* 
00552  * The write-data time-out is the number of milliseconds to wait in 
00553  * msg_receive() for a write-data sound buffer from the DSP.
00554  * On time-out, it is assumed that the DSP is not sending any more
00555  * write-data, and the thread reading write data terminates.
00556  */
00557 
00558 
00559 extern int DSPMKGetWriteDataTimeOut(void);
00560 /* 
00561  * Get number of milliseconds to wait in msg_receive() for a sound buffer
00562  * from the DSP before giving up.
00563  */
00564 
00565 
00566 extern int DSPMKSetWriteDataTimeOut(int to);
00567 /* 
00568  * Set number of milliseconds to wait in msg_receive() for a sound buffer
00569  * from the DSP before giving up.  The default is 60 seconds.  It must be
00570  * made larger if the DSP program might take longer than this to compute
00571  * a single buffer of data, and it can be set shorter to enable faster
00572  * detection of a hung DSP program.
00573  */
00574 
00575 
00576 typedef void (*DSPMKWriteDataUserFunc)
00577     (short *data,unsigned int dataCount,int dspNum);
00578 
00579 extern int DSPMKSetUserWriteDataFunc(DSPMKWriteDataUserFunc userFunc);
00580 /* Set user function to be called on each write data buffer.  Args to userFunc
00581    are the data buffer, the number of words in that buffer, the actual 
00582    vm size of that buffer (for vm_deallocate), and the dsp number.
00583    The caller should not deallocate the buffer, that's done automatically
00584    immediately following the call to the user func.  The user func is
00585    called in the write data thread.  If the data is to be passed to the
00586    Music Kit or application thread, it may be passed as out-of-line data
00587    in a Mach message.  In this case, the receiving thread *should* call
00588    vm_deallocate(), using vmCount as the size.
00589 */
00590 
00591 extern int DSPMKSoundOutDMASize(void);
00592 /*
00593  * Returns the size of single DMA transfer used for DSP sound-out
00594  * 16-bit words.  This may change at run time depending on whether
00595  * read-data is used or if a smaller buffer size is requested.
00596  */
00597 
00598 
00599 extern int DSPMKClearDSPSoundOutBufferTimed(DSPTimeStamp *aTimeStamp);
00600 /*
00601  * Clears the DSP's sound-out buffer.  Normally, this is unnecessary
00602  * because the DSP orchestra puts out zeros by default.
00603  */
00604 
00605 /***************************** ReadData Setup *******************************/
00606 
00607 /*
00608  * "Read data" is DSP sound data (stereo or mono) which is being read from 
00609  * disk and sent to a Music Kit Orchestra running on the DSP.
00610  */
00611 
00612 
00613 extern int DSPMKEnableReadData(void);
00614 /* 
00615  * Enable DSP read data.
00616  * When the DSP is next opened, a read-data stream to the DSP will be opened.
00617  */
00618 
00619 
00620 extern int DSPMKDisableReadData(void);
00621 /* 
00622  * Disable DSP read data (default).
00623  */
00624 
00625 
00626 extern int DSPMKReadDataIsEnabled(void);
00627 /* 
00628  * Return state of DSP read-data enable flag.
00629  */
00630 
00631 
00632 extern int DSPMKSetReadDataFile(const char *fn);
00633 /* 
00634  * Set the read-data file-name to fn.
00635  */
00636 
00637 
00638 /*********************** OPENING AND CLOSING THE DSP ***********************/
00639 
00640 extern int DSPOpenNoBootHighPriority(void);
00641 /*
00642  * Open the DSP at highest priority.
00643  * This will normally only be called by a debugger trying to obtain
00644  * ownership of the DSP when another task has ownership already.
00645  */ 
00646 
00647 
00648 extern int DSPOpenNoBoot(void);
00649 /*
00650  * Open the DSP in the state implied by the DSP state variables.
00651  * If the open is successful or DSP is already open, 0 is returned.
00652  * After DSPOpenNoBoot, the DSP is open in the reset state awaiting
00653  * a bootstrap program download.  Normally, only DSPBoot or a debugger
00654  * will ever call this routine.  More typically, DSPInit() is called 
00655  * to open and reboot the DSP.
00656  */
00657 
00658 
00659 extern int DSPIsOpen(void);
00660 /* 
00661  * Returns nonzero if the DSP is open.
00662  */
00663 
00664 
00665 DSPLoadSpec *DSPGetSystemImage(void);
00666 /* 
00667  * Get pointer to struct containing DSP load image installed by DSPBoot().
00668  * If no system has been loaded, NULL is returned.
00669  */
00670 
00671 
00672 extern int DSPClose(void);
00673 /*
00674  * Close the DSP device (if open). If sound-out DMA is in progress, 
00675  * it is first turned off which leaves the DSP in a better state.
00676  * Similarly, SSI sound-out from the DSP, if running, is halted.
00677  */
00678 
00679 
00680 extern int DSPCloseSaveState(void);
00681 /*
00682  * Same as DSPClose(), but retains all enabled features such that
00683  * a subsequent DSPBoot() or DSPOpenNoBoot() will come up in the same mode.
00684  * If sound-out DMA is in progress, it is first turned off.
00685  * If SSI sound-out is running, it is halted.
00686  */
00687 
00688 
00689 extern int DSPRawCloseSaveState(void);
00690 /*
00691  * Close the DSP device without trying to clean up things in the DSP,
00692  * and without clearing the open state (so that a subsequent open
00693  * will be with the same modes).
00694  * This function is normally only called by DSPCloseSaveState, but it is nice
00695  * to have interactively from gdb when the DSP is wedged.
00696  */
00697 
00698 
00699 extern int DSPRawClose(void);
00700 /*
00701  * Close the DSP device without trying to clean up things in the DSP.
00702  * This function is normally only called by DSPClose, but it is nice
00703  * to have interactively from gdb when the DSP is known to be hosed.
00704  */
00705 
00706 
00707 extern int DSPOpenWhoFile(void);
00708 /*
00709  * Open DSP "who file" (unless already open) and log PID and time of open.
00710  * This file is read to find out who has the DSP when an attempt to
00711  * access the DSP fails because another task has ownership of the DSP
00712  * device port.  The file is removed by DSPClose().  If a task is
00713  * killed before it can delete the who file, nothing bad will happen.
00714  * It will simply be overwritten by the next open.
00715  */
00716 
00717 
00718 extern int DSPCloseWhoFile(void);
00719 /*
00720  * Close and delete the DSP lock file.
00721  */
00722 
00723 
00724 char *DSPGetOwnerString(void);
00725 /*
00726  * Return string containing information about the current task owning
00727  * the DSP.  An example of the returned string is as follows:
00728  * 
00729  *      DSP opened in PID 351 by me on Sun Jun 18 17:50:46 1989
00730  *
00731  * The string is obtained from the file /tmp/dsp_lock and was written
00732  * when the DSP was initialized.  If the DSP is not in use, or if there
00733  * was a problem reading the lock file, NULL is returned.
00734  * The owner string is returned without a newline.
00735  */
00736 
00737 
00738 extern int DSPReset(void);
00739 /* 
00740  * Reset the DSP.
00741  * The DSP must be open.
00742  * On return, the DSP should be awaiting a 512-word bootstrap program.
00743  */
00744 
00745 
00746 /************************ Opening the DSP in special modes **************************/
00747 
00748 #define DSP_8K  (0x1bff)  /* 7k-1  */
00749 #define DSP_16K  (0x3bff)  /* 15k-1  */
00750 #define DSP_32K (0x7bff)  /* 31k-1 */
00751 #define DSP_64K (0xfbff)  /* 63k-1 */
00752 
00753 #if m68k  /* We currently only support memory sensing on NeXT hardware */
00754 extern int DSPSenseMem(int *memCount);
00755     /* Returns 0 for success, 1 otherwise.
00756      * If successful, *memCount is DSP_8K, DSP_32K or DSP_64K (or 64k x 3 = 192K)
00757      */
00758 #endif
00759 
00760 
00761 /* 
00762  * These are equivalent to some combination of DSPEnable*() and/or DSPDisable*()
00763  * function calls followed by DSPOpen().
00764  */
00765 
00766 extern int DSPMKInit(void);
00767 /* NOTE: The Music Kit currently uses its own version of this function
00768  *       so that it can check the "app wrapper" for a version of the monitor.
00769  *
00770  * Open and reset the DSP such that it is ready to receive a user 
00771  * orchestra program.  It is the same as DSPBoot(musicKitSystem)
00772  * followed by starting up sound-out or write-data, if enabled.
00773  * Also differs from DSPInit() in that "Host Message" protocol is enabled.
00774  * This protocol implies that DSP messages (any word sent by the DSP
00775  * to the host outside of a data transfer is a DSP message) with the
00776  * high-order bit on are error messages, and they are routed to an
00777  * error port separate from the DSP message port.  Only the Music Kit
00778  * currently uses this protocol.
00779  */
00780 
00781 
00782 extern int DSPMKInitWithSoundOut(int lowSamplingRate);
00783 /* 
00784  * Open and reset the DSP such that it is ready to receive a user 
00785  * orchestra program.  Also set up link from DSP to sound-out.
00786  * If lowSamplingRate is TRUE, the sound-output sampling rate is set
00787  * to 22KHz, otherwise it is set to 44KHz.
00788  */
00789 
00790 
00791 /****************************** SoundOut Handling ****************************/
00792 
00793 extern int DSPMKStartSoundOut(void);
00794 /*
00795  * Tell the DSP to begin sending sound-out packets which were linked
00796  * to the sound-out hardware by calling DSPMKEnableSoundOut().
00797  * The DSP must have been initialized via DSPMKInit() already.
00798  */
00799 
00800 
00801 extern int DSPMKStopSoundOut(void);
00802 /*
00803  * Tell DSP to stop sending sound-out packets.
00804  */
00805 
00806 
00807 /***************************** WriteData Handling ****************************/
00808 
00809 extern int DSPMKStartWriteDataTimed(DSPTimeStamp *aTimeStampP);
00810 /*
00811  * Tell the DSP to start sending sound-out requests to the DSP driver when a
00812  * buffer of sound-out data is ready in the DSP.  A thread is spawned which
00813  * blocks in msg_receive() until each record region is received, and the
00814  * buffers are written to disk in the file established by
00815  * DSPMKSetWriteDataFile().  A second effect of this function is that the 
00816  * DSP will now block until the driver reads each sound-out buffer.
00817  * This function must be called after the DSP is initialized by DSPMKInit().
00818  *
00819  * If sound-out is also requested (via DSPMKEnableSoundOut()), each buffer
00820  * will be played immediately after it is written to disk.  In this case,
00821  * there is no need to also call DSPMKStartSoundOut().
00822  *
00823  * Bug: Audible sound-out is disabled during write data.
00824  * Since this should be fixed in the future, do not call both 
00825  * DSPMKEnableSoundOut() and DSPMKEnableWriteData() if you want
00826  * the same behavior in future releases.
00827  */
00828 
00829 
00830 extern int DSPMKStartWriteData(void);
00831 /*
00832  * Equivalent to DSPMKStartWriteDataTimed(DSPMK_UNTIMED);
00833  */
00834 
00835 
00836 extern int DSPMKGetWriteDataSampleCount(void);
00837 /* 
00838  * Get number of samples written to disk since write-data was initialized.
00839  */
00840 
00841 
00842 extern int DSPMKStopWriteDataTimed(DSPTimeStamp *aTimeStampP);
00843 /*
00844  * Tell DSP not to generate write-data requests.
00845  * If write-data is going to disk, it does NOT tell the write-data thread
00846  * to exit.  This must be the case since only the DSP knows when to turn
00847  * off write-data. Call DSPMKStopWriteData() to halt the write-data thread,
00848  * or let it time-out and abort on its own, (cf. DSPMKSetWriteDataTimeOut()).
00849  * Note that as far as the DSP is concerned, there is no difference between
00850  * write-data and sound-out.  Thus, calling this function will also turn off
00851  * sound-out, if it was enabled, whether or not write data was specifically
00852  * enabled.  A byproduct of this function is that the DSP stops blocking 
00853  * until each sound-out buffer is read by the driver. The timed start/stop
00854  * write-data functions can be used to write out specific sections of
00855  * a Music Kit performance, running as fast as possible (silently, throwing
00856  * away sound output buffers) during intervals between the stop and start
00857  * times.
00858  */
00859 
00860 
00861 extern int DSPMKStopWriteData(void);
00862 /*
00863  * Same as DSPMKStopWriteDataTimed(aTimeStampP) but using an untimed
00864  * host message to the DSP.  Called by DSPMKStopSoundOut().
00865  * If write-data is going to disk, also tells write-data thread
00866  * to exit.  See DSPMKStopWriteDataTimed() above.
00867  */
00868 
00869 
00870 extern int DSPMKRewindWriteData(void);
00871 /*
00872  * Rewind write-data to beginning of file.
00873  * DSPMKStopWriteData() must have been called first to terminate
00874  * the thread which actively writes the file.
00875  * After this, write-data can be resumed by DSPMKStartWriteData{Timed}().
00876  */
00877 
00878 extern int DSPMKCloseWriteDataFile(void);
00879 /*
00880  * Close the write-data file.
00881  * DSPMKStopWriteData() is called automatically if write-data is running.
00882  * This function is called by DSPClose(), so it is normally not used
00883  * unless the file is needed as an input before the DSP is next closed and
00884  * reopened.
00885  */
00886 
00887 /***************************** ReadData Handling ****************************/
00888 
00889 extern int DSPMKStartReadDataTimed(DSPTimeStamp *aTimeStampP);
00890 /*
00891  * Start read-data flowing from disk to the DSP.
00892  * This function must be called after the DSP is initialized by DSPMKInit()
00893  * with read-data enabled by DSPMKEnableReadData(), and with
00894  * the input disk file having been specified by DSPMKSetReadDataFile().
00895  * The first two buffers of read-data are sent to the DSP immediately,
00896  * and a timed message is sent to the DSP saying when to start consumption.
00897  * A thread is spawned which blocks in msg_send() until each buffer is taken.
00898  * The DSP will request buffer refills from the driver as needed.
00899  * There is no timeout as there is for write data because the thread knows 
00900  * how much data to expect from the file, and it waits forever trying to give 
00901  * buffers to the DSP.  
00902  *
00903  * A second effect of this function is that the DSP orchestra program will 
00904  * begin blocking on read-data underrun.  There are two read-data buffers in 
00905  * the DSP, so blocking tends not happen if the host is able to convey sound 
00906  * from the disk to the DSP in real time or better, on average.
00907  *
00908  * If aTimeStamp == DSPMK_UNTIMED, the read-data is started in the PAUSED
00909  * state.  A subsequent DSPMKResumeReadDataTimed() is necessary to tell the
00910  * DSP when to begin consuming the read data.  The time-stamp can be set to 
00911  * contain zero which means start read data immediately in the DSP.
00912  *
00913  * Note that DSPMKStartReadDataTimed(ts) is equivalent to
00914  * DSPMKStartReadDataPaused() followed by DSPMKResumeReadDataTimed(ts).
00915  */
00916 
00917 
00918 extern int DSPMKStartReadDataPaused(void);
00919 /*
00920  * Equivalent to DSPMKStartReadDataTimed(DSPMK_UNTIMED);
00921  */
00922 
00923 
00924 extern int DSPMKStartReadData(void);
00925 /*
00926  * Equivalent to DSPMKStartReadDataTimed(&DSPMKTimeStamp0);
00927  * Read-data starts in the DSP immediately.
00928  */
00929 
00930 
00931 extern int DSPMKGetReadDataSampleCount(void);
00932 /* 
00933  * Get number of samples sent to the DSP since read-data was started.
00934  */
00935 
00936 
00937 extern int DSPMKPauseReadDataTimed(DSPTimeStamp *aTimeStampP); 
00938 /* 
00939  * Tell the DSP to stop requesting read-data buffer refills at the
00940  * specified time.  When this happens, the read-data stream going from
00941  * disk to the DSP will block.
00942  * 
00943  * This function and its "resume" counterpart provide
00944  * a way to save disk space in the read-data file when there are stretches
00945  * of time in the Music Kit performance during which no read-data is needed.
00946  * Silence in the read-data file can be squeezed out, and the pause/resume
00947  * functions can be used to read in the sound sections only when needed.
00948  */
00949 
00950 
00951 extern int DSPMKResumeReadDataTimed(DSPTimeStamp *aTimeStampP);
00952 /* 
00953  * Tell the DSP to resume read-data at the specified time.
00954  */
00955 
00956 
00957 extern int DSPMKReadDataIsRunning(void);
00958 /* 
00959  * Return nonzero if DSP read data thread is still running.
00960  * "Paused" is considered a special case of "running" since the
00961  * thread which spools data to the DSP is still alive.
00962  */
00963 
00964 
00965 extern int DSPMKStopReadData(void);
00966 /*
00967  * Tell DSP to stop read-data consumption, if active, and tell the host
00968  * read-data thread to exit.  See also DSPMKPauseReadDataTimed() above.
00969  */
00970 
00971 
00972 extern int DSPMKRewindReadData(void);
00973 /*
00974  * Rewind read-data to beginning of file.
00975  * The read-data thread should be paused or stopped during this operation.
00976  */
00977 
00978 
00979 extern int DSPMKSetReadDataBytePointer(int offset);
00980 /*
00981  * Move read-data file pointer to given offset in bytes.
00982  * Returns file pointer in bytes from beginning of file after the seek
00983  * or -1 if an error occurs.
00984  * The read-data thread should be paused or stopped during this operation.
00985  */
00986 
00987 extern int DSPMKIncrementReadDataBytePointer(int offset);
00988 /*
00989  * Move read-data file pointer to given offset from current location in bytes.
00990  * Returns file pointer in bytes from beginning of file after the seek
00991  * or -1 if an error occurs.
00992  * The read-data thread should be paused or stopped during this operation.
00993  */
00994 
00995 
00996 /******************************* User aborted function ***********************/
00997 
00998 extern void DSPSetUserAbortedFunction(char (*abortFunc)(void));
00999 
01000 /******************************* DSP Negotiation Port ************************/
01001 
01002 int DSPSetNegotiationPort(mach_port_t neg_port);
01003 /* 
01004  * Set port given to anyone attempting to open the DSP.
01005  */
01006 
01007 mach_port_t DSPGetNegotiationPort(void);
01008 /* 
01009  * Get port set by DSPSetNegotiationPort().
01010  */
01011 
01012 /******************************* Port fetching *******************************/
01013 
01014 /*
01015  * In all these routines for obtaining Mach ports,
01016  * the DSP must be opened before asking for the ports.
01017  */
01018 
01019 mach_port_t DSPGetOwnerPort(void);
01020 /* 
01021  * Get port conveying DSP and sound-out ownership capability.
01022  */
01023 
01024 
01025 mach_port_t DSPGetHostMessagePort(void);
01026 /* 
01027  * Get port used to send "host messages" to the DSP.
01028  * Also called the "command port" in other contexts.
01029  */
01030 
01031 
01032 mach_port_t DSPGetDSPMessagePort(void);
01033 /* 
01034  * Get port used to send "DSP messages" from the DSP to the host.
01035  * Messages on this port are enabled by DSPEnableHostMsg().
01036  */
01037 
01038 
01039 mach_port_t DSPGetErrorPort(void);
01040 /* 
01041  * Get port used to send "DSP error messages" from the DSP to the host.
01042  * Error messages on this port are enabled by DSPEnableHostMsg().
01043  */
01044 
01045 
01046 mach_port_t DSPGetSoundPort(void);
01047 /* 
01048  * Get sound device port.
01049  */
01050 
01051 
01052 mach_port_t DSPMKGetWriteDataStreamPort(void);
01053 /* 
01054  * Get stream port used to receive "DSP write data" buffers from the DSP.
01055  */
01056 
01057 
01058 mach_port_t DSPMKGetSoundOutStreamPort(void);
01059 /* 
01060  * Get stream port used to convey "sound out" buffers from the DSP
01061  * to the stereo DAC.
01062  */
01063 
01064 mach_port_t DSPMKGetWriteDataReplyPort(void);
01065 /* 
01066  * Get reply port used to receive status information on "DSP write data" 
01067  * buffers transfers from the DSP.
01068  */
01069 
01070 /************************ SIMULATOR FILE MANAGEMENT **************************/
01071 
01072 extern int DSPIsSimulated(void);
01073 /* 
01074  * Returns nonzero if the DSP is simulated.
01075  */
01076 
01077 
01078 extern int DSPIsSimulatedOnly(void);
01079 /* 
01080  * Returns nonzero if the DSP simulator output is open but the DSP device 
01081  * is not open.  This would happen if DSPOpenSimulatorFile() were called
01082  * without opening the DSP.
01083  */
01084 
01085 
01086 FILE *DSPGetSimulatorFP(void);
01087 /*
01088  * Returns file pointer used for the simulator output file, if any.
01089  */
01090 
01091 
01092 extern int DSPOpenSimulatorFile(char *fn);                      
01093 /* 
01094  * Open simulator output file fn.
01095  */
01096 
01097 
01098 extern int DSPStartSimulator(void);
01099 /*
01100  * Initiate simulation mode, copying DSP commumications to the simulator
01101  * file pointer.
01102  */
01103 
01104 
01105 extern int DSPStartSimulatorFP(FILE *fp);
01106 /*
01107  * Initiate simulation mode, copying DSP commumications to the file pointer fp.
01108  * If fp is NULL, the previously set fp, if any, will be used.
01109  */
01110 
01111 
01112 extern int DSPStopSimulator(void);
01113 /*
01114  * Clear simulation bit, halting DSP command output to the simulator file.
01115  */
01116 
01117 
01118 extern int DSPCloseSimulatorFile(void);
01119 /* 
01120  * Close simulator output file.
01121  */
01122 
01123 /*********************** DSP COMMANDS FILE MANAGEMENT ************************/
01124 
01125 extern int DSPIsSavingCommands(void);
01126 /* 
01127  * Returns nonzero if a "DSP commands file" is open.
01128  */
01129 
01130 extern int DSPIsSavingCommandsOnly(void);
01131 /* 
01132  * Returns nonzero if the DSP commands file is open but the DSP device 
01133  * is not open.  This would happen if DSPOpenCommandsFile() were called
01134  * without opening the DSP.
01135  */
01136 
01137 extern int DSPOpenCommandsFile(const char *fn);
01138 /*
01139  * Opens a "DSP Commands file" which will receive all Mach messages
01140  * to the DSP.  The filename suffix should be ".snd".  This pseudo-
01141  * sound file can be played by the sound library.
01142  */
01143 
01144 extern int DSPCloseCommandsFile(DSPFix48 *endTimeStamp);
01145 /*
01146  * Closes a "DSP Commands file".  The endTimeStamp is used by the
01147  * sound library to terminate the DSP-sound playback thread.
01148  */
01149 
01150 extern int DSPBailingOut(int dspNum);
01151 /* Returns non-zero if the DSP library aborted for the current DSP because 
01152  * of a seemingly dead DSP */
01153 
01154 
01155 /******************************* DSP Driver Protocol *******************************/
01156 
01157 int DSPGetProtocol(void);
01158 /*
01159  * Returns the DSP protocol int in effect.  Some of the relevant bits are
01160  *
01161  *   SNDDRIVER_DSP_PROTO_RAW     - disable all DSP interrupts
01162  *   SNDDRIVER_DSP_PROTO_DSPMSG  - enable DSP messages (via intrpt)
01163  *   SNDDRIVER_DSP_PROTO_DSPERR  - enable DSP error messages (hi bit on)
01164  *   SNDDRIVER_DSP_PROTO_C_DMA   - enable "complex DMA mode"
01165  *   SNDDRIVER_DSP_PROTO_HFABORT - recognize HF2&HF3 as "DSP aborted"
01166  *
01167  * See the snddriver function documentation for more information (e.g.
01168  * snddriver_dsp_protocol()).
01169  */
01170 
01171 int DSPSetProtocol(int newProto);
01172 /*
01173  * Sets the protocol used by the DSP driver.
01174  * This function logically calls snddriver_dsp_proto(), but it's faster
01175  * inside libdsp optimization blocks.  (As many Mach messages as possible are 
01176  * combined into a single message to maximize performance.)
01177  */
01178 
01179 extern int DSPSetComplexDMAModeBit(int bit);
01180 /*
01181  * Set or clear the bit "SNDDRIVER_DSP_PROTO_C_DMA" in the DSP driver protocol.
01182  * For DMA transfers carried out by libdsp, this protocol bit is automatically
01183  * set before and cleared after the transfer.  If you use 
01184  * snddriver_dsp_dma_{read,write}() to carry out DMA transfers between the
01185  * DSP and main memory, you must set the C_DMA protocol bit yourself.
01186  */
01187 
01188 extern int DSPSetHostMessageMode(void);
01189 /*
01190  * Set "Host Message" protocol.  This is the dynamic version of DSPEnableHostMsg()
01191  * followed by a form of DSPOpen().  It can be called after the DSP is already open.
01192  * Host message mode consists of the driver protocol flags 
01193  * SNDDRIVER_DSP_PROTO_{DSPMSG|DSPERR} in addition to the flags enabled by libdsp
01194  * when not in host message mode, which are SNDDRIVER_DSP_PROTO_{RAW|HFABORT}.
01195  */
01196 
01197 extern int DSPClearHostMessageMode(void);
01198 /*
01199  * Clear "Host Message" protocol.  This is the dynamic version of DSPDisableHostMsg()
01200  * followed by a form of DSPOpen().  It can be called after the DSP is already open.
01201  * Clearing host message mode means clearing the driver protocol flags 
01202  * SNDDRIVER_DSP_PROTO_{DSPMSG|DSPERR}.  The usual protocol bits
01203  * SNDDRIVER_DSP_PROTO_{RAW|HFABORT} are left on.  
01204  * 
01205  * Note that the "complex DMA mode bit " bit is not touched.  
01206  * If you have enabled the SNDDRIVER_DSP_PROTO_C_DMA protocol bit,
01207  * clearing host message mode will probably not do what you want (prevent the driver
01208  * from taking DSP interrupts and filling the message buffer with whatever the
01209  * DSP has to send).  In general, the driver is taking DSP interrupts whenever
01210  * SNDDRIVER_DSP_PROTO_RAW is off and when any of
01211  * SNDDRIVER_DSP_PROTO_{DSPMSG|DSPERR|C_DMA} are set.  
01212  * 
01213  * When the "RAW" mode bit is off, you can think of it as "release 1.0 mode", 
01214  * where you get DSPERR mode by default, even with no other protocol bits enabled.
01215  * Consult the snddriver function documentation for more details
01216  * of this complicated protocol business.  Yes, there's actually documentation.
01217  * ("Inside every mode, there is a simpler mode struggling to get out.")
01218  */
01219 
01220 /******************************  DSP Symbols *********************************/
01221 
01222 /*
01223  * DSP symbols are produced by asm56000, the DSP56000/1 assembler.
01224  * They are written into either a .lnk or .lod file, depending on 
01225  * whether the assembly was "relative" or "absolute", respectively.
01226  * When DSPReadFile() reads one of these files (ASCII), or their .dsp file
01227  * counterparts (binary), all symbols are loaded as well into the
01228  * structs described in /usr/include/dsp/dsp_structs.h.  The functions
01229  * below support finding these symbols and their values.  Because the
01230  * assembler does not fully support mixed case, all symbol names are 
01231  * converted to upper case when read in, and any name to be searched for
01232  * in the symbol table is converted to upper case before the search.
01233  */
01234 
01235 
01236 extern int DSPSymbolIsFloat(DSPSymbol *sym);
01237 /* 
01238  * Returns TRUE if the DSP assembler symbol is type 'F'.
01239  */
01240 
01241 
01242 extern DSPSymbol *DSPGetSectionSymbol(char *name, DSPSection *sec);
01243 /*
01244  * Find symbol within the given DSPSection with the given name. 
01245  * See "/LocalDeveloper/Headers/dsp/dsp_structs.h" for the definition of a 
01246  * DSPSection. Equivalent to trying DSPGetSectionSymbolInLC() for each of 
01247  * the 12 DSP location counters.
01248  */
01249 
01250 
01251 extern DSPSymbol *DSPGetSectionSymbolInLC(char *name, DSPSection *sec, 
01252                                    DSPLocationCounter lc);
01253 /*
01254  * Find symbol within the given DSPSection and location counter
01255  * with the given name.  See "/LocalDeveloper/Headers/dsp/dsp_structs.h" 
01256  * for an lc list.
01257  */
01258 
01259 
01260 extern int DSPReadSectionSymbolAddress(DSPMemorySpace *spacep,
01261                                        DSPAddress *addressp,
01262                                        char *name,
01263                                        DSPSection *sec);
01264 /*
01265  * Returns the space and address of symbol with the given name in the 
01266  * given DSP section.  Note that there is no "Get" version because
01267  * both space and address need to be returned.
01268  */
01269 
01270 extern int DSPGetSystemSymbolValue(char *name);
01271 /*
01272  * Returns the value of the symbol "name" in the DSP system image, or -1 if
01273  * the symbol is not found or the DSP is not opened.  
01274  *
01275  * The "system image" is that of the currently loaded monitor in the currently
01276  * selected DSP.  The current DSP must be open so for this monitor image to
01277  * be available.
01278  * 
01279  * The requested symbol
01280  * is assumed to be type "I" and residing in the GLOBAL section under location
01281  * counter "DSP_LC_N" (i.e., no memory space is associated with the symbol).
01282  * No fixups are performed, i.e., the symbol is assumed to belong to an 
01283  * absolute (non-relocatable) section.  
01284  * See /usr/local/lib/dsp/monitor/apmon_8k.lod and mkmon_A_8k.lod for example 
01285  * system files which compatibly define system symbols.
01286  *
01287  * Equivalent to
01288  *  DSPGetSectionSymbol(name,DSPGetUserSection(DSPGetSystemImage()));
01289  * (because the DSP system is assembled in absolute mode, and there
01290  * is only one section, the global section, for absolute assemblies).
01291  */
01292 
01293 extern int DSPGetSystemSymbolValueInLC(char *name, DSPLocationCounter lc);
01294 /*
01295  * Same as DSPGetSystemSymbolValue() except faster because the location 
01296  * counter is known, and the rest are not searched.
01297  */
01298 
01299 int DSPReadSystemSymbolAddress(DSPMemorySpace *spacep, DSPAddress *addressp,
01300                                char *name);
01301 /*
01302  * Same as DSPReadSectionSymbolAddress() except it knows to look in the
01303  * system section (GLOBAL).
01304  */
01305 
01306 #endif