  The DOSEMU Alterer Novices Guide DANG
  Alistair MacDonald, am20@unix.york.ac.uk
  For DOSEMU v pl

  This Document is the DOSEMU Alterer Novices Guide. It is known as the
  DANG.

  1.  Introduction

  This document is the preliminary draft of a manual to help people
  understand the inner workings of dosemu.  It is the goal of this
  document to create new dosemu hackers.  This concept was inspired by
  the linux kernel hackers guide.

  This Guide was concieved and originally written by "Corey Sweeney"
  <corey@amiganet.chi.il.us>. It has been completely revised. It is now
  generated automatically directly from the source code. Special thanks
  to "James B. MacLean" <jmaclean@fox.nstn.ns.ca> for supplying the
  original information. (It was mostly ripped out of a mail message.)
  "Jochen Hein" has made many useful comments & suggestions.

  At the end if this document is a section detailing how this guide is
  put together. This may help you when trying to locate the relevant
  pieces of code. If you add new code, it would be useful if the
  relevant markers are added where appropriate.

  This file is a collective effort. If you don't like one of the
  explanations, or want to add anything, please send me something!





  2.  The Main group of Modules

  These files are used to start DOSEMU as well as hold globally called
  functions and global vars.



  2.1.	dos.c Information

  Initial program executed to run DOSEMU. Gets access to libdosemu and
  sets international character parms. Finally calls entry point of
  DOSEMU emulate() function which is loaded above the usual DOS memory
  area from 0 - 1meg. Emulate() is in emu.c.



  2.1.1.  Functions in dos.c

  These are the functions defined in dos.c.


  2.1.1.1.  dosemu


  o  argc - Count of argumnents.

  o  argc - Actual arguments.

     Function created by entry point into libdosemu. Called to jump into
     the emulate function of DOSEMU.



  2.1.2.  Remarks in dos.c

  Apparently, no-one has anything interesting to say about dos.c.


  2.1.3.  Items for Fixing in dos.c

  Apparently, nothing needs fixing in dos.c.


  2.1.4.  New Ideas for dos.c

  Apparently, there are no new ideas for dos.c.


  2.2.	emu.c Information

  Here is where DOSEMU gets booted. From emu.c external calls are made
  to the specific I/O systems (video/keyboard/serial/etc...) to
  initialize them. Memory is cleared/set up and the boot sector is read
  from the boot drive. Many SIGNALS are set so that DOSEMU can exploit
  things like timers, I/O signals, illegal instructions, etc... When
  every system gives the green light, vm86() is called to switch into
  vm86 mode and start executing i86 code.

  The vm86() function will return to DOSEMU when certain `exceptions`
  occur as when some interrupt instructions occur (0xcd).

  The top level function emulate() is called from dos.c by way of a dll
  entry point.



  2.2.1.  Functions in emu.c

  These are the functions defined in emu.c.


  2.2.1.1.  jmp_emulate

  call the emulate function by way of the dll headers. Always make sure
  that this line is the first of emu.c and link emu.o as the first
  object file to the lib



  2.2.1.2.  run_vm86

  which also has the registers that it will be called with. It will stop
  vm86 mode for many reasons, like trying to execute an interrupt, doing
  port I/O to ports not opened for I/O, etc ...



  2.2.1.3.  SIG_int

  Requires the sig/sillyint.o driver loaded (using NEW modules package),
  or a kernel patch (implementing sig/int.c driver).  The IRQ numbers to
  monitor are taken from config.sillyint, each bit corresponding to one
  IRQ. The higher 16 bit are defining the use of SIGIO






  2.2.1.4.  emulate

  prepare it for running in vm86 mode. This involves catching signals,
  preparing memory, calling all the initialization functions for the I/O
  subsystems (video/serial/etc...), getting the boot sector instructions
  and calling vm86().



  2.2.1.5.  io_select_init

  NON-SIGIO.



  2.2.1.6.  add_to_io_select


  o  Specifiy whether you want SIGIO (1) if it's available, or not (0).

     whether the kernel can handle SIGIO.



  2.2.1.7.  remove_from_io_select


  o  Specifiy whether you used SIGIO (1) if it's available, or not (0).

     on whether the kernel can handle SIGIO.



  2.2.2.  Remarks in emu.c

  DOSEMU must not work within the 1 meg DOS limit, so start of code is
  loaded at a higher address, at some time this could conflict with
  other shared libs. If DOSEMU is compiled statically (without shared
  libs), and org instruction is used to provide the jump above 1 meg.
  -----

  At this time we have to use SIGALRM in addition to SIGIO I don't (yet)
  know why the SIGIO signal gets lost sometimes (once per minute or
  longer). But if it happens, we can retrigger this way over SIGALRM.
  Normally SIGIO happens before SIGALARM, so nothing hurts. (Hans)


  2.2.3.  Items for Fixing in emu.c

  Apparently, nothing needs fixing in emu.c.


  2.2.4.  New Ideas for emu.c

  Apparently, there are no new ideas for emu.c.


  2.3.	include/emu.h Information

  There appears to be no MODULE information for this file.


  2.3.1.  Functions in include/emu.h

  These are the functions defined in include/emu.h.

  2.3.1.1.  NEWSETQSIG


  o  sig - the signal to have a handler installed to.

  o  fun - the signal handler function to install

     All signals that wish to be handled properly in context with the
     execution of vm86() mode, and signals that wish to use non-
     reentrant functions should add themselves to the SIGNALS_THAT_QUEUE
     define and use SETQSIG(). To that end they will also need to be set
     up in an order such as SIGIO.



  2.3.2.  Remarks in include/emu.h

  The `vm86_struct` is used to pass all the necessary status/registers
  to DOSEMU when running in vm86 mode.

  -----

  We assume system call restarting... under linux 0.99pl8 and earlier,
  this was the default.	SA_RESTART was defined in 0.99pl8 to explicitly
  request restarting (and thus does nothing).  However, if this ever
  changes, I want to be safe

  -----

  DOSEMU keeps system wide configuration status in a structure called
  config.

  -----

  The var `fatalerr` can be given a true value at any time to have
  DOSEMU exit on the next return from vm86 mode.


  2.3.3.  Items for Fixing in include/emu.h

  Apparently, nothing needs fixing in include/emu.h.


  2.3.4.  New Ideas for include/emu.h

  Apparently, there are no new ideas for include/emu.h.


  3.  The Clients group of Modules

  One of the long term aims of the DOSEMU development team is to provide
  a client-server based system. This will allow people to add different
  display systems in more simply. Those in current development are
  detailed in this section.



  3.1.	clients/ncurses.c Information

  There appears to be no MODULE information for this file.


  3.1.1.  Functions in clients/ncurses.c

  We appear to have no information on the functions in
  clients/ncurses.c.
  3.1.2.  Remarks in clients/ncurses.c

  Apparently, no-one has anything interesting to say about
  clients/ncurses.c.


  3.1.3.  Items for Fixing in clients/ncurses.c

  Apparently, nothing needs fixing in clients/ncurses.c.


  3.1.4.  New Ideas for clients/ncurses.c

  Apparently, there are no new ideas for clients/ncurses.c.


  4.  The DPMI group of Modules

  DPMI is Lutz's Baby. It's a really important part of the Emulator as
  far as we are concerned, since it will allow us to run so many more
  programs and, most importantly, bcc. This is the one thing that the
  WINE developers want that we haven't been able to give them.

  Now that Dong has come on mainstream, these two gurus are creating
  patches hand over fist as we approach being able to run Windows 3.1

  If you think you can help .... "Away you Go!" (Sorry to those non-UK
  folks ...  Thats a reference to a UK kids sports programme from my
  youth ... anyway ...	enough of this banter. You'll be wanting to know
  that this is all about DPMI ...)



  4.1.	dpmi/dpmi.c Information

  dpmi.c

  DOS Protected Mode Interface allows DOS programs to run in the
  protected mode of 2345..86 processors



  4.1.1.  Functions in dpmi/dpmi.c

  These are the functions defined in dpmi/dpmi.c.


  4.1.1.1.  dpmi_control

  This function is similar to the vm86() syscall in the kernel and
  switches to dpmi code.



  4.1.1.2.  run_pm_int

  This routine is used for running protected mode hardware interrupts
  and software interrupts 0x1c, 0x23 and 0x24.	run_pm_int() switches to
  the locked protected mode stack and calls the handler. If no handler
  is installed the real mode interrupt routine is called.






  4.1.1.3.  do_default_cpu_exception

  This is the default CPU exception handler.  Exceptions 0, 1, 2, 3, 4,
  5 and 7 are reflected to real mode. All other exceptions are
  terminating the client (and may be dosemu too :-)).



  4.1.1.4.  do_cpu_exception

  This routine switches to the locked protected mode stack, disables
  interrupts and calls the DPMI client exception handler.  If no handler
  is installed the default handler is called.



  4.1.1.5.  dpmi_fault

  This is the brain of DPMI. All CPU exceptions are first reflected
  (from the signal handlers) to this code.  Exception from nonpriveleged
  instructions INT XX, STI, CLI, HLT and from WINDOWS 3.1 are handled
  here.	All here unhandled exceptions are reflected to
  do_cpu_exception()



  4.1.2.  Remarks in dpmi/dpmi.c

  We are caching ldt here for speed reasons and for Windows 3.1.  I
  would love to have an readonly ldt-alias (located in the first 16MByte
  for use with 16-Bit descriptors (WIN-LDT)). This is on my wish list
  for the kernel hackers (Linus mainly) :-))))))).


  -----

  DPMI is designed such that the stack change needs a task switch.  We
  are doing it via an SIGSEGV - instead of one task switch we have now
  four :-(.  Arrgh this is the point where I should start to include
  DPMI stuff in the kernel, but then we could include the rest of dosemu
  too.	Would Linus love this? I don't :-((((.	Anyway I would love to
  see first a working DPMI port, maybe we will later (with version 0.9
  or similar :-)) start with it to get a really fast dos
  emulator...............


  -----

  Handling of the virtuell interruptflag is still not correct and there
  are many open questions since DPMI specifications are unclear in this
  point.  An example: If IF=1 in protected mode and real mode code is
  called which is disabling interrupts via cli and returning to
  protected mode, is IF then still one or zero?	I guess I have to think
  a lot about this and to write a small dpmi client running under a
  commercial dpmi server :-).


  4.1.3.  Items for Fixing in dpmi/dpmi.c

  We shouldn't return to dosemu code if IF=0, but it helps - WHY?

  -----

  we should not change registers for hardware interrupts


  4.1.4.  New Ideas for dpmi/dpmi.c

  Simulate Local Descriptor Table for MS-Windows 3.1 must be read only,
  so if krnl386.exe/krnl286.exe try to write to this table, we will bomb
  into sigsegv() and and emulate direct ldt access


  5.  The Video group of Modules

  All of the Video handling code is in the "video" subdirectory.

  There is one file for each video card or chipset and the master file.
  To Add a new card, it needs a set of save & restore routines putting
  in a file here.



  5.1.	video/vc.c Information

  Here's all the calls to the code to try and properly save & restore
  the video state between VC's and the attempts to control updates to
  the VC whilst the user is using another. We map between the real
  screen address and that used by DOSEMU here too.

  Attempts to use a cards own bios require the addition of the parameter
  "graphics" to the video statement in "/etc/dosemu.conf". This will
  make the emulator try to execute the card's initialization routine
  which is normally located at address c000:0003. This can now be
  changed as an option.



  5.1.1.  Functions in video/vc.c

  We appear to have no information on the functions in video/vc.c.


  5.1.2.  Remarks in video/vc.c

  Apparently, no-one has anything interesting to say about video/vc.c.


  5.1.3.  Items for Fixing in video/vc.c

  Apparently, nothing needs fixing in video/vc.c.


  5.1.4.  New Ideas for video/vc.c

  Apparently, there are no new ideas for video/vc.c.


  5.2.	video/video.c Information

  There appears to be no MODULE information for this file.


  5.2.1.  Functions in video/video.c

  These are the functions defined in video/video.c.


  5.2.1.1.  video_init

  Set pointer to correct structure of functions to initialize, close,
  etc... video routines.
  5.2.2.  Remarks in video/video.c

  Here the sleeping lion will be awoken and eat much of CPU time !!!

  The result of setting VM86_SCREEN_BITMAP (at state of Linux 1.1.56):
  Each vm86 call will set 32 pages of video mem RD-only (there may be
  1000000 per second) Write access to RD-only page results in page-fault
  (mm/memory.c), which will set a bit in current->screen_bitmap and
  calls do_wp_page() which does __get_free_page(GFP_KERNEL) but frees it
  immediatly, because copy-on-write is not neccessary and sets RD/WR for
  the page.  (this could happen 32000000 per second, if the CPU were
  fast enough) It would be better to get the DIRTY-bit directly from the
  page table, isn't it?	A special syscall in emumodule could do this.

  -----

  reserve_video_memory()

  This procedure is trying to eke out all the UMB blocks possible to
  maximize your memory under DOSEMU.  If you know about dual monitor
  setups, you can contribute by putting in the correct graphics page
  address values.


  5.2.3.  Items for Fixing in video/video.c

  Apparently, nothing needs fixing in video/video.c.


  5.2.4.  New Ideas for video/video.c

  Apparently, there are no new ideas for video/video.c.


  5.3.	video/X.c Information

  There appears to be no MODULE information for this file.


  5.3.1.  Functions in video/X.c

  We appear to have no information on the functions in video/X.c.


  5.3.2.  Remarks in video/X.c

  Apparently, no-one has anything interesting to say about video/X.c.


  5.3.3.  Items for Fixing in video/X.c

  Apparently, nothing needs fixing in video/X.c.


  5.3.4.  New Ideas for video/X.c

  Apparently, there are no new ideas for video/X.c.


  5.4.	video/console.c Information

  There appears to be no MODULE information for this file.




  5.4.1.  Functions in video/console.c

  We appear to have no information on the functions in video/console.c.


  5.4.2.  Remarks in video/console.c

  Apparently, no-one has anything interesting to say about
  video/console.c.


  5.4.3.  Items for Fixing in video/console.c

  Apparently, nothing needs fixing in video/console.c.


  5.4.4.  New Ideas for video/console.c

  Apparently, there are no new ideas for video/console.c.


  5.5.	video/dualmon.c Information

  The dual monitor support files to use a monochrome card as second
  video subsystem. Usefull with for example Borland Turbo Debugger and
  Turbo Profiler, HelpPC.  Supported cards are: - MDA (Monochrome
  Display Adapter) - Hercules Graphics Card (_the_ Hercules card) -
  Hercules Graphics Card Plus (a.k.a. Hercules RamFont) - Hercules
  InColor (the "color monochrome card").



  5.5.1.  Functions in video/dualmon.c

  These are the functions defined in video/dualmon.c.


  5.5.1.1.  MDA_init


  o  returns: nothing

     Initializes the monochrome card. First detects which monochrome
     card is used, because the Hercules RamFont and the Hercules InColor
     need one more register to be initialized. If there is no monochrome
     card at all, we just think there is one and poke an peek in the
     void.  After the detection the card is initialized.



  5.5.2.  Remarks in video/dualmon.c

  After MDA_init() the VGA is configured, something in video.c or
  console.c "reprograms" the monochrome card again in such a way that I
  always have to run hgc.com before I can use any program that uses the
  monochrome card. I've spent a day trying to find it, but I can't
  figure out. Something is writing to one of the following ports: 0x3b4,
  0x3b5, 0x3b8, 0x3b9, 0x3ba, 0x3bb, 0x3bf.  The problem occurs at (at
  least) the following 2 systems:

  - AMD 386DX40, Trident 9000/512Kb ISA, Hercules Graphics Card Plus -
  Intel 486DX2/66, Cirrus Logic 5426/1Mb VLB, Hercules clone

  The problem doesn't occur when I start dosemu from a telnet connection
  or from a VT100 terminal. (Erik Mouw, jakmouw@et.tudelft.nl)

  5.5.3.  Items for Fixing in video/dualmon.c

  Apparently, nothing needs fixing in video/dualmon.c.


  5.5.4.  New Ideas for video/dualmon.c

  Apparently, there are no new ideas for video/dualmon.c.


  5.6.	video/et4000.c Information

  There appears to be no MODULE information for this file.


  5.6.1.  Functions in video/et4000.c

  We appear to have no information on the functions in video/et4000.c.


  5.6.2.  Remarks in video/et4000.c

  Apparently, no-one has anything interesting to say about
  video/et4000.c.


  5.6.3.  Items for Fixing in video/et4000.c

  Apparently, nothing needs fixing in video/et4000.c.


  5.6.4.  New Ideas for video/et4000.c

  Apparently, there are no new ideas for video/et4000.c.


  5.7.	video/hgc.c Information

  There appears to be no MODULE information for this file.


  5.7.1.  Functions in video/hgc.c

  We appear to have no information on the functions in video/hgc.c.


  5.7.2.  Remarks in video/hgc.c

  Apparently, no-one has anything interesting to say about video/hgc.c.


  5.7.3.  Items for Fixing in video/hgc.c

  Apparently, nothing needs fixing in video/hgc.c.


  5.7.4.  New Ideas for video/hgc.c

  Apparently, there are no new ideas for video/hgc.c.


  5.8.	video/int10.c Information

  There appears to be no MODULE information for this file.


  5.8.1.  Functions in video/int10.c

  We appear to have no information on the functions in video/int10.c.


  5.8.2.  Remarks in video/int10.c

  Apparently, no-one has anything interesting to say about
  video/int10.c.


  5.8.3.  Items for Fixing in video/int10.c

  Apparently, nothing needs fixing in video/int10.c.


  5.8.4.  New Ideas for video/int10.c

  Apparently, there are no new ideas for video/int10.c.


  5.9.	video/s3.c Information

  There appears to be no MODULE information for this file.


  5.9.1.  Functions in video/s3.c

  We appear to have no information on the functions in video/s3.c.


  5.9.2.  Remarks in video/s3.c

  Apparently, no-one has anything interesting to say about video/s3.c.


  5.9.3.  Items for Fixing in video/s3.c

  Apparently, nothing needs fixing in video/s3.c.


  5.9.4.  New Ideas for video/s3.c

  Apparently, there are no new ideas for video/s3.c.


  5.10.	video/terminal.c Information

  There appears to be no MODULE information for this file.


  5.10.1.  Functions in video/terminal.c

  We appear to have no information on the functions in video/terminal.c.


  5.10.2.  Remarks in video/terminal.c

  Apparently, no-one has anything interesting to say about
  video/terminal.c.


  5.10.3.  Items for Fixing in video/terminal.c

  Apparently, nothing needs fixing in video/terminal.c.

  5.10.4.  New Ideas for video/terminal.c

  Apparently, there are no new ideas for video/terminal.c.


  5.11.	video/trident.c Information

  There appears to be no MODULE information for this file.


  5.11.1.  Functions in video/trident.c

  We appear to have no information on the functions in video/trident.c.


  5.11.2.  Remarks in video/trident.c

  Apparently, no-one has anything interesting to say about
  video/trident.c.


  5.11.3.  Items for Fixing in video/trident.c

  Apparently, nothing needs fixing in video/trident.c.


  5.11.4.  New Ideas for video/trident.c

  Apparently, there are no new ideas for video/trident.c.


  5.12.	video/vga.c Information

  There appears to be no MODULE information for this file.


  5.12.1.  Functions in video/vga.c

  We appear to have no information on the functions in video/vga.c.


  5.12.2.  Remarks in video/vga.c

  Apparently, no-one has anything interesting to say about video/vga.c.


  5.12.3.  Items for Fixing in video/vga.c

  Apparently, nothing needs fixing in video/vga.c.


  5.12.4.  New Ideas for video/vga.c

  Apparently, there are no new ideas for video/vga.c.


  6.  The Keyboard group of Modules


  All of the Keyboard handling code is in the "keyboard" subdirectory.

  Latest addition is SLANG.




  6.1.	keyboard/termio.c Information

  There appears to be no MODULE information for this file.


  6.1.1.  Functions in keyboard/termio.c

  We appear to have no information on the functions in
  keyboard/termio.c.


  6.1.2.  Remarks in keyboard/termio.c

  Apparently, no-one has anything interesting to say about
  keyboard/termio.c.


  6.1.3.  Items for Fixing in keyboard/termio.c

  Apparently, nothing needs fixing in keyboard/termio.c.


  6.1.4.  New Ideas for keyboard/termio.c

  Apparently, there are no new ideas for keyboard/termio.c.


  6.2.	keyboard/Xkeyb.c Information

  There appears to be no MODULE information for this file.


  6.2.1.  Functions in keyboard/Xkeyb.c

  We appear to have no information on the functions in keyboard/Xkeyb.c.


  6.2.2.  Remarks in keyboard/Xkeyb.c

  Apparently, no-one has anything interesting to say about
  keyboard/Xkeyb.c.


  6.2.3.  Items for Fixing in keyboard/Xkeyb.c

  Apparently, nothing needs fixing in keyboard/Xkeyb.c.


  6.2.4.  New Ideas for keyboard/Xkeyb.c

  Apparently, there are no new ideas for keyboard/Xkeyb.c.


  6.3.	keyboard/keymaps.c Information

  These are definitions, giving which key is related to which scancode
  in raw keyboard mode. Basically, the code of 'x' on a US keyboard may
  be that of a 'Y' on a German keyboard. This way, all types of keyboard
  can be represented under DOSEMU. Also, the right ALT-key is often a
  function key in it's own right.






  6.3.1.  Functions in keyboard/keymaps.c

  We appear to have no information on the functions in
  keyboard/keymaps.c.


  6.3.2.  Remarks in keyboard/keymaps.c

  Apparently, no-one has anything interesting to say about
  keyboard/keymaps.c.


  6.3.3.  Items for Fixing in keyboard/keymaps.c

  Apparently, nothing needs fixing in keyboard/keymaps.c.


  6.3.4.  New Ideas for keyboard/keymaps.c

  Apparently, there are no new ideas for keyboard/keymaps.c.


  6.4.	keyboard/slang-termio.c Information

  There appears to be no MODULE information for this file.


  6.4.1.  Functions in keyboard/slang-termio.c

  We appear to have no information on the functions in keyboard/slang-
  termio.c.


  6.4.2.  Remarks in keyboard/slang-termio.c

  Apparently, no-one has anything interesting to say about
  keyboard/slang-termio.c.


  6.4.3.  Items for Fixing in keyboard/slang-termio.c

  Apparently, nothing needs fixing in keyboard/slang-termio.c.


  6.4.4.  New Ideas for keyboard/slang-termio.c

  Apparently, there are no new ideas for keyboard/slang-termio.c.


  7.  The Misc group of Modules

  These are the remaining important files, that do not really fit into
  another group. These should not be dismissed as unimportant - rather,
  they are often amongst the most important.



  7.1.	dosemu/bios_emm.c Information

  There appears to be no MODULE information for this file.


  7.1.1.  Functions in dosemu/bios_emm.c

  We appear to have no information on the functions in
  dosemu/bios_emm.c.
  7.1.2.  Remarks in dosemu/bios_emm.c

  Apparently, no-one has anything interesting to say about
  dosemu/bios_emm.c.


  7.1.3.  Items for Fixing in dosemu/bios_emm.c

  Apparently, nothing needs fixing in dosemu/bios_emm.c.


  7.1.4.  New Ideas for dosemu/bios_emm.c

  Apparently, there are no new ideas for dosemu/bios_emm.c.


  7.2.	dosemu/xms.c Information

  Currently the XMS 3.0 spec is covered in this file. XMS is fairly
  simple as it only deals with allocating extended memory and then
  moving it around in specific calls. This spec also includes the
  allocation of UMB's, so they are also included as part of this file.
  The amount of xms memory returned to DOS programs via the XMS
  requests, or int15 fnc88 is set in "/etc/dosemu.conf" via the XMS
  paramter.



  7.2.1.  Functions in dosemu/xms.c

  We appear to have no information on the functions in dosemu/xms.c.


  7.2.2.  Remarks in dosemu/xms.c

  Apparently, no-one has anything interesting to say about dosemu/xms.c.


  7.2.3.  Items for Fixing in dosemu/xms.c

  Apparently, nothing needs fixing in dosemu/xms.c.


  7.2.4.  New Ideas for dosemu/xms.c

  Apparently, there are no new ideas for dosemu/xms.c.


  7.3.	dosemu/sigsegv.c Information

  There appears to be no MODULE information for this file.


  7.3.1.  Functions in dosemu/sigsegv.c

  These are the functions defined in dosemu/sigsegv.c.


  7.3.1.1.  inb

  INB is used to do controlled emulation of input from ports.





  7.3.1.2.  vm86_GP_fault

  All from the kernel unhandled general protection faults from V86 mode
  are handled here. This are mainly port IO and the HLT instruction.



  7.3.1.3.  dosemu_fault

  All CPU exceptions (except 13=general_protection from V86 mode, which
  is directly scaned by the kernel) are handled here.



  7.3.2.  Remarks in dosemu/sigsegv.c

  In a properly functioning emulator :-), sigsegv's will never come
  while in a non-reentrant system call (ioctl, select, etc).  Therefore,
  there's really no reason to worry about them, so I say that I'm NOT in
  a signal handler (I might make this a little clearer later, to show
  that the purpose of in_sighandler is to stop non-reentrant system
  calls from being reentered.  I reiterate: sigsegv's should only happen
  when I'm running the vm86 system call, so I really shouldn't be in a
  non-reentrant system call (except maybe vm86) - Robert Sanders


  7.3.3.  Items for Fixing in dosemu/sigsegv.c

  Apparently, nothing needs fixing in dosemu/sigsegv.c.


  7.3.4.  New Ideas for dosemu/sigsegv.c

  Apparently, there are no new ideas for dosemu/sigsegv.c.


  7.4.	include/int.h Information

  There appears to be no MODULE information for this file.


  7.4.1.  Functions in include/int.h

  We appear to have no information on the functions in include/int.h.


  7.4.2.  Remarks in include/int.h

  Apparently, no-one has anything interesting to say about
  include/int.h.


  7.4.3.  Items for Fixing in include/int.h

  Apparently, nothing needs fixing in include/int.h.


  7.4.4.  New Ideas for include/int.h

  Apparently, there are no new ideas for include/int.h.


  7.5.	include/ports.h Information

  There appears to be no MODULE information for this file.

  7.5.1.  Functions in include/ports.h

  We appear to have no information on the functions in include/ports.h.


  7.5.2.  Remarks in include/ports.h

  Apparently, no-one has anything interesting to say about
  include/ports.h.


  7.5.3.  Items for Fixing in include/ports.h

  Apparently, nothing needs fixing in include/ports.h.


  7.5.4.  New Ideas for include/ports.h

  Apparently, there are no new ideas for include/ports.h.


  7.6.	dosemu/dosio.c Information

  There appears to be no MODULE information for this file.


  7.6.1.  Functions in dosemu/dosio.c

  We appear to have no information on the functions in dosemu/dosio.c.


  7.6.2.  Remarks in dosemu/dosio.c

  Apparently, no-one has anything interesting to say about
  dosemu/dosio.c.


  7.6.3.  Items for Fixing in dosemu/dosio.c

  Apparently, nothing needs fixing in dosemu/dosio.c.


  7.6.4.  New Ideas for dosemu/dosio.c

  Apparently, there are no new ideas for dosemu/dosio.c.


  7.7.	dosemu/serial.c Information

  There appears to be no MODULE information for this file.


  7.7.1.  Functions in dosemu/serial.c

  These are the functions defined in dosemu/serial.c.


  7.7.1.1.  serial_init

  The following is the master serial initialization function called
  externally (from this serial.c module) during DOSEMU startup. It
  initializes all the configured serial ports.




  7.7.2.  Remarks in dosemu/serial.c

  Apparently, no-one has anything interesting to say about
  dosemu/serial.c.


  7.7.3.  Items for Fixing in dosemu/serial.c

  Apparently, nothing needs fixing in dosemu/serial.c.


  7.7.4.  New Ideas for dosemu/serial.c

  Apparently, there are no new ideas for dosemu/serial.c.


  7.8.	dosemu/disks.c Information

  There appears to be no MODULE information for this file.


  7.8.1.  Functions in dosemu/disks.c

  These are the functions defined in dosemu/disks.c.


  7.8.1.1.  disk_init

  Test by opening all floppies/hardrives configured.



  7.8.2.  Remarks in dosemu/disks.c

  Apparently, no-one has anything interesting to say about
  dosemu/disks.c.


  7.8.3.  Items for Fixing in dosemu/disks.c

  Apparently, nothing needs fixing in dosemu/disks.c.


  7.8.4.  New Ideas for dosemu/disks.c

  Apparently, there are no new ideas for dosemu/disks.c.


  7.9.	dosemu/cpu.c Information

  CPU/V86 support for dosemu



  7.9.1.  Functions in dosemu/cpu.c

  These are the functions defined in dosemu/cpu.c.


  7.9.1.1.  cpu_init

  Setup initial interrupts which can be revectored so that the kernel
  does not need to return to DOSEMU if such an interrupt occurs.



  7.9.2.  Remarks in dosemu/cpu.c

  Apparently, no-one has anything interesting to say about dosemu/cpu.c.


  7.9.3.  Items for Fixing in dosemu/cpu.c

  Apparently, nothing needs fixing in dosemu/cpu.c.


  7.9.4.  New Ideas for dosemu/cpu.c

  Apparently, there are no new ideas for dosemu/cpu.c.


  7.10.	dosemu/lpt.c Information

  There appears to be no MODULE information for this file.


  7.10.1.  Functions in dosemu/lpt.c

  These are the functions defined in dosemu/lpt.c.


  7.10.1.1.  printer_init

  Initialize printer control structures



  7.10.2.  Remarks in dosemu/lpt.c

  Apparently, no-one has anything interesting to say about dosemu/lpt.c.


  7.10.3.  Items for Fixing in dosemu/lpt.c

  Apparently, nothing needs fixing in dosemu/lpt.c.


  7.10.4.  New Ideas for dosemu/lpt.c

  Apparently, there are no new ideas for dosemu/lpt.c.


  8.  The Mouse group of Modules


  All of the Mouse handling code is in the "mouse" subdirectory.

  There are only 2 main files, mouse.c and mouseint.c.



  8.1.	mouse/mouse.c Information

  There appears to be no MODULE information for this file.


  8.1.1.  Functions in mouse/mouse.c

  These are the functions defined in mouse/mouse.c.



  8.1.1.1.  mouse_init

  Initialize internal mouse.



  8.1.2.  Remarks in mouse/mouse.c

  Apparently, no-one has anything interesting to say about
  mouse/mouse.c.


  8.1.3.  Items for Fixing in mouse/mouse.c

  Apparently, nothing needs fixing in mouse/mouse.c.


  8.1.4.  New Ideas for mouse/mouse.c

  Apparently, there are no new ideas for mouse/mouse.c.


  9.  The Bios group of Modules


  All of the Bios code is in the "bios" subdirectory.

  DOSEMU requires certain code to be coded in assembler and also code to
  be located in the F000 segment. This is where all such code should be
  put.



  9.1.	bios/bios.S Information

  There appears to be no MODULE information for this file.


  9.1.1.  Functions in bios/bios.S

  We appear to have no information on the functions in bios/bios.S.


  9.1.2.  Remarks in bios/bios.S

  Apparently, no-one has anything interesting to say about bios/bios.S.


  9.1.3.  Items for Fixing in bios/bios.S

  Apparently, nothing needs fixing in bios/bios.S.


  9.1.4.  New Ideas for bios/bios.S

  Apparently, there are no new ideas for bios/bios.S.


  10.  The PIC group of Modules

  All of the PIC handling code is in the "PIC" subdirectory.





  10.1.	pic/pic.c Information

  pic.c is a fairly co,plete emulation of both 8259 Priority Interrupt
  Controllers.	It also includes provision for 16 lower level
  interrupts.  This implementation supports the following i/o commands:

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

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

  Reads of both pic ports are supported completely.

  An important concept to understand in pic is the interrupt level.
  This is a value which represents the priority of the current
  interrupt.  It is used to identify interrupts, and IRQs can be mapped
  to these levels(see pic.h ). The currently active interrupt level is
  maintained in pic_ilevel, which is globally available,   A pic_ilevel
  of 32 means no interrupts are active; 0, the highest priority,
  represents the NMI.  IRQs 0 through 15 are mapped, in priority order,
  to values of 1-15 (there is no IRQ2 in an AT). Values of 16 - 31
  represent additional interrupt levels available for internal dosemu
  usage.

  More detail is available in the file README.pic



  10.1.1.  Functions in pic/pic.c

  These are the functions defined in pic/pic.c.


  10.1.1.1.  write_pic0

  write_pic_0() and write_pic1() implement dos writes to the pic ports.
  They are called by the code that emulates inb and outb instructions.
  Each function implements both ports for the pic:  pic0 is on ports
  0x20 and 0x21; pic1 is on ports 0xa0 and 0xa1.  These functions take
  two arguements: a port number (0 or 1) and a value to be written.



  10.1.1.2.  read_pic0

  read_pic0 and read_pic1 return the values for the interrupt mask
  register (port 1), or either the in service register or interrupt
  request register, as determined by the last OCW3 command (port 0).
  These functions take a single parameter, which is a port number (0 or
  1).  They are called by code that emulates the inb instruction.



  10.1.1.3.  pic_mask

  The pic maintains an additional interrupt mask which is not visible to
  the DOS process.  This is normally cleared (enabling an interrupt)
  when an interrupt is initialized, but dosemu code may choose to use
  this mask internally.	One possible use is to implement the interrupt
  gate controlled by the OUT2 bit of the 16550A UART's Modem Control
  Register.  This mask is cleared by pic_unmaski() and set by
  pic_maski()

  10.1.1.4.  pic_seti

  pic_seti is used to initialize an interrupt for dosemu.  It requires
  three parameters.  The first parameter is the interrupt level, which
  man select the NMI, any of the IRQs, or any of the 16 extra levels (16
  - 31).  The second parameter is the dosemu function to be called when
  the interrupt is activated.  This function should call do_irq() if the
  DOS interruptis really to be activated.  If there is no special dosemu
  code to call, the second parameter can specify do_irq(), but see that
  description for some special considerations.



  10.1.1.5.  run_irqs

  run_irqs, which is initiated via the macro pic_run, is the "brains" of
  the pic.  It is called from the vm86() loop, checks for the highest
  priority interrupt requested, and executes it.  This function is
  written in assembly language in order to take advantage of atomic
  (indivisible) instructions, so that it should be safe for a two
  process model, even in a multiple CPU machine.  A c language version
  was started, but it became impossible, even with in-line assembly
  macros, because such macros can only return a single result.	If I
  find a way to do it in c, I will, but don't hold your breath.



  10.1.1.6.  do_irq

  do_irq() calls the correct do_int().	It then executes a vm86 loop
  until an outb( end-of-interrupt) is found.  For priority levels 0 and
  >15 (not real IRQs), vm86 executes once, then returns, since no outb20
  will come.  Returns: 0 = complete, 1 = interrupt not run because it
  directly calls our "bios"   See run_timer_tick() in timer.c for an
  example To assure notification when the irq completes, we push flags,
  ip, and cs here and fake cs:ip to PIC_SEG,OFF, where there is a hlt.
  This makes the irq generate a sigsegv, which calls pic_iret when it
  completes.  pic_iret then pops the real cs:ip from the stack.	This
  routine is RE-ENTRANT - it calls run_irqs, which which may call an
  interrupt routine, which may call do_irq().  Be Careful!
  !!!!!!!!!!!!!!!!!!  No single interrupt is ever re-entered.



  10.1.1.7.  pic_request

  pic_request triggers an interrupt.  There is presently no way to "un-
  trigger" an interrupt.  The interrupt will be initiated the next time
  pic_run is called, unless masked or superceded by a higher priority
  interrupt.  pic_request takes one arguement, an interrupt level, which
  specifies the interrupt to be triggered.  If that interrupt is already
  active, the request will be queued until all active interrupts have
  been completed.  The queue is only one request deep for each
  interrupt, so it is the responsibility of the interrupt code to
  retrigger itself if more interrupts are needed.



  10.1.1.8.  pic_iret

  pic_iret is used to sense that all active interrupts are really
  complete, so that interrupts queued by pic_request can be triggered.
  Interrupts end when they issue an outb 0x20 to the pic, however it is
  not yet safe at that time to retrigger interrupts, since the stack has
  not been restored to its initial state by an iret.  pic_iret is called
  whenever interrupts have been enabled by a popf, sti, or iret.  It
  determines if an iret was the cause by comparing stack contents with
  cs and ip.  If so, it decrements a count of interrupts on the stack
  (set by do_irq()).  If the count is then zero, pic_iret moves all
  queued interrupts to the interrupt request register.	It is possible
  for pic_iret to be fooled by dos code; for this reason active
  interrupts are checked, any queued interrupts that are also active
  will remain queued.  Also, some programs fake an iret, so that it is
  possible for pic_iret to fail.  See pic_watch for the watchdog timer
  that catches and fixes this event.



  10.1.1.9.  pic_watch

  pic_watch is a watchdog timer for pending interrupts.	If pic_iret
  somehow fails to activate a pending interrupt request for 2
  consecutive timer ticks, pic_watch will activate them anyway.
  pic_watch is called by do_irq0, the timer interrupt routine.



  10.1.1.10.  do_irq0

  This is the routine for timer interrupts.  It simply calls
  pic_watch(), then triggers IRQ0 via do_irq().



  10.1.2.  Remarks in pic/pic.c

  Apparently, no-one has anything interesting to say about pic/pic.c.


  10.1.3.  Items for Fixing in pic/pic.c

  Apparently, nothing needs fixing in pic/pic.c.


  10.1.4.  New Ideas for pic/pic.c

  Apparently, there are no new ideas for pic/pic.c.


  10.2.	pic/pic.h Information

  There appears to be no MODULE information for this file.


  10.2.1.  Functions in pic/pic.h

  We appear to have no information on the functions in pic/pic.h.


  10.2.2.  Remarks in pic/pic.h

  Apparently, no-one has anything interesting to say about pic/pic.h.


  10.2.3.  Items for Fixing in pic/pic.h

  Apparently, nothing needs fixing in pic/pic.h.





  10.2.4.  New Ideas for pic/pic.h

  Apparently, there are no new ideas for pic/pic.h.


  11.  The Shared group of Modules

  All code being created to allow sharing of DOSEMU related information
  between separate running process is found here. This is headed in the
  direction of supporting DOSEMU in a client/server format.




  11.1.	dosemu/shared.c Information

  Memory areas needed to be shared between the DOSEMU process and other
  clients.



  11.1.1.  Functions in dosemu/shared.c

  These are the functions defined in dosemu/shared.c.


  11.1.1.1.  shared_qf_memory_init

  Setup all memory areas to be shared with clients.



  11.1.2.  Remarks in dosemu/shared.c

  Set to 0 all client request area

  -----

  Output info required for client activity


  11.1.3.  Items for Fixing in dosemu/shared.c

  Apparently, nothing needs fixing in dosemu/shared.c.


  11.1.4.  New Ideas for dosemu/shared.c

  Apparently, there are no new ideas for dosemu/shared.c.


  12.  And Finally ...

  The Following items are used to delimit the text used to create this
  file.	Whilst it is not necessary to know this, they are included
  because they may be useful for searching, as they are (at least at the
  moment) reasonably unique.

  DANG_BEGIN_MODULE / DANG_END_MODULE This will bracket a description of
  the file (normally at the start).

  DANG_BEGIN_FUNCTION / DANG_END_FUNCTION This brackets a description of
  functions (good this, isn't it!)  Not every function needs to be
  described in this way - just the major ones.
