<sect>DOSEmu Programmable Interrupt Controller
<p>
     This emulation, in files picu.c and picu.h, emulates all of the useful
  features of the two 8259 programmable interrupt controllers.  Support
  includes these i/o commands:

<descrip>
      <tag/ICW1    bits 0 and 1/     number of ICWs to expect
      <tag/ICW2    bits 3 - 7/       base address of IRQs
      <tag/ICW3    no bits/          accepted but ignored
      <tag/ICW4    no bits/          accepted but ignored

      <tag/OCW1    all bits/         sets interrupt mask
      <tag/OCW2    bits 7,5-0/       EOI commands only
      <tag/OCW3    bits 0,1,5,6/     select read register, 
                               select special mask mode
</descrip>

  Reads of both PICs ports are supported completely.
  <p>
<sect1>  Other features
<p>  
<itemize>
<item>     Support for 16 additional lower priority interrupts.  Interrupts
  are run in a fully nested fashion.  All interrupts call dosemu functions,
  which may then determine if the vm mode interrupt should be executed.  The
  vm mode interrupt is executed via a function call.

<item>     Limited support for the non-maskable interrupt.  This is handled the
  same way as the extra low priority interrupts, but has the highest
  priority of all.

<item>       Masking is handled correctly: masking bit 2 of PIC0 also masks all
  IRQs on PIC1.
  
<item>     An additional mask register is added for use by dosemu itself.  This
  register initially has all interrupts masked, and checks that a dosemu
  function has been registered for the interrupt before unmasking it.
  
<item>     Dos IRQ handlers are deemed complete when they notify the PIC via 
  OCW2 writes.  The additional lower priority interrupts are deemed 
  complete as soon as they are successfully started.
  
<item>     Interrupts are triggered when the PIC emulator, called in the vm86
  loop, detects a bit set in the interrupt request register.  This
  register is a global variable, so that any dosemu code can easily trigger
  an interrupt.
</itemize>
  
<sect1>  Caveats
  <p>
     OCW2 support is not exactly correct for IRQs 8 - 15.  The correct
  sequence is that an OCW2 to PIC0 enables IRQs 0, 1, 3, 4, 5, 6, and 7;
  and an OCW2 to PIC1 enables IRQs 8-15 (IRQ2 is really IRQ9).  This
  emulation simply enables everything after two OCW2s, regardless of
  which PIC they are sent to.
<p>     
     OCW2s reset the currently executing interrupt, not the highest
  priority one, although the two should always be the same, unless some
  dos programmer tries special mask mode.  This emulation works correctly
  in special mask mode:  all types of EOIs (specific and non-specific) are 
  treated as specific EOIs to the currently executing interrupt.  The
  interrupt specification in a specific EOI is ignored.
  <p>
     Modes not supported:
<itemize>     
<item>     Auto-EOI (see below)
<item>     8080-8085
<item>     Polling
<item>     Rotating Priority
</itemize>
     
  None of these modes is useable in a PC, anyway.  The 16 additional
  interrupts are run in Auto-EOI mode, since any dos code for them
  shouldn't include OCW2s.  The level 0 (NMI) interrupt is also handled
  this way.
     
<sect1>Notes on theory of operation:
  <p>
     The documentation refers to levels.  These are priority levels,
  the lowest (0) having highest priority.  Priority zero is reserved
  for use by NMI.  The levels correspond with IRQ numbers as follows:
  
<tscreen><verb>
  IRQ0=1  IRQ1=2   IRQ8=3  IRQ9=4  IRQ10=5 IRQ11=6 IRQ12=7 IRQ13=8
  IRQ14=9 IRQ15=10 IRQ3=11 IRQ4=12 IRQ5=13 IRQ6=14 IRQ7=15
</verb></tscreen>
  
  There is no IRQ2; it's really IRQ9.
<p>  
  There are 16 more levels (16 - 31) available for use by dosemu functions.
<p>  
  If all levels were activated, from 31 down to 1 at the right rate, the
  two functions run_irqs() and do_irq() could recurse up to 15 times.  No
  other functions would recurse; however a top level interrupt handler
  that served more than one level could get re-entered, but only while the
  first level started was in a call to do_irq().  If all levels were
  activated at once, there would be no recursion.  There would also be no
  recursion if the dos irq code didn't enable interrupts early, which is
  quite common.
    
<sect2>Functions supported from DOSEmu side
<p>
<sect3>Functions that Interface with DOS:
<p>
<descrip>  
  <tag>unsigned char read_picu0(port),
  unsigned char read_picu1(port)</tag>
  
  should be called by the i/o handler whenever a read of the PIC i/o ports
  is requested.  The "port" parameter is either a 0 or a 1; for PIC0 these
  correspond to i/o addresses 0x20 and 0x21.  For PIC1 they correspond with
  i/o addresses 0xa0 and 0xa1.  The returned value is the byte that was
  read.
  
  <tag>void write_picu0(port,unsigned char value),
  void write_picu1(port,unsigned char value)</tag>
  
  should be called by the i/o handler whenever a write to a PIC port is
  requested.  Port mapping is the same as for read_picu, above.  The value
  to be written is passed in parameter "value".
  
  <tag>int do_irq()</tag>
  
  is the function that actually executes a dos interrupt.  do_irq() looks
  up the correct interrupt, and if it points to the dosemu "bios", does
  nothing and returns a 1.  It is assumed that the calling function will
  test this value and run the dosemu emulation code directly if needed.
  If the interrupt is revectored to dos or application code, run_int() is
  called, followed by a while loop executing the standard run_vm86() and
  other calls.  The in-service register is checked by the while statement,
  and when the necessary OCW2s have been received, the loop exits and
  a 0 is returned to the caller.  Note that the 16 interrupts that are not
  part of the standard AT PIC system will not be writing OCW2s; for these
  interrupts the vm86 loop is executed once, and control is returned before
  the corresponding dos code has completed.  If run_int() is called, the
  flags, cs, and ip are pushed onto the stack, and cs:ip is pointed to
  PIC_SEG:PIC_OFF in the bios, where there is a hlt instruction.  This is
  handled by pic_iret.
<p>
  Since the while loop above checks for interrupts, this function can be
  re-entered.  In the worst case, a total of about 1k of process stack space
  could be needed.
  
  <tag>pic_sti(),
  pic_cli()</tag>

  These are really macros that should be called when an sti or cli
  instruction is encountered.  Alternately, these could be called as part of
  run_irqs() before anything else is done, based on the condition of the
  vm86 v_iflag.  Note that pic_cli() sets the pic_iflag to a non-zero value,
  and pic_sti() sets pic_iflag to zero.

  <tag>pic_iret()</tag>

  should be called whenever it is reasonably certain that an iret has
  occurred.  This call need not be done at exactly the right time, its
  only function is to activate any pending interrupts.  A pending interrupt
  is one which was self-scheduled.  For example, if the IRQ4 code calls
  pic_request(PIC_IRQ4), the request won't have any effect until after
  pic_iret() is called.  It is held off until this call in an effort 
  to avoid filling up the stack.  If pic_iret() is called too soon,
  it may aggravate stack overflow problems.  If it is called too late,
  a self-scheduled interrupt won't occur quite as soon.  To guarantee
  that pic_iret will be called, do_irq saves the real return address on the
  stack, then pushes the address of a hlt, which generates a SIGSEGV.
  Because the SIGSEGV comes before the hlt, pic_iret can be called by the
  signal handler, as well as from the vm86 loop.  In either case, pic_iret
  looks for this situation, and pops the real flags, cs, and ip.
</descrip>

<sect2>Other Functions
<p>  
<descrip>
  <tag>void run_irqs()</tag>
  
     causes the PIC code to run all requested interrupts, in priority order.
  The execution of this function is described below.
  <p>
     First we save the old interrupt level.  Then *or* the interrupt mask
  and the in-service register, and use the complement of that to mask off
  any interrupt requests that are inhibited.  Then we enter a loop, looking
  for any bits still set.  When one is found, it's interrupt level is
  compared with the old level, to make sure it is a higher priority.  If
  special mask mode is set, the old level is biased so that this test can't
  fail.  Once we know we want to run this interrupt, the request bit is
  atomicly cleared and double checked (in case something else came along and 
  cleared it somehow).  Finally, if the bit was actually cleared by this
  code, the appropriate bit is set in the in-service register.  The second
  pic register (for PIC1) is also set if needed.  Then the user code
  registered for this interrupt is called.  Finally, when the user code
  returns, the in-service register(s) are reset, the old interrupt level is
  restored, and control is returned to the caller.  The assembly language
  version of this funcction takes up to about 16 486 clocks if no request 
  bits are set, plus 100-150 clocks for each bit that is set in the request
  register.


  <tag>void picu_seti(unsigned int level,void (*func), unsigned int ivec)</tag>
  
  sets the interrupt vector and emulator function to be called then the
  bit of the interrupt request register corresponding to level is set.
  The interrupt vector is ignored if level<16, since those vectors are
  under the control of dos.  If the function is specified as NULL, the
  mask bit for that level is set.
  
  <tag>void picu_maski(int level)</tag>
  
  sets the emulator mask bit for that level, inhibiting its execution.
  
  
  <tag>void picu_unmask(int ilevel)</tag>
  
  checks if an emulator function is assigned to the given level.  If so,
  the mask bit for the level is reset.

  <tag>void pic_watch()</tag>

  runs periodically and checks for 'stuck' interrupt requests.  These
  can happen if an irq causes a stack switch and enables interrupts
  before returning.  If an interrupt is stuck this way for 2 successive
  calls to pic_watch, that interrupt is activated.
</descrip>

<sect1>A (very) little technical information for the curious
<p>
There are two big differences when using pic.  First, interrupts are not
queued beyond a depth of 1 for each interrupt.  It is up to the interrupt
code to detect that further interrupts are required and reschedule itself.
Second, interrupt handlers are designated at dosemu initialization time.
Triggering them involves merely specifying the appropriate irq.
<p>
Since timer interrupts are always spaced apart, the lack of queueing has no
effect on them.  The keyboard interrupts are re-scheduled if there is
anything in the scan_queue.  

