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