MusicKit  0.0.0
DSPMessage.ReaderThreadForAll.h
00001 #ifndef __MK_DSPMessage.ReaderThreadForAll_H___
00002 #define __MK_DSPMessage.ReaderThreadForAll_H___
00003 /* DSPMessage.h - procedure prototypes having to do with DSP messages.
00004  * Copyright 1988-1992, NeXT Inc.  All rights reserved.
00005  * Author: Julius O. Smith III
00006  */
00007 
00008 /******************************** DSP MESSAGES *******************************/
00009 
00010 /* 
00011  * Any unsolicited single word written by the DSP to the host (via RX) 
00012  * is defined as a "DSP Message".  This 24-bit message consist of a high-order
00013  * "opcode" byte, and two low-order "data" bytes. 
00014  *
00015  * If  "DSPEnableHostMsg()" is called before opening the DSP, 
00016  * "Host Message protocol" is used by the DSP driver.  In terms of the 
00017  * Sound/DSP driver protocol bits, "host message mode" is defined as
00018  * SNDDRIVER_DSP_PROTO_{DSPMSG|DSPERR|HFABORT|RAW}.
00019  * In this mode, RREQ is kept on in the DSP interface,
00020  * and each "DSP message" causes an interrupt in the host.  The DSP messages 
00021  * are buffered up by the driver.  When not using host message protocol,
00022  * RXDF is ignored, and only "data" is assumed to come from the DSP.
00023  * The data does not go into a driver buffer.  Instead, the user
00024  * explicitly reads data from the RX register.
00025  *
00026  * Note that "complex DMA mode" also
00027  * forces the driver to "listen" to the DSP.  In that case, if an 
00028  * unrecognized DSP message comes in (anything other than a DMA request)
00029  * the message goes to the DSP message buffer as in host message protocol
00030  * mode.
00031  * 
00032  * In the functions below, those with "Message" in their name are intended
00033  * to be used in host message mode, and those with "Data" in their name
00034  * are intended to be used outside of host message mode.  There exist
00035  * functions DSP{Set,Clear}HostMessageMode() for toggling between the two
00036  * states dynamically (i.e., while the DSP is open).
00037  *
00038  * The following macro
00039  *
00040  * #import "/LocalDeveloper/Headers/dsp/dsp.h"
00041  * #import <sound/sound.h>
00042  * #define DSP_CAN_INTERRUPT ( !(DSPGetProtocol() & SNDDRIVER_DSP_PROTO_RAW) \
00043  *      || (DSPGetProtocol() \
00044  *          & (SNDDRIVER_DSP_PROTO_DSPMSG | SNDDRIVER_DSP_PROTO_C_DMA)) \
00045  *      )
00046  *
00047  * can be used as follows, for example:
00048  *
00049  * if (DSP_CAN_INTERRUPT)
00050  *    return DSPAwaitHostMessage(msTimeLimit? msTimeLimit : _DSP_MACH_FOREVER);
00051  *  else
00052  *    return DSPAwaitCondition((DSP_ISR_RXDF<<8),
00053  *                             (DSP_ISR_RXDF<<8),
00054  *                             msTimeLimit);
00055  *
00056  */
00057 
00058 extern int DSPDataIsAvailable(void);
00059 /*
00060  * Return nonzero if RXDF is set.
00061  */
00062 
00063 extern int DSPAwaitData(int msTimeLimit);
00064 /*
00065  * Block until RXDF is set in the DSP host interface.
00066  * An msTimeLimit of zero means wait forever.
00067  * Returns 0 when data available, nonzero if
00068  * no data available before time-out.
00069  */
00070 
00071 extern int DSPMessageIsAvailable(void);
00072 /*
00073  * Return nonzero if DSP has one or more pending DSP messages waiting in the
00074  * DSP host interface.  
00075  * Only useable in host message protocol mode or to look for unrecognized
00076  * messages in complex DMA mode.
00077  */
00078 
00079 extern int DSPAwaitMessages(int msTimeLimit);
00080 /*
00081  * Block until DSPMessageIsAvailable() will return nonzero.
00082  * An msTimeLimit of zero means wait forever.
00083  * Returns 0 when a message is available, nonzero on time-out.
00084  * Only useable in host message protocol mode.
00085  */
00086 
00087 /*
00088  * REMOVED IN RELEASE 4.0:
00089  *
00090  * extern int DSPReadMessages(int msTimeLimit);
00091  *
00092  * Read messages from DSP into internal buffers.
00093  * Returns 0 if DSP messages were read by msTimeLimit milliseconds.
00094  * A 0 msTimeLimit means DON'T WAIT if there are no messages waiting
00095  * from the DSP.  See DSPMessage.h for functions which process the messages.
00096  * Only useable in host message protocol mode or to look for unrecognized
00097  * messages in complex DMA mode.
00098  *
00099  * This function is now called internally by a separate thread. 
00100  * To control the polling interval for DSP messages, use the following
00101  * function.
00102  */
00103 
00104 extern int DSPMKSetMessageReaderPollingInterval(int msg_read_timeout);
00105 /*
00106  * (New in release 4.0)
00107  *
00108  * Sets the sleep time (in milliseconds) between successive read attempts
00109  * of the DSP host interface.
00110  */
00111 
00112 extern int DSPMKGetMessageReaderPollingInterval(void);
00113 /*
00114  * (New in release 4.0)
00115  *
00116  * Gets the sleep time (in milliseconds) used between read attempts
00117  * of the DSP host interface.
00118  */
00119 
00120 extern int DSPFlushMessages(void);
00121 /*
00122  * Flush any unread messages from the DSP.
00123  */
00124 
00125 extern int DSPFlushMessageBuffer(void);
00126 /*
00127  * Flush any DSP messages cached internally in libdsp.
00128  * Same as DSPFlushMessages() except that the DSP
00129  * is not checked for more messages.  Anything
00130  * queued up in the driver buffer will stay there.
00131  * Use DSPFlushMessages() to flush the driver's message queue.
00132  * Note: since there is no input-data buffer in the driver,
00133  * there is no DSPFlushDataBuffer() function.
00134  */
00135 
00136 
00137 extern int DSPBreakPoint(int dsp_bp_msg);
00138 /*
00139  * Process a breakpoint generated by DSP software.  A "breakpoint" is just a
00140  * "DSP message" with an op-code of 0x80.
00141  * It currently just prints the DSP breakpoint message, reads any messages
00142  * trying to get out of the DSP, and pauses so that the Ariel debugger (Bug56)
00143  * can be used to see what's going on before anything else happens.
00144  * Only useable in host message protocol mode.
00145  */
00146 
00147 
00148 extern int DSPMessagesOff(void);
00149 /* 
00150  * Turn off DSP messages at their source in the DSP.  The messages will pile
00151  * up in the DSP until its "DSP Message Queue" (DMQ) fills up, unless the
00152  * host message DSP_HM_BLOCK_OFF was sent to it.  The Music Kit and array
00153  * processing DSP monitors support this protocol.
00154  */
00155 
00156 
00157 extern int DSPMessagesOn(void);
00158 /* 
00159  * Enable DSP messages in the MK or AP monitor (on by default).
00160  */
00161 
00162 
00163 extern int DSPMessageGet(int *msgp);
00164 /*
00165  * Return a single DSP message in *msgp, if one is waiting,
00166  * otherwise it returns the DSP error code DSP_ENOMSG.
00167  * The DSP message returned in *msgp is 24 bits, right justified.
00168  */
00169 
00170 
00171 extern int DSPAwaitAnyMessage(
00172     int *dspackp,               /* returned DSP message */
00173     int msTimeLimit);           /* time-out in milliseconds */
00174 /*
00175  * Await any message from the DSP.
00176  */
00177 
00178 
00179 extern int DSPAwaitUnsignedReply(
00180     DSPAddress opcode,         /* opcode of expected DSP message */
00181     DSPFix24 *datum,           /* datum of  expected DSP message (returned) */
00182     int msTimeLimit);          /* time-out in milliseconds */
00183 /* 
00184  * Wait for specific DSP message containing an unsigned datum.
00185  */
00186 
00187 
00188 extern int DSPAwaitSignedReply(
00189     DSPAddress opcode,      /* opcode of expected DSP message */
00190     int *datum,             /* datum of  expected DSP message (returned) */
00191     int msTimeLimit);       /* time-out in milliseconds */
00192 /* 
00193  * Wait for specific DSP message containing a signed datum.
00194  */
00195 
00196 
00197 extern int DSPAwaitMessage(
00198     DSPAddress opcode,          /* opcode of expected DSP message */
00199     int msTimeLimit);           /* time-out in milliseconds */
00200 /* 
00201  * Return specific DSP message, declaring any others as errors.
00202  */
00203 
00204 
00205 extern int DSPHostMessage(int msg);
00206 /* 
00207  * Issue untimed DSP "host message" (minus args) by issuing "xhm" 
00208  * host command.  Example: DSPHostMessage(DSP_HM_ABORT).
00209  */
00210 
00211 
00212 extern int DSPMKHostMessageTimed(DSPFix48 *aTimeStampP, int msg);
00213 
00214 /* 
00215  * Issue timed or untimed DSP "host message" (0 args) by issuing "xhm" 
00216  * host command.  Example: DSPMKHostMessageTimed(aTimeStampP,DSP_HM_ABORT).
00217  */
00218 
00219 
00220 extern int DSPMKHostMessageTimedFromInts(
00221     int msg,          /* Host message opcode. */
00222     int hiwd,         /* High word of time stamp. */
00223     int lowd);        /* Lo   word of time stamp. */
00224 /* 
00225  * Same as DSPMKHostMessageTimed(), but taking time stamp from ints
00226  * instead of a DSPFix48 struct.
00227  */
00228 
00229 
00230 extern int DSPCall(
00231     DSPAddress hm_opcode,
00232     int nArgs,
00233     DSPFix24 *argArray);
00234 /*
00235  * Send an untimed host message to the DSP.
00236  */
00237 
00238 
00239 extern int DSPCallB(
00240     DSPAddress hm_opcode,
00241     int nArgs,
00242     DSPFix24 *argArray);
00243 /*
00244  * Same as DSPCall() except that the argArray is sent in reverse
00245  * order to the DSP.
00246  */
00247 
00248 
00249 extern int DSPCallV(DSPAddress hm_opcode,int nArgs,...);
00250 /*
00251  * Usage is int DSPCallV(hm_opcode,nArgs,arg1,...,ArgNargs);
00252  * Same as DSPCall() except that a variable number of host message arguments 
00253  * is specified explicitly (using varargs) rather than being passed in an
00254  * array.
00255  */
00256 
00257 
00258 extern int DSPMKStartReaders(void);
00259 /* 
00260  * Start error and message readers.
00261  * Called by DSPMKInit() after DSPBoot().
00262  * Necessary to field and discard "kernel acks" from the DSP
00263  * during a performance.
00264  */
00265 
00266 extern int DSPMKStopMsgReader(void);
00267 /* 
00268  * Stop message reader.  Error reader is stopped by closing DSP.
00269  * The Music Kit calls this before waiting for requesting a 
00270  * message at the end of time. 
00271  */
00272 
00273 extern int DSPMKFlushTimedMessages(void);
00274 /* 
00275  * Flush all combined timed messages for the current time. 
00276  * You must send this if you are sending updates to the DSP 
00277  * asynchronously (e.g. in response to mouse events 
00278  * as opposed to via the Music Kit Conductor). The Music Kit
00279  * automatically calls it for Conductor and MIDI events.
00280  */
00281 
00282 extern int DSPMKCallTimed(
00283     DSPFix48 *aTimeStampP,
00284     DSPAddress hm_opcode,
00285     int nArgs,
00286     DSPFix24 *argArray);
00287 /*
00288  * Enqueue a timed host message for the DSP.  If the time stamp of the
00289  * host message is greater than that of the host messages currently
00290  * in the timed message buffer, the buffer is flushed before the
00291  * new message is enqueued.  If the timed stamp is equal to those
00292  * currently in the buffer, it is appended to the buffer.  It is an
00293  * error for the time stamp to be less than that of the current
00294  * timed message buffer, unless it is zero; a zero time stamp means
00295  * execute the message at the end of the current "tick" in the DSP.
00296  * If aTimeStamp is NULL, the host message is executed untimed.  
00297  */
00298 
00299 
00300 extern int DSPMKCallTimedV(DSPFix48 *aTimeStampP,int hm_opcode,int nArgs,...);
00301 /*
00302  * Usage is int DSPMKCallTimedV(aTimeStampP,hm_opcode,nArgs,arg1,...,ArgNargs);
00303  * Same as DSPMKCallTimed() except that a variable number of host message 
00304  * arguments is specified explicitly in the argument list (using stdarg) 
00305  * rather than being passed in an array.
00306  */
00307 
00308 #endif