home *** CD-ROM | disk | FTP | other *** search
/ Amiga Developer CD v1.2 / amidev_cd_12.iso / inc&ad2.0 / text_autodocs / cia.doc < prev    next >
Text File  |  1992-09-01  |  8KB  |  246 lines
  1. TABLE OF CONTENTS
  2.  
  3. cia.resource/AbleICR
  4. cia.resource/AddICRVector
  5. cia.resource/RemICRVector
  6. cia.resource/SetICR
  7. cia.resource/AbleICR                                     cia.resource/AbleICR
  8.  
  9.    NAME
  10.     AbleICR -- Enable/disable ICR interrupts.
  11.  
  12.    SYNOPSIS
  13.     oldMask = AbleICR( Resource, mask )
  14.     D0                 A6        D0
  15.  
  16.     WORD AbleICR( struct Library *, WORD );
  17.  
  18.    FUNCTION
  19.     This function provides a means of enabling and disabling 8520
  20.     CIA interrupt control registers. In addition it returns the
  21.     previous enable mask.
  22.  
  23.    INPUTS
  24.     mask            A bit mask indicating which interrupts to be
  25.                         modified. If bit 7 is clear the mask
  26.                         indicates interrupts to be disabled. If
  27.                         bit 7 is set, the mask indicates
  28.                         interrupts to be enabled. Bit positions
  29.                         are identical to those in 8520 ICR.
  30.  
  31.    RESULTS
  32.     oldMask         The previous enable mask before the requested
  33.                         changes. To get the current mask without
  34.                         making changes, call the function with a
  35.                         null parameter.
  36.  
  37.    EXAMPLES
  38.     Get the current mask:
  39.         mask = AbleICR(0)
  40.     Enable both timer interrupts:
  41.         AbleICR(0x83)
  42.     Disable serial port interrupt:
  43.         AbleICR(0x08)
  44.  
  45.    EXCEPTIONS
  46.     Enabling the mask for a pending interrupt will cause an
  47.     immediate processor interrupt (that is if everything else is
  48.     enabled). You may want to clear the pending interrupts with
  49.     SetICR() prior to enabling them.
  50.  
  51.    NOTE
  52.     The CIA resources are special in that there is more than one
  53.     of them in the system. Because of this, the C language stubs
  54.     in amiga.lib for the CIA resources require an extra parameter
  55.     to specify which CIA resource to use. The synopsys for the
  56.     amiga.lib stubs is as follows:
  57.  
  58.     oldMask = AbleICR( Resource, mask )
  59.     D0                 A6        D0
  60.  
  61.     WORD AbleICR( struct Library *, WORD );
  62.  
  63.    SEE ALSO
  64.     cia.resource/SetICR()
  65.  
  66. cia.resource/AddICRVector                           cia.resource/AddICRVector
  67.  
  68.    NAME
  69.     AddICRVector -- attach an interrupt handler to a CIA bit.
  70.  
  71.    SYNOPSIS
  72.     interrupt = AddICRVector( Resource, iCRBit, interrupt )
  73.     D0                        A6        D0      A1
  74.  
  75.     struct Interrupt *AddICRVector( struct Library *, WORD,
  76.         struct Interrupt * );
  77.  
  78.    FUNCTION
  79.     Assign interrupt processing code to a particular interrupt bit
  80.     of the CIA ICR.  If the interrupt bit has already been
  81.     assigned, this function will fail, and return a pointer to the
  82.     owner interrupt.  If it succeeds, a null is returned.
  83.  
  84.     This function will also enable the CIA interrupt for the given
  85.     ICR bit.
  86.  
  87.    INPUTS
  88.     iCRBit          Bit number to set (0..4).
  89.     interrupt       Pointer to interrupt structure.
  90.  
  91.    RESULT
  92.     interrupt       Zero if successful, otherwise returns a
  93.                         pointer to the current owner interrupt
  94.                         structure.
  95.  
  96.    NOTE
  97.     A processor interrupt may be generated immediatly if this call
  98.     is successful.
  99.  
  100.     In general, it is probably best to only call this function
  101.     while DISABLED so that the resource to which the interrupt
  102.     handler is being attached may be set to a known state before
  103.     the handler is called. You MUST NOT change the state of the
  104.     resource before attaching your handler to it.
  105.  
  106.     The CIA resources are special in that there is more than one
  107.     of them in the system. Because of this, the C language stubs
  108.     in amiga.lib for the CIA resources require an extra parameter
  109.     to specify which CIA resource to use. The synopsys for the
  110.     amiga.lib stubs is as follows:
  111.  
  112.     interrupt = AddICRVector( Resource, iCRBit, interrupt )
  113.     D0                        A6        D0      A1
  114.  
  115.     struct Interrupt *AddICRVector( struct Library *, WORD,
  116.         struct Interrupt *);
  117.  
  118.     ***WARNING***
  119.  
  120.     Never assume that any of the CIA hardware is free for use.
  121.     Always use the AddICRVector() function to obtain ownership
  122.     of the CIA hardware registers your code will use.
  123.  
  124.     Note that there are two (2) interval timers per CIA.  If
  125.     your application needs one of the interval timers, you
  126.     can try to obtain any one of the four (4) until AddICRVector()
  127.     succeeds.  If all four interval timers are in-use, your
  128.     application should exit cleanly.
  129.  
  130.     If you just want ownership of a CIA hardware timer, or register,
  131.     but do not want interrupts generated, use the AddICRVector()
  132.     function to obtain ownership, and use the AbleICR() function
  133.     to turn off (or on) interrupts as needed.
  134.  
  135.     Note that CIA-B generates level 6 interrupts (which can degrade
  136.     system performance by blocking lower priority interrupts).  As
  137.     usual, interrupt handling code should be optimized for speed.
  138.  
  139.     Always call RemICRVector() when your code exits to release
  140.     ownership of any CIA hardware obtained with AddICRVector().
  141.  
  142.    SEE ALSO
  143.     cia.resource/RemICRVector(), cia.resource/AbleICR()
  144.  
  145. cia.resource/RemICRVector                           cia.resource/RemICRVector
  146.  
  147.    NAME
  148.     RemICRVector -- Detach an interrupt handler from a CIA bit.
  149.  
  150.    SYNOPSIS
  151.     RemICRVector( Resource, iCRBit, interrupt )
  152.                   A6        D0      A1
  153.  
  154.     void RemICRVector( struct Library *, WORD, struct Interrupt *);
  155.  
  156.    FUNCTION
  157.     Disconnect interrupt processing code for a particular
  158.     interrupt bit of the CIA ICR.
  159.  
  160.     This function will also disable the CIA interrupt for the
  161.     given ICR bit.
  162.  
  163.    INPUTS
  164.     iCRBit          Bit number to set (0..4).
  165.     interrupt       Pointer to interrupt structure.
  166.  
  167.    RESULT
  168.  
  169.    NOTE
  170.     The CIA resources are special in that there is more than one
  171.     of them in the system. Because of this, the C language stubs
  172.     in amiga.lib for the CIA resources require an extra parameter
  173.     to specify which CIA resource to use. The synopsys for the
  174.     amiga.lib stubs is as follows:
  175.  
  176.     RemICRVector( Resource, iCRBit, interrupt )
  177.                   A6        D0      A1
  178.  
  179.     void RemICRVector( struct Library *, WORD, struct Interrupt *);
  180.  
  181.    SEE ALSO
  182.     cia.resource/AddICRVector()
  183.  
  184. cia.resource/SetICR                                       cia.resource/SetICR
  185.  
  186.    NAME
  187.     SetICR -- Cause, clear, and sample ICR interrupts.
  188.  
  189.    SYNOPSIS
  190.     oldMask = SetICR( Resource, mask )
  191.     D0                A6        D0
  192.  
  193.     WORD SetICR( struct Library *, WORD );
  194.  
  195.    FUNCTION
  196.     This function provides a means of reseting, causing, and
  197.     sampling 8520 CIA interrupt control registers.
  198.  
  199.    INPUTS
  200.     mask            A bit mask indicating which interrupts to be
  201.                         effected. If bit 7 is clear the mask
  202.                         indicates interrupts to be reset.  If bit
  203.                         7 is set, the mask indicates interrupts to
  204.                         be caused. Bit positions are identical to
  205.                         those in 8520 ICR.
  206.  
  207.    RESULTS
  208.     oldMask         The previous interrupt register status before
  209.                         making the requested changes.  To sample
  210.                         current status without making changes,
  211.                         call the function with a null parameter.
  212.  
  213.    EXAMPLES
  214.     Get the interrupt mask:
  215.         mask = SetICR(0)
  216.     Clear serial port interrupt:
  217.         SetICR(0x08)
  218.  
  219.    NOTE
  220.     The CIA resources are special in that there is more than one
  221.     of them in the system. Because of this, the C language stubs
  222.     in amiga.lib for the CIA resources require an extra parameter
  223.     to specify which CIA resource to use. The synopsys for the
  224.     amiga.lib stubs is as follows:
  225.  
  226.     oldMask = SetICR( Resource, mask )
  227.     D0                A6        D0
  228.  
  229.     WORD SetICR( struct Library *, WORD );
  230.  
  231.     ***WARNING***
  232.  
  233.     Never read the contents of the CIA interrupt control registers
  234.     directly.  Reading the contents of one of the CIA interrupt
  235.     control registers clears the register.  This can result in
  236.     interrupts being missed by critical operating system code, and
  237.     other applications.
  238.  
  239.    EXCEPTIONS
  240.     Setting an interrupt bit for an enabled interrupt will cause
  241.     an immediate interrupt.
  242.  
  243.    SEE ALSO
  244.     cia.resource/AbleICR()
  245.  
  246.