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