[Contents] [Index] [Help] [Retrace] [Browse <] [Browse >]

TABLE OF CONTENTS

audio.device/AbortIO
audio.device/ADCMD_ALLOCATE
audio.device/ADCMD_FINISH
audio.device/ADCMD_FREE
audio.device/ADCMD_LOCK
audio.device/ADCMD_PERVOL
audio.device/ADCMD_SETPREC
audio.device/ADCMD_WAITCYCLE
audio.device/BeginIO
audio.device/CloseDevice
audio.device/CMD_CLEAR
audio.device/CMD_FLUSH
audio.device/CMD_READ
audio.device/CMD_RESET
audio.device/CMD_START
audio.device/CMD_STOP
audio.device/CMD_UPDATE
audio.device/CMD_WRITE
audio.device/Expunge
audio.device/OpenDevice
audio.device/AbortIO                                     audio.device/AbortIO

   NAME
       AbortIO - abort a device command

   SYNOPSIS
       AbortIO(iORequest);
                   A1

   FUNCTION
       AbortIO tries to abort a device command.  It is allowed to be
       unsuccessful.  If the Abort is successful, the io_Error field of the
       iORequest contains an indication that IO was aborted.

   INPUTS
       iORequest -- pointer to the I/O Request for the command to abort

audio.device/ADCMD_ALLOCATE                       audio.device/ADCMD_ALLOCATE
       ADCMD_ALLOCATE -- allocate a set of audio channels

   FUNCTION
       ADCMD_ALLOCATE is a command that allocates multiple audio channels.
       ADCMD_ALLOCATE takes an array of possible channel combinations
       (ioa_Data) and an allocation precedence (ln_Pri) and tries to allocate
       one of the combinations of channels.

       If the channel combination array is zero length (ioa_Length), the
       allocation succeeds; otherwise, ADCMD_ALLOCATE checks each
       combination, one at a time, in the specified order, to find one
       combination that does not require ADCMD_ALLOCATE to steal allocated
       channels.

       If it must steal allocated channels, it uses the channel combination
       that steals the lowest precedence channels.

       ADCMD_ALLOCATE cannot steal a channel of equal or greater precedence
       than the allocation precedence (ln_Pri).

       If it fails to allocate any channel combination and the no-wait flag
       (ADIOF_NOWAIT) is set ADCMD_ALLOCATE returns a zero in the unit field
       of the I/O request (io_Unit) and an error (IOERR_ALLOCFAILED).  If the
       no-wait flag is clear, it places the I/O request in a list that tries
       to allocate again whenever ADCMD_FREE frees channels or ADCMD_SETPREC
       lowers the channels' precedences.

       If the allocation is successful, ADCMD_ALLOCATE checks if any channels
       are locked (ADCMD_LOCK) and if so, replies (ReplyMsg) the lock I/O
       request with an error (ADIOERR_CHANNELSTOLEN). Then it places the
       allocation I/O request in a list waiting for the locked channels to be
       freed.  When all the allocated channels are un-locked, ADCMD_ALLOCATE:
         . resets (CMD_RESET) the allocated channels,
         . generates a new allocation key (ioa_AllocKey), if it is zero,
         . copies the allocation key into each of the allocated channels
         . copies the allocation precedence into each of the allocated
           channels, and
         . copies the channel bit map into the unit field of the I/O request.

       If channels are allocated with a non-zero allocation key,
       ADCMD_ALLOCATE allocates with that same key; otherwise, it generates a
       new and unique key.

       ADCMD_ALLOCATE is synchronous:
         . if the allocation succeeds and there are no locked channels to be
           stolen, or
         . if the allocation fails and the no-wait flag is set.

       In either case, ADCMD_ALLOCATE only replies (mn_ReplyPort) if the
       quick flag (IOF_QUICK) is clear; otherwise, the allocation is
       asynchronous, so it clears the quick flag and replies the I/O request
       after the allocation is finished.  If channels are stolen, all audio
       device commands return an error (IOERR_NOALLOCATION) when the former
       user tries to use them again.  Do not use ADCMD_ALLOCATE in interrupt
       code.

       If you decide to store directly to the audio hardware registers, you
       must either lock the channels you've allocated, or set the precedence
       to maximum (ADALLOC_MAXPREC) to prevent the channels from being
       stolen.

       Under all circumstances, unless channels are stolen, you must free
       (ADCMD_FREE) all allocated channels when you are finished using them.

   INPUTS
       ln_Pri      - allocation precedence (-128 thru 127)
       mn_ReplyPort- pointer to message port that receives I/O request after
                     the allocation completes is asynchronous or quick flag
                     (ADIOF_QUICK) is set
       io_Device   - pointer to device node, must be set by (or copied from
                     I/O block set by) OpenDevice function
       io_Command  - command number for ADCMD_ALLOCATE
       io_Flags    - flags, must be cleared if not used:
                     IOF_QUICK   - (CLEAR) reply I/O request
                                   (SET) only reply I/O request only if
                                         asynchronous (see above text)
                     ADIOF_NOWAIT- (CLEAR) if allocation fails, wait till is
                                           succeeds
                                   (SET) if allocation fails, return error
                                         (ADIOERR_ALLOCFAILED)
       ioa_AllocKey- allocation key, zero to generate new key; otherwise,
                     it must be set by (or copied from I/O block set by)
                     OpenDevice function or previous ADCMD_ALLOCATE command
       ioa_Data    - pointer to channel combination options (byte array, bits
                     0 thru 3 correspond to channels 0 thru 3)
       ioa_Length  - length of the channel combination option array
                     (0 thru 16, 0 always succeeds)

   OUTPUTS
       io_Unit     - bit map of successfully allocated channels (bits 0 thru
                     3 correspond to channels 0 thru 3)
       io_Flags    - IOF_QUICK flag cleared if asynchronous (see above text)
       io_Error    - error number:
                     0                   - no error
                     ADIOERR_ALLOCFAILED - allocation failed
       ioa_AllocKey- allocation key, set to a unique number if passed a zero
                     and command succeeds

audio.device/ADCMD_FINISH                           audio.device/ADCMD_FINISH

   NAME
       ADCMD_FINISH -- abort writes in progress to audio channels

   FUNCTION
       ADCMD_FINISH is a command for multiple audio channels.  For each
       selected channel (io_Unit), if the allocation key (ioa_AllocKey) is
       correct and there is a write (CMD_WRITE)in progress, ADCMD_FINISH
       aborts the current write immediately or at the end of the current
       cycle depending on the sync flag (ADIOF_SYNCCYCLE).  If the allocation
       key is incorrect ADCMD_FINISH returns an error (ADIOERR_NOALLOCATION).
       ADCMD_FINISH is synchronous and only replies (mn_ReplyPort) if the
       quick flag (IOF_QUICK) is clear.  Do not use ADCMD_FINISH in interrupt
       code at interrupt level 5 or higher.

   INPUTS
       mn_ReplyPort- pointer to message port that receives I/O request
                     if the quick flag (IOF_QUICK) is clear
       io_Device   - pointer to device node, must be set by (or copied from
                     I/O block set by) OpenDevice function
       io_Unit     - bit map of channels to finish (bits 0 thru 3 correspond
                     to channels 0 thru 3)
       io_Command  - command number for ADCMD_FINISH
       io_Flags    - flags, must be cleared if not used:
                     IOF_QUICK      - (CLEAR) reply I/O request
                     ADIOF_SYNCCYCLE- (CLEAR) finish immediately
                                      (SET) finish at the end of current
                                            cycle

       ioa_AllocKey- allocation key, must be set by (or copied from I/O block
                     set by) OpenDevice function or ADCMD_ALLOCATE command

   OUTPUTS
       io_Unit     - bit map of channels successfully finished (bits 0 thru 3
                     correspond to channels 0 thru 3)
       io_Error    - error number:
                     0                    - no error
                     ADIOERR_NOALLOCATION - allocation key (ioa_AllocKey)
                                            does not match key for channel

audio.device/ADCMD_FREE                               audio.device/ADCMD_FREE

   NAME
       ADCMD_FREE -- free audio channels for allocation

   FUNCTION
       ADCMD_FREE is a command for multiple audio channels.  For each
       selected channel (io_Unit), if the allocation key (ioa_AllocKey) is
       correct, ADCMD_FREE does the following:
         . restores the channel to a known state (CMD_RESET),
         . changes the channels allocation key, and
         . makes the channel available for re-allocation.
         . If the channel is locked (ADCMD_LOCK) ADCMD_FREE unlocks it and
           clears the bit for the channel (io_Unit) in the lock I/O request.
           If the lock I/O request has no channel bits set ADCMD_FREE replies
           the lock I/O request, and
         . checks if there are allocation requests (ADCMD_ALLOCATE) waiting
           for the channel.

       Otherwise, ADCMD_FREE returns an error (ADIOERR_NOALLOCATION).
       ADCMD_FREE is synchronous and only replies (mn_ReplyPort) if the quick
       flag (IOF_QUICK) is clear.  Do not use ADCMD_FREE in interrupt code.

   INPUTS
       mn_ReplyPort- pointer to message port that receives I/O request
                     if the quick flag (IOF_QUICK) is clear
       io_Device   - pointer to device node, must be set by (or copied from
                     I/O block set by) OpenDevice function
       io_Unit     - bit map of channels to free (bits 0 thru 3 correspond to
                     channels 0 thru 3)
       io_Command  - command number for ADCMD_FREE
       io_Flags    - flags, must be cleared if not used:
                     IOF_QUICK - (CLEAR) reply I/O request
       ioa_AllocKey- allocation key, must be set by (or copied from I/O block
                     set by) OpenDevice function or ADCMD_ALLOCATE command

   OUTPUTS
       io_Unit     - bit map of channels successfully freed (bits 0 thru 3
                     correspond to channels 0 thru 3)
       io_Error    - error number:
                     0                    - no error
                     ADIOERR_NOALLOCATION - allocation key (ioa_AllocKey)
                                            does not match key for channel

audio.device/ADCMD_LOCK                               audio.device/ADCMD_LOCK

   NAME
       ADCMD_LOCK -- prevent audio channels from being stolen

   FUNCTION
       ADCMD_LOCK is a command for multiple audio channels.  For each
       selected channel (io_Unit), if the allocation key (ioa_AllocKey) is
       correct, ADCMD_LOCK locks the channel, preventing subsequent
       allocations (ADCMD_ALLOCATE or OpenDevice) from stealing the channel.
       Otherwise, ADCMD_LOCK returns an error (ADIOERR_NOALLOCATION) and will
       not lock any channels.

       Unlike setting the precedence (ADCMD_SETPREC, ADCMD_ALLOCATE or
       OpenDevice) to maximum (ADALLOC_MAXPREC) which would cause all
       subsequent allocations to fail, ADCMD_LOCK causes all higher
       precedence allocations, even no-wait (ADIOF_NOWAIT) allocations, to
       wait until the channels are un-locked.

       Locked channels can only be unlocked by freeing them (ADCMD_FREE),
       which clears the channel select bits (io_Unit).  ADCMD_LOCK does not
       reply the I/O request (mn_ReplyPort) until all the channels it locks
       are freed, unless a higher precedence allocation attempts to steal one
       the locked channels. If a steal occurs, ADCMD_LOCK replies and returns
       an error (ADIOERR_CHANNELSTOLEN).  If the lock is replied
       (mn_ReplyPort) with this error, the channels should be freed as soon
       as possible.  To avoid a possible deadlock, never make the freeing of
       stolen channels dependent on another allocations completion.

       ADCMD_LOCK is only asynchronous if the allocation key is correct, in
       which case it clears the quick flag (IOF_QUICK); otherwise, it is
       synchronous and only replies if the quick flag (IOF_QUICK) is clear.
       Do not use ADCMD_LOCK in interrupt code.

   INPUTS
       mn_ReplyPort- pointer to message port that receives I/O request
                     if the quick flag (IOF_QUICK) is clear
       io_Device   - pointer to device node, must be set by (or copied from
                     I/O block set by) OpenDevice function
       io_Unit     - bit map of channels to lock (bits 0 thru 3 correspond to
                     channels 0 thru 3)
       io_Command  - command number for ADCMD_LOCK
       io_Flags    - flags, must be cleared
       ioa_AllocKey- allocation key, must be set by (or copied from I/O block
                     set by) OpenDevice function or ADCMD_ALLOCATE command

   OUTPUTS
       io_Unit     - bit map of successfully locked channels (bits 0 thru 3
                     correspond to channels 0 thru 3) not freed (ADCMD_FREE)
       io_Flags    - IOF_QUICK flag cleared if the allocation key is correct
                     (no ADIOERR_NOALLOCATION error)
       io_Error    - error number:
                     0                    - no error
                     ADIOERR_NOALLOCATION - allocation key (ioa_AllocKey)
                                            does not match key for channel
                     ADIOERR_CHANNELSTOLEN- allocation attempting to steal
                                            locked channel

audio.device/ADCMD_PERVOL                           audio.device/ADCMD_PERVOL

   NAME
       ADCMD_PERVOL -- change the period and volume for writes in progress to
                       audio channels

   FUNCTION
       ADCMD_PERVOL is a command for multiple audio channels.  For each
       selected channel (io_Unit), if the allocation key (ioa_AllocKey) is
       correct and there is a write (CMD_WRITE) in progress, ADCMD_PERVOL
       loads a new volume and period immediately or at the end of the current
       cycle depending on the sync flag (ADIOF_SYNCCYCLE).  If the allocation
       key in incorrect, ADCMD_PERVOL returns an error
       (ADIOERR_NOALLOCATION).  ADCMD_PERVOL is synchronous and only replies
       (mn_ReplyPort) if the quick flag (IOF_QUICK) is clear.  Do not use
       ADCMD_PERVOL in interrupt code at interrupt level 5 or higher.

   INPUTS
       mn_ReplyPort- pointer to message port that receives I/O request
                     if the quick flag (IOF_QUICK) is clear
       io_Device   - pointer to device node, must be set by (or copied from
                     I/O block set by) OpenDevice function
       io_Unit     - bit map of channels to load period and volume (bits 0
                     thru 3 correspond to channels 0 thru 3)
       io_Command  - command number for ADCMD_PERVOL
       io_Flags    - flags, must be cleared if not used:
                     IOF_QUICK      - (CLEAR) reply I/O request
                     ADIOF_SYNCCYCLE- (CLEAR) load period and volume
                                              immediately
                                      (SET) load period and volume at the end
                                            of the current cycle
       ioa_AllocKey- allocation key, must be set by (or copied from I/O block
                     set by) OpenDevice function or ADCMD_ALLOCATE command
       ioa_Period  - new sample period in 279.365 ns increments (124 thru
                     65536, anti-aliasing filter works below 300 to 500
                     depending on waveform)
       ioa_Volume  - new volume (0 thru 64, linear)

   OUTPUTS
       io_Unit     - bit map of channels that successfully loaded period and
                     volume (bits 0 thru 3 correspond to channels 0 thru 3)
       io_Error    - error number:
                     0                    - no error
                     ADIOERR_NOALLOCATION - allocation key (ioa_AllocKey)
                                            does not match key for channel

audio.device/ADCMD_SETPREC                         audio.device/ADCMD_SETPREC

   NAME
       ADCMD_SETPREC -- set the allocation precedence for audio channels

   FUNCTION
       ADCMD_SETPREC is a command for multiple audio channels.  For each
       selected channel (io_Unit), if the allocation key (ioa_AllocKey) is
       correct, ADCMD_SETPREC sets the allocation precedence to a new value
       (ln_Pri) and checks if there are allocation requests (ADCMD_ALLOCATE)
       waiting for the channel which now have higher precedence; otherwise,
       ADCMD_SETPREC returns an error (ADIOERR_NOALLOCATION).  ADCMD_SETPREC
       is synchronous and only replies (mn_ReplyPort) if the quick flag
       (IOF_QUICK) is clear.  Do not use ADCMD_SETPREC in interrupt code.

   INPUTS
       ln_Pri      - new allocation precedence (-128 thru 127)
       mn_ReplyPort- pointer to message port that receives I/O request
                     if the quick flag (IOF_QUICK) is clear
       io_Device   - pointer to device node, must be set by (or copied from
                     I/O block set by) OpenDevice function
       io_Unit     - bit map of channels to set precedence (bits 0 thru 3
                     correspond to channels 0 thru 3)
       io_Command  - command number for ADCMD_SETPREC
       io_Flags    - flags, must be cleared if not used:
                     IOF_QUICK - (CLEAR) reply I/O request
       ioa_AllocKey- allocation key, must be set by (or copied from I/O block
                     set by) OpenDevice function or ADCMD_ALLOCATE command

   OUTPUTS
       io_Unit     - bit map of channels that successfully set precedence
                     (bits 0 thru 3 correspond to channels 0 thru 3)
       io_Error    - error number:
                     0                    - no error
                     ADIOERR_NOALLOCATION - allocation key (ioa_AllocKey)
                                            does not match key for channel

audio.device/ADCMD_WAITCYCLE                     audio.device/ADCMD_WAITCYCLE

   NAME
       ADCMD_WAITCYCLE -- wait for an audio channel to complete the current
                          cycle of a write

   FUNCTION
       ADCMD_WAITCYCLE is a command for a single audio channel (io_Unit).
       If the allocation key (ioa_AllocKey) is correct and there is a write
       (CMD_WRITE) in progress on selected channel, ADCMD_WAITCYCLE does not
       reply (mn_ReplyPort) until the end of the current cycle.  If there is
       no write is progress, ADCMD_WAITCYCLE replies immediately.  If the
       allocation key is incorrect, ADCMD_WAITCYCLE returns an error
       (ADIOERR_NOALLOCATION).  ADCMD_WAITCYCLE returns an error
       (IOERR_ABORTED) if it is canceled (AbortIO) or the channel is stolen
       (ADCMD_ALLOCATE).  ADCMD_WAITCYCLE is only asynchronous if it is
       waiting for a cycle to complete, in which case it clears the quick
       flag (IOF_QUICK); otherwise, it is synchronous and only replies if the
       quick flag (IOF_QUICK) is clear.  Do not use ADCMD_WAITCYCLE in
       interrupt code at interrupt level 5 or higher.

   INPUTS
       mn_ReplyPort- pointer to message port that receives I/O request, if
                     the quick flag (IOF_QUICK) is clear, or if a write is in
                     progress on the selected channel and a cycle has
                     completed
       io_Device   - pointer to device node, must be set by (or copied from
                     I/O block set by) OpenDevice function
       io_Unit     - bit map of channel to wait for cycle (bits 0 thru 3
                     correspond to channels 0 thru 3), if more then one bit
                     is set lowest bit number channel is used
       io_Command  - command number for CMD_WAITCYCLE
       io_Flags    - flags, must be cleared if not used:
                     IOF_QUICK - (CLEAR) reply I/O request
                                 (SET) only reply I/O request if a write is
                                       in progress on the selected channel
                                       and a cycle has completed
       ioa_AllocKey- allocation key, must be set by (or copied from I/O block
                     set by) OpenDevice function or ADCMD_ALLOCATE command

   OUTPUTS
       io_Unit     - bit map of channel that successfully waited for cycle
                     (bits 0 thru 3 correspond to channels 0 thru 3)
       io_Flags    - IOF_QUICK flag cleared if a write is in progress on the
                     selected channel
       io_Error    - error number:
                     0                    - no error
                     IOERR_ABORTED        - canceled (AbortIO) or channel
                                            stolen
                     ADIOERR_NOALLOCATION - allocation key (ioa_AllocKey)
                                            does not match key for channel

audio.device/BeginIO                                     audio.device/BeginIO

   NAME
       BeginIO - dispatch a device command

   SYNOPSIS
       BeginIO(iORequest);
                   A1

   FUNCTION
       BeginIO has the responsibility of dispatching all device commands.
       Immediate commands are always called directly, and all other commands
       are queued to make them single threaded.

   INPUTS
       iORequest -- pointer to the I/O Request for this command

audio.device/CloseDevice                             audio.device/CloseDevice

   NAME
       CloseDevice - terminate access to the audio device

   SYNOPSIS
       CloseDevice(iORequest);
                       A1

   FUNCTION
       The CloseDevice routine notifies the audio device that it will no
       longer be used.  It takes an I/O audio request block (IOAudio) and
       clears the device pointer (io_Device).  If there are any channels
       allocated with the same allocation key (ioa_AllocKey), CloseDevice
       frees (ADCMD_FREE) them. CloseDevice decrements the open count, and if
       it falls to zero and an expunge (Expunge) is pending, the device is
       expunged.

   INPUTS
       iORequest   - pointer to audio request block (struct IOAudio)
               io_Device   - pointer to device node, must be set by (or
                             copied from I/O block set by) open (OpenDevice)
               io_Unit     - bit map of channels to free (ADCMD_FREE) (bits 0
                             thru 3 correspond to channels 0 thru 3)
               ioa_AllocKey- allocation key, used to free channels

   OUTPUTS
       iORequest - pointer to audio request block (struct IOAudio)
               io_Device   - set to -1
               io_Unit     - set to zero

audio.device/CMD_CLEAR                                 audio.device/CMD_CLEAR

   NAME
       CMD_CLEAR -- throw away internal caches

   FUNCTION
       CMD_CLEAR is a standard command for multiple audio channels.  For each
       selected channel (io_Unit), if the allocation key (ioa_AllocKey) is
       correct, CMD_CLEAR does nothing; otherwise, CMD_CLEAR returns an error
       (ADIOERR_NOALLOCATION).  CMD_CLEAR is synchronous and only replies
       (mn_ReplyPort) if the quick flag (IOF_QUICK) is clear.

   INPUTS
       mn_ReplyPort- pointer to message port that receives I/O request after
                     if the quick flag (IOF_QUICK) is clear
       io_Device   - pointer to device node, must be set by (or copied from
                     I/O block set by) OpenDevice function
       io_Unit     - bit map of channels to clear (bits 0 thru 3 correspond
                     to channels 0 thru 3)
       io_Command  - command number for CMD_CLEAR
       io_Flags    - flags, must be cleared if not used:
                     IOF_QUICK - (CLEAR) reply I/O request
       ioa_AllocKey- allocation key, must be set by (or copied from I/O block
                     set by) OpenDevice function or ADCMD_ALLOCATE command

   OUTPUTS
       io_Unit     - bit map of channels successfully cleared (bits 0 thru 3
                     correspond to channels 0 thru 3)
       io_Error    - error number:
                     0                    - no error
                     ADIOERR_NOALLOCATION - allocation key (ioa_AllocKey)
                                            does not match key for channel

audio.device/CMD_FLUSH                                 audio.device/CMD_FLUSH

   NAME
       CMD_FLUSH -- cancel all pending I/O

   FUNCTION
       CMD_FLUSH is a standard command for multiple audio channels.  For each
       selected channel (io_Unit), if the allocation key (ioa_AllocKey) is
       correct, CMD_FLUSH aborts all writes (CMD_WRITE) in progress or queued
       and any I/O requests waiting to synchronize with the end of the cycle
       (ADCMD_WAITCYCLE); otherwise, CMD_FLUSH returns an error
       (ADIOERR_NOALLOCATION).  CMD_FLUSH is synchronous and only replies
       (mn_ReplyPort) if the quick flag (IOF_QUICK) is clear.  Do not use
       CMD_FLUSH in interrupt code at interrupt level 5 or higher.

   INPUTS
       mn_ReplyPort- pointer to message port that receives I/O request
                     if the quick flag (IOF_QUICK) is clear
       io_Device   - pointer to device node, must be set by (or copied from
                     I/O block set by) OpenDevice function
       io_Unit     - bit map of channels to flush (bits 0 thru 3 correspond
                     to channels 0 thru 3)
       io_Command  - command number for CMD_FLUSH
       io_Flags    - flags, must be cleared if not used:
                     IOF_QUICK - (CLEAR) reply I/O request
       ioa_AllocKey- allocation key, must be set by (or copied from I/O block
                     set by) OpenDevice function or ADCMD_ALLOCATE command

   OUTPUTS
       io_Unit     - bit map of channels successfully flushed (bits 0 thru 3
                     correspond to channels 0 thru 3)
       io_Error    - error number:
                     0                    - no error
                     ADIOERR_NOALLOCATION - allocation key (ioa_AllocKey)
                                            does not match key for channel

audio.device/CMD_READ                                   audio.device/CMD_READ

   NAME
       CMD_READ -- normal I/O entry point

   FUNCTION
       CMD_READ is a standard command for a single audio channel (io_Unit).
       If the allocation key (ioa_AllocKey) is correct, CMD_READ returns a
       pointer (io_Data) to the I/O block currently writing (CMD_WRITE) on
       the selected channel; otherwise, CMD_READ returns an error
       (ADIOERR_NOALLOCATION).  If there is no write in progress, CMD_READ
       returns zero.  CMD_READ is synchronous and only replies (mn_ReplyPort)
       if the quick bit (IOF_QUICK) is clear.

   INPUTS
       mn_ReplyPort- pointer to message port that receives I/O request after
                     if the quick flag (IOF_QUICK) is clear
       io_Device   - pointer to device node, must be set by (or copied from
                     I/O block set by) OpenDevice function
       io_Unit     - bit map of channel to read (bit 0 thru 3 corresponds to
                     channel 0 thru 3), if more then one bit is set lowest
                     bit number channel read
       io_Command  - command number for CMD_READ
       io_Flags    - flags, must be cleared if not used:
                     IOF_QUICK - (CLEAR) reply I/O request
       ioa_AllocKey- allocation key, must be set by (or copied from I/O block
                     set by) OpenDevice function or ADCMD_ALLOCATE command

   OUTPUTS
       io_Unit     - bit map of channel successfully read (bit 0 thru 3
                     corresponds to channel 0 thru 3)
       io_Error    - error number:
                     0                    - no error
                     ADIOERR_NOALLOCATION - allocation key (ioa_AllocKey)
                                            does not match key for channel
       ioa_Data    - pointer to I/O block for current write, zero if none is
                     progress

audio.device/CMD_RESET                                 audio.device/CMD_RESET

   NAME
       CMD_RESET -- restore device to a known state

   FUNCTION
       CMD_RESET is a standard command for multiple audio channels.  For each
       selected channel (io_Unit), if the allocation key (ioa_AllocKey) is
       correct, CMD_RESET:
         . clears the hardware audio registers and attach bits,
         . sets the audio interrupt vector,
         . cancels all pending I/O (CMD_FLUSH), and
         . un-stops the channel if it is stopped (CMD_STOP),

       Otherwise, CMD_RESET returns an error (ADIOERR_NOALLOCATION).
       CMD_RESET is synchronous and only replies (mn_ReplyPort) if the quick
       flag (IOF_QUICK) is clear.  Do not use CMD_RESET in interrupt code at
       interrupt level 5 or higher.

   INPUTS
       mn_ReplyPort- pointer to message port that receives I/O request
                     if the quick flag (IOF_QUICK) is clear
       io_Device   - pointer to device node, must be set by (or copied from
                     I/O block set by) OpenDevice function
       io_Unit     - bit map of channels to reset (bits 0 thru 3 correspond
                     to channels 0 thru 3)
       io_Command  - command number for CMD_RESET
       io_Flags    - flags, must be cleared if not used:
                     IOF_QUICK - (CLEAR) reply I/O request
       ioa_AllocKey- allocation key, must be set by (or copied from I/O block
                     set by) OpenDevice function or ADCMD_ALLOCATE command

   OUTPUTS
       io_Unit     - bit map of channels to successfully reset (bits 0 thru 3
                     correspond to channels 0 thru 3)
       io_Error    - error number:
                     0                    - no error
                     ADIOERR_NOALLOCATION - allocation key (ioa_AllocKey)
                                            does not match key for channel

audio.device/CMD_START                                 audio.device/CMD_START

   NAME
       CMD_START -- start device processing (like ^Q)

   FUNCTION
       CMD_START is a standard command for multiple audio channels.  For each
       selected channel (io_Unit), if the allocation key (ioa_AllocKey) is
       correct and the channel was previously stopped (CMD_STOP), CMP_START
       immediately starts all writes (CMD_WRITE) to the channel.  If the
       allocation key is incorrect, CMD_START returns an error
       (ADIOERR_NOALLOCATION).  CMD_START starts multiple channels
       simultaneously to minimize distortion if the channels are playing the
       same waveform and their outputs are mixed. CMD_START is synchronous an
d
       only replies (mn_ReplyPort) if the quick flag (IOF_QUICK) is clear.  D
o
       not use CMD_START in interrupt code at interrupt level 5 or higher.

   INPUTS
       mn_ReplyPort- pointer to message port that receives I/O request after
                     if the quick flag (IOF_QUICK) is clear
       io_Device   - pointer to device node, must be set by (or copied from
                     I/O block set by) OpenDevice function
       io_Unit     - bit map of channels to start (bits 0 thru 3 correspond
                     to channels 0 thru 3)
       io_Command  - command number for CMD_START
       io_Flags    - flags, must be cleared if not used:
                     IOF_QUICK - (CLEAR) reply I/O request
       ioa_AllocKey- allocation key, must be set by (or copied from I/O block
                     set by) OpenDevice function or ADCMD_ALLOCATE command

   OUTPUTS
       io_Unit     - bit map of channels successfully started (bits 0 thru 3
                     correspond to channels 0 thru 3)
       io_Error    - error number:
                     0                    - no error
                     ADIOERR_NOALLOCATION - allocation key (ioa_AllocKey)
                                            does not match key for channel

audio.device/CMD_STOP                                   audio.device/CMD_STOP

   NAME
       CMD_STOP -- stop device processing (like ^S)

   FUNCTION
       CMD_STOP is a standard command for multiple audio channels.  For each
       selected channel (io_Unit), if the allocation key (ioa_AllocKey) is
       correct, CMD_STOP immediately stops any writes (CMD_WRITE) in
       progress; otherwise, CMD_STOP returns an error (ADIOERR_NOALLOCATION).
       CMD_WRITE queues up writes to a stopped channel until CMD_START starts
       the channel or CMD_RESET resets the channel. CMD_STOP is synchronous
       and only replies (mn_ReplyPort) if the quick flag (IOF_QUICK) is
       clear.  Do not use CMD_STOP in interrupt code at interrupt level 5 or
       higher.

   INPUTS
       mn_ReplyPort- pointer to message port that receives I/O request after
                     if the quick flag (IOF_QUICK) is clear
       io_Device   - pointer to device node, must be set by (or copied from
                     I/O block set by) OpenDevice function
       io_Unit     - bit map of channels to stop (bits 0 thru 3 correspond to
                     channels 0 thru 3)
       io_Command  - command number for CMD_STOP
       io_Flags    - flags, must be cleared if not used:
                     IOF_QUICK - (CLEAR) reply I/O request
       ioa_AllocKey- allocation key, must be set by (or copied from I/O block
                     set by) OpenDevice function or ADCMD_ALLOCATE command

   OUTPUTS
       io_Unit     - bit map of channels successfully stopped (bits 0 thru 3
                     correspond to channels 0 thru 3)
       io_Error    - error number:
                     0                    - no error
                     ADIOERR_NOALLOCATION - allocation key (ioa_AllocKey)
                                            does not match key for channel

audio.device/CMD_UPDATE                               audio.device/CMD_UPDATE

   NAME
       CMD_UPDATE -- force dirty buffers out

   FUNCTION
       CMD_UPDATE is a standard command for multiple audio channels.  For
       each selected channel (io_Unit), if the allocation key (ioa_AllocKey)
       is correct, CMD_UPDATE does nothing; otherwise, CMD_UPDATE returns an
       error (ADIOERR_NOALLOCATION).  CMD_UPDATE is synchronous and only
       replies (mn_ReplyPort) if the quick flag (IOF_QUICK) is clear.

   INPUTS
       mn_ReplyPort- pointer to message port that receives I/O request after
                     if the quick flag (IOF_QUICK) is clear
       io_Device   - pointer to device node, must be set by (or copied from
                     I/O block set by) OpenDevice function
       io_Unit     - bit map of channels to update (bits 0 thru 3 correspond
                     to channels 0 thru 3)
       io_Command  - command number for CMD_UPDATE
       io_Flags    - flags, must be cleared if not used:
                     IOF_QUICK - (CLEAR) reply I/O request
       ioa_AllocKey- allocation key, must be set by (or copied from I/O block
                     set by) OpenDevice function or ADCMD_ALLOCATE command

   OUTPUTS
       io_Unit     - bit map of channels successfully updated (bits 0 thru 3
                     correspond to channels 0 thru 3)
       io_Error    - error number:
                     0                    - no error
                     ADIOERR_NOALLOCATION - allocation key (ioa_AllocKey)
                                            does not match key for channel

audio.device/CMD_WRITE                                 audio.device/CMD_WRITE

   NAME
       CMD_WRITE -- normal I/O entry point

   FUNCTION
       CMD_WRITE is a standard command for a single audio channel (io_Unit).
       If the allocation key (ioa_AllocKey) is correct, CMD_WRITE plays a
       sound using the selected channel; otherwise, it returns an error
       (ADIOERR_NOALLOCATION).  CMD_WRITE queues up requests if there is
       another write in progress or if the channel is stopped (CMD_STOP).
       When the write actually starts; if the ADIOF_PERVOL flag is set,
       CMD_WRITE loads volume (ioa_Volume) and period (ioa_Period), and if
       the ADIOF_WRITEMESSAGE flag is set, CMD_WRITE replies the write
       message (ioa_WriteMsg).  CMD_WRITE returns an error (IOERR_ABORTED) if
       it is canceled (AbortIO) or the channel is stolen (ADCMD_ALLOCATE).
       CMD_WRITE is only asynchronous if there is no error, in which case it
       clears the quick flag (IOF_QUICK) and replies the I/O request
       (mn_ReplyPort) after it finishes writting; otherwise, it is synchronou
s
       and only replies if the quick flag (IOF_QUICK) is clear.  Do not use
       CMD_WRITE in interrupt code at interrupt level 5 or higher.

   INPUTS
       mn_ReplyPort- pointer to message port that receives I/O request after
                     the write completes
       io_Device   - pointer to device node, must be set by (or copied from
                     I/O block set by) OpenDevice function
       io_Unit     - bit map of channel to write (bit 0 thru 3 corresponds to
                     channel 0 thru 3), if more then one bit is set lowest
                     bit number channel is written
       io_Command  - command number for CMD_WRITE
       io_Flags    - flags, must be cleared if not used:
                     ADIOF_PERVOL       - (SET) load volume and period
                     ADIOF_WRITEMESSAGE - (SET) reply message at write start
       ioa_AllocKey- allocation key, must be set by (or copied from I/O block
                     set by) OpenDevice function or ADCMD_ALLOCATE command
       ioa_Data    - pointer to waveform array (signed bytes (-128 thru 127)
                     in custom chip addressable ram and word aligned)
       ioa_Length  - length of the wave array in bytes (2 thru 131072, must
                     be even number)
       ioa_Period  - sample period in 279.365 ns increments (124 thru 65536,
                     anti-aliasing filter works below 300 to 500 depending on
                     waveform), if enabled by ADIOF_PERVOL
       ioa_Volume  - volume (0 thru 64, linear), if enabled by ADIOF_PERVOL
       ioa_Cycles  - number of times to repeat array (0 thru 65535, 0 for
                     infinite)
       ioa_WriteMsg- message replied at start of write,  if enabled by
                     ADIOF_WRITEMESSAGE

   OUTPUTS
       io_Unit     - bit map of channel successfully written (bit 0 thru 3
                     corresponds to channel 0 thru 3)
       io_Flags    - IOF_QUICK flag cleared if there is no error
       io_Error    - error number:
                     0                    - no error
                     IOERR_ABORTED        - canceled (AbortIO) or channel
                                            stolen
                     ADIOERR_NOALLOCATION - allocation key (ioa_AllocKey)
                                            does not match key for channel

   BUGS
       If CMD_WRITE starts the write immediately after stopping a previous
       write, you must set the ADIOF_PERVOL flag or else the new data pointer
       (ioa_Data) and length (ioa_Length) may not be loaded.

audio.device/Expunge                                     audio.device/Expunge

   NAME
       EXPUNGE - indicate a desire to remove the Audio device

   FUNCTION
       The Expunge routine is called when a user issues a RemDevice call.  By
       the time it is called, the device has already been removed from the
       device list, so no new opens will succeed.  The existence of any other
       users of the device, as determined by the device open count being
       non-zero, will cause the Expunge to be deferred.  When the device is
       not in use, or no longer in use, the Expunge is actually performed.

audio.device/OpenDevice                               audio.device/OpenDevice

   NAME
       OpenDevice - open the audio device

   SYNOPSIS
       error = OpenDevice("audio.device", unitNumber, iORequest, flags);

   FUNCTION
       The OpenDevice routine grants access to the audio device.  It takes an
       I/O audio request block (iORequest) and if it can successfully open
       the audio device, it loads the device pointer (io_Device) and the
       allocation key (ioa_AllocKey); otherwise, it returns an error
       (IOERR_OPENFAIL).  OpenDevice increments the open count keeping the
       device from being expunged (Expunge).  If the length (ioa_Length) is
       non-zero, OpenDevice tries to allocate (ADCMD_ALLOCATE) audio channels
       from a array of channel combination options (ioa_Data). If the
       allocation succeeds, the allocated channel combination is loaded into
       the unit field (ioa_Unit); otherwise, OpenDevice returns an error
       (ADIOERR_ALLOCFAILED).  OpenDevice does not wait for allocation to
       succeed and closes (CloseDevice) the audio device if it fails.  To
       allocate channels, OpenDevice also requires a properly initialized
       reply port (mn_ReplyPort) with an allocated signal bit.

   INPUTS
       unitNumber- not used
       iORequest - pointer to audio request block (struct IOAudio)
               ln_Pri      - allocation precedence (-128 thru 127), only
                             necessary for allocation (non-zero length)
               mn_ReplyPort- pointer to message port for allocation, only
                             necessary for allocation (non-zero length)
               ioa_AllocKey- allocation key; zero to generate new key.
                             Otherwise, it must be set by (or copied from I/O
                             block that is set by) previous OpenDevice
                             function or ADCMD_ALLOCATE command (non-zero
                             length)
               ioa_Data    - pointer to channel combination options (byte
                             array, bits 0 thru 3 correspond to channels 0
                             thru 3), only necessary for allocation (non-zero
                             length)
               ioa_Length  - length of the channel combination option array
                             (0 thru 16), zero for no allocation
       flags     - not used

   OUTPUTS
       iORequest - pointer to audio request block (struct IOAudio)
               io_Device   - pointer to device node if OpenDevice succeeds,
                             otherwise -1
               io_Unit     - bit map of successfully allocated channels (bits
                             0 thru 3 correspond to channels 0 thru 3)
               io_Error    - error number:
                             0                   - no error
                             IOERR_OPENFAIL      - open failed
                             ADIOERR_ALLOCFAILED - allocation failed, no open
               ioa_AllocKey- allocation key, set to a unique number if passed
                             a zero and OpenDevice succeeds
       error     - copy of io_Error