home *** CD-ROM | disk | FTP | other *** search
/ Amiga ISO Collection / AmigaUtilCD2.iso / Programming / Misc / TRSICAT.LZX / CATS_CD2_TRSI / Inc&AD1.3 / Text_Autodocs / audio.doc < prev    next >
Encoding:
Text File  |  1992-09-12  |  40.5 KB  |  828 lines
  1. TABLE OF CONTENTS
  2.  
  3. audio.device/CloseDevice
  4. audio.device/ADCMD_ALLOCATE
  5. audio.device/ADCMD_FINISH
  6. audio.device/ADCMD_FREE
  7. audio.device/ADCMD_LOCK
  8. audio.device/ADCMD_PERVOL
  9. audio.device/ADCMD_SETPREC
  10. audio.device/ADCMD_WAITCYCLE
  11. audio.device/CMD_CLEAR
  12. audio.device/CMD_FLUSH
  13. audio.device/CMD_READ
  14. audio.device/CMD_RESET
  15. audio.device/CMD_START
  16. audio.device/CMD_STOP
  17. audio.device/CMD_UPDATE
  18. audio.device/CMD_WRITE
  19. audio.device/OpenDevice
  20.  
  21.  
  22. audio.device/CloseDevice
  23.  
  24.    NAME
  25.        CloseDevice - terminate access to the audio device
  26.  
  27.    SYNOPSIS
  28.        CloseDevice(iORequest);
  29.                        A1
  30.  
  31.    FUNCTION
  32.        The CloseDevice routine notifies the audio device that it will no
  33.        longer be used.  It takes an I/O audio request block (IOAudio) and
  34.        clears the device pointer (io_Device).  If there are any channels
  35.        allocated with the same allocation key (ioa_AllocKey), CloseDevice
  36.        frees (ADCMD_FREE) them. CloseDevice decrements the open count, if the
  37.        count falls to zero, and the system needs memory, the device is expunged.
  38.  
  39.    INPUTS
  40.        iORequest   - pointer to audio request block (struct IOAudio)
  41.                io_Device   - pointer to device node, must be set by (or
  42.                              copied from I/O block set by) open (OpenDevice)
  43.                io_Unit     - bit map of channels to free (ADCMD_FREE) (bits 0
  44.                              thru 3 correspond to channels 0 thru 3)
  45.                ioa_AllocKey- allocation key, used to free channels
  46.  
  47.    OUTPUTS
  48.        iORequest - pointer to audio request block (struct IOAudio)
  49.                io_Device   - set to -1
  50.                io_Unit     - set to zero
  51.  
  52.  
  53. audio.device/ADCMD_ALLOCATE
  54.  
  55.    NAME
  56.        ADCMD_ALLOCATE -- allocate a set of audio channels
  57.  
  58.    FUNCTION
  59.        ADCMD_ALLOCATE is a command that allocates multiple audio channels.
  60.        ADCMD_ALLOCATE takes an array of possible channel combinations
  61.        (ioa_Data) and an allocation precedence (ln_Pri) and tries to allocate
  62.        one of the combinations of channels.
  63.  
  64.        If the channel combination array is zero length (ioa_Length), the
  65.        allocation succeeds; otherwise, ADCMD_ALLOCATE checks each
  66.        combination, one at a time, in the specified order, to find one
  67.        combination that does not require ADCMD_ALLOCATE to steal allocated
  68.        channels.
  69.  
  70.        If it must steal allocated channels, it uses the channel combination
  71.        that steals the lowest precedence channels.
  72.  
  73.        ADCMD_ALLOCATE cannot steal a channel of equal or greater precedence
  74.        than the allocation precedence (ln_Pri).
  75.  
  76.        If it fails to allocate any channel combination and the no-wait flag
  77.        (ADIOF_NOWAIT) is set ADCMD_ALLOCATE returns a zero in the unit field
  78.        of the I/O request (io_Unit) and an error (IOERR_ALLOCFAILED).  If the
  79.        no-wait flag is clear, it places the I/O request in a list that tries
  80.        to allocate again whenever ADCMD_FREE frees channels or ADCMD_SETPREC
  81.        lowers the channels' precedences.
  82.  
  83.        If the allocation is successful, ADCMD_ALLOCATE checks if any channels
  84.        are locked (ADCMD_LOCK) and if so, replies (ReplyMsg) the lock I/O
  85.        request with an error (ADIOERR_CHANNELSTOLEN). Then it places the
  86.        allocation I/O request in a list waiting for the locked channels to be
  87.        freed.  When all the allocated channels are un-locked, ADCMD_ALLOCATE:
  88.          . resets (CMD_RESET) the allocated channels,
  89.          . generates a new allocation key (ioa_AllocKey), if it is zero,
  90.          . copies the allocation key into each of the allocated channels
  91.          . copies the allocation precedence into each of the allocated
  92.            channels, and
  93.          . copies the channel bit map into the unit field of the I/O request.
  94.  
  95.        If channels are allocated with a non-zero allocation key,
  96.        ADCMD_ALLOCATE allocates with that same key; otherwise, it generates a
  97.        new and unique key.
  98.  
  99.        ADCMD_ALLOCATE is synchronous:
  100.          . if the allocation succeeds and there are no locked channels to be
  101.            stolen, or
  102.          . if the allocation fails and the no-wait flag is set.
  103.         . if the allocation fails and the no-wait flag is set.
  104.        In either case, ADCMD_ALLOCATE only replies (mn_ReplyPort) if the
  105.        quick flag (IOF_QUICK) is clear; otherwise, the allocation is
  106.        asynchronous, so it clears the quick flag and replies the I/O request
  107.        after the allocation is finished.  If channels are stolen, all audio
  108.        device commands return an error (IOERR_NOALLOCATION) when the former
  109.        user tries to use them again.  Do not use ADCMD_ALLOCATE in interrupt
  110.        code.
  111.  
  112.        If you decide to store directly to the audio hardware registers, you
  113.        must either lock the channels you've allocated, or set the precedence
  114.        to maximum (ADALLOC_MAXPREC) to prevent the channels from being
  115.        stolen.
  116.  
  117.        Under all circumstances, unless channels are stolen, you must free
  118.        (ADCMD_FREE) all allocated channels when you are finished using them.
  119.  
  120.    INPUTS
  121.        ln_Pri      - allocation precedence (-128 thru 127)
  122.        mn_ReplyPort- pointer to message port that receives I/O request after
  123.                      the allocation completes is asynchronous or quick flag
  124.                      (ADIOF_QUICK) is set
  125.        io_Device   - pointer to device node, must be set by (or copied from
  126.                      I/O block set by) OpenDevice function
  127.        io_Command  - command number for ADCMD_ALLOCATE
  128.        io_Flags    - flags, must be cleared if not used:
  129.                      IOF_QUICK   - (CLEAR) reply I/O request
  130.                                    (SET) only reply I/O request only if
  131.                                          asynchronous (see above text)
  132.                      ADIOF_NOWAIT- (CLEAR) if allocation fails, wait till is
  133.                                            succeeds
  134.                                    (SET) if allocation fails, return error
  135.                                          (ADIOERR_ALLOCFAILED)
  136.        ioa_AllocKey- allocation key, zero to generate new key; otherwise,
  137.                      it must be set by (or copied from I/O block set by)
  138.                      OpenDevice function or previous ADCMD_ALLOCATE command
  139.        ioa_Data    - pointer to channel combination options (byte array, bits
  140.                      0 thru 3 correspond to channels 0 thru 3)
  141.        ioa_Length  - length of the channel combination option array
  142.                      (0 thru 16, 0 always succeeds)
  143.  
  144.    OUTPUTS
  145.        io_Unit     - bit map of successfully allocated channels (bits 0 thru
  146.                      3 correspond to channels 0 thru 3)
  147.        io_Flags    - IOF_QUICK flag cleared if asynchronous (see above text)
  148.        io_Error    - error number:
  149.                      0                   - no error
  150.                      ADIOERR_ALLOCFAILED - allocation failed
  151.        ioa_AllocKey- allocation key, set to a unique number if passed a zero
  152.                      and command succeeds
  153.  
  154.  
  155. audio.device/ADCMD_FINISH             audio.device/command/ADCMD_FINISH
  156.  
  157.    NAME
  158.        ADCMD_FINISH -- abort writes in progress to audio channels
  159.  
  160.    FUNCTION
  161.        ADCMD_FINISH is a command for multiple audio channels.  For each
  162.        selected channel (io_Unit), if the allocation key (ioa_AllocKey) is
  163.        correct and there is a write (CMD_WRITE)in progress, ADCMD_FINISH
  164.        aborts the current write immediately or at the end of the current
  165.        cycle depending on the sync flag (ADIOF_SYNCCYCLE).  If the allocation
  166.        key is incorrect ADCMD_FINISH returns an error (ADIOERR_NOALLOCATION).
  167.        ADCMD_FINISH is synchronous and only replies (mn_ReplyPort) if the
  168.        quick flag (IOF_QUICK) is clear.  Do not use ADCMD_FINISH in interrupt
  169.        code at interrupt level 5 or higher.
  170.    
  171.    INPUTS
  172.        mn_ReplyPort- pointer to message port that receives I/O request
  173.                      if the quick flag (IOF_QUICK) is clear
  174.        io_Device   - pointer to device node, must be set by (or copied from
  175.                      I/O block set by) OpenDevice function
  176.        io_Unit     - bit map of channels to finish (bits 0 thru 3 correspond
  177.                      to channels 0 thru 3)
  178.        io_Command  - command number for ADCMD_FINISH
  179.        io_Flags    - flags, must be cleared if not used:
  180.                      IOF_QUICK      - (CLEAR) reply I/O request
  181.                      ADIOF_SYNCCYCLE- (CLEAR) finish immediately
  182.                                       (SET) finish at the end of current
  183.                                             cycle
  184.  
  185.        ioa_AllocKey- allocation key, must be set by (or copied from I/O block
  186.                      set by) OpenDevice function or ADCMD_ALLOCATE command
  187.  
  188.    OUTPUTS
  189.        io_Unit     - bit map of channels successfully finished (bits 0 thru 3
  190.                      correspond to channels 0 thru 3)
  191.        io_Error    - error number:
  192.                      0                    - no error
  193.                      ADIOERR_NOALLOCATION - allocation key (ioa_AllocKey)
  194.                                             does not match key for channel
  195.  
  196.  
  197. audio.device/ADCMD_FREE                 audio.device/command/ADCMD_FREE
  198.  
  199.    NAME
  200.        ADCMD_FREE -- free audio channels for allocation
  201.  
  202.    FUNCTION
  203.        ADCMD_FREE is a command for multiple audio channels.  For each
  204.        selected channel (io_Unit), if the allocation key (ioa_AllocKey) is
  205.        correct, ADCMD_FREE does the following:
  206.          . restores the channel to a known state (CMD_RESET),
  207.          . changes the channels allocation key, and
  208.          . makes the channel available for re-allocation.
  209.          . If the channel is locked (ADCMD_LOCK) ADCMD_FREE unlocks it and
  210.            clears the bit for the channel (io_Unit) in the lock I/O request.
  211.            If the lock I/O request has no channel bits set ADCMD_FREE replies
  212.            the lock I/O request, and
  213.          . checks if there are allocation requests (ADCMD_ALLOCATE) waiting
  214.            for the channel.
  215.  
  216.        Otherwise, ADCMD_FREE returns an error (ADIOERR_NOALLOCATION).
  217.        ADCMD_FREE is synchronous and only replies (mn_ReplyPort) if the quick
  218.        flag (IOF_QUICK) is clear.  Do not use ADCMD_FREE in interrupt code.
  219.  
  220.    INPUTS
  221.        mn_ReplyPort- pointer to message port that receives I/O request
  222.                      if the quick flag (IOF_QUICK) is clear
  223.        io_Device   - pointer to device node, must be set by (or copied from
  224.                      I/O block set by) OpenDevice function
  225.        io_Unit     - bit map of channels to free (bits 0 thru 3 correspond to
  226.                      channels 0 thru 3)
  227.        io_Command  - command number for ADCMD_FREE
  228.        io_Flags    - flags, must be cleared if not used:
  229.                      IOF_QUICK - (CLEAR) reply I/O request
  230.        ioa_AllocKey- allocation key, must be set by (or copied from I/O block
  231.                      set by) OpenDevice function or ADCMD_ALLOCATE command
  232.  
  233.    OUTPUTS
  234.        io_Unit     - bit map of channels successfully freed (bits 0 thru 3
  235.                      correspond to channels 0 thru 3)
  236.        io_Error    - error number:
  237.                      0                    - no error
  238.                      ADIOERR_NOALLOCATION - allocation key (ioa_AllocKey)
  239.                                             does not match key for channel
  240.  
  241.  
  242. audio.device/ADCMD_LOCK                 audio.device/command/ADCMD_LOCK
  243.  
  244.    NAME
  245.        ADCMD_LOCK -- prevent audio channels from being stolen
  246.  
  247.    FUNCTION
  248.        ADCMD_LOCK is a command for multiple audio channels.  For each
  249.        selected channel (io_Unit), if the allocation key (ioa_AllocKey) is
  250.        correct, ADCMD_LOCK locks the channel, preventing subsequent
  251.        allocations (ADCMD_ALLOCATE or OpenDevice) from stealing the channel.
  252.        Otherwise, ADCMD_LOCK returns an error (ADIOERR_NOALLOCATION) and will
  253.        not lock any channels.
  254.  
  255.        Unlike setting the precedence (ADCMD_SETPREC, ADCMD_ALLOCATE or
  256.        OpenDevice) to maximum (ADALLOC_MAXPREC) which would cause all
  257.        subsequent allocations to fail, ADCMD_LOCK causes all higher
  258.        precedence allocations, even no-wait (ADIOF_NOWAIT) allocations, to
  259.        wait until the channels are un-locked.
  260.  
  261.        Locked channels can only be unlocked by freeing them (ADCMD_FREE),
  262.        which clears the channel select bits (io_Unit).  ADCMD_LOCK does not
  263.        reply the I/O request (mn_ReplyPort) until all the channels it locks
  264.        are freed, unless a higher precedence allocation attempts to steal one
  265.        the locked channels. If a steal occurs, ADCMD_LOCK replies and returns
  266.        an error (ADIOERR_CHANNELSTOLEN).  If the lock is replied
  267.        (mn_ReplyPort) with this error, the channels should be freed as soon
  268.        as possible.  To avoid a possible deadlock, never make the freeing of
  269.        stolen channels dependent on another allocations completion.
  270.  
  271.        ADCMD_LOCK is only asynchronous if the allocation key is correct, in
  272.        which case it clears the quick flag (IOF_QUICK); otherwise, it is
  273.        synchronous and only replies if the quick flag (IOF_QUICK) is clear.
  274.        Do not use ADCMD_LOCK in interrupt code.
  275.        
  276.    INPUTS
  277.        mn_ReplyPort- pointer to message port that receives I/O request
  278.                      if the quick flag (IOF_QUICK) is clear
  279.        io_Device   - pointer to device node, must be set by (or copied from
  280.                      I/O block set by) OpenDevice function
  281.        io_Unit     - bit map of channels to lock (bits 0 thru 3 correspond to
  282.                      channels 0 thru 3)
  283.        io_Command  - command number for ADCMD_LOCK
  284.        io_Flags    - flags, must be cleared
  285.        ioa_AllocKey- allocation key, must be set by (or copied from I/O block
  286.                      set by) OpenDevice function or ADCMD_ALLOCATE command
  287.  
  288.    OUTPUTS
  289.        io_Unit     - bit map of successfully locked channels (bits 0 thru 3
  290.                      correspond to channels 0 thru 3) not freed (ADCMD_FREE)
  291.        io_Flags    - IOF_QUICK flag cleared if the allocation key is correct
  292.                      (no ADIOERR_NOALLOCATION error)
  293.        io_Error    - error number:
  294.                      0                    - no error
  295.                      ADIOERR_NOALLOCATION - allocation key (ioa_AllocKey)
  296.                                             does not match key for channel
  297.                      ADIOERR_CHANNELSTOLEN- allocation attempting to steal
  298.                                             locked channel
  299.  
  300.  
  301. audio.device/ADCMD_PERVOL             audio.device/command/ADCMD_PERVOL
  302.  
  303.    NAME
  304.        ADCMD_PERVOL -- change the period and volume for writes in progress to
  305.                        audio channels
  306.  
  307.    FUNCTION
  308.        ADCMD_PERVOL is a command for multiple audio channels.  For each
  309.        selected channel (io_Unit), if the allocation key (ioa_AllocKey) is
  310.        correct and there is a write (CMD_WRITE) in progress, ADCMD_PERVOL
  311.        loads a new volume and period immediately or at the end of the current
  312.        cycle depending on the sync flag (ADIOF_SYNCCYCLE).  If the allocation
  313.        key in incorrect, ADCMD_PERVOL returns an error
  314.        (ADIOERR_NOALLOCATION).  ADCMD_PERVOL is synchronous and only replies
  315.        (mn_ReplyPort) if the quick flag (IOF_QUICK) is clear.  Do not use
  316.        ADCMD_PERVOL in interrupt code at interrupt level 5 or higher.
  317.    
  318.    INPUTS
  319.        mn_ReplyPort- pointer to message port that receives I/O request
  320.                      if the quick flag (IOF_QUICK) is clear
  321.        io_Device   - pointer to device node, must be set by (or copied from
  322.                      I/O block set by) OpenDevice function
  323.        io_Unit     - bit map of channels to load period and volume (bits 0
  324.                      thru 3 correspond to channels 0 thru 3)
  325.        io_Command  - command number for ADCMD_PERVOL
  326.        io_Flags    - flags, must be cleared if not used:
  327.                      IOF_QUICK      - (CLEAR) reply I/O request
  328.                      ADIOF_SYNCCYCLE- (CLEAR) load period and volume
  329.                                               immediately
  330.                                       (SET) load period and volume at the end
  331.                                             of the current cycle
  332.        ioa_AllocKey- allocation key, must be set by (or copied from I/O block
  333.                      set by) OpenDevice function or ADCMD_ALLOCATE command
  334.        ioa_Period  - new sample period in 279.365 ns increments (124 thru
  335.                      65536, anti-aliasing filter works below 300 to 500
  336.                      depending on waveform)
  337.        ioa_Volume  - new volume (0 thru 64, linear)
  338.    
  339.    OUTPUTS
  340.        io_Unit     - bit map of channels that successfully loaded period and
  341.                      volume (bits 0 thru 3 correspond to channels 0 thru 3)
  342.        io_Error    - error number:
  343.                      0                    - no error
  344.                      ADIOERR_NOALLOCATION - allocation key (ioa_AllocKey)
  345.                                             does not match key for channel
  346.  
  347.  
  348. audio.device/ADCMD_SETPREC           audio.device/command/ADCMD_SETPREC
  349.  
  350.    NAME
  351.        ADCMD_SETPREC -- set the allocation precedence for audio channels
  352.  
  353.    FUNCTION
  354.        ADCMD_SETPREC is a command for multiple audio channels.  For each
  355.        selected channel (io_Unit), if the allocation key (ioa_AllocKey) is
  356.        correct, ADCMD_SETPREC sets the allocation precedence to a new value
  357.        (ln_Pri) and checks if there are allocation requests (ADCMD_ALLOCATE)
  358.        waiting for the channel which now have higher precedence; otherwise,
  359.        ADCMD_SETPREC returns an error (ADIOERR_NOALLOCATION).  ADCMD_SETPREC
  360.        is synchronous and only replies (mn_ReplyPort) if the quick flag
  361.        (IOF_QUICK) is clear.  Do not use ADCMD_SETPREC in interrupt code.
  362.  
  363.    INPUTS
  364.        ln_Pri      - new allocation precedence (-128 thru 127)
  365.        mn_ReplyPort- pointer to message port that receives I/O request
  366.                      if the quick flag (IOF_QUICK) is clear
  367.        io_Device   - pointer to device node, must be set by (or copied from
  368.                      I/O block set by) OpenDevice function
  369.        io_Unit     - bit map of channels to set precedence (bits 0 thru 3
  370.                      correspond to channels 0 thru 3)
  371.        io_Command  - command number for ADCMD_SETPREC
  372.        io_Flags    - flags, must be cleared if not used:
  373.                      IOF_QUICK - (CLEAR) reply I/O request
  374.        ioa_AllocKey- allocation key, must be set by (or copied from I/O block
  375.                      set by) OpenDevice function or ADCMD_ALLOCATE command
  376.  
  377.    OUTPUTS
  378.        io_Unit     - bit map of channels that successfully set precedence
  379.                      (bits 0 thru 3 correspond to channels 0 thru 3)
  380.        io_Error    - error number:
  381.                      0                    - no error
  382.                      ADIOERR_NOALLOCATION - allocation key (ioa_AllocKey)
  383.                                             does not match key for channel
  384.  
  385.  
  386. audio.device/ADCMD_WAITCYCLE
  387.  
  388.    NAME
  389.        ADCMD_WAITCYCLE -- wait for an audio channel to complete the current
  390.                           cycle of a write
  391.  
  392.    FUNCTION
  393.        ADCMD_WAITCYCLE is a command for a single audio channel (io_Unit).
  394.        If the allocation key (ioa_AllocKey) is correct and there is a write
  395.        (CMD_WRITE) in progress on selected channel, ADCMD_WAITCYCLE does not
  396.        reply (mn_ReplyPort) until the end of the current cycle.  If there is
  397.        no write is progress, ADCMD_WAITCYCLE replies immediately.  If the
  398.        allocation key is incorrect, ADCMD_WAITCYCLE returns an error
  399.        (ADIOERR_NOALLOCATION).  ADCMD_WAITCYCLE returns an error
  400.        (IOERR_ABORTED) if it is canceled (AbortIO) or the channel is stolen
  401.        (ADCMD_ALLOCATE).  ADCMD_WAITCYCLE is only asynchronous if it is
  402.        waiting for a cycle to complete, in which case it clears the quick
  403.        flag (IOF_QUICK); otherwise, it is synchronous and only replies if the
  404.        quick flag (IOF_QUICK) is clear.  Do not use ADCMD_WAITCYCLE in
  405.        interrupt code at interrupt level 5 or higher.
  406.    
  407.    INPUTS
  408.        mn_ReplyPort- pointer to message port that receives I/O request, if
  409.                      the quick flag (IOF_QUICK) is clear, or if a write is in
  410.                      progress on the selected channel and a cycle has
  411.                      completed
  412.        io_Device   - pointer to device node, must be set by (or copied from
  413.                      I/O block set by) OpenDevice function
  414.        io_Unit     - bit map of channel to wait for cycle (bits 0 thru 3
  415.                      correspond to channels 0 thru 3), if more then one bit
  416.                      is set lowest bit number channel is used
  417.        io_Command  - command number for CMD_WAITCYCLE
  418.        io_Flags    - flags, must be cleared if not used:
  419.                      IOF_QUICK - (CLEAR) reply I/O request
  420.                                  (SET) only reply I/O request if a write is
  421.                                        in progress on the selected channel
  422.                                        and a cycle has completed
  423.        ioa_AllocKey- allocation key, must be set by (or copied from I/O block
  424.                      set by) OpenDevice function or ADCMD_ALLOCATE command
  425.  
  426.    OUTPUTS
  427.        io_Unit     - bit map of channel that successfully waited for cycle
  428.                      (bits 0 thru 3 correspond to channels 0 thru 3)
  429.        io_Flags    - IOF_QUICK flag cleared if a write is in progress on the
  430.                      selected channel
  431.        io_Error    - error number:
  432.                      0                    - no error
  433.                      IOERR_ABORTED        - canceled (AbortIO) or channel
  434.                                             stolen
  435.                      ADIOERR_NOALLOCATION - allocation key (ioa_AllocKey)
  436.                                             does not match key for channel
  437.  
  438.  
  439. audio.device/CMD_CLEAR                   audio.device/command/CMD_CLEAR
  440.  
  441.    NAME
  442.        CMD_CLEAR -- throw away internal caches
  443.  
  444.    FUNCTION
  445.        CMD_CLEAR is a standard command for multiple audio channels.  For each
  446.        selected channel (io_Unit), if the allocation key (ioa_AllocKey) is
  447.        correct, CMD_CLEAR does nothing; otherwise, CMD_CLEAR returns an error
  448.        (ADIOERR_NOALLOCATION).  CMD_CLEAR is synchronous and only replies
  449.        (mn_ReplyPort) if the quick flag (IOF_QUICK) is clear.
  450.  
  451.    INPUTS
  452.        mn_ReplyPort- pointer to message port that receives I/O request after
  453.                      if the quick flag (IOF_QUICK) is clear
  454.        io_Device   - pointer to device node, must be set by (or copied from
  455.                      I/O block set by) OpenDevice function
  456.        io_Unit     - bit map of channels to clear (bits 0 thru 3 correspond
  457.                      to channels 0 thru 3)
  458.        io_Command  - command number for CMD_CLEAR
  459.        io_Flags    - flags, must be cleared if not used:
  460.                      IOF_QUICK - (CLEAR) reply I/O request
  461.        ioa_AllocKey- allocation key, must be set by (or copied from I/O block
  462.                      set by) OpenDevice function or ADCMD_ALLOCATE command
  463.  
  464.    OUTPUTS
  465.        io_Unit     - bit map of channels successfully cleared (bits 0 thru 3
  466.                      correspond to channels 0 thru 3)
  467.        io_Error    - error number:
  468.                      0                    - no error
  469.                      ADIOERR_NOALLOCATION - allocation key (ioa_AllocKey)
  470.                                             does not match key for channel
  471.  
  472.  
  473. audio.device/CMD_FLUSH                   audio.device/command/CMD_FLUSH
  474.  
  475.    NAME
  476.        CMD_FLUSH -- cancel all pending I/O
  477.  
  478.    FUNCTION
  479.        CMD_FLUSH is a standard command for multiple audio channels.  For each
  480.        selected channel (io_Unit), if the allocation key (ioa_AllocKey) is
  481.        correct, CMD_FLUSH aborts all writes (CMD_WRITE) in progress or queued
  482.        and any I/O requests waiting to synchronize with the end of the cycle
  483.        (ADCMD_WAITCYCLE); otherwise, CMD_FLUSH returns an error
  484.        (ADIOERR_NOALLOCATION).  CMD_FLUSH is synchronous and only replies
  485.        (mn_ReplyPort) if the quick flag (IOF_QUICK) is clear.  Do not use
  486.        CMD_FLUSH in interrupt code at interrupt level 5 or higher.
  487.  
  488.    INPUTS
  489.        mn_ReplyPort- pointer to message port that receives I/O request
  490.                      if the quick flag (IOF_QUICK) is clear
  491.        io_Device   - pointer to device node, must be set by (or copied from
  492.                      I/O block set by) OpenDevice function
  493.        io_Unit     - bit map of channels to flush (bits 0 thru 3 correspond
  494.                      to channels 0 thru 3)
  495.        io_Command  - command number for CMD_FLUSH
  496.        io_Flags    - flags, must be cleared if not used:
  497.                      IOF_QUICK - (CLEAR) reply I/O request
  498.        ioa_AllocKey- allocation key, must be set by (or copied from I/O block
  499.                      set by) OpenDevice function or ADCMD_ALLOCATE command
  500.  
  501.    OUTPUTS
  502.        io_Unit     - bit map of channels successfully flushed (bits 0 thru 3
  503.                      correspond to channels 0 thru 3)
  504.        io_Error    - error number:
  505.                      0                    - no error
  506.                      ADIOERR_NOALLOCATION - allocation key (ioa_AllocKey)
  507.                                             does not match key for channel
  508.  
  509.  
  510. audio.device/CMD_READ                     audio.device/command/CMD_READ
  511.  
  512.    NAME
  513.        CMD_READ -- normal I/O entry point 
  514.  
  515.    FUNCTION
  516.        CMD_READ is a standard command for a single audio channel (io_Unit).
  517.        If the allocation key (ioa_AllocKey) is correct, CMD_READ returns a
  518.        pointer (io_Data) to the I/O block currently writing (CMD_WRITE) on
  519.        the selected channel; otherwise, CMD_READ returns an error
  520.        (ADIOERR_NOALLOCATION).  If there is no write in progress, CMD_READ
  521.        returns zero.  CMD_READ is synchronous and only replies (mn_ReplyPort)
  522.        if the quick bit (IOF_QUICK) is clear.
  523.    
  524.    INPUTS
  525.        mn_ReplyPort- pointer to message port that receives I/O request after
  526.                      if the quick flag (IOF_QUICK) is clear
  527.        io_Device   - pointer to device node, must be set by (or copied from
  528.                      I/O block set by) OpenDevice function
  529.        io_Unit     - bit map of channel to read (bit 0 thru 3 corresponds to
  530.                      channel 0 thru 3), if more then one bit is set lowest
  531.                      bit number channel read
  532.        io_Command  - command number for CMD_READ
  533.        io_Flags    - flags, must be cleared if not used:
  534.                      IOF_QUICK - (CLEAR) reply I/O request
  535.        ioa_AllocKey- allocation key, must be set by (or copied from I/O block
  536.                      set by) OpenDevice function or ADCMD_ALLOCATE command
  537.  
  538.    OUTPUTS
  539.        io_Unit     - bit map of channel successfully read (bit 0 thru 3
  540.                      corresponds to channel 0 thru 3)
  541.        io_Error    - error number:
  542.                      0                    - no error
  543.                      ADIOERR_NOALLOCATION - allocation key (ioa_AllocKey)
  544.                                             does not match key for channel
  545.        ioa_Data    - pointer to I/O block for current write, zero if none is
  546.                      progress
  547.  
  548.  
  549. audio.device/CMD_RESET                   audio.device/command/CMD_RESET
  550.  
  551.    NAME
  552.        CMD_RESET -- restore device to a known state
  553.  
  554.    FUNCTION
  555.        CMD_RESET is a standard command for multiple audio channels.  For each
  556.        selected channel (io_Unit), if the allocation key (ioa_AllocKey) is
  557.        correct, CMD_RESET:
  558.          . clears the hardware audio registers and attach bits,
  559.          . sets the audio interrupt vector,
  560.          . cancels all pending I/O (CMD_FLUSH), and
  561.          . un-stops the channel if it is stopped (CMD_STOP),
  562.  
  563.        Otherwise, CMD_RESET returns an error (ADIOERR_NOALLOCATION).
  564.        CMD_RESET is synchronous and only replies (mn_ReplyPort) if the quick
  565.        flag (IOF_QUICK) is clear.  Do not use CMD_RESET in interrupt code at
  566.        interrupt level 5 or higher.
  567.    
  568.    INPUTS
  569.        mn_ReplyPort- pointer to message port that receives I/O request
  570.                      if the quick flag (IOF_QUICK) is clear
  571.        io_Device   - pointer to device node, must be set by (or copied from
  572.                      I/O block set by) OpenDevice function
  573.        io_Unit     - bit map of channels to reset (bits 0 thru 3 correspond
  574.                      to channels 0 thru 3)
  575.        io_Command  - command number for CMD_RESET
  576.        io_Flags    - flags, must be cleared if not used:
  577.                      IOF_QUICK - (CLEAR) reply I/O request
  578.        ioa_AllocKey- allocation key, must be set by (or copied from I/O block
  579.                      set by) OpenDevice function or ADCMD_ALLOCATE command
  580.  
  581.    OUTPUTS
  582.        io_Unit     - bit map of channels to successfully reset (bits 0 thru 3
  583.                      correspond to channels 0 thru 3)
  584.        io_Error    - error number:
  585.                      0                    - no error
  586.                      ADIOERR_NOALLOCATION - allocation key (ioa_AllocKey)
  587.                                             does not match key for channel
  588.  
  589.  
  590. audio.device/CMD_START                   audio.device/command/CMD_START
  591.  
  592.    NAME
  593.        CMD_START -- start device processing (like ^Q)
  594.  
  595.    FUNCTION
  596.        CMD_START is a standard command for multiple audio channels.  For each
  597.        selected channel (io_Unit), if the allocation key (ioa_AllocKey) is
  598.        correct and the channel was previously stopped (CMD_STOP), CMP_START
  599.        immediately starts all writes (CMD_WRITE) to the channel.  If the
  600.        allocation key is incorrect, CMD_START returns an error
  601.        (ADIOERR_NOALLOCATION).  CMD_START starts multiple channels
  602.        simultaneously to minimize distortion if the channels are playing the
  603.        same waveform and their outputs are mixed. CMD_START is synchronous and
  604.  
  605.        only replies (mn_ReplyPort) if the quick flag (IOF_QUICK) is clear.  Do
  606.  
  607.        not use CMD_START in interrupt code at interrupt level 5 or higher.
  608.    
  609.    INPUTS
  610.        mn_ReplyPort- pointer to message port that receives I/O request after
  611.                      if the quick flag (IOF_QUICK) is clear
  612.        io_Device   - pointer to device node, must be set by (or copied from
  613.                      I/O block set by) OpenDevice function
  614.        io_Unit     - bit map of channels to start (bits 0 thru 3 correspond
  615.                      to channels 0 thru 3)
  616.        io_Command  - command number for CMD_START
  617.        io_Flags    - flags, must be cleared if not used:
  618.                      IOF_QUICK - (CLEAR) reply I/O request
  619.        ioa_AllocKey- allocation key, must be set by (or copied from I/O block
  620.                      set by) OpenDevice function or ADCMD_ALLOCATE command
  621.  
  622.    OUTPUTS
  623.        io_Unit     - bit map of channels successfully started (bits 0 thru 3
  624.                      correspond to channels 0 thru 3)
  625.        io_Error    - error number:
  626.                      0                    - no error
  627.                      ADIOERR_NOALLOCATION - allocation key (ioa_AllocKey)
  628.                                             does not match key for channel
  629.  
  630.  
  631. audio.device/CMD_STOP                     audio.device/command/CMD_STOP
  632.  
  633.    NAME
  634.        CMD_STOP -- stop device processing (like ^S)
  635.  
  636.    FUNCTION
  637.        CMD_STOP is a standard command for multiple audio channels.  For each
  638.        selected channel (io_Unit), if the allocation key (ioa_AllocKey) is
  639.        correct, CMD_STOP immediately stops any writes (CMD_WRITE) in
  640.        progress; otherwise, CMD_STOP returns an error (ADIOERR_NOALLOCATION).
  641.        CMD_WRITE queues up writes to a stopped channel until CMD_START starts
  642.        the channel or CMD_RESET resets the channel. CMD_STOP is synchronous
  643.        and only replies (mn_ReplyPort) if the quick flag (IOF_QUICK) is
  644.        clear.  Do not use CMD_STOP in interrupt code at interrupt level 5 or
  645.        higher.
  646.  
  647.    INPUTS
  648.        mn_ReplyPort- pointer to message port that receives I/O request after
  649.                      if the quick flag (IOF_QUICK) is clear
  650.        io_Device   - pointer to device node, must be set by (or copied from
  651.                      I/O block set by) OpenDevice function
  652.        io_Unit     - bit map of channels to stop (bits 0 thru 3 correspond to
  653.                      channels 0 thru 3)
  654.        io_Command  - command number for CMD_STOP
  655.        io_Flags    - flags, must be cleared if not used:
  656.                      IOF_QUICK - (CLEAR) reply I/O request
  657.        ioa_AllocKey- allocation key, must be set by (or copied from I/O block
  658.                      set by) OpenDevice function or ADCMD_ALLOCATE command
  659.  
  660.    OUTPUTS
  661.        io_Unit     - bit map of channels successfully stopped (bits 0 thru 3
  662.                      correspond to channels 0 thru 3)
  663.        io_Error    - error number:
  664.                      0                    - no error
  665.                      ADIOERR_NOALLOCATION - allocation key (ioa_AllocKey)
  666.                                             does not match key for channel
  667.  
  668.  
  669. audio.device/CMD_UPDATE                 audio.device/command/CMD_UPDATE
  670.  
  671.    NAME
  672.        CMD_UPDATE -- force dirty buffers out
  673.  
  674.    FUNCTION
  675.        CMD_UPDATE is a standard command for multiple audio channels.  For
  676.        each selected channel (io_Unit), if the allocation key (ioa_AllocKey)
  677.        is correct, CMD_UPDATE does nothing; otherwise, CMD_UPDATE returns an
  678.        error (ADIOERR_NOALLOCATION).  CMD_UPDATE is synchronous and only
  679.        replies (mn_ReplyPort) if the quick flag (IOF_QUICK) is clear.
  680.  
  681.    INPUTS
  682.        mn_ReplyPort- pointer to message port that receives I/O request after
  683.                      if the quick flag (IOF_QUICK) is clear
  684.        io_Device   - pointer to device node, must be set by (or copied from
  685.                      I/O block set by) OpenDevice function
  686.        io_Unit     - bit map of channels to update (bits 0 thru 3 correspond
  687.                      to channels 0 thru 3)
  688.        io_Command  - command number for CMD_UPDATE
  689.        io_Flags    - flags, must be cleared if not used:
  690.                      IOF_QUICK - (CLEAR) reply I/O request
  691.        ioa_AllocKey- allocation key, must be set by (or copied from I/O block
  692.                      set by) OpenDevice function or ADCMD_ALLOCATE command
  693.  
  694.    OUTPUTS
  695.        io_Unit     - bit map of channels successfully updated (bits 0 thru 3
  696.                      correspond to channels 0 thru 3)
  697.        io_Error    - error number:
  698.                      0                    - no error
  699.                      ADIOERR_NOALLOCATION - allocation key (ioa_AllocKey)
  700.                                             does not match key for channel
  701.  
  702.  
  703. audio.device/CMD_WRITE                   audio.device/command/CMD_WRITE
  704.  
  705.    NAME
  706.        CMD_WRITE -- normal I/O entry point 
  707.  
  708.    FUNCTION
  709.        CMD_WRITE is a standard command for a single audio channel (io_Unit).
  710.        If the allocation key (ioa_AllocKey) is correct, CMD_WRITE plays a
  711.        sound using the selected channel; otherwise, it returns an error
  712.        (ADIOERR_NOALLOCATION).  CMD_WRITE queues up requests if there is
  713.        another write in progress or if the channel is stopped (CMD_STOP).
  714.        When the write actually starts; if the ADIOF_PERVOL flag is set,
  715.        CMD_WRITE loads volume (ioa_Volume) and period (ioa_Period), and if
  716.        the ADIOF_WRITEMESSAGE flag is set, CMD_WRITE replies the write
  717.        message (ioa_WriteMsg).  CMD_WRITE returns an error (IOERR_ABORTED) if
  718.        it is canceled (AbortIO) or the channel is stolen (ADCMD_ALLOCATE).
  719.        CMD_WRITE is only asynchronous if there is no error, in which case it
  720.        clears the quick flag (IOF_QUICK) and replies the I/O request
  721.        (mn_ReplyPort) after it finishes writting; otherwise, it is synchronous
  722.  
  723.        and only replies if the quick flag (IOF_QUICK) is clear.  Do not use
  724.        CMD_WRITE in interrupt code at interrupt level 5 or higher.
  725.    
  726.    INPUTS
  727.        mn_ReplyPort- pointer to message port that receives I/O request after
  728.                      the write completes
  729.        io_Device   - pointer to device node, must be set by (or copied from
  730.                      I/O block set by) OpenDevice function
  731.        io_Unit     - bit map of channel to write (bit 0 thru 3 corresponds to
  732.                      channel 0 thru 3), if more then one bit is set lowest
  733.                      bit number channel is written
  734.        io_Command  - command number for CMD_WRITE
  735.        io_Flags    - flags, must be cleared if not used:
  736.                      ADIOF_PERVOL       - (SET) load volume and period
  737.                      ADIOF_WRITEMESSAGE - (SET) reply message at write start
  738.        ioa_AllocKey- allocation key, must be set by (or copied from I/O block
  739.                      set by) OpenDevice function or ADCMD_ALLOCATE command
  740.        ioa_Data    - pointer to waveform array (signed bytes (-128 thru 127)
  741.                      in custom chip addressable ram and word aligned)
  742.        ioa_Length  - length of the wave array in bytes (2 thru 131072, must
  743.                      be even number)
  744.        ioa_Period  - sample period in 279.365 ns increments (124 thru 65536,
  745.                      anti-aliasing filter works below 300 to 500 depending on
  746.                      waveform), if enabled by ADIOF_PERVOL
  747.        ioa_Volume  - volume (0 thru 64, linear), if enabled by ADIOF_PERVOL
  748.        ioa_Cycles  - number of times to repeat array (0 thru 65535, 0 for
  749.                      infinite)
  750.        ioa_WriteMsg- message replied at start of write,  if enabled by
  751.                      ADIOF_WRITEMESSAGE
  752.  
  753.    OUTPUTS
  754.        io_Unit     - bit map of channel successfully written (bit 0 thru 3
  755.                      corresponds to channel 0 thru 3)
  756.        io_Flags    - IOF_QUICK flag cleared if there is no error
  757.        io_Error    - error number:
  758.                      0                    - no error
  759.                      IOERR_ABORTED        - canceled (AbortIO) or channel
  760.                                             stolen
  761.                      ADIOERR_NOALLOCATION - allocation key (ioa_AllocKey)
  762.                                             does not match key for channel
  763.  
  764.    BUGS
  765.        If CMD_WRITE starts the write immediately after stopping a previous
  766.        write, you must set the ADIOF_PERVOL flag or else the new data pointer
  767.        (ioa_Data) and length (ioa_Length) may not be loaded.
  768.        
  769.  
  770. audio.device/OpenDevice                                 audio.device/OpenDevice
  771.  
  772.    NAME
  773.        OpenDevice - open the audio device 
  774.  
  775.    SYNOPSIS
  776.        error = OpenDevice("audio.device", unitNumber, iORequest, flags);
  777.  
  778.    FUNCTION
  779.        The OpenDevice routine grants access to the audio device.  It takes an
  780.        I/O audio request block (iORequest) and if it can successfully open
  781.        the audio device, it loads the device pointer (io_Device) and the
  782.        allocation key (ioa_AllocKey); otherwise, it returns an error
  783.        (IOERR_OPENFAIL).  OpenDevice increments the open count keeping the
  784.        device from being expunged (Expunge).  If the length (ioa_Length) is
  785.        non-zero, OpenDevice tries to allocate (ADCMD_ALLOCATE) audio channels
  786.        from a array of channel combination options (ioa_Data). If the
  787.        allocation succeeds, the allocated channel combination is loaded into
  788.        the unit field (ioa_Unit); otherwise, OpenDevice returns an error
  789.        (ADIOERR_ALLOCFAILED).  OpenDevice does not wait for allocation to
  790.        succeed and closes (CloseDevice) the audio device if it fails.  To
  791.        allocate channels, OpenDevice also requires a properly initialized
  792.        reply port (mn_ReplyPort) with an allocated signal bit.
  793.  
  794.    INPUTS
  795.        unitNumber- not used
  796.        iORequest - pointer to audio request block (struct IOAudio)
  797.                ln_Pri      - allocation precedence (-128 thru 127), only
  798.                              necessary for allocation (non-zero length)
  799.                mn_ReplyPort- pointer to message port for allocation, only
  800.                              necessary for allocation (non-zero length)
  801.                ioa_AllocKey- allocation key; zero to generate new key.
  802.                              Otherwise, it must be set by (or copied from I/O
  803.                              block that is set by) previous OpenDevice
  804.                              function or ADCMD_ALLOCATE command (non-zero
  805.                              length)    
  806.                ioa_Data    - pointer to channel combination options (byte
  807.                              array, bits 0 thru 3 correspond to channels 0
  808.                              thru 3), only necessary for allocation (non-zero
  809.                              length)
  810.                ioa_Length  - length of the channel combination option array 
  811.                              (0 thru 16), zero for no allocation
  812.        flags     - not used
  813.  
  814.    OUTPUTS
  815.        iORequest - pointer to audio request block (struct IOAudio)
  816.                io_Device   - pointer to device node if OpenDevice succeeds,
  817.                              otherwise -1
  818.                io_Unit     - bit map of successfully allocated channels (bits
  819.                              0 thru 3 correspond to channels 0 thru 3)
  820.                io_Error    - error number:
  821.                              0                   - no error
  822.                              IOERR_OPENFAIL      - open failed
  823.                              ADIOERR_ALLOCFAILED - allocation failed, no open
  824.                ioa_AllocKey- allocation key, set to a unique number if passed
  825.                              a zero and OpenDevice succeeds
  826.        error     - copy of io_Error
  827.  
  828.