DSPMessage.h

#ifndef __MK_DSPMessage_H___
#define __MK_DSPMessage_H___
/* $Id: DSPMessage.h 218 2000-01-31 20:23:53Z leigh $
 * Procedure prototypes having to do with DSP messages.
 * Copyright 1988-1992, NeXT Inc.  All rights reserved.
 * Author: Julius O. Smith III
 */

/******************************** DSP MESSAGES *******************************/

/* 
 * Any unsolicited single word written by the DSP to the host (via RX) 
 * is defined as a "DSP Message".  This 24-bit message consist of a high-order
 * "opcode" byte, and two low-order "data" bytes. 
 *
 * If  "DSPEnableHostMsg()" is called before opening the DSP, 
 * "Host Message protocol" is used by the DSP driver.  In terms of the 
 * Sound/DSP driver protocol bits, "host message mode" is defined as
 * SNDDRIVER_DSP_PROTO_{DSPMSG|DSPERR|HFABORT|RAW}.
 * In this mode, RREQ is kept on in the DSP interface,
 * and each "DSP message" causes an interrupt in the host.  The DSP messages 
 * are buffered up by the driver.  When not using host message protocol,
 * RXDF is ignored, and only "data" is assumed to come from the DSP.
 * The data does not go into a driver buffer.  Instead, the user
 * explicitly reads data from the RX register.
 *
 * Note that "complex DMA mode" also
 * forces the driver to "listen" to the DSP.  In that case, if an 
 * unrecognized DSP message comes in (anything other than a DMA request)
 * the message goes to the DSP message buffer as in host message protocol
 * mode.
 * 
 * In the functions below, those with "Message" in their name are intended
 * to be used in host message mode, and those with "Data" in their name
 * are intended to be used outside of host message mode.  There exist
 * functions DSP{Set,Clear}HostMessageMode() for toggling between the two
 * states dynamically (i.e., while the DSP is open).
 *
 * The following macro
 *
 * #import "/LocalDeveloper/Headers/dsp/dsp.h"
 * #import <sound/sound.h>
 * #define DSP_CAN_INTERRUPT ( !(DSPGetProtocol() & SNDDRIVER_DSP_PROTO_RAW) \
 *      || (DSPGetProtocol() \
 *          & (SNDDRIVER_DSP_PROTO_DSPMSG | SNDDRIVER_DSP_PROTO_C_DMA)) \
 *      )
 *
 * can be used as follows, for example:
 *
 * if (DSP_CAN_INTERRUPT)
 *    return DSPReadMessages(msTimeLimit? msTimeLimit : _DSP_MACH_FOREVER);
 *  else
 *    return DSPAwaitCondition((DSP_ISR_RXDF<<8),
 *                             (DSP_ISR_RXDF<<8),
 *                             msTimeLimit);
 *
 */

extern int DSPDataIsAvailable(void);
/*
 * Return nonzero if RXDF is set.
 */

extern int DSPAwaitData(int msTimeLimit);
/*
 * Block until RXDF is set in the DSP host interface.
 * An msTimeLimit of zero means wait forever.
 * Returns 0 when data available, nonzero if
 * no data available before time-out.
 */

extern int DSPMessageIsAvailable(void);
/*
 * Return nonzero if DSP has one or more pending DSP messages waiting in the
 * DSP host interface.  
 * Only useable in host message protocol mode or to look for unrecognized
 * messages in complex DMA mode.
 */

extern int DSPAwaitMessages(int msTimeLimit);
/*
 * Block until DSPMessageIsAvailable() will return nonzero.
 * An msTimeLimit of zero means wait forever.
 * Returns 0 when a message is available, nonzero on time-out.
 * Only useable in host message protocol mode.
 */

extern int DSPReadMessages(int msTimeLimit);
/*
 * Read messages from DSP into internal buffers.
 * Returns 0 if DSP messages were read by msTimeLimit milliseconds.
 * A 0 msTimeLimit means DON'T WAIT if there are no messages waiting
 * from the DSP.  See DSPMessage.h for functions which process the messages.
 * Only useable in host message protocol mode or to look for unrecognized
 * messages in complex DMA mode.
 */

extern int DSPMessageGet(int *msgp);
/*
 * Return a single DSP message in *msgp, if one is waiting,
 * otherwise wait DSPDefaultTimeLimit for it (0 => wait forever). 
 * On time-out, returns the DSP error code DSP_ENOMSG.
 * The DSP message returned in *msgp is 24 bits, right justified.
 * Only called when a message is really expected.
 * Use DSPAwaitMessages(msTimeLimit) to obtain a precise time-limit.
 * Use DSPMessageIsAvailable() to determine if a message is waiting.
 */

extern int DSPFlushMessages(void);
/*
 * Flush any unread messages from the DSP.
 */

extern int DSPFlushMessageBuffer(void);
/*
 * Flush any DSP messages cached internally in libdsp.
 * Same as DSPFlushMessages() except that the DSP
 * is not checked for more messages.  Anything
 * queued up in the driver buffer will stay there.
 * Use DSPFlushMessages() to flush the driver's message queue.
 * Note: since there is no input-data buffer in the driver,
 * there is no DSPFlushDataBuffer() function.
 */


extern int DSPBreakPoint(int dsp_bp_msg);
/*
 * Process a breakpoint generated by DSP software.  A "breakpoint" is just a
 * "DSP message" with an op-code of 0x80.
 * It currently just prints the DSP breakpoint message, reads any messages
 * trying to get out of the DSP, and pauses so that the Ariel debugger (Bug56)
 * can be used to see what's going on before anything else happens.
 * Only useable in host message protocol mode.
 */


extern int DSPMessagesOff(void);
/* 
 * Turn off DSP messages at their source in the DSP.  The messages will pile
 * up in the DSP until its "DSP Message Queue" (DMQ) fills up, unless the
 * host message DSP_HM_BLOCK_OFF was sent to it.  The Music Kit and array
 * processing DSP monitors support this protocol.
 */


extern int DSPMessagesOn(void);
/* 
 * Enable DSP messages in the MK or AP monitor (on by default).
 */


extern int DSPMessageGet(int *msgp);
/*
 * Return a single DSP message in *msgp, if one is waiting,
 * otherwise it returns the DSP error code DSP_ENOMSG.
 * The DSP message returned in *msgp is 24 bits, right justified.
 */


extern int DSPAwaitAnyMessage(
    int *dspackp,               /* returned DSP message */
    int msTimeLimit);           /* time-out in milliseconds */
/*
 * Await any message from the DSP.
 */


extern int DSPAwaitUnsignedReply(
    DSPAddress opcode,         /* opcode of expected DSP message */
    DSPFix24 *datum,           /* datum of  expected DSP message (returned) */
    int msTimeLimit);          /* time-out in milliseconds */
/* 
 * Wait for specific DSP message containing an unsigned datum.
 */


extern int DSPAwaitSignedReply(
    DSPAddress opcode,      /* opcode of expected DSP message */
    int *datum,             /* datum of  expected DSP message (returned) */
    int msTimeLimit);       /* time-out in milliseconds */
/* 
 * Wait for specific DSP message containing a signed datum.
 */


extern int DSPAwaitMessage(
    DSPAddress opcode,          /* opcode of expected DSP message */
    int msTimeLimit);           /* time-out in milliseconds */
/* 
 * Return specific DSP message, declaring any others as errors.
 */


extern int DSPHostMessage(int msg);
/* 
 * Issue untimed DSP "host message" (minus args) by issuing "xhm" 
 * host command.  Example: DSPHostMessage(DSP_HM_ABORT).
 */


extern int DSPMKHostMessageTimed(DSPFix48 *aTimeStampP, int msg);

/* 
 * Issue timed or untimed DSP "host message" (0 args) by issuing "xhm" 
 * host command.  Example: DSPMKHostMessageTimed(aTimeStampP,DSP_HM_ABORT).
 */


extern int DSPMKHostMessageTimedFromInts(
    int msg,          /* Host message opcode. */
    int hiwd,         /* High word of time stamp. */
    int lowd);        /* Lo   word of time stamp. */
/* 
 * Same as DSPMKHostMessageTimed(), but taking time stamp from ints
 * instead of a DSPFix48 struct.
 */


extern int DSPCall(
    DSPAddress hm_opcode,
    int nArgs,
    DSPFix24 *argArray);
/*
 * Send an untimed host message to the DSP.
 */


extern int DSPCallB(
    DSPAddress hm_opcode,
    int nArgs,
    DSPFix24 *argArray);
/*
 * Same as DSPCall() except that the argArray is sent in reverse
 * order to the DSP.
 */


extern int DSPCallV(DSPAddress hm_opcode,int nArgs,...);
/*
 * Usage is int DSPCallV(hm_opcode,nArgs,arg1,...,ArgNargs);
 * Same as DSPCall() except that a variable number of host message arguments 
 * is specified explicitly (using varargs) rather than being passed in an
 * array.
 */


extern int DSPMKStartReaders(void);
/* 
 * Start error and message readers.
 * Called by DSPMKInit() after DSPBoot().
 * Necessary to field and discard "kernel acks" from the DSP
 * during a performance.
 */

extern int DSPMKStopMsgReader(void);
/* 
 * Stop message reader.  Error reader is stopped by closing DSP.
 * The Music Kit calls this before waiting for requesting a 
 * message at the end of time. 
 */

extern int DSPMKFlushTimedMessages(void);
/* 
 * Flush all combined timed messages for the current time. 
 * You must send this if you are sending updates to the DSP 
 * asynchronously (e.g. in response to mouse events 
 * as opposed to via the Music Kit Conductor). The Music Kit
 * automatically calls it for Conductor and MIDI events.
 */

extern int DSPMKCallTimed(
    DSPFix48 *aTimeStampP,
    DSPAddress hm_opcode,
    int nArgs,
    DSPFix24 *argArray);
/*
 * Enqueue a timed host message for the DSP.  If the time stamp of the
 * host message is greater than that of the host messages currently
 * in the timed message buffer, the buffer is flushed before the
 * new message is enqueued.  If the timed stamp is equal to those
 * currently in the buffer, it is appended to the buffer.  It is an
 * error for the time stamp to be less than that of the current
 * timed message buffer, unless it is zero; a zero time stamp means
 * execute the message at the end of the current "tick" in the DSP.
 * If aTimeStamp is NULL, the host message is executed untimed.  
 */


extern int DSPMKCallTimedV(DSPFix48 *aTimeStampP,int hm_opcode,int nArgs,...);
/*
 * Usage is int DSPMKCallTimedV(aTimeStampP,hm_opcode,nArgs,arg1,...,ArgNargs);
 * Same as DSPMKCallTimed() except that a variable number of host message 
 * arguments is specified explicitly in the argument list (using stdarg) 
 * rather than being passed in an array.
 */

extern int DSPMKAwaitEndOfTime(DSPFix48 *aTimeStampP);
/* 
 * Issues a timed message for the specified time, then blocks until that message
 * is received. 
 */

#endif

---