Autodocs
Devices:
audio.device
ADCMD_ALLOCATE
ADCMD_FINISH
ADCMD_FREE
ADCMD_LOCK
ADCMD_PERVOL
ADCMD_SETPREC
ADCMD_WAITCYCLE
AbortIO
BeginIO
CMD_CLEAR
CMD_FLUSH
CMD_READ
CMD_RESET
CMD_START
CMD_STOP
CMD_UPDATE
CMD_WRITE
CloseDevice
Expunge
OpenDevice
Include
GuruMeditation
|
Docs » Autodocs » audio.device » ADCMD_ALLOCATE
ADCMD_ALLOCATE -- allocate a set of audio channels
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.
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)
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
|
