"Fossies" - the Fresh Open Source Software Archive

Member "dosemu-1.4.0/doc/DANG.txt" (4 May 2007, 124332 Bytes) of package /linux/misc/old/dosemu-1.4.0.tgz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 
    2 The DOSEMU Alterer Novices Guide
    3 
    4 Alistair MacDonald, <alistair@slitesys.demon.co.uk>
    5 
    6    version dosemu-1.4.0
    7 
    8    This Document is the DOSEMU Alterer Novices Guide. It is known as the
    9    DANG.
   10      _________________________________________________________________
   11 
   12    Table of Contents
   13    1. Introduction
   14    2. The Main group of Modules
   15 
   16         2.1. Functions in dos.c
   17 
   18               2.1.1. dosemu
   19 
   20         2.2. Functions in emu.c
   21 
   22               2.2.1. jmp_emulate
   23               2.2.2. emulate
   24 
   25         2.3. Remarks in emu.c
   26         2.4. Remarks in include/emu.h
   27 
   28    3. The Init group of Modules
   29 
   30         3.1. Functions in base/init/init.c
   31 
   32               3.1.1. stdio_init
   33               3.1.2. time_setting_init
   34               3.1.3. timer_interrupt_init
   35               3.1.4. map_video_bios
   36               3.1.5. map_custom_bios
   37               3.1.6. memory_init
   38               3.1.7. device_init
   39               3.1.8. low_mem_init
   40               3.1.9. version_init
   41 
   42         3.2. Functions in base/init/config.c
   43 
   44               3.2.1. cpu_override
   45               3.2.2. register_config_scrub
   46               3.2.3. unregister_config_scrub
   47               3.2.4. config_scrub
   48               3.2.5. config_init
   49 
   50         3.3. Remarks in base/init/config.c
   51 
   52    4. The DPMI group of Modules
   53 
   54         4.1. Functions in dosext/dpmi/dpmi.c
   55 
   56               4.1.1. dpmi_control
   57               4.1.2. run_pm_int
   58               4.1.3. run_pm_dos_int
   59               4.1.4. do_default_cpu_exception
   60               4.1.5. do_cpu_exception
   61               4.1.6. dpmi_fault
   62 
   63         4.2. Remarks in dosext/dpmi/dpmi.c
   64         4.3. Items for Fixing in dosext/dpmi/dpmi.c
   65 
   66    5. The Video group of Modules
   67 
   68         5.1. Functions in env/video/video.c
   69 
   70               5.1.1. video_init
   71 
   72         5.2. Remarks in env/video/video.c
   73         5.3. Functions in plugin/X/X.c
   74 
   75               5.3.1. X_init
   76               5.3.2. X_close
   77               5.3.3. X_shm_init
   78               5.3.4. X_shm_init
   79               5.3.5. X_set_mouse_cursor
   80               5.3.6. X_handle_events
   81               5.3.7. graphics_cmap_init
   82               5.3.8. X_set_videomode
   83               5.3.9. set_mouse_position
   84 
   85         5.4. Remarks in plugin/X/X.c
   86         5.5. Functions in env/video/vgaemu.c
   87 
   88               5.5.1. VGA_emulate_outb
   89               5.5.2. VGA_emulate_inb
   90               5.5.3. vga_emu_fault
   91               5.5.4. vga_emu_init
   92               5.5.5. vga_emu_update
   93               5.5.6. vgaemu_switch_plane
   94               5.5.7. vga_emu_switch_bank
   95               5.5.8. vga_emu_find_mode
   96               5.5.9. vga_emu_setmode
   97               5.5.10. vga_emu_set_textsize
   98               5.5.11. dirty_all_video_pages
   99               5.5.12. dirty_all_vga_colors
  100               5.5.13. changed_vga_colors
  101               5.5.14. vgaemu_adj_cfg
  102 
  103         5.6. Functions in env/video/vesa.c
  104 
  105               5.6.1. vbe_init
  106               5.6.2. do_vesa_int
  107 
  108         5.7. Functions in env/video/attremu.c
  109 
  110               5.7.1. Attr_init
  111               5.7.2. Attr_get_entry
  112               5.7.3. Attr_set_entry
  113               5.7.4. Attr_read_value
  114               5.7.5. Attr_write_value
  115               5.7.6. Attr_get_index
  116 
  117         5.8. Functions in env/video/dacemu.c
  118 
  119               5.8.1. DAC_init
  120               5.8.2. DAC_set_width
  121               5.8.3. DAC_get_entry
  122               5.8.4. DAC_set_entry
  123               5.8.5. DAC_rgb2gray
  124               5.8.6. DAC_set_read_index
  125               5.8.7. DAC_set_write_index
  126               5.8.8. DAC_read_value
  127               5.8.9. DAC_write_value
  128               5.8.10. DAC_get_pel_mask
  129               5.8.11. DAC_set_pel_mask
  130               5.8.12. DAC_get_state
  131 
  132         5.9. Functions in env/video/crtcemu.c
  133 
  134               5.9.1. CRTC_init
  135 
  136         5.10. Functions in env/video/dualmon.c
  137 
  138               5.10.1. MDA_init
  139 
  140         5.11. Remarks in env/video/dualmon.c
  141         5.12. Functions in env/video/vgaemu.c
  142 
  143               5.12.1. VGA_emulate_outb
  144               5.12.2. VGA_emulate_inb
  145               5.12.3. vga_emu_fault
  146               5.12.4. vga_emu_init
  147               5.12.5. vga_emu_update
  148               5.12.6. vgaemu_switch_plane
  149               5.12.7. vga_emu_switch_bank
  150               5.12.8. vga_emu_find_mode
  151               5.12.9. vga_emu_setmode
  152               5.12.10. vga_emu_set_textsize
  153               5.12.11. dirty_all_video_pages
  154               5.12.12. dirty_all_vga_colors
  155               5.12.13. changed_vga_colors
  156               5.12.14. vgaemu_adj_cfg
  157 
  158         5.13. Functions in env/video/instremu.c
  159 
  160               5.13.1. instr_len
  161               5.13.2. instr_sim
  162               5.13.3. instr_emu
  163 
  164    6. The New_Keyboard group of Modules
  165 
  166         6.1. Functions in plugin/kbd_unicode/serv_xlat.c
  167 
  168               6.1.1. compute_keynum
  169               6.1.2. translate_key
  170               6.1.3. put_rawkey
  171               6.1.4. move_keynum
  172               6.1.5. keysym_to_keynum
  173               6.1.6. move_key
  174               6.1.7. put_symbol
  175               6.1.8. put_modified_symbol
  176               6.1.9. get_shiftstate
  177               6.1.10. set_shiftstate
  178 
  179         6.2. Functions in plugin/kbd_unicode/keyb_clients.c
  180 
  181               6.2.1. keyb_client_init
  182 
  183         6.3. Functions in plugin/kbd_unicode/keyb_none.c
  184 
  185               6.3.1. none_probe
  186 
  187         6.4. Functions in plugin/kbd_unicode/keyb_raw.c
  188 
  189               6.4.1. raw_keyboard_init
  190               6.4.2. raw_keyboard_reset
  191 
  192         6.5. Functions in plugin/term/keyb_slang.c
  193 
  194               6.5.1. setup_pc_scancode_mode
  195               6.5.2. exit_pc_scancode_mode
  196               6.5.3. do_pc_scancode_getkeys
  197               6.5.4. slang_keyb_init()
  198               6.5.5. slang_keyb_probe()
  199 
  200    7. The Misc group of Modules
  201 
  202         7.1. Functions in base/async/int.c
  203 
  204               7.1.1. int1a
  205               7.1.2. ms_dos
  206               7.1.3. run_caller_func(i, revect)
  207               7.1.4. DO_INT
  208               7.1.5. setup_interrupts
  209               7.1.6. int_vector_setup
  210 
  211         7.2. Remarks in base/async/int.c
  212         7.3. Functions in arch/linux/async/sigsegv.c
  213 
  214               7.3.1. dosemu_fault(int, struct sigcontext_struct);
  215               7.3.2. print_exception_info
  216 
  217         7.4. Functions in arch/linux/async/signal.c
  218 
  219               7.4.1. NEWSETQSIG
  220               7.4.2. SIG_init
  221               7.4.3. signal_init
  222               7.4.4. handle_signals
  223               7.4.5. SIGNAL_save
  224               7.4.6. SIGIO_call
  225 
  226         7.5. Remarks in arch/linux/async/signal.c
  227         7.6. Functions in base/misc/disks.c
  228 
  229               7.6.1. disk_init
  230 
  231         7.7. Functions in base/dev/misc/timers.c
  232 
  233               7.7.1. initialize_timers
  234               7.7.2. timer_tick
  235               7.7.3. do_sound
  236               7.7.4. timer_int_engine
  237 
  238         7.8. Functions in base/misc/dos2linux.c
  239 
  240               7.8.1. run_unix_command
  241 
  242         7.9. Functions in base/misc/ioctl.c
  243 
  244               7.9.1. io_select_init
  245               7.9.2. add_to_io_select
  246               7.9.3. remove_from_io_select
  247 
  248         7.10. Functions in base/dev/misc/lpt.c
  249 
  250               7.10.1. printer_init
  251 
  252         7.11. Functions in base/dev/misc/pci.c
  253 
  254               7.11.1. pci_read_header
  255               7.11.2. pci_setup
  256 
  257         7.12. Functions in base/dev/misc/joystick.c
  258 
  259               7.12.1. joy_latency_over
  260               7.12.2. joy_emu_button_set
  261               7.12.3. joy_emu_axis_set
  262               7.12.4. joy_emu_axis_conv
  263               7.12.5. joy_linux_process_event
  264               7.12.6. joy_linux_read_events
  265               7.12.7. joy_linux_read_status
  266               7.12.8. joy_linux_read_buttons_(family)
  267               7.12.9. joy_linux_read_axis_(family)
  268               7.12.10. joy_bios_read
  269               7.12.11. joy_port_inb
  270 
  271         7.13. Remarks in base/dev/misc/joystick.c
  272         7.14. Items for Fixing in base/dev/misc/joystick.c
  273         7.15. Remarks in include/doshelpers.h
  274 
  275    8. The CPU_Intel group of Modules
  276 
  277         8.1. Functions in emu-i386/cpu.c
  278 
  279               8.1.1. cpu_trap_0f
  280               8.1.2. cpu_setup
  281 
  282         8.2. Functions in emu-i386/ports.c
  283 
  284               8.2.1. port_inb(ioport_t port)
  285               8.2.2. port_outb(ioport_t port, Bit8u byte)
  286               8.2.3. port_inw(ioport_t port)
  287               8.2.4. port_outw(ioport_t port, Bit16u word)
  288               8.2.5. port_ind(ioport_t port)
  289               8.2.6. special_port_inb,special_port_outb
  290               8.2.7. port_init()
  291               8.2.8. extra_port_init()
  292               8.2.9. port_register_handler
  293               8.2.10. set_ioperm
  294 
  295         8.3. Remarks in emu-i386/ports.c
  296         8.4. Items for Fixing in emu-i386/ports.c
  297         8.5. Functions in emu-i386/do_vm86.c
  298 
  299               8.5.1. vm86_GP_fault
  300               8.5.2. run_vm86
  301               8.5.3. loopstep_run_vm86
  302 
  303         8.6. Remarks in emu-i386/do_vm86.c
  304         8.7. Functions in emu-i386/cputime.c
  305 
  306               8.7.1. GETcpuTIME
  307               8.7.2. GETusTIME(sc)
  308               8.7.3. GETtickTIME(sc)
  309               8.7.4. GETusSYSTIME()
  310 
  311         8.8. Remarks in emu-i386/cputime.c
  312         8.9. Functions in emu-i386/simx86/sigsegv.c
  313 
  314               8.9.1. dosemu_fault(int, struct sigcontext_struct);
  315 
  316    9. The Serial group of Modules
  317 
  318         9.1. Remarks in base/serial/ser_defs.h
  319         9.2. Functions in base/serial/ser_init.c
  320 
  321               9.2.1. serial_init
  322 
  323         9.3. Items for Fixing in base/serial/ser_init.c
  324         9.4. Functions in base/serial/ser_ports.c
  325 
  326               9.4.1. do_serial_in
  327               9.4.2. do_serial_out
  328 
  329         9.5. Items for Fixing in base/serial/ser_ports.c
  330         9.6. Functions in base/serial/ser_irq.c
  331 
  332               9.6.1. serial_int_engine
  333               9.6.2. pic_serial_run
  334               9.6.3. serial_run
  335 
  336         9.7. Remarks in base/serial/ser_irq.c
  337         9.8. Items for Fixing in base/serial/ser_irq.c
  338         9.9. Functions in base/serial/int14.c
  339 
  340               9.9.1. int14
  341 
  342         9.10. New Ideas for base/serial/int14.c
  343         9.11. Items for Fixing in base/serial/fossil.c
  344         9.12. Items for Fixing in include/serial.h
  345 
  346    10. The Mouse group of Modules
  347 
  348         10.1. Functions in base/mouse/mouse.c
  349 
  350               10.1.1. mouse_init
  351 
  352         10.2. Remarks in base/mouse/mouse.c
  353 
  354    11. The Bios group of Modules
  355 
  356         11.1. Functions in base/bios/hlt.c
  357 
  358               11.1.1. hlt_init(void)
  359               11.1.2. hlt_handle()
  360 
  361    12. The PIC group of Modules
  362 
  363         12.1. Functions in base/dev/pic/pic.c
  364 
  365               12.1.1. pic_print
  366               12.1.2. write_pic0,write_pic1
  367               12.1.3. read_pic0,read_pic1
  368               12.1.4. pic_seti
  369               12.1.5. run_irqs
  370               12.1.6. do_irq
  371               12.1.7. pic_resched
  372               12.1.8. pic_request
  373               12.1.9. pic_iret
  374               12.1.10. pic_watch
  375               12.1.11. pic_pending
  376               12.1.12. pic_activate
  377               12.1.13. pic_sched
  378 
  379         12.2. Remarks in base/dev/pic/pic.c
  380 
  381    13. The Sound group of Modules
  382 
  383         13.1. Functions in dosext/sound/sound.c
  384 
  385               13.1.1. sb_io_read
  386               13.1.2. adlib_io_read
  387               13.1.3. mpu401_io_read
  388               13.1.4. sb_io_write
  389               13.1.5. sb_dsp_write
  390 
  391         13.2. Remarks in dosext/sound/sound.c
  392         13.3. Items for Fixing in dosext/sound/sound.c
  393         13.4. Remarks in base/dev/dma/dma.c
  394         13.5. Items for Fixing in base/dev/dma/dma.c
  395 
  396    14. The FileAccess group of Modules
  397 
  398         14.1. Remarks in dosext/mfs/mfs.c
  399         14.2. Items for Fixing in dosext/mfs/mfs.c
  400 
  401    15. And Finally ...
  402 
  403 1. Introduction
  404 
  405    This document is the preliminary draft of a manual to help people
  406    understand the inner workings of dosemu. It is the goal of this
  407    document to create new dosemu hackers. This concept was inspired by
  408    the linux kernel hackers guide.
  409 
  410    This Guide was concieved and originally written by "Corey Sweeney"
  411    <corey@interaccess.com>. It has been completely revised. It is now
  412    generated automatically directly from the source code. Special thanks
  413    to "James B. MacLean" <macleajb@ednet.ns.ca> for supplying the
  414    original information. (It was mostly ripped out of a mail message.)
  415    "Jochen Hein" has made many useful comments & suggestions.
  416 
  417    At the end if this document is a section detailing how this guide is
  418    put together. This may help you when trying to locate the relevant
  419    pieces of code. If you add new code, it would be useful if the
  420    relevant markers are added where appropriate.
  421 
  422    This file is a collective effort. If you don't like one of the
  423    explanations, or want to add anything, please send me something!
  424      _________________________________________________________________
  425 
  426 2. The Main group of Modules
  427 
  428    These files are used to start DOSEMU as well as hold globally called
  429    functions and global vars.
  430      _________________________________________________________________
  431 
  432 2.1. Functions in dos.c
  433 
  434    These are the functions defined in dos.c.
  435      _________________________________________________________________
  436 
  437 2.1.1. dosemu
  438 
  439    Arguments are:
  440 
  441      * argc - Count of argumnents.
  442      * argc - Actual arguments.
  443 
  444    Function created by entry point into libdosemu. Called to jump into
  445    the emulate function of DOSEMU.
  446      _________________________________________________________________
  447 
  448 2.2. Functions in emu.c
  449 
  450    These are the functions defined in emu.c.
  451      _________________________________________________________________
  452 
  453 2.2.1. jmp_emulate
  454 
  455    call the emulate function by way of the dll headers. Always make sure
  456    that this line is the first of emu.c and link emu.o as the first
  457    object file to the lib
  458      _________________________________________________________________
  459 
  460 2.2.2. emulate
  461 
  462    Arguments are:
  463 
  464      * argc - Argument count.
  465      * argv - Arguments.
  466 
  467    Emulate gets called from dos.c. It initializes DOSEMU to prepare it
  468    for running in vm86 mode. This involves catching signals, preparing
  469    memory, calling all the initialization functions for the I/O
  470    subsystems (video/serial/etc...), getting the boot sector instructions
  471    and calling vm86().
  472      _________________________________________________________________
  473 
  474 2.3. Remarks in emu.c
  475 
  476    DOSEMU must not work within the 1 meg DOS limit, so start of code is
  477    loaded at a higher address, at some time this could conflict with
  478    other shared libs. If DOSEMU is compiled statically (without shared
  479    libs), and org instruction is used to provide the jump above 1 meg.
  480      _________________________________________________________________
  481 
  482 2.4. Remarks in include/emu.h
  483 
  484    The `vm86_struct` is used to pass all the necessary status/registers
  485    to DOSEMU when running in vm86 mode.
  486 
  487    -----
  488 
  489    DOSEMU keeps system wide configuration status in a structure called
  490    config.
  491 
  492    -----
  493 
  494    The var `fatalerr` can be given a true value at any time to have
  495    DOSEMU exit on the next return from vm86 mode.
  496 
  497    -----
  498 
  499    The var 'running_DosC' is set by the DosC kernel and is used to handle
  500    some things differently, e.g. the redirector. It interfaces via
  501    INTe6,0xDC (DOS_HELPER_DOSC), but only if running_DosC is !=0. At the
  502    very startup DosC issues a INTe6,0xdcDC to set running_DosC with the
  503    contents of BX (which is the internal DosC version).
  504      _________________________________________________________________
  505 
  506 3. The Init group of Modules
  507 
  508    These files are used for initialization and runtime configuration of
  509    DOSEMU
  510      _________________________________________________________________
  511 
  512 3.1. Functions in base/init/init.c
  513 
  514    These are the functions defined in base/init/init.c.
  515      _________________________________________________________________
  516 
  517 3.1.1. stdio_init
  518 
  519    Initialize stdio, open debugging output file if user specified one
  520      _________________________________________________________________
  521 
  522 3.1.2. time_setting_init
  523 
  524    Beats me
  525      _________________________________________________________________
  526 
  527 3.1.3. timer_interrupt_init
  528 
  529    Tells the OS to send us periodic timer messages
  530      _________________________________________________________________
  531 
  532 3.1.4. map_video_bios
  533 
  534    Map the video bios into main memory
  535      _________________________________________________________________
  536 
  537 3.1.5. map_custom_bios
  538 
  539    Setup the dosemu amazing custom BIOS, quietly overwriting anything was
  540    copied there before. Do not overwrite graphic fonts!
  541      _________________________________________________________________
  542 
  543 3.1.6. memory_init
  544 
  545    Set up all memory areas as would be present on a typical i86 during
  546    the boot phase.
  547      _________________________________________________________________
  548 
  549 3.1.7. device_init
  550 
  551    Calls all initialization routines for devices (keyboard, video,
  552    serial, disks, etc.)
  553      _________________________________________________________________
  554 
  555 3.1.8. low_mem_init
  556 
  557    Initializes the lower 1Meg via mmap & sets up the HMA region
  558      _________________________________________________________________
  559 
  560 3.1.9. version_init
  561 
  562    Find version of OS running and set necessary global parms.
  563      _________________________________________________________________
  564 
  565 3.2. Functions in base/init/config.c
  566 
  567    These are the functions defined in base/init/config.c.
  568      _________________________________________________________________
  569 
  570 3.2.1. cpu_override
  571 
  572    Process user CPU override from the config file ('cpu xxx') or from the
  573    command line. Returns the selected CPU identifier or -1 on error.
  574      _________________________________________________________________
  575 
  576 3.2.2. register_config_scrub
  577 
  578    register a function Enforce consistency upon the `config` structure
  579    after all values have been set to remove silly option combinations
  580      _________________________________________________________________
  581 
  582 3.2.3. unregister_config_scrub
  583 
  584    Complement of register_config_scrub This removes a scrub function.
  585      _________________________________________________________________
  586 
  587 3.2.4. config_scrub
  588 
  589    Enforce consistency upon the `config` structure after all values have
  590    been set to remove silly option combinations
  591      _________________________________________________________________
  592 
  593 3.2.5. config_init
  594 
  595    This is called to parse the command-line arguments and config files.
  596      _________________________________________________________________
  597 
  598 3.3. Remarks in base/init/config.c
  599 
  600    For simpler support of X, DOSEMU can be started by a symbolic link
  601    called `xdos` which DOSEMU will use to switch into X-mode.
  602      _________________________________________________________________
  603 
  604 4. The DPMI group of Modules
  605 
  606    DPMI is Lutz's Baby. It's a really important part of the Emulator as
  607    far as we are concerned, since it will allow us to run so many more
  608    programs and, most importantly, bcc. This is the one thing that the
  609    WINE developers want that we haven't been able to give them.
  610 
  611    If you think you can help .... "Away you Go!" (Sorry to those non-UK
  612    folks ... Thats a reference to a UK kids sports programme from my
  613    youth ... anyway ... enough of this banter. You'll be wanting to know
  614    that this is all about DPMI ...)
  615      _________________________________________________________________
  616 
  617 4.1. Functions in dosext/dpmi/dpmi.c
  618 
  619    These are the functions defined in dosext/dpmi/dpmi.c.
  620      _________________________________________________________________
  621 
  622 4.1.1. dpmi_control
  623 
  624    This function is similar to the vm86() syscall in the kernel and
  625    switches to dpmi code.
  626      _________________________________________________________________
  627 
  628 4.1.2. run_pm_int
  629 
  630    This routine is used for running protected mode hardware interrupts.
  631    run_pm_int() switches to the locked protected mode stack and calls the
  632    handler. If no handler is installed the real mode interrupt routine is
  633    called.
  634      _________________________________________________________________
  635 
  636 4.1.3. run_pm_dos_int
  637 
  638    This routine is used for reflecting the software interrupts 0x1c, 0x23
  639    and 0x24 to protected mode.
  640      _________________________________________________________________
  641 
  642 4.1.4. do_default_cpu_exception
  643 
  644    This is the default CPU exception handler. Exceptions 0, 1, 2, 3, 4, 5
  645    and 7 are reflected to real mode. All other exceptions are terminating
  646    the client (and may be dosemu too :-)).
  647      _________________________________________________________________
  648 
  649 4.1.5. do_cpu_exception
  650 
  651    This routine switches to the locked protected mode stack, disables
  652    interrupts and calls the DPMI client exception handler. If no handler
  653    is installed the default handler is called.
  654      _________________________________________________________________
  655 
  656 4.1.6. dpmi_fault
  657 
  658    This is the brain of DPMI. All CPU exceptions are first reflected
  659    (from the signal handlers) to this code.
  660 
  661    Exception from nonprivileged instructions INT XX, STI, CLI, HLT and
  662    from WINDOWS 3.1 are handled here.
  663 
  664    All here unhandled exceptions are reflected to do_cpu_exception()
  665 
  666    Note for cpu-emu: exceptions generated from the emulator are handled
  667    here. 'Real' system exceptions (e.g. from an emulator fault) are
  668    redirected to emu_dpmi_fault() in fullemu mode
  669      _________________________________________________________________
  670 
  671 4.2. Remarks in dosext/dpmi/dpmi.c
  672 
  673    We are caching ldt here for speed reasons and for Windows 3.1. I would
  674    love to have an readonly ldt-alias (located in the first 16MByte for
  675    use with 16-Bit descriptors (WIN-LDT)). This is on my wish list for
  676    the kernel hackers (Linus mainly) :-))))))).
  677 
  678    -----
  679 
  680    DPMI is designed such that the stack change needs a task switch. We
  681    are doing it via an SIGSEGV - instead of one task switch we have now
  682    four :-(. Arrgh this is the point where I should start to include DPMI
  683    stuff in the kernel, but then we could include the rest of dosemu too.
  684    Would Linus love this? I don't :-((((. Anyway I would love to see
  685    first a working DPMI port, maybe we will later (with version 0.9 or
  686    similar :-)) start with it to get a really fast dos
  687    emulator...............
  688 
  689    NOTE: Using DIRECT_DPMI_CONTEXT_SWITCH we avoid these 4 taskswitches
  690    actually doing 0. We don't need a 'physical' taskswitch (not having
  691    different TSS for us and DPMI), we only need a complete register
  692    (context) replacement. For back-switching, however, we need the
  693    sigcontext technique, so we build a proper sigcontext structure even
  694    for 'hand made taskswitch'. (Hans Lermen, June 1996)
  695 
  696    -- the whole emu_stack_frame could be eliminated except for eip/rip
  697    and esp/rsp. For the most part GCC can worry about clobbered registers
  698    (Bart Oldeman, October 2006)
  699 
  700    dpmi_control is called only from dpmi_run when in_dpmi_dos_int==0
  701 
  702    -----
  703 
  704    Hopefully the below LAR can serve as a replacement for the KERNEL_LDT,
  705    which we are abandoning now. Especially the 'accessed-bit' will get
  706    updated in the ldt-cache with the code below. Most DPMI-clients
  707    fortunately _are_ using LAR also to get this info, however, some do
  708    not. Some of those which do _not_, at least use the DPMI-GetDescriptor
  709    function, so this may solve the problem. (Hans Lermen, July 1996)
  710 
  711    -----
  712 
  713    Here we handle all prefixes prior switching to the appropriate
  714    routines The exception CS:EIP will point to the first prefix that
  715    effects the the faulting instruction, hence, 0x65 0x66 is same as 0x66
  716    0x65. So we collect all prefixes and remember them. - Hans Lermen
  717      _________________________________________________________________
  718 
  719 4.3. Items for Fixing in dosext/dpmi/dpmi.c
  720 
  721    We shouldn't return to dosemu code if IF=0, but it helps - WHY? */
  722      _________________________________________________________________
  723 
  724 5. The Video group of Modules
  725 
  726    All of the Video handling code is in the "video" subdirectory.
  727 
  728    There is one file for each video card or chipset and the master file.
  729    To Add a new card, it needs a set of save & restore routines putting
  730    in a file here.
  731      _________________________________________________________________
  732 
  733 5.1. Functions in env/video/video.c
  734 
  735    These are the functions defined in env/video/video.c.
  736      _________________________________________________________________
  737 
  738 5.1.1. video_init
  739 
  740    Set pointer to correct structure of functions to initialize, close,
  741    etc... video routines.
  742      _________________________________________________________________
  743 
  744 5.2. Remarks in env/video/video.c
  745 
  746    Here the sleeping lion will be awoken and eat much of CPU time !!!
  747 
  748    The result of setting VM86_SCREEN_BITMAP (at state of Linux 1.1.56):
  749    Each vm86 call will set 32 pages of video mem RD-only (there may be
  750    1000000 per second) Write access to RD-only page results in page-fault
  751    (mm/memory.c), which will set a bit in current->screen_bitmap and
  752    calls do_wp_page() which does __get_free_page(GFP_KERNEL) but frees it
  753    immediatly, because copy-on-write is not neccessary and sets RD/WR for
  754    the page. (this could happen 32000000 per second, if the CPU were fast
  755    enough) It would be better to get the DIRTY-bit directly from the page
  756    table, isn't it? A special syscall in emumodule could do this.
  757 
  758    -----
  759 
  760    reserve_video_memory()
  761 
  762    This procedure is trying to eke out all the UMB blocks possible to
  763    maximize your memory under DOSEMU. If you know about dual monitor
  764    setups, you can contribute by putting in the correct graphics page
  765    address values.
  766      _________________________________________________________________
  767 
  768 5.3. Functions in plugin/X/X.c
  769 
  770    These are the functions defined in plugin/X/X.c.
  771      _________________________________________________________________
  772 
  773 5.3.1. X_init
  774 
  775    Initialize everything X-related.
  776      _________________________________________________________________
  777 
  778 5.3.2. X_close
  779 
  780    Destroy the window, unload font, pixmap and colormap.
  781      _________________________________________________________________
  782 
  783 5.3.3. X_shm_init
  784 
  785    Check availability of the MIT-SHM shared memory extension.
  786      _________________________________________________________________
  787 
  788 5.3.4. X_shm_init
  789 
  790    Turn off usage of the MIT-SHM shared memory extension.
  791      _________________________________________________________________
  792 
  793 5.3.5. X_set_mouse_cursor
  794 
  795    called by mouse.c to hide/display the mouse and set it's position.
  796    This is currently the only callback from mouse.c to X.
  797      _________________________________________________________________
  798 
  799 5.3.6. X_handle_events
  800 
  801    Handle pending X events (called from SIGALRM handler).
  802      _________________________________________________________________
  803 
  804 5.3.7. graphics_cmap_init
  805 
  806    Allocate a colormap for graphics modes and initialize it. Do mostly
  807    nothing on true color displays. Otherwise, do: - if colormaps have
  808    less than 256 entries (notably 16 or 2 colors), don't use a private
  809    colormap - if a shared map is requested and there are less than 36
  810    colors (3/4/3) available, use a private colormap
  811 
  812    Note: Text modes always use the screen's default colormap.
  813      _________________________________________________________________
  814 
  815 5.3.8. X_set_videomode
  816 
  817    This is the interface function called by the video subsystem to set a
  818    video mode.
  819 
  820    NOTE: The actual mode is taken from the global variable "video_mode".
  821 
  822    Set the video mode. If mode_class is -1, this will only reinitialize
  823    the current mode. The other arguments are ignored in this case.
  824      _________________________________________________________________
  825 
  826 5.3.9. set_mouse_position
  827 
  828    Place the mouse on the right position.
  829      _________________________________________________________________
  830 
  831 5.4. Remarks in plugin/X/X.c
  832 
  833    DO NOT REMOVE THIS TEST!!! It is magic, without it EMS fails on my
  834    machine under X. Perhaps someday when we don't use a buggy
  835    /proc/self/mem.. -- EB 18 May 1998 A slightly further look says it's
  836    not the test so much as suppressing noop resize events... -- EB 1 June
  837    1998
  838      _________________________________________________________________
  839 
  840 5.5. Functions in env/video/vgaemu.c
  841 
  842    These are the functions defined in env/video/vgaemu.c.
  843      _________________________________________________________________
  844 
  845 5.5.1. VGA_emulate_outb
  846 
  847    Emulates writes to VGA ports. This is a hardware emulation function.
  848 
  849    Arguments are:
  850 
  851      * port - The port being written to.
  852      * value - The value written,
  853      _________________________________________________________________
  854 
  855 5.5.2. VGA_emulate_inb
  856 
  857    Emulates reads from VGA ports. This is a hardware emulation function.
  858 
  859    Arguments are:
  860 
  861      * port - The port being read from.
  862      _________________________________________________________________
  863 
  864 5.5.3. vga_emu_fault
  865 
  866    vga_emu_fault() is used to catch video access, and handle it. This
  867    function is called from arch/linux/async/sigsegv.c::dosemu_fault1().
  868    The sigcontext_struct is defined in include/cpu.h. Now it catches only
  869    changes in a 4K page, but maybe it is useful to catch each video
  870    access. The problem when you do that is, you have to simulate each
  871    instruction which could write to the video memory. It is easy to get
  872    the place where the exception happens (scp->cr2), but what are those
  873    changes? An other problem is, it could eat a lot of time, but it does
  874    now also.
  875 
  876    MODIFICATION: VGA mode 12h under X is supported in exactly the way
  877    that was suggested above. Not every instruction needs to be simulated
  878    in order to make this feature useful, just the ones used to access
  879    video RAM by key applications (Borland BGI, Protel, etc.).
  880 
  881    MODIFICATION: all VGA modes now work and almost all instructions are
  882    simulated.
  883 
  884    Arguments are:
  885 
  886      * scp - A pointer to a struct sigcontext_struct holding some
  887        relevant data.
  888      _________________________________________________________________
  889 
  890 5.5.4. vga_emu_init
  891 
  892    vga_emu_init() must be called before using the VGAEmu functions. It is
  893    only called from env/video/X.c::X_init() at the moment. This function
  894    basically initializes the global variable `vga' and allocates the VGA
  895    memory.
  896 
  897    It does in particular *not* map any memory into the range 0xa0000 -
  898    0xc0000, this is done as part of a VGA mode switch.
  899 
  900    There should be an accompanying vga_emu_done().
  901 
  902    Arguments are:
  903 
  904      * vedt - Pointer to struct describing the type of display we are
  905        actually
  906      * attached to.
  907      _________________________________________________________________
  908 
  909 5.5.5. vga_emu_update
  910 
  911    vga_emu_update() scans the VGA memory for dirty (= written to since
  912    last update) pages and returns the changed area in *veut. See the
  913    definition of vga_emu_update_type in env/video/vgaemu_inside.h for
  914    details.
  915 
  916    You will need to call this function repeatedly until it returns 0 to
  917    grab all changes. You can specify an upper limit for the size of the
  918    area that will be returned using `veut->max_max_len' and
  919    `veut->max_len'. See the example in env/video/X.c how this works.
  920 
  921    If the return value of vga_emu_update() is >= 0, it is the number of
  922    changed pages, -1 means there are still changed pages but the maximum
  923    update chunk size (`veut->max_max_len') was exceeded.
  924 
  925    This function does in its current form not work for Hercules modes; it
  926    does, however work for text modes, although this feature is currently
  927    not used.
  928 
  929    Arguments are:
  930 
  931      * veut - A pointer to a vga_emu_update_type object holding all
  932        relevant info.
  933      _________________________________________________________________
  934 
  935 5.5.6. vgaemu_switch_plane
  936 
  937    vgaemu_switch_plane() maps the specified plane.
  938 
  939    This function returns True on success and False on error, usually
  940    indicating an invalid bank number.
  941 
  942    Arguments are:
  943 
  944      * plane (0..3) - The plane to map.
  945      _________________________________________________________________
  946 
  947 5.5.7. vga_emu_switch_bank
  948 
  949    vga_emu_switch_bank() is used to emulate video-bankswitching.
  950 
  951    This function returns True on success and False on error, usually
  952    indicating an invalid bank number.
  953 
  954    Arguments are:
  955 
  956      * bank - The bank to switch to.
  957      _________________________________________________________________
  958 
  959 5.5.8. vga_emu_find_mode
  960 
  961    Searches a video mode with the requested mode number.
  962 
  963    The search starts with the mode *after* the mode `vmi' points to. If
  964    `vmi' == NULL, starts at the beginning of the internal mode table.
  965    `mode' may be a standard VGA mode number (0 ... 0x7f) or a VESA mode
  966    number (>= 0x100). The mode number may have its don't-clear-bit (bit 7
  967    or bit 15) or its use-lfb-bit (bit 14) set. The special mode number -1
  968    will match any mode and may be used to scan through the whole table.
  969 
  970    Returns NULL if no mode was found and a pointer into the mode table
  971    otherwise. The returned pointer is a suitable argument for subsequent
  972    calls to this function.
  973 
  974    You should (and can) access the mode table only through this function.
  975 
  976    Arguments are:
  977 
  978      * mode - video mode.
  979      * vmi - pointer into internal mode list
  980      _________________________________________________________________
  981 
  982 5.5.9. vga_emu_setmode
  983 
  984    Set a video mode.
  985 
  986    Switches to `mode' with text sizes `width' and `height' or (if no such
  987    mode was found) at least `width' and `height'.
  988 
  989    Arguments are:
  990 
  991      * mode - The new video mode.
  992      * width - Number of text columns.
  993      * height - Number of text rows.
  994      _________________________________________________________________
  995 
  996 5.5.10. vga_emu_set_textsize
  997 
  998    Sets the text mode resolution. Typically called after a font change.
  999 
 1000    Arguments are:
 1001 
 1002      * width - Number of text columns.
 1003      * height - Number of text rows.
 1004      _________________________________________________________________
 1005 
 1006 5.5.11. dirty_all_video_pages
 1007 
 1008    Marks the whole VGA memory as modified.
 1009      _________________________________________________________________
 1010 
 1011 5.5.12. dirty_all_vga_colors
 1012 
 1013    Marks all colors as changed.
 1014      _________________________________________________________________
 1015 
 1016 5.5.13. changed_vga_colors
 1017 
 1018    Checks DAC and Attribute Controller to find all colors with changed
 1019    RGB-values. Returns number of changed colors. Note: the list _must_ be
 1020    large enough, that is, have at least min(256, (1 << vga.pixel_size))
 1021    entries!
 1022 
 1023    Arguments are:
 1024 
 1025      * de - list of DAC entries to store changed colors in
 1026      _________________________________________________________________
 1027 
 1028 5.5.14. vgaemu_adj_cfg
 1029 
 1030    Adjust VGAEmu according to VGA register changes.
 1031      _________________________________________________________________
 1032 
 1033 5.6. Functions in env/video/vesa.c
 1034 
 1035    These are the functions defined in env/video/vesa.c.
 1036      _________________________________________________________________
 1037 
 1038 5.6.1. vbe_init
 1039 
 1040    Initializes the VGA/VBE BIOS and the VBE support.
 1041 
 1042    Arguments are:
 1043 
 1044      * vedt - Pointer to struct describing the type of display we are
 1045        actually
 1046      * attached to.
 1047      _________________________________________________________________
 1048 
 1049 5.6.2. do_vesa_int
 1050 
 1051    This is the VESA interrupt handler.
 1052 
 1053    It is called from base/bios/int10.c::int10(). The VESA interrupt is
 1054    called with 0x4f in AH and the function number (0x00 ... 0x10) in AL.
 1055      _________________________________________________________________
 1056 
 1057 5.7. Functions in env/video/attremu.c
 1058 
 1059    These are the functions defined in env/video/attremu.c.
 1060      _________________________________________________________________
 1061 
 1062 5.7.1. Attr_init
 1063 
 1064    Initializes the attribute controller. This is an interface function.
 1065      _________________________________________________________________
 1066 
 1067 5.7.2. Attr_get_entry
 1068 
 1069    Directly reads the Attribute Controller's registers. This is an
 1070    interface function.
 1071      _________________________________________________________________
 1072 
 1073 5.7.3. Attr_set_entry
 1074 
 1075    Directly sets the Attribute Controller's registers. This is an
 1076    interface function.
 1077      _________________________________________________________________
 1078 
 1079 5.7.4. Attr_read_value
 1080 
 1081    Emulates reads from the attribute controller. This is a hardware
 1082    emulation function.
 1083      _________________________________________________________________
 1084 
 1085 5.7.5. Attr_write_value
 1086 
 1087    Emulates writes to attribute controller combined index and data
 1088    register. Read VGADOC for details. This is a hardware emulation
 1089    function.
 1090      _________________________________________________________________
 1091 
 1092 5.7.6. Attr_get_index
 1093 
 1094    Returns the current index of the attribute controller. This is a
 1095    hardware emulation function, though in fact this function is undefined
 1096    in a real attribute controller. Well, it is exactly what my VGA board
 1097    (S3) does. -- sw This is a hardware emulation function.
 1098      _________________________________________________________________
 1099 
 1100 5.8. Functions in env/video/dacemu.c
 1101 
 1102    These are the functions defined in env/video/dacemu.c.
 1103      _________________________________________________________________
 1104 
 1105 5.8.1. DAC_init
 1106 
 1107    Initializes the DAC. It depends on a correct value in vga.pixel_size.
 1108    This function should be called during VGA mode initialization. This is
 1109    an interface function.
 1110      _________________________________________________________________
 1111 
 1112 5.8.2. DAC_set_width
 1113 
 1114    Sets the DAC width. Typical values are 6 or 8 bits. In theory, we
 1115    support other values as well (untested). This is an interface
 1116    function.
 1117      _________________________________________________________________
 1118 
 1119 5.8.3. DAC_get_entry
 1120 
 1121    Returns a complete DAC entry (r, g, b). Don't forget to set
 1122    DAC_entry.index first! This is an interface function.
 1123      _________________________________________________________________
 1124 
 1125 5.8.4. DAC_set_entry
 1126 
 1127    Sets a complete DAC entry (r,g,b). This is an interface function.
 1128      _________________________________________________________________
 1129 
 1130 5.8.5. DAC_rgb2gray
 1131 
 1132    Converts a DAC register's RGB values to gray scale. This is an
 1133    interface function.
 1134      _________________________________________________________________
 1135 
 1136 5.8.6. DAC_set_read_index
 1137 
 1138    Specifies which palette entry is read. This is a hardware emulation
 1139    function.
 1140      _________________________________________________________________
 1141 
 1142 5.8.7. DAC_set_write_index
 1143 
 1144    Specifies which palette entry is written. This is a hardware emulation
 1145    function.
 1146      _________________________________________________________________
 1147 
 1148 5.8.8. DAC_read_value
 1149 
 1150    Read a value from the DAC. Each read will cycle through the registers
 1151    for red, green and blue. After a ``blue read'' the read index will be
 1152    incremented. Read VGADOC4 if you want to know more about the DAC. This
 1153    is a hardware emulation function.
 1154      _________________________________________________________________
 1155 
 1156 5.8.9. DAC_write_value
 1157 
 1158    Write a value to the DAC. Each write will cycle through the registers
 1159    for red, green and blue. After a ``blue write'' the write index will
 1160    be incremented. This is a hardware emulation function.
 1161      _________________________________________________________________
 1162 
 1163 5.8.10. DAC_get_pel_mask
 1164 
 1165    Returns the current PEL mask. Note that changed_vga_colors() already
 1166    applies the PEL mask; so applications should not worry too much about
 1167    it. This is a hardware emulation function.
 1168      _________________________________________________________________
 1169 
 1170 5.8.11. DAC_set_pel_mask
 1171 
 1172    Sets the PEL mask and marks all DAC entries as dirty. This is a
 1173    hardware emulation function.
 1174      _________________________________________________________________
 1175 
 1176 5.8.12. DAC_get_state
 1177 
 1178    Returns the current state of the DAC. This is a hardware emulation
 1179    function.
 1180      _________________________________________________________________
 1181 
 1182 5.9. Functions in env/video/crtcemu.c
 1183 
 1184    These are the functions defined in env/video/crtcemu.c.
 1185      _________________________________________________________________
 1186 
 1187 5.9.1. CRTC_init
 1188 
 1189    Initializes the CRT Controller. This is an interface function.
 1190      _________________________________________________________________
 1191 
 1192 5.10. Functions in env/video/dualmon.c
 1193 
 1194    These are the functions defined in env/video/dualmon.c.
 1195      _________________________________________________________________
 1196 
 1197 5.10.1. MDA_init
 1198 
 1199    Initializes the monochrome card. First detects which monochrome card
 1200    is used, because the Hercules RamFont and the Hercules InColor need
 1201    one more register to be initialized. If there is no monochrome card at
 1202    all, we just think there is one and poke an peek in the void. After
 1203    the detection the card is initialized.
 1204 
 1205    returns: nothing
 1206 
 1207    Arguments are:
 1208 
 1209      * none
 1210      _________________________________________________________________
 1211 
 1212 5.11. Remarks in env/video/dualmon.c
 1213 
 1214    After MDA_init() the VGA is configured, something in video.c or
 1215    console.c "reprograms" the monochrome card again in such a way that I
 1216    always have to run hgc.com before I can use any program that uses the
 1217    monochrome card. I've spent a day trying to find it, but I can't
 1218    figure out. Something is writing to one of the following ports: 0x3b4,
 1219    0x3b5, 0x3b8, 0x3b9, 0x3ba, 0x3bb, 0x3bf. The problem occurs at (at
 1220    least) the following 2 systems:
 1221 
 1222    - AMD 386DX40, Trident 9000/512Kb ISA, Hercules Graphics Card Plus -
 1223    Intel 486DX2/66, Cirrus Logic 5426/1Mb VLB, Hercules clone
 1224 
 1225    The problem doesn't occur when I start dosemu from a telnet connection
 1226    or from a VT100 terminal. (Erik Mouw, jakmouw@et.tudelft.nl)
 1227      _________________________________________________________________
 1228 
 1229 5.12. Functions in env/video/vgaemu.c
 1230 
 1231    These are the functions defined in env/video/vgaemu.c.
 1232      _________________________________________________________________
 1233 
 1234 5.12.1. VGA_emulate_outb
 1235 
 1236    Emulates writes to VGA ports. This is a hardware emulation function.
 1237 
 1238    Arguments are:
 1239 
 1240      * port - The port being written to.
 1241      * value - The value written,
 1242      _________________________________________________________________
 1243 
 1244 5.12.2. VGA_emulate_inb
 1245 
 1246    Emulates reads from VGA ports. This is a hardware emulation function.
 1247 
 1248    Arguments are:
 1249 
 1250      * port - The port being read from.
 1251      _________________________________________________________________
 1252 
 1253 5.12.3. vga_emu_fault
 1254 
 1255    vga_emu_fault() is used to catch video access, and handle it. This
 1256    function is called from arch/linux/async/sigsegv.c::dosemu_fault1().
 1257    The sigcontext_struct is defined in include/cpu.h. Now it catches only
 1258    changes in a 4K page, but maybe it is useful to catch each video
 1259    access. The problem when you do that is, you have to simulate each
 1260    instruction which could write to the video memory. It is easy to get
 1261    the place where the exception happens (scp->cr2), but what are those
 1262    changes? An other problem is, it could eat a lot of time, but it does
 1263    now also.
 1264 
 1265    MODIFICATION: VGA mode 12h under X is supported in exactly the way
 1266    that was suggested above. Not every instruction needs to be simulated
 1267    in order to make this feature useful, just the ones used to access
 1268    video RAM by key applications (Borland BGI, Protel, etc.).
 1269 
 1270    MODIFICATION: all VGA modes now work and almost all instructions are
 1271    simulated.
 1272 
 1273    Arguments are:
 1274 
 1275      * scp - A pointer to a struct sigcontext_struct holding some
 1276        relevant data.
 1277      _________________________________________________________________
 1278 
 1279 5.12.4. vga_emu_init
 1280 
 1281    vga_emu_init() must be called before using the VGAEmu functions. It is
 1282    only called from env/video/X.c::X_init() at the moment. This function
 1283    basically initializes the global variable `vga' and allocates the VGA
 1284    memory.
 1285 
 1286    It does in particular *not* map any memory into the range 0xa0000 -
 1287    0xc0000, this is done as part of a VGA mode switch.
 1288 
 1289    There should be an accompanying vga_emu_done().
 1290 
 1291    Arguments are:
 1292 
 1293      * vedt - Pointer to struct describing the type of display we are
 1294        actually
 1295      * attached to.
 1296      _________________________________________________________________
 1297 
 1298 5.12.5. vga_emu_update
 1299 
 1300    vga_emu_update() scans the VGA memory for dirty (= written to since
 1301    last update) pages and returns the changed area in *veut. See the
 1302    definition of vga_emu_update_type in env/video/vgaemu_inside.h for
 1303    details.
 1304 
 1305    You will need to call this function repeatedly until it returns 0 to
 1306    grab all changes. You can specify an upper limit for the size of the
 1307    area that will be returned using `veut->max_max_len' and
 1308    `veut->max_len'. See the example in env/video/X.c how this works.
 1309 
 1310    If the return value of vga_emu_update() is >= 0, it is the number of
 1311    changed pages, -1 means there are still changed pages but the maximum
 1312    update chunk size (`veut->max_max_len') was exceeded.
 1313 
 1314    This function does in its current form not work for Hercules modes; it
 1315    does, however work for text modes, although this feature is currently
 1316    not used.
 1317 
 1318    Arguments are:
 1319 
 1320      * veut - A pointer to a vga_emu_update_type object holding all
 1321        relevant info.
 1322      _________________________________________________________________
 1323 
 1324 5.12.6. vgaemu_switch_plane
 1325 
 1326    vgaemu_switch_plane() maps the specified plane.
 1327 
 1328    This function returns True on success and False on error, usually
 1329    indicating an invalid bank number.
 1330 
 1331    Arguments are:
 1332 
 1333      * plane (0..3) - The plane to map.
 1334      _________________________________________________________________
 1335 
 1336 5.12.7. vga_emu_switch_bank
 1337 
 1338    vga_emu_switch_bank() is used to emulate video-bankswitching.
 1339 
 1340    This function returns True on success and False on error, usually
 1341    indicating an invalid bank number.
 1342 
 1343    Arguments are:
 1344 
 1345      * bank - The bank to switch to.
 1346      _________________________________________________________________
 1347 
 1348 5.12.8. vga_emu_find_mode
 1349 
 1350    Searches a video mode with the requested mode number.
 1351 
 1352    The search starts with the mode *after* the mode `vmi' points to. If
 1353    `vmi' == NULL, starts at the beginning of the internal mode table.
 1354    `mode' may be a standard VGA mode number (0 ... 0x7f) or a VESA mode
 1355    number (>= 0x100). The mode number may have its don't-clear-bit (bit 7
 1356    or bit 15) or its use-lfb-bit (bit 14) set. The special mode number -1
 1357    will match any mode and may be used to scan through the whole table.
 1358 
 1359    Returns NULL if no mode was found and a pointer into the mode table
 1360    otherwise. The returned pointer is a suitable argument for subsequent
 1361    calls to this function.
 1362 
 1363    You should (and can) access the mode table only through this function.
 1364 
 1365    Arguments are:
 1366 
 1367      * mode - video mode.
 1368      * vmi - pointer into internal mode list
 1369      _________________________________________________________________
 1370 
 1371 5.12.9. vga_emu_setmode
 1372 
 1373    Set a video mode.
 1374 
 1375    Switches to `mode' with text sizes `width' and `height' or (if no such
 1376    mode was found) at least `width' and `height'.
 1377 
 1378    Arguments are:
 1379 
 1380      * mode - The new video mode.
 1381      * width - Number of text columns.
 1382      * height - Number of text rows.
 1383      _________________________________________________________________
 1384 
 1385 5.12.10. vga_emu_set_textsize
 1386 
 1387    Sets the text mode resolution. Typically called after a font change.
 1388 
 1389    Arguments are:
 1390 
 1391      * width - Number of text columns.
 1392      * height - Number of text rows.
 1393      _________________________________________________________________
 1394 
 1395 5.12.11. dirty_all_video_pages
 1396 
 1397    Marks the whole VGA memory as modified.
 1398      _________________________________________________________________
 1399 
 1400 5.12.12. dirty_all_vga_colors
 1401 
 1402    Marks all colors as changed.
 1403      _________________________________________________________________
 1404 
 1405 5.12.13. changed_vga_colors
 1406 
 1407    Checks DAC and Attribute Controller to find all colors with changed
 1408    RGB-values. Returns number of changed colors. Note: the list _must_ be
 1409    large enough, that is, have at least min(256, (1 << vga.pixel_size))
 1410    entries!
 1411 
 1412    Arguments are:
 1413 
 1414      * de - list of DAC entries to store changed colors in
 1415      _________________________________________________________________
 1416 
 1417 5.12.14. vgaemu_adj_cfg
 1418 
 1419    Adjust VGAEmu according to VGA register changes.
 1420      _________________________________________________________________
 1421 
 1422 5.13. Functions in env/video/instremu.c
 1423 
 1424    These are the functions defined in env/video/instremu.c.
 1425      _________________________________________________________________
 1426 
 1427 5.13.1. instr_len
 1428 
 1429    Returns the length of an instruction; 0 if it could not be determined.
 1430      _________________________________________________________________
 1431 
 1432 5.13.2. instr_sim
 1433 
 1434    instr_sim is used to simulate instructions that access the VGA video
 1435    memory in planar modes when using X as the video output device.
 1436 
 1437    It is necessary to do this in order to simulate the effects of the
 1438    hardware VGA controller in X mode.
 1439 
 1440    If the return value is 0, it means the instruction was not one that
 1441    for which a simulation is provided. The return value is 1 for success,
 1442    but the function exits because we need to go back to the DOSEMU's main
 1443    loop or count runs out.
 1444 
 1445    Arguments are:
 1446 
 1447      * x86: the structure holding everything about the cpu-state we need.
 1448      _________________________________________________________________
 1449 
 1450 5.13.3. instr_emu
 1451 
 1452    instr_emu is the main interface to instr_sim. It puts the processor
 1453    state in the x86 structure.
 1454 
 1455    Arguments are:
 1456 
 1457      * scp - A pointer to a struct sigcontext_struct holding some
 1458        relevant data.
 1459      * pmode - flags protected mode
 1460      * cnt - number of instructions to be simulated
 1461      _________________________________________________________________
 1462 
 1463 6. The New_Keyboard group of Modules
 1464 
 1465    Most of the New Keyboard handling code is in the "plugin/kbd_unicode"
 1466    subdirectory.
 1467      _________________________________________________________________
 1468 
 1469 6.1. Functions in plugin/kbd_unicode/serv_xlat.c
 1470 
 1471    These are the functions defined in plugin/kbd_unicode/serv_xlat.c.
 1472      _________________________________________________________________
 1473 
 1474 6.1.1. compute_keynum
 1475 
 1476    The task of compute_keynum() is to 'collect' keyboard bytes (e.g. 0xe0
 1477    prefixes) until it thinks it has assembled an entire keyboard event.
 1478    The entire keyboard event is then returned, otherwise NUM_VOID is
 1479    returned.
 1480      _________________________________________________________________
 1481 
 1482 6.1.2. translate_key
 1483 
 1484    translate_key takes a keysym event and calculates the appropriate bios
 1485    translation.
 1486 
 1487    As a side effect translate_key updates the apropriate pieces of state
 1488    to reflect the current keyboard state.
 1489 
 1490    Calling translate_key twice on the same data is likely to be
 1491    hazardous.
 1492      _________________________________________________________________
 1493 
 1494 6.1.3. put_rawkey
 1495 
 1496    This function sends a raw keycode byte, e.g. read directly from the
 1497    hardware, to DOS. It is both queued for the port60h emulation and
 1498    processed for the BIOS keyboard buffer, using the national translation
 1499    tables etc.
 1500 
 1501    For DOS applications using int16h we will therefore not have to load
 1502    KEYB.EXE, others (e.g. games) need their own drivers anyway.
 1503 
 1504    This function is used if we are at the console and
 1505    config.rawkeyboard=on.
 1506      _________________________________________________________________
 1507 
 1508 6.1.4. move_keynum
 1509 
 1510    This does all the work of sending a key event to DOS. Either pressing
 1511    a key releasing one. The key to move is the key specified by keynum.
 1512 
 1513    keynum - the keynum from keynum.h indicating a physical key make -
 1514    TRUE for key press, FALSE for release
 1515 
 1516    Applications using int16h will always see the appropriate ASCII code
 1517    for the given keyboard key and the current keyboard state. All the
 1518    chracter translation is done for you to keep from reporting
 1519    inconsistent key events.
 1520 
 1521    An emulated hardware scancode is also sent to port60h.
 1522 
 1523    Note that you have to send both MAKE (press) and BREAK (release)
 1524    events. If no BREAK codes are available (e.g. terminal mode), send
 1525    them immediately after the MAKE codes.
 1526      _________________________________________________________________
 1527 
 1528 6.1.5. keysym_to_keynum
 1529 
 1530    Allows peeking into the keytables. This returns the keynum a given
 1531    keysym sits on.
 1532      _________________________________________________________________
 1533 
 1534 6.1.6. move_key
 1535 
 1536    This does all the work of sending a key event to DOS. Either pressing
 1537    a key releasing one. The key to move is the key that is labeled with
 1538    the specified keysym.
 1539 
 1540    key - the keysym, one of the KEY_ constants from new-kbd.h make - TRUE
 1541    for key press, FALSE for release
 1542 
 1543    Applications using int16h will always see the appropriate ASCII code
 1544    for the given keyboard key and the current keyboard state. All the
 1545    chracter translation is done for you to keep from reporting
 1546    inconsistent key events.
 1547 
 1548    An emulated hardware scancode is also sent to port60h.
 1549 
 1550    Note that you have to send both MAKE (press) and BREAK (release)
 1551    events. If no BREAK codes are available (e.g. terminal mode), send
 1552    them immediately after the MAKE codes.
 1553      _________________________________________________________________
 1554 
 1555 6.1.7. put_symbol
 1556 
 1557    This does all the work of sending a key event to DOS. sym -- The
 1558    unicode value of the symbol you want to send
 1559 
 1560    Applications using int16h will always see the symbol passed here, if
 1561    it is representable in the current dos character set. The appropriate
 1562    scancodes are generated automatically to keep the keyboard code
 1563    consistent.
 1564 
 1565    An emulated hardware scancode is also sent to port60h.
 1566 
 1567    Note that you have to send both MAKE (press) and BREAK (release)
 1568    events. If no BREAK codes are available (e.g. terminal mode), send
 1569    them immediately after the MAKE codes.
 1570      _________________________________________________________________
 1571 
 1572 6.1.8. put_modified_symbol
 1573 
 1574    This does all the work of sending a key event to DOS. sym -- The
 1575    unicode value of the symbol you want to send modifiers -- modifiers
 1576    like alt etc you what to change your symbol with.
 1577 
 1578    This function is a concession to the reality, in which key events are
 1579    a composed of active modifiers, and a key label.
 1580 
 1581    This function behaves as put_symbol does, except before pressing the
 1582    key it adds the specified modifiers to the modifiers it would normally
 1583    use.
 1584 
 1585    For cases where the symbol can only be created by an alt# combination
 1586    or by pressing a dead key (Basically any case where more than one key
 1587    is requried, after setting the shiftstate) it gives up and just sends
 1588    the symbol.
 1589 
 1590    Note that you have to send both MAKE (press) and BREAK (release)
 1591    events. If no BREAK codes are available (e.g. terminal mode), send
 1592    them immediately after the MAKE codes.
 1593      _________________________________________________________________
 1594 
 1595 6.1.9. get_shiftstate
 1596 
 1597    This simply reads the keyboard server's shift state.
 1598 
 1599    This is intended to be used in conjunction with set_shiftstate to sync
 1600    up a shiftstate with a source of key events.
 1601 
 1602    With the addition of this function the keyboard inteface is clean
 1603    enough so if needed a completly different translation engine can be
 1604    dropped in to support a totally different environment (windows or
 1605    whatever).
 1606      _________________________________________________________________
 1607 
 1608 6.1.10. set_shiftstate
 1609 
 1610    This simply sets the keyboard server's shift state.
 1611 
 1612    If there are shiftstate bits you want to keep fixed simply grab them
 1613    with get_shiftstate, before calling this function.
 1614 
 1615    This changes the keyboard flags by generating the appropriate shift
 1616    key make/break codes that normally come along with such changes. So
 1617    this function should be safe in any context.
 1618 
 1619    Note also that you can't simply write to the shiftstate variable
 1620    instead of using this function.
 1621      _________________________________________________________________
 1622 
 1623 6.2. Functions in plugin/kbd_unicode/keyb_clients.c
 1624 
 1625    These are the functions defined in plugin/kbd_unicode/keyb_clients.c.
 1626      _________________________________________________________________
 1627 
 1628 6.2.1. keyb_client_init
 1629 
 1630    Figures out which keyboard client to use and initialises it.
 1631 
 1632    First it calls the probe method to see if it should use the client,
 1633    Then it call init to set that client up.
 1634 
 1635    If probe or init fails it trys another client.
 1636 
 1637    Eventually falling back to Keyboard_none a dummy client, which does
 1638    nothing.
 1639      _________________________________________________________________
 1640 
 1641 6.3. Functions in plugin/kbd_unicode/keyb_none.c
 1642 
 1643    These are the functions defined in plugin/kbd_unicode/keyb_none.c.
 1644      _________________________________________________________________
 1645 
 1646 6.3.1. none_probe
 1647 
 1648    Succeed if we can run the dummy keyboard client, (we always can). but
 1649    first try the other fall-back (slang keyboard)
 1650      _________________________________________________________________
 1651 
 1652 6.4. Functions in plugin/kbd_unicode/keyb_raw.c
 1653 
 1654    These are the functions defined in plugin/kbd_unicode/keyb_raw.c.
 1655      _________________________________________________________________
 1656 
 1657 6.4.1. raw_keyboard_init
 1658 
 1659    Initialize the keyboard for RAW mode.
 1660      _________________________________________________________________
 1661 
 1662 6.4.2. raw_keyboard_reset
 1663 
 1664    Reset the keyboard shiftstate to match the keyboard LED's
 1665      _________________________________________________________________
 1666 
 1667 6.5. Functions in plugin/term/keyb_slang.c
 1668 
 1669    These are the functions defined in plugin/term/keyb_slang.c.
 1670      _________________________________________________________________
 1671 
 1672 6.5.1. setup_pc_scancode_mode
 1673 
 1674    Initialize the keyboard in pc scancode mode. This functionality is
 1675    ideal but rarely supported on a terminal.
 1676      _________________________________________________________________
 1677 
 1678 6.5.2. exit_pc_scancode_mode
 1679 
 1680    Set the terminal back to a keyboard mode other programs can
 1681    understand.
 1682      _________________________________________________________________
 1683 
 1684 6.5.3. do_pc_scancode_getkeys
 1685 
 1686    Set the terminal back to a keyboard mode other programs can
 1687    understand.
 1688      _________________________________________________________________
 1689 
 1690 6.5.4. slang_keyb_init()
 1691 
 1692    Code is called at start up to set up the terminal line for non-raw
 1693    mode.
 1694      _________________________________________________________________
 1695 
 1696 6.5.5. slang_keyb_probe()
 1697 
 1698    Code is called at start up to see if we can use the slang keyboard.
 1699      _________________________________________________________________
 1700 
 1701 7. The Misc group of Modules
 1702 
 1703    These are the remaining important files, that do not really fit into
 1704    another group. These should not be dismissed as unimportant - rather,
 1705    they are often amongst the most important.
 1706      _________________________________________________________________
 1707 
 1708 7.1. Functions in base/async/int.c
 1709 
 1710    These are the functions defined in base/async/int.c.
 1711      _________________________________________________________________
 1712 
 1713 7.1.1. int1a
 1714 
 1715    int 0x1A call
 1716 
 1717    This has (among other things) the calls that DOS makes to get/set its
 1718    sense of time. On booting, DOS gets the RTC time and date with AH=2
 1719    and AH=4, after that it should use AH=0 calls to read the 'tick'
 1720    counter from BIOS memory. Each time this crosses midnight, a flag is
 1721    set that DOS uses to increment its date.
 1722 
 1723    Here we can now change the 'view' of time so the calls either return
 1724    BIOS tick (most DOS like), read the PIT counter (avoids INT-8 changes)
 1725    or gets LINUX time (most accurate for long term NTP-adjusted time
 1726    keeping).
 1727      _________________________________________________________________
 1728 
 1729 7.1.2. ms_dos
 1730 
 1731    int0x21 call
 1732 
 1733    we trap this for two functions: simulating the EMMXXXX0 device and
 1734    fudging the CONFIG.XXX and AUTOEXEC.XXX bootup files.
 1735 
 1736    note that the emulation herein may cause problems with programs that
 1737    like to take control of certain int 21h functions, or that change
 1738    functions that the true int 21h functions use. An example of the
 1739    latter is ANSI.SYS, which changes int 10h, and int 21h uses int 10h.
 1740    for the moment, ANSI.SYS won't work anyway, so it's no problem.
 1741      _________________________________________________________________
 1742 
 1743 7.1.3. run_caller_func(i, revect)
 1744 
 1745    This function runs the specified caller function in response to an int
 1746    instruction. Where i is the interrupt function to execute.
 1747 
 1748    revect specifies whether we call a non-revectored leaf interrupt
 1749    function or a "watcher" that sits in between: the leaf interrupt
 1750    function is called if cs:ip is at f000:i*10 or if (the int vector
 1751    points there and the int is labelled non-revectored) otherwise the
 1752    non-leaf interrupt function is called, which may chain through to the
 1753    real interrupt function (if it returns 0)
 1754 
 1755    This function runs the instruction with the following model _CS:_IP is
 1756    the address to start executing at after the caller function
 1757    terminates, and _EFLAGS are the flags to use after termination. For
 1758    the simple case of an int instruction this is easy. _CS:_IP =
 1759    retCS:retIP and _FLAGS = retFLAGS as well equally the current values
 1760    (retIP = curIP +2 technically).
 1761 
 1762    However if the function is called (from dos) by simulating an int
 1763    instruction (something that is common with chained interrupt vectors)
 1764    _CS:_IP = BIOS_SEG:HLT_OFF(i) and _FLAGS = curFLAGS while retCS,
 1765    retIP, and retFlags are on the stack. These I pop and place in the
 1766    appropriate registers.
 1767 
 1768    This functions actions certainly correct for functions executing an
 1769    int/iret discipline. And almost certianly correct for functions
 1770    executing an int/retf#2 discipline (with flag changes), as an iret is
 1771    always possilbe. However functions like dos int 0x25 and 0x26
 1772    executing with a int/retf will not be handled correctlty by this
 1773    function and if you need to handle them inside dosemu use a halt
 1774    handler instead.
 1775 
 1776    Finally there is a possible trouble spot lurking in this code.
 1777    Interrupts are only implicitly disabled when it calls the caller
 1778    function, so if for some reason the main loop would be entered before
 1779    the caller function returns wrong code may execute if the retFLAGS
 1780    have interrupts enabled!
 1781 
 1782    This is only a real handicap for sequences of dosemu code execute for
 1783    long periods of time as we try to improve timer response and prevent
 1784    signal queue overflows! -- EB 10 March 1997
 1785 
 1786    Grumble do to code that executes before interrupts, and the semantics
 1787    of default_interupt, I can't implement this function as I would like.
 1788    In the tricky case of being called from dos by simulating an int
 1789    instruction, I must leave retCS, retIP, on the stack. But I can safely
 1790    read retFlags so I do. I pop retCS, and retIP just before returning to
 1791    dos, as well as dropping the stack slot that held retFlags.
 1792 
 1793    This improves consistency of interrupt handling, but not quite as much
 1794    as if I could handle it the way I would like. -- EB 30 Nov 1997
 1795 
 1796    Trying to get it right now -- BO 25 Jan 2003
 1797 
 1798    This function returns 1 if it's completely finished (no need to run
 1799    real_run_int()), otherwise 0.
 1800      _________________________________________________________________
 1801 
 1802 7.1.4. DO_INT
 1803 
 1804    DO_INT is used to deal with interrupts returned to DOSEMU by the
 1805    kernel.
 1806      _________________________________________________________________
 1807 
 1808 7.1.5. setup_interrupts
 1809 
 1810    SETUP_INTERRUPTS is used to initialize the interrupt_function array
 1811    which directs handling of interrupts in protected mode and also
 1812    initializes the base vector for interrupts in real mode.
 1813      _________________________________________________________________
 1814 
 1815 7.1.6. int_vector_setup
 1816 
 1817    Setup initial interrupts which can be revectored so that the kernel
 1818    does not need to return to DOSEMU if such an interrupt occurs.
 1819      _________________________________________________________________
 1820 
 1821 7.2. Remarks in base/async/int.c
 1822 
 1823    Many video BIOSes use hi interrupt vector locations as scratchpad area
 1824    - this is because they come before DOS and feel safe to do it. But we
 1825    are initializing vectors before video, so this only causes trouble. I
 1826    assume no video BIOS will ever: - change vectors < 0xe0 (0:380-0:3ff
 1827    area) - change anything in the vector area _after_ installation - AV
 1828      _________________________________________________________________
 1829 
 1830 7.3. Functions in arch/linux/async/sigsegv.c
 1831 
 1832    These are the functions defined in arch/linux/async/sigsegv.c.
 1833      _________________________________________________________________
 1834 
 1835 7.3.1. dosemu_fault(int, struct sigcontext_struct);
 1836 
 1837    All CPU exceptions (except 13=general_protection from V86 mode, which
 1838    is directly scanned by the kernel) are handled here.
 1839      _________________________________________________________________
 1840 
 1841 7.3.2. print_exception_info
 1842 
 1843    Prints information about an exception: exception number, error code,
 1844    address, reason, etc.
 1845      _________________________________________________________________
 1846 
 1847 7.4. Functions in arch/linux/async/signal.c
 1848 
 1849    These are the functions defined in arch/linux/async/signal.c.
 1850      _________________________________________________________________
 1851 
 1852 7.4.1. NEWSETQSIG
 1853 
 1854    Arguments are:
 1855 
 1856      * sig - the signal to have a handler installed to.
 1857      * fun - the signal handler function to install
 1858 
 1859    All signals that wish to be handled properly in context with the
 1860    execution of vm86() mode, and signals that wish to use non-reentrant
 1861    functions should add themselves to the ADDSET_SIGNALS_THAT_QUEUE
 1862    define and use SETQSIG(). To that end they will also need to be set up
 1863    in an order such as SIGIO.
 1864      _________________________________________________________________
 1865 
 1866 7.4.2. SIG_init
 1867 
 1868    The IRQ numbers to monitor are taken from config.sillyint, each bit
 1869    corresponding to one IRQ. The higher 16 bit are defining the use of
 1870    SIGIO
 1871      _________________________________________________________________
 1872 
 1873 7.4.3. signal_init
 1874 
 1875    Initialize the signals to have NONE being blocked. Currently this is
 1876    NOT of much use to DOSEMU.
 1877      _________________________________________________________________
 1878 
 1879 7.4.4. handle_signals
 1880 
 1881    Due to signals happening at any time, the actual work to be done
 1882    because a signal occurs is done here in a serial fashion.
 1883 
 1884    The concept, should this eventualy work, is that a signal should only
 1885    flag that it has occurred and let DOSEMU deal with it in an orderly
 1886    fashion as it executes the rest of it's code.
 1887      _________________________________________________________________
 1888 
 1889 7.4.5. SIGNAL_save
 1890 
 1891    Arguments are:
 1892 
 1893      * context - signal context to save.
 1894      * signal_call - signal handling routine to be called.
 1895 
 1896    Save into an array structure queue the signal context of the current
 1897    signal as well as the function to call for dealing with this signal.
 1898    This is a queue because any signal may occur multiple times before
 1899    DOSEMU deals with it down the road.
 1900      _________________________________________________________________
 1901 
 1902 7.4.6. SIGIO_call
 1903 
 1904    Whenever I/O occurs on devices allowing SIGIO to occur, DOSEMU will be
 1905    flagged to run this call which inturn checks which fd(s) was set and
 1906    execute the proper routine to get the I/O from that device.
 1907      _________________________________________________________________
 1908 
 1909 7.5. Remarks in arch/linux/async/signal.c
 1910 
 1911    We assume system call restarting... under linux 0.99pl8 and earlier,
 1912    this was the default. SA_RESTART was defined in 0.99pl8 to explicitly
 1913    request restarting (and thus does nothing). However, if this ever
 1914    changes, I want to be safe
 1915 
 1916    -----
 1917 
 1918    Check for keyboard coming from client For now, first byte is interrupt
 1919    requests from Client
 1920      _________________________________________________________________
 1921 
 1922 7.6. Functions in base/misc/disks.c
 1923 
 1924    These are the functions defined in base/misc/disks.c.
 1925      _________________________________________________________________
 1926 
 1927 7.6.1. disk_init
 1928 
 1929    Test by opening all floppies/hardrives configured.
 1930      _________________________________________________________________
 1931 
 1932 7.7. Functions in base/dev/misc/timers.c
 1933 
 1934    These are the functions defined in base/dev/misc/timers.c.
 1935      _________________________________________________________________
 1936 
 1937 7.7.1. initialize_timers
 1938 
 1939    ensure the 0x40 port timer is initially set correctly
 1940      _________________________________________________________________
 1941 
 1942 7.7.2. timer_tick
 1943 
 1944    Every time we get a TIMER signal from Linux, this procedure is called.
 1945    It checks to see if we should queue a timer interrupt based on the
 1946    current values.
 1947      _________________________________________________________________
 1948 
 1949 7.7.3. do_sound
 1950 
 1951    do_sound handles the _emulated_ mode pc-speaker emulation.
 1952 
 1953    As far as I can determine all cases of the pc-speaker are now
 1954    emulated. But I am not sure where Rainer Zimmerman got his
 1955    (pit[2].mode == 2) || (pit[2].mode == 3) test in the original
 1956    implementation, it doesn't seem to cause problems though.
 1957 
 1958    The implementation of speaker_on & speaker_off can be found in
 1959    src/base/speaker.c
 1960 
 1961    Major Changes from version written by Rainter Zimmerman.
 1962 
 1963    o Added support for programs that control the directly through bit 1
 1964    of port61.
 1965 
 1966    o Added a generic interface to allow multiple speaker backends.
 1967 
 1968    o Implemented X speaker code so the emulated speaker now works in X.
 1969 
 1970    --EB 21 September 1997
 1971      _________________________________________________________________
 1972 
 1973 7.7.4. timer_int_engine
 1974 
 1975    This is experimental TIMER-IRQ CHAIN code! This is a function to
 1976    determine whether it is time to invoke a new timer irq 0 event.
 1977    Normally it is 18 times a second, but many video games set it to 100
 1978    times per second or more. Since the kernel cannot keep an accurate
 1979    timer interrupt, the job of this routine is to perform a chained timer
 1980    irq 0 right after the previous timer irq 0. This routine should,
 1981    ideally, be called right after the end of a timer irq, if possible.
 1982 
 1983    This would speed up high frequency timer interrupts if this code can
 1984    be converted into an assembly macro equivalent!
 1985 
 1986    PLEASE NOTE
 1987 
 1988    This code has been replaced by interrupt scheduling code in pic. The
 1989    result is that we simply call pic_sched and run the dos interrupt. If
 1990    the new code causes no problems, I'll revise this section permanently.
 1991      _________________________________________________________________
 1992 
 1993 7.8. Functions in base/misc/dos2linux.c
 1994 
 1995    These are the functions defined in base/misc/dos2linux.c.
 1996      _________________________________________________________________
 1997 
 1998 7.8.1. run_unix_command
 1999 
 2000    Runs a command and prints the (stdout and stderr) output on the dosemu
 2001    screen.
 2002 
 2003    Return values mean:
 2004 
 2005    Arguments are:
 2006 
 2007      * buffer - string with command to execute
 2008      _________________________________________________________________
 2009 
 2010 7.9. Functions in base/misc/ioctl.c
 2011 
 2012    These are the functions defined in base/misc/ioctl.c.
 2013      _________________________________________________________________
 2014 
 2015 7.9.1. io_select_init
 2016 
 2017    Initialize fd_sets to NULL for both SIGIO and NON-SIGIO.
 2018      _________________________________________________________________
 2019 
 2020 7.9.2. add_to_io_select
 2021 
 2022    Arguments are:
 2023 
 2024      * fd - File handle to add to select statment
 2025      * want_sigio - want SIGIO (1) if it's available, or not (0).
 2026 
 2027    Add file handle to one of 2 select FDS_SET's depending on whether the
 2028    kernel can handle SIGIO.
 2029      _________________________________________________________________
 2030 
 2031 7.9.3. remove_from_io_select
 2032 
 2033    Arguments are:
 2034 
 2035      * fd - File handle to remove from select statment.
 2036      * used_sigio - used SIGIO (1) if it's available, or not (0).
 2037 
 2038    Remove a file handle from one of 2 select FDS_SET's depending on
 2039    whether the kernel can handle SIGIO.
 2040      _________________________________________________________________
 2041 
 2042 7.10. Functions in base/dev/misc/lpt.c
 2043 
 2044    These are the functions defined in base/dev/misc/lpt.c.
 2045      _________________________________________________________________
 2046 
 2047 7.10.1. printer_init
 2048 
 2049    Initialize printer control structures
 2050      _________________________________________________________________
 2051 
 2052 7.11. Functions in base/dev/misc/pci.c
 2053 
 2054    These are the functions defined in base/dev/misc/pci.c.
 2055      _________________________________________________________________
 2056 
 2057 7.11.1. pci_read_header
 2058 
 2059    Use standard 32-bit (type 1) access method to read PCI configuration
 2060    space data
 2061      _________________________________________________________________
 2062 
 2063 7.11.2. pci_setup
 2064 
 2065    Register standard PCI ports 0xcf8-0xcff
 2066      _________________________________________________________________
 2067 
 2068 7.12. Functions in base/dev/misc/joystick.c
 2069 
 2070    These are the functions defined in base/dev/misc/joystick.c.
 2071      _________________________________________________________________
 2072 
 2073 7.12.1. joy_latency_over
 2074 
 2075    Tells DOSEMU whether or not it is time to update its internal status
 2076    of the joystick (for nonblocking reads only).
 2077 
 2078    DOS programs read/poll from the joystick port hundreds of thousands of
 2079    times per second so the idea is that we really don't need to read from
 2080    Linux for every such query (increasing performance by about 40%)
 2081    because:
 2082 
 2083    1. humans are incapable of changing the status of the joystick
 2084    (moving, pressing buttons) more than about 10 times per second
 2085 
 2086    2. no one will not notice a delay in DOS registering the joystick
 2087    status (if it is in the order of a few milliseconds)
 2088 
 2089    Of course, this means that you should not set joy_latency in
 2090    dosemu.conf to more than 1000/(#times I can press a button/move joy
 2091    per second * 2), unless you want DOSEMU to miss quick axis/button
 2092    changes and want to wait a ridiculous amount of time before DOSEMU
 2093    registers any changes at all.
 2094      _________________________________________________________________
 2095 
 2096 7.12.2. joy_emu_button_set
 2097 
 2098    Update the button status for each joystick.
 2099 
 2100    We must perform "button mapping" if only the first joystick is enabled
 2101    i.e. we are required to map the "excessive" buttons (>2) from the
 2102    first joystick onto the second:
 2103 
 2104    a) 3rd button of 1st joy --> 1st button of 2nd joy
 2105 
 2106    b) 4th button of 1st joy --> 2nd button of 2nd joy
 2107      _________________________________________________________________
 2108 
 2109 7.12.3. joy_emu_axis_set
 2110 
 2111    Update the axis status for each joystick.
 2112 
 2113    We must perform "axis mapping" if only the first joystick is enabled
 2114    i.e. we are required to map the "excessive" axes (>2) from the first
 2115    joystick onto the second:
 2116 
 2117    a) 3rd axis of 1st joy --> 2st axis of 2nd joy
 2118 
 2119    b) 4th axis of 1st joy --> 1st axis of 2nd joy (yes, these are
 2120    reversed deliberately because it's what happens in DOS)
 2121      _________________________________________________________________
 2122 
 2123 7.12.4. joy_emu_axis_conv
 2124 
 2125    Convert a Linux joystick axis reading to a DOS one by making use of
 2126    the differences in the allowable range of axis values.
 2127 
 2128    NOTE: I don't know whether or not Linux returns exponential values for
 2129    the joystick but (apparently) DOS programs expect the values to be
 2130    exponential and so if this is to be fixed, it should probably be done
 2131    in this function.
 2132      _________________________________________________________________
 2133 
 2134 7.12.5. joy_linux_process_event
 2135 
 2136    Update global joystick status variables given a Linux joystick event.
 2137      _________________________________________________________________
 2138 
 2139 7.12.6. joy_linux_read_events
 2140 
 2141    Process the event queue for _both_ linux joysticks using nonblocking
 2142    reads with the new joystick API (joy_driver_new).
 2143 
 2144    This should be done before (well, actually, not before _every_ single
 2145    read -- see joy_latency_over()) the joystick status is returned to DOS
 2146    as all Linux joystick events are queued until they are processed and
 2147    we want to return a reasonably current state of the joystick -- not
 2148    what it was a long time ago. _Both_ joysticks are processed here
 2149    because of axis/button mapping affecting the status of both emulated
 2150    joysticks (what DOS sees).
 2151      _________________________________________________________________
 2152 
 2153 7.12.7. joy_linux_read_status
 2154 
 2155    Read both the current position and current button status of the
 2156    joystick from Linux (joy_driver_old).
 2157      _________________________________________________________________
 2158 
 2159 7.12.8. joy_linux_read_buttons_(family)
 2160 
 2161    Eventually called from DOS to get the button status of the joysticks.
 2162    The threaded version will simply get the status from global variables.
 2163    The unthreaded versions will perform non-blocking reads.
 2164      _________________________________________________________________
 2165 
 2166 7.12.9. joy_linux_read_axis_(family)
 2167 
 2168    Eventually called from DOS to get the axis status of the joysticks.
 2169    The threaded version will simply get the values from global variables.
 2170    The unthreaded versions will perform non-blocking reads.
 2171 
 2172    Arguments are:
 2173 
 2174      * invalid_val - value to return to signify a non-existent axis
 2175      * update - whether DOSEMU should update its internal axis values
 2176        from Linux
 2177      * (for each read of the joystick position, set this flag _only_
 2178      * on the first of the 4 calls to this function unless you want
 2179      * the axis positions to be from different points in time :)
 2180      _________________________________________________________________
 2181 
 2182 7.12.10. joy_bios_read
 2183 
 2184    This is the int15 function 0x84 handler (i.e. BIOS joystick
 2185    emulation), called from src/base/async/int.c.
 2186 
 2187    The real BIOS actually reads its values straight from the joystick
 2188    port (0x201) but we don't bother because we can do it faster :)
 2189 
 2190    Because of this, it returns the joystick axis values with the same
 2191    range as port 0x201 BUT the range for a real BIOS varies between
 2192    computers as it is dependant on how it reads from the port (hopefully
 2193    this won't cause any problems).
 2194      _________________________________________________________________
 2195 
 2196 7.12.11. joy_port_inb
 2197 
 2198    This function emulates reads from the joystick port (0x201) -- this is
 2199    the most common way of detecting and reading the joystick.
 2200 
 2201    The real implementation of this port sets a bit for each axis for a
 2202    certain period of time, corresponding to analog measurements of the
 2203    position of each axis (so "if you count the analog values in software,
 2204    a faster machine yields different values from a slow machine [unless
 2205    you use a timer]" - DOS 6: A Developer's Guide).
 2206 
 2207    In contrast, this implementation sets the bits high for a certain
 2208    number of port reads, corresponding to the position of each axis
 2209    (independent of time). This means that, for most programs, the axis
 2210    range will be that specified in dosemu.conf (which is rather
 2211    convenient) and avoids the issue of super-fast computers causing DOS
 2212    program axis counters to overflow (e.g. in a real system, if the
 2213    program used an 8-bit variable for storing the position of an axis and
 2214    the system was fast enough to read from the port more than 127 or 255
 2215    times, there would be trouble).
 2216      _________________________________________________________________
 2217 
 2218 7.13. Remarks in base/dev/misc/joystick.c
 2219 
 2220    We make a runtime decision based on the detected joystick API version
 2221    and #ifdef USE_PTHREADS, on the way in which we obtain the joystick
 2222    status from Linux (a "driver"):
 2223 
 2224    1. joy_driver_nojoy: simply tells DOS programs that you have no
 2225    joystick(s)
 2226 
 2227    2. joy_driver_old: uses old, non-blocking joystick API (<1.0.0);
 2228    limited to 2 axes; supported because DOSEMU supports old kernels
 2229 
 2230    3. joy_driver_new: uses new, non-blocking joystick API (>=1.0.0); a
 2231    (little) slower than joy_driver_new_threaded
 2232 
 2233    4. joy_driver_new_threaded: uses new, BLOCKING joystick API (>=1.0.0);
 2234    efficient but requires pthreads (which is known to make DOSEMU
 2235    unstable!)
 2236 
 2237    The same driver is used for both joysticks.
 2238 
 2239    -----
 2240 
 2241    if the 2nd joystick is enabled, we ignore any button >= 2 regardless
 2242    of which joystick it is (if it's the 1st, the 2nd joystick would
 2243    overwrite its buttons; if it's the 2nd, it would be out of range)
 2244 
 2245    -----
 2246 
 2247    if the 2nd joystick is enabled, we ignore any axis >= 2 regardless of
 2248    which joystick it is (if it's the 1st, the 2nd joystick would
 2249    overwrite its axes; if it's the 2nd, it would be out of range)
 2250 
 2251    -----
 2252 
 2253    Apparently, the Carry Flag is cleared if int15 function 0x84 exists
 2254    and it is set if it doesn't exist.
 2255 
 2256    But what does this mean? Does the existence of such a BIOS function
 2257    depend on the existence of a Game Card/SoundBlaster, or does it just
 2258    mean that there is such an implemented BIOS function, regardless of
 2259    whether or not you have a joystick?
 2260 
 2261    I have never seen a real BIOS set the Carry Flag on this call, even on
 2262    a computer without a joystick -- so to mimick what happens in the real
 2263    world, I just clear the Carry Flag regardless of whether the user has
 2264    a joystick or not. This could be incorrect behaviour so it may have to
 2265    be changed in the future.
 2266 
 2267    -----
 2268 
 2269    Here we set bits based on joystick axis counters. The code here is
 2270    particularly tricky and if you try to change it, you will probably
 2271    break it :)
 2272 
 2273    -----
 2274 
 2275    Here we read the button status from Linux (programs can read the
 2276    button status from the port, _without_ making a dummy write to the
 2277    port first so the Linux read must be done _here_) and return it.
 2278      _________________________________________________________________
 2279 
 2280 7.14. Items for Fixing in base/dev/misc/joystick.c
 2281 
 2282    does this code work for ports other than 0x201?
 2283 
 2284    -----
 2285 
 2286    joy_reset() is called immediately after joy_init(), which is rather
 2287    inconvenient (anyone heard of a port_unregister_handler()?) so we
 2288    don't bother resetting at all but in the future this could cause
 2289    problems
 2290 
 2291    -----
 2292 
 2293    perhaps we should not have been called to start with?
 2294      _________________________________________________________________
 2295 
 2296 7.15. Remarks in include/doshelpers.h
 2297 
 2298    The Helper Interrupt uses the following groups:
 2299 
 2300    0x00 - Check for DOSEMU 0x01-0x11 - Initialisation functions &
 2301    Debugging 0x12 - Set hogthreshold (aka garrot?) 0x20 - MFS functions
 2302    0x21-0x22 - EMS functions 0x28 - Garrot Functions for use with the
 2303    mouse 0x29 - Serial functions 0x30 - Whether to use the BOOTDISK
 2304    predicate 0x33 - Mouse Functions 0x40 - CD-ROM functions 0x50-0x5f -
 2305    DOSEMU/Linux communications 50 -- run unix command in ES:DX 51,52? 53
 2306    -- do system(ES:DX) 54 -- get CPU speed 55 -- get terminal type
 2307    0x60-0x6f - reserved for plug-ins 0x7a - IPX functions 0x8x -- utility
 2308    functions 0x80 -- getcwd(ES:DX, size AX) 0x81 -- chdir(ES:DX) 0xdc -
 2309    helper for DosC kernel 0xfe - called from our MBR, emulate MBR-code.
 2310    0xff - Terminate DOSEMU
 2311 
 2312    There are (as yet) no guidelines on choosing areas for new functions.
 2313      _________________________________________________________________
 2314 
 2315 8. The CPU_Intel group of Modules
 2316 
 2317    These files all relate to Intel-x86 specific code.
 2318      _________________________________________________________________
 2319 
 2320 8.1. Functions in emu-i386/cpu.c
 2321 
 2322    These are the functions defined in emu-i386/cpu.c.
 2323      _________________________________________________________________
 2324 
 2325 8.1.1. cpu_trap_0f
 2326 
 2327    process opcodes 0F xx xx trapped by GP_fault returns 1 if handled, 0
 2328    otherwise Main difference with previous version: bits in our
 2329    pseudo-control regs can now be written. This should make CPU detection
 2330    pgms happy.
 2331      _________________________________________________________________
 2332 
 2333 8.1.2. cpu_setup
 2334 
 2335    Setup initial interrupts which can be revectored so that the kernel
 2336    does not need to return to DOSEMU if such an interrupt occurs.
 2337      _________________________________________________________________
 2338 
 2339 8.2. Functions in emu-i386/ports.c
 2340 
 2341    These are the functions defined in emu-i386/ports.c.
 2342      _________________________________________________________________
 2343 
 2344 8.2.1. port_inb(ioport_t port)
 2345 
 2346    Handles/simulates an inb() port IO read
 2347      _________________________________________________________________
 2348 
 2349 8.2.2. port_outb(ioport_t port, Bit8u byte)
 2350 
 2351    Handles/simulates an outb() port IO write
 2352      _________________________________________________________________
 2353 
 2354 8.2.3. port_inw(ioport_t port)
 2355 
 2356    Handles/simulates an inw() port IO read. Usually this invokes
 2357    port_inb() twice, but it may be necessary to do full word i/o for some
 2358    video boards.
 2359      _________________________________________________________________
 2360 
 2361 8.2.4. port_outw(ioport_t port, Bit16u word)
 2362 
 2363    Handles/simulates an outw() port IO write
 2364      _________________________________________________________________
 2365 
 2366 8.2.5. port_ind(ioport_t port)
 2367 
 2368    Handles/simulates an ind()/outd() port IO read/write.
 2369      _________________________________________________________________
 2370 
 2371 8.2.6. special_port_inb,special_port_outb
 2372 
 2373    I don't know what to do of this stuff... it was added incrementally to
 2374    port.c and has mainly to do with video code. This is not the right
 2375    place for it... Anyway, this implements some HGC stuff for X and the
 2376    emuretrace port access for 0x3c0/0x3da
 2377      _________________________________________________________________
 2378 
 2379 8.2.7. port_init()
 2380 
 2381    Resets all the port port_handler information. This must be called
 2382    before parsing the config file - This must NOT be called again when
 2383    warm booting! Can't use debug logging, it is called too early.
 2384      _________________________________________________________________
 2385 
 2386 8.2.8. extra_port_init()
 2387 
 2388    Catch all the special cases previously defined in ports.c mainly video
 2389    stuff that should be moved away from here This must be called at the
 2390    end of initialization phase
 2391 
 2392    NOTE: the order in which these inits are done could be significant! I
 2393    tried to keep it the same it was in ports.c but this code surely can
 2394    still have bugs
 2395      _________________________________________________________________
 2396 
 2397 8.2.9. port_register_handler
 2398 
 2399    Assigns a handle in the port table to a range of ports with or without
 2400    a device, and registers the ports
 2401      _________________________________________________________________
 2402 
 2403 8.2.10. set_ioperm
 2404 
 2405    wrapper for the ioperm() syscall, returns -1 if not successful.
 2406      _________________________________________________________________
 2407 
 2408 8.3. Remarks in emu-i386/ports.c
 2409 
 2410    The following port_{in|out}{bwd} functions are the main entry points
 2411    to the port code. They look into the port_handle_table and call the
 2412    appropriate code, usually the std_port_ functions, but each device is
 2413    free to register its own functions which in turn will call std_port or
 2414    directly access I/O (like video code does), or emulate it - AV
 2415 
 2416    -----
 2417 
 2418    optimized versions for rep - basically we avoid changing privileges
 2419    and iopl on and off lots of times. We are safe letting iopl=3 here
 2420    since we don't exit from this code until finished. This code is shared
 2421    between VM86 and DPMI.
 2422 
 2423    -----
 2424 
 2425    This is the core of the new emuretrace algorithm: If a read of port
 2426    0x3da is performed we just set it as pending and set ioperm OFF for
 2427    port 0x3c0 When a write to port 0x3c0 is then trapped, we perform any
 2428    pending read to 0x3da and reset the ioperm for 0x3c0 in the default ON
 2429    state. This way we avoid extra port accesses when the program is only
 2430    looking for the sync bits, and we don't miss the case where the read
 2431    to 0x3da is used to reset the index/data flipflop for port 0x3c0.
 2432    Futher accesses to port 0x3c0 are handled at full speed.
 2433 
 2434    -----
 2435 
 2436    find out whether the port address request is available; this way, try
 2437    to deny uncoordinated access
 2438 
 2439    If it is not listed in /proc/ioports, register them (we need some
 2440    syscall to do so bo 960609)... (we have a module to do so AV 970813)
 2441    if it is registered, we need the name of a device to open if we can't
 2442    open it, we disallow access to that port
 2443 
 2444    -----
 2445 
 2446    We need to check if our required port range is in use by some device.
 2447    So we look into proc/ioports to check the addresses. Fine, but at this
 2448    point we must supply a device name ourselves, and we can't check from
 2449    here if it's the right one. The device is then open and left open
 2450    until dosemu ends; for the rest, in the original code the device
 2451    wasn't used, just locked, and only then port access was granted.
 2452      _________________________________________________________________
 2453 
 2454 8.4. Items for Fixing in emu-i386/ports.c
 2455 
 2456    This stuff should be moved to video code!!
 2457 
 2458    -----
 2459 
 2460    we should free the name but we are going to exit anyway
 2461      _________________________________________________________________
 2462 
 2463 8.5. Functions in emu-i386/do_vm86.c
 2464 
 2465    These are the functions defined in emu-i386/do_vm86.c.
 2466      _________________________________________________________________
 2467 
 2468 8.5.1. vm86_GP_fault
 2469 
 2470    All from the kernel unhandled general protection faults from V86 mode
 2471    are handled here. This are mainly port IO and the HLT instruction.
 2472      _________________________________________________________________
 2473 
 2474 8.5.2. run_vm86
 2475 
 2476    Here is where DOSEMU runs VM86 mode with the vm86() call which also
 2477    has the registers that it will be called with. It will stop vm86 mode
 2478    for many reasons, like trying to execute an interrupt, doing port I/O
 2479    to ports not opened for I/O, etc ...
 2480      _________________________________________________________________
 2481 
 2482 8.5.3. loopstep_run_vm86
 2483 
 2484    Here we collect all stuff, that has to be executed within _one_ pass
 2485    (step) of a loop containing run_vm86().
 2486      _________________________________________________________________
 2487 
 2488 8.6. Remarks in emu-i386/do_vm86.c
 2489 
 2490    Here we handle all prefixes prior switching to the appropriate
 2491    routines The exception CS:EIP will point to the first prefix that
 2492    effects the faulting instruction, hence, 0x65 0x66 is same as 0x66
 2493    0x65. So we collect all prefixes and remember them. - Hans Lermen
 2494      _________________________________________________________________
 2495 
 2496 8.7. Functions in emu-i386/cputime.c
 2497 
 2498    These are the functions defined in emu-i386/cputime.c.
 2499      _________________________________________________________________
 2500 
 2501 8.7.1. GETcpuTIME
 2502 
 2503    GETcpuTIME is a pointer to a function which returns the relative CPU
 2504    time. Different methods of getting the time can then be implemented,
 2505    currently there are two using gettimeofday() for 486 and TSC for
 2506    pentium
 2507      _________________________________________________________________
 2508 
 2509 8.7.2. GETusTIME(sc)
 2510 
 2511    GETusTIME returns the DOS time with 1-usec resolution using GETcpuTIME
 2512    to get the implementation-dependent CPU time. The 'sc' parameter is
 2513    unused.
 2514      _________________________________________________________________
 2515 
 2516 8.7.3. GETtickTIME(sc)
 2517 
 2518    GETtickTIME returns the DOS time with 838ns resolution using
 2519    GETcpuTIME to get the implementation-dependent CPU time. The 'sc'
 2520    parameter is unused.
 2521      _________________________________________________________________
 2522 
 2523 8.7.4. GETusSYSTIME()
 2524 
 2525    GETusSYSTIME returns the real CPU time with 1-usec resolution
 2526      _________________________________________________________________
 2527 
 2528 8.8. Remarks in emu-i386/cputime.c
 2529 
 2530    At the heart of the timing system in dosemu >= 0.67.11 is the
 2531    availability of the system time as a 64-bit [type hitimer_t] monoton
 2532    value. (a 64-bit timer on a 200MHz CPU increments by 2^48 a day).
 2533 
 2534    Dosemu needs this time under two resolutions:
 2535 
 2536        - a MICROSECOND resolution for general timing purposes
 2537        - a TICK(838ns) resolution for PIT
 2538 
 2539    On non-pentium machines, only the first one is available via the
 2540    kernel call gettimeofday(). On the pentium and up, the situation is
 2541    better since we have a cheap hi-res timer on-chip, and worse since
 2542    this timer runs at a speed depending from the CPU clock (which we need
 2543    to know/measure, and could be not 100% accurate esp. if the speed is a
 2544    non-integer multiple of 33.3333).
 2545 
 2546    dosemu >= 0.67.11 can use both timing methods (call them 486 and
 2547    pentium), and switch between them in a dynamic way when configuring.
 2548 
 2549    At the first level (local to the file cputime.c) there are the RAW
 2550    timer functions, addressed by RAWcpuTIME(). These get the actual
 2551    absolute CPU time in usecs.
 2552 
 2553    At the second level, GETcpuTIME() returns the relative, zero-based
 2554    system time. This is where the 486/pentium switch happens.
 2555 
 2556    The third level is the actual timer interface for dosemu and is made
 2557    of two functions:
 2558 
 2559       - GETusTIME(s)   gives the time in usecs
 2560       - GETtickTIME(s) gives the time in ticks
 2561 
 2562    The 's' parameter can be used to control secondary time functions like
 2563    'time stretching' (see the READMEs). The function GETusSYSTIME() never
 2564    activates this stretching, and is used only by the realtime
 2565    thread-based 1-sec timer in rtc.c.
 2566 
 2567    All timing are RELATIVE to a base. The use of a based time allows us
 2568    to play more freely with time, e.g. stop and restart it during
 2569    debugging, stretch it, make it go at different speeds between
 2570    real-time and CPU emulation, etc. The base has been chosen to be zero,
 2571    because it will avoid overflows in calculations, produce more readable
 2572    and more easily comparable debug log files, and also because only
 2573    int0x1a and BIOS timer require knowledge of the actual time, PIT and
 2574    PIC are not sensitive.
 2575      _________________________________________________________________
 2576 
 2577 8.9. Functions in emu-i386/simx86/sigsegv.c
 2578 
 2579    These are the functions defined in emu-i386/simx86/sigsegv.c.
 2580      _________________________________________________________________
 2581 
 2582 8.9.1. dosemu_fault(int, struct sigcontext_struct);
 2583 
 2584    All CPU exceptions (except 13=general_protection from V86 mode, which
 2585    is directly scanned by the kernel) are handled here.
 2586      _________________________________________________________________
 2587 
 2588 9. The Serial group of Modules
 2589 
 2590    This is the code that works our serial emulation. This needs to be
 2591    very fast if we are to convince DOS that we have a very fast serial
 2592    port.
 2593      _________________________________________________________________
 2594 
 2595 9.1. Remarks in base/serial/ser_defs.h
 2596 
 2597    Extensions to serial debugging.
 2598 
 2599    SER_DEBUG_MAIN (0 or 1) - extra debug output on the most critical
 2600    information.
 2601 
 2602    SER_DEBUG_HEAVY (0 or 1) - super-heavy extra debug output, including
 2603    all ports reads and writes, and every character received and
 2604    transmitted!
 2605 
 2606    SER_DEBUG_INTERRUPT (0 or 1) - additional debug output related to
 2607    serial interrupt code, including flagging serial interrupts, or
 2608    PIC-driven code.
 2609 
 2610    SER_DEBUG_FOSSIL_RW (0 or 1) - heavy FOSSIL debug output, including
 2611    all reads and writes.
 2612 
 2613    SER_DEBUG_FOSSIL_STATUS (0 or 1) - super-heavy FOSSIL debug output,
 2614    including all status checks.
 2615 
 2616    You must recompile dosemu everytime one of these constants are
 2617    modified. Just type 'make' in the dosemu dir and it will recompile the
 2618    changes only.
 2619 
 2620    -----
 2621 
 2622    IMPORTANT INFO about com[] variable array structure used in serial.c
 2623 
 2624    Most of the serial variables are stored in the com[] array. The com[]
 2625    array is a structure in itself. Take a look at the 'serial_t' struct
 2626    declaration in the serial.h module for more info about this. Only the
 2627    most commonly referenced global variables are listed here:
 2628 
 2629    config.num_ser Number of serial ports active. com[x].base_port The
 2630    base port address of emulated serial port. com[x].real_comport The COM
 2631    port number. com[x].interrupt The PIC interrupt level (based on IRQ
 2632    number) com[x].mouse Flag mouse (to enable extended features)
 2633    com[x].fd File descriptor for port device com[x].dev[] Filename of
 2634    port port device com[x].dev_locked Flag whether device has been locked
 2635 
 2636    The arbritary example variable 'x' in com[x] can have a minimum value
 2637    of 0 and a maximum value of (config.numser - 1). There can be no gaps
 2638    for the value 'x', even though gaps between actual COM ports are
 2639    permitted. It is strongly noted that the 'x' does not equal the COM
 2640    port number. This example code illustrates the fact, and how the com[]
 2641    array works:
 2642 
 2643    for (i = 0; i < config.numser; i++) s_printf("COM port number %d has a
 2644    base address of %x", com[i].real_comport, com[i].base_port);
 2645      _________________________________________________________________
 2646 
 2647 9.2. Functions in base/serial/ser_init.c
 2648 
 2649    These are the functions defined in base/serial/ser_init.c.
 2650      _________________________________________________________________
 2651 
 2652 9.2.1. serial_init
 2653 
 2654    This is the master serial initialization function that is called upon
 2655    startup of DOSEMU to initialize ALL the emulated UARTs for all
 2656    configured serial ports. The UART is initialized via the
 2657    initialize_uart function, which opens the serial ports and defines
 2658    variables for the specific UART.
 2659 
 2660    If the port is a mouse, the port is only initialized when i
 2661      _________________________________________________________________
 2662 
 2663 9.3. Items for Fixing in base/serial/ser_init.c
 2664 
 2665    This needs more work before it is implemented into /etc/dosemu.conf as
 2666    an 'rtscts' option.
 2667      _________________________________________________________________
 2668 
 2669 9.4. Functions in base/serial/ser_ports.c
 2670 
 2671    These are the functions defined in base/serial/ser_ports.c.
 2672      _________________________________________________________________
 2673 
 2674 9.4.1. do_serial_in
 2675 
 2676    The following function returns a value from an I/O port. The port is
 2677    an I/O address such as 0x3F8 (the base port address of COM1). There
 2678    are 8 I/O addresses for each serial port which ranges from the base
 2679    port (ie 0x3F8) to the base port plus seven (ie 0x3FF). [num =
 2680    abritary port number for serial line, address = I/O port address]
 2681      _________________________________________________________________
 2682 
 2683 9.4.2. do_serial_out
 2684 
 2685    The following function writes a value to an I/O port. The port is an
 2686    I/O address such as 0x3F8 (the base port address of COM1). [num =
 2687    abritary port number for serial line, address = I/O port address, val
 2688    = value to write to I/O port address]
 2689      _________________________________________________________________
 2690 
 2691 9.5. Items for Fixing in base/serial/ser_ports.c
 2692 
 2693    Should clearing UART cause THRE int if it's enabled? */
 2694 
 2695    -----
 2696 
 2697    Fix the calculation assumption
 2698 
 2699    -----
 2700 
 2701    Is this safe to put this here? */
 2702 
 2703    -----
 2704 
 2705    Is this safe to put this here? */
 2706      _________________________________________________________________
 2707 
 2708 9.6. Functions in base/serial/ser_irq.c
 2709 
 2710    These are the functions defined in base/serial/ser_irq.c.
 2711      _________________________________________________________________
 2712 
 2713 9.6.1. serial_int_engine
 2714 
 2715    This function is the serial interrupts scheduler. Its purpose is to
 2716    update interrupt status and/or invoke a requested serial interrupt. If
 2717    interrupts are not enabled, the Interrupt Identification Register is
 2718    still updated and the function returns. See pic_serial_run() below it
 2719    is executed right at the instant the interrupt is actually invoked.
 2720 
 2721    Since it is not possible to run the interrupt on the spot, it triggers
 2722    the interrupt via the pic_request() function (which is in pic.c) and
 2723    sets a flag that an interrupt is going to be occur soon.
 2724 
 2725    Please read pic_serial_run() for more information about interrupts.
 2726    [num = port, int_requested = the requested serial interrupt]
 2727      _________________________________________________________________
 2728 
 2729 9.6.2. pic_serial_run
 2730 
 2731    This function is called by the priority iunterrupt controller when a
 2732    serial interrupt occurs. It executes the highest priority serial
 2733    interrupt for that port. (Priority order is: RLSI, RDI, THRI, MSI)
 2734 
 2735    Because it is theoretically possible for things to change between the
 2736    interrupt trigger and the actual interrupt, some checks must be
 2737    repeated.
 2738      _________________________________________________________________
 2739 
 2740 9.6.3. serial_run
 2741 
 2742    This is the main housekeeping function, which should be called about
 2743    20 to 100 times per second. The more frequent, the better, up to a
 2744    certain point. However, it should be self-compensating if it executes
 2745    10 times or even 1000 times per second. Serial performance increases
 2746    with frequency of execution of serial_run.
 2747 
 2748    Serial mouse performance becomes more smooth if the time between calls
 2749    to serial_run are smaller.
 2750      _________________________________________________________________
 2751 
 2752 9.7. Remarks in base/serial/ser_irq.c
 2753 
 2754    Linux code hackers: How do I detect a break signal without having to
 2755    rely on Linux signals? Can I peek a 'break state bit'? Also, how do I
 2756    'turn on' and 'turn off' the break state, via an ioctl() or
 2757    tcsetattr(), rather than using POSIX tcsendbrk()?
 2758      _________________________________________________________________
 2759 
 2760 9.8. Items for Fixing in base/serial/ser_irq.c
 2761 
 2762    how do we cancel a PIC interrupt, when we have come this far?
 2763      _________________________________________________________________
 2764 
 2765 9.9. Functions in base/serial/int14.c
 2766 
 2767    These are the functions defined in base/serial/int14.c.
 2768      _________________________________________________________________
 2769 
 2770 9.9.1. int14
 2771 
 2772    The following function executes a BIOS interrupt 0x14 function. This
 2773    code by Mark Rejhon replaced some very buggy, old int14 interface a
 2774    while back. These routines are not flawless since it does not wait for
 2775    a character during receive, and this may confuse some programs.
 2776      _________________________________________________________________
 2777 
 2778 9.10. New Ideas for base/serial/int14.c
 2779 
 2780    If any of you coders are ambitious, try thinking of the following: -
 2781    Converting this into inline assembler and use direct port access
 2782      _________________________________________________________________
 2783 
 2784 9.11. Items for Fixing in base/serial/fossil.c
 2785 
 2786    This really should be write-with-wait. */
 2787      _________________________________________________________________
 2788 
 2789 9.12. Items for Fixing in include/serial.h
 2790 
 2791    Why does a RX_BUFFER_SIZE of 256 cause slower performance than a size
 2792    of 128?
 2793      _________________________________________________________________
 2794 
 2795 10. The Mouse group of Modules
 2796 
 2797    All of the Mouse handling code is in the "mouse" subdirectory.
 2798 
 2799    There are only 2 main files, mouse.c and mouseint.c.
 2800      _________________________________________________________________
 2801 
 2802 10.1. Functions in base/mouse/mouse.c
 2803 
 2804    These are the functions defined in base/mouse/mouse.c.
 2805      _________________________________________________________________
 2806 
 2807 10.1.1. mouse_init
 2808 
 2809    Initialize internal mouse.
 2810      _________________________________________________________________
 2811 
 2812 10.2. Remarks in base/mouse/mouse.c
 2813 
 2814    I have not properly tested this INT74 - JES 96/10/20 I have removed
 2815    it. INT74 is irq 12. Which I suppose is the proper irq for a ps2
 2816    mouse. It appears initial support was planned to support irq 12 and at
 2817    Mouse_ROUTINE_OFF is a routine that acknowledges an irq. That routine
 2818    is probably what should be acknowledging irq12, and what int 0x74
 2819    should point to. I have disabled int0x74 support for now. --EB 29 Oct
 2820    1997 Got it working --BO 4 Nov 2004
 2821 
 2822    -----
 2823 
 2824    Whoever wrote the dos mouse driver spec was brain dead... For some
 2825    video modes the mouse driver appears to randomly pick a shift factor,
 2826    possibly to keep at least a 640x200 resolution.
 2827 
 2828    The general programming documentation doesn't make this clear. And
 2829    says that in text modes it is safe to divide the resolution by 8 to
 2830    get the coordinates in characters.
 2831 
 2832    The only safe way to handle the mouse driver is to call function 0x26
 2833    Get max x & max y coordinates and scale whatever the driver returns
 2834    yourself.
 2835 
 2836    To handle programs written by programmers who weren't so cautious a
 2837    doctrine of least suprise has been implemented.
 2838 
 2839    As much as possible do the same as a standard dos mouse driver in the
 2840    original vga modes 0,1,2,3,4,5,6,7,13,14,15,16,17,18,19.
 2841 
 2842    For other text modes allow the divide by 8 technique to work. For
 2843    other graphics modes return x & y in screen coordinates. Except when
 2844    those modes are either 40x?? or 320x??? and then handle the x
 2845    resolution as in 40x25 and 320x200 modes.
 2846 
 2847    320x200 modes are slightly controversial as I have indications that
 2848    not all mouse drivers do the same thing. So I have taken the simplest,
 2849    and most common route, which is also long standing dosemu practice of
 2850    always shifting the xaxis by 1. When I researched this I could find no
 2851    examples that did otherwise.
 2852 
 2853    -- Eric Biederman 19 August 1998
 2854 
 2855    This code has now been updated so it defaults as above but allows work
 2856    arounds if necessary. Because tweaking dosemu is easier than fixing
 2857    applications without source.
 2858 
 2859    -- Eric Biederman 29 May 2000
 2860      _________________________________________________________________
 2861 
 2862 11. The Bios group of Modules
 2863 
 2864    All of the Bios code is in the "bios" subdirectory.
 2865 
 2866    DOSEMU requires certain code to be coded in assembler and also code to
 2867    be located in the F000 segment. This is where all such code should be
 2868    put.
 2869      _________________________________________________________________
 2870 
 2871 11.1. Functions in base/bios/hlt.c
 2872 
 2873    These are the functions defined in base/bios/hlt.c.
 2874      _________________________________________________________________
 2875 
 2876 11.1.1. hlt_init(void)
 2877 
 2878    Resets all the HLT handlers
 2879      _________________________________________________________________
 2880 
 2881 11.1.2. hlt_handle()
 2882 
 2883    Handles a HLT instruction reached inside the dos emulator.
 2884      _________________________________________________________________
 2885 
 2886 12. The PIC group of Modules
 2887 
 2888    All of the PIC handling code is in the "PIC" subdirectory.
 2889      _________________________________________________________________
 2890 
 2891 12.1. Functions in base/dev/pic/pic.c
 2892 
 2893    These are the functions defined in base/dev/pic/pic.c.
 2894      _________________________________________________________________
 2895 
 2896 12.1.1. pic_print
 2897 
 2898    This is the pic debug message printer. It writes out some basic
 2899    information, followed by an informative message. The basic information
 2900    consists of: interrupt nesting counter change flag (+, -, or blank)
 2901    interrupt nesting count (pic_icount) interrupt level change flag (+,
 2902    -, or blank) current interrupt level interrupt in-service register
 2903    interrupt mask register interrupt request register message part one
 2904    decimal data value message part two
 2905 
 2906    If the message part 2 pointer is a null pointer, then only message
 2907    part one (without the data value) is printed.
 2908 
 2909    The change flags are there to facilitate grepping for changes in
 2910    pic_ilevel and pic_icount
 2911 
 2912    To avoid line wrap, the first seven values are printed without labels.
 2913    Instead, a header line is printed every 15 messages.
 2914      _________________________________________________________________
 2915 
 2916 12.1.2. write_pic0,write_pic1
 2917 
 2918    write_pic_0() and write_pic1() implement dos writes to the pic ports.
 2919    They are called by the code that emulates inb and outb instructions.
 2920    Each function implements both ports for the pic: pic0 is on ports 0x20
 2921    and 0x21; pic1 is on ports 0xa0 and 0xa1. These functions take
 2922 
 2923    Arguments are:
 2924      _________________________________________________________________
 2925 
 2926 12.1.3. read_pic0,read_pic1
 2927 
 2928    read_pic0 and read_pic1 return the values for the interrupt mask
 2929    register (port 1), or either the in service register or interrupt
 2930    request register, as determined by the last OCW3 command (port 0).
 2931    These functions take a single parameter, which is a port number (0 or
 2932    1). They are called by code that emulates the inb instruction.
 2933      _________________________________________________________________
 2934 
 2935 12.1.4. pic_seti
 2936 
 2937    pic_seti is used to initialize an interrupt for dosemu. It requires
 2938    four parameters. The first parameter is the interrupt level, which may
 2939    select the NMI, any of the IRQs, or any of the 16 extra levels (16 -
 2940    31). The second parameter is the dosemu function to be called when the
 2941    interrupt is activated. This function should call do_irq() if the DOS
 2942    interrupt is really to be activated. If there is no special dosemu
 2943    code to call, the second parameter can specify do_irq(), but see that
 2944    description for some special considerations. The third parameter is a
 2945    number of an interrupt to activate if there is no default interrupt
 2946    for this ilevel. The fourth parameter is the dosemu function to be
 2947    called from do_irq(). Required by some internal dosemu drivers that
 2948    needs some additional code before calling an actual handler. This
 2949    function MUST provide a EOI at the end of a callback.
 2950      _________________________________________________________________
 2951 
 2952 12.1.5. run_irqs
 2953 
 2954    run_irqs, which is initiated via the macro pic_run, is the "brains" of
 2955    the pic. It is called from the vm86() loop, checks for the highest
 2956    priority interrupt requested, and executes it. This function is
 2957    written in assembly language in order to take advantage of atomic
 2958    (indivisible) instructions, so that it should be safe for a two
 2959    process model, even in a multiple CPU machine. A c language version
 2960    was started, but it became impossible, even with in-line assembly
 2961    macros, because such macros can only return a single result. If I find
 2962    a way to do it in c, I will, but don't hold your breath.
 2963 
 2964    I found a way to write it in C --EB 15 Jan 97
 2965      _________________________________________________________________
 2966 
 2967 12.1.6. do_irq
 2968 
 2969    do_irq() calls the correct do_int(). It then executes a vm86 loop
 2970    until an outb( end-of-interrupt) is found. For priority levels 0 and
 2971    >15 (not real IRQs), vm86 executes once, then returns, since no outb20
 2972    will come. Returns: 0 = complete, 1 = interrupt not run because it
 2973    directly calls our "bios" See run_timer_tick() in timer.c for an
 2974    example To assure notification when the irq completes, we push flags,
 2975    ip, and cs here and fake cs:ip to PIC_[SEG,OFF], where there is a hlt.
 2976    This makes the irq generate a sigsegv, which calls pic_iret when it
 2977    completes. pic_iret then pops the real cs:ip from the stack. This
 2978    routine is RE-ENTRANT - it calls run_irqs, which may call an interrupt
 2979    routine, which may call do_irq(). Be Careful! !!!!!!!!!!!!!!!!!! No
 2980    single interrupt is ever re-entered.
 2981 
 2982    Callers: base/misc/ioctl.c base/keyboard/serv_8042.c
 2983    base/keyboard/keyboard-server.c base/serial/ser_irq.c
 2984    dosext/sound/sound.c dosext/net/net/pktnew.c
 2985      _________________________________________________________________
 2986 
 2987 12.1.7. pic_resched
 2988 
 2989    pic_resched decrements a count of interrupts on the stack (set by
 2990    do_irq()). If the count is then less or equal to some pre-defined
 2991    value (normally 1, pic_icount_od), pic_resched moves all queued
 2992    interrupts to the interrupt request register.
 2993 
 2994    Normally it is called from pic_iret(), but it can also be called
 2995    directly if dosemu was fooled by the program and failed to catch iret.
 2996      _________________________________________________________________
 2997 
 2998 12.1.8. pic_request
 2999 
 3000    pic_request triggers an interrupt. There is presently no way to
 3001    "un-trigger" an interrupt. The interrupt will be initiated the next
 3002    time pic_run is called, unless masked or superceded by a higher
 3003    priority interrupt. pic_request takes one argument, an interrupt
 3004    level, which specifies the interrupt to be triggered. If that
 3005    interrupt is already active, the request will be queued until all
 3006    active interrupts have been completed. The queue is only one request
 3007    deep for each interrupt, so it is the responsibility of the interrupt
 3008    code to retrigger itself if more interrupts are needed.
 3009      _________________________________________________________________
 3010 
 3011 12.1.9. pic_iret
 3012 
 3013    pic_iret is used to sense that all active interrupts are really
 3014    complete, so that interrupts queued by pic_request can be triggered.
 3015    Interrupts end when they issue an outb 0x20 to the pic, however it is
 3016    not yet safe at that time to retrigger interrupts, since the stack has
 3017    not been restored to its initial state by an iret. pic_iret is called
 3018    whenever interrupts have been enabled by a popf, sti, or iret. It
 3019    determines if an iret was the cause by comparing stack contents with
 3020    cs and ip. If so, it calls pic_resched() and does the actual iret by
 3021    pop'ing ip and cs from stack. It is possible for pic_iret to be fooled
 3022    by dos code; for this reason active interrupts are checked, any queued
 3023    interrupts that are also active will remain queued. Also, some
 3024    programs fake an iret, so that it is possible for pic_iret to fail.
 3025    See pic_watch for the watchdog timer that catches and fixes this
 3026    event.
 3027      _________________________________________________________________
 3028 
 3029 12.1.10. pic_watch
 3030 
 3031    pic_watch is a watchdog timer for pending interrupts. If pic_iret
 3032    somehow fails to activate a pending interrupt request for 2
 3033    consecutive timer ticks, pic_watch will activate them anyway.
 3034    pic_watch is called ONLY by timer_tick, the interval timer signal
 3035    handler, so the two functions will probably be merged.
 3036      _________________________________________________________________
 3037 
 3038 12.1.11. pic_pending
 3039 
 3040    This function returns a non-zero value if the designated interrupt has
 3041    been requested and is not masked. In these circumstances, it is
 3042    important for a hardware emulation to return a status which does *not*
 3043    reflect the event(s) which caused the request, until the interrupt
 3044    actually gets processed. This, in turn, hides the interrupt latency of
 3045    pic from the dos software.
 3046 
 3047    The single parameter ilevel is the interrupt level (see pic.h) of the
 3048    interrupt of interest.
 3049 
 3050    If the requested interrupt level is currently active, the returned
 3051    status will depend upon whether the interrupt code has re-requested
 3052    itself. If no re-request has occurred, a value of false (zero) will be
 3053    returned.
 3054      _________________________________________________________________
 3055 
 3056 12.1.12. pic_activate
 3057 
 3058    pic_activate requests any interrupts whose scheduled time has arrived.
 3059    anything after pic_dos_time and before pic_sys_time is activated.
 3060    pic_dos_time is advanced to the earliest time scheduled.
 3061      _________________________________________________________________
 3062 
 3063 12.1.13. pic_sched
 3064 
 3065    pic_sched schedules an interrupt for activation after a designated
 3066    time interval. The time measurement is in unis of 1193047/second, the
 3067    same rate as the pit counters. This is convenient for timer emulation,
 3068    but can also be used for pacing other functions, such as serial
 3069    emulation, incoming keystrokes, or video updates. Some sample
 3070    intervals:
 3071 
 3072    rate/sec: 5 7.5 11 13.45 15 30 60 interval: 238608 159072 108459 88702
 3073    79536 39768 19884
 3074 
 3075    rate/sec: 120 180 200 240 360 480 720 interval: 9942 6628 5965 4971
 3076    3314 2485 1657
 3077 
 3078    rate/sec: 960 1440 1920 2880 3840 5760 11520 interval: 1243 829 621
 3079    414 311 207 103
 3080 
 3081    pic_sched expects two parameters: an interrupt level and an interval.
 3082    To assure proper repeat scheduling, pic_sched should be called from
 3083    within the interrupt handler for the same interrupt. The maximum
 3084    interval is 15 minutes (0x3fffffff).
 3085      _________________________________________________________________
 3086 
 3087 12.2. Remarks in base/dev/pic/pic.c
 3088 
 3089    pic_push,pic_pop
 3090 
 3091    Pic maintains two stacks of the current interrupt level. an internal
 3092    one is maintained by run_irqs, and is valid whenever the emulator code
 3093    for an interrupt is active. These functions maintain an external
 3094    stack, which is valid from the time the dos interrupt code is called
 3095    until the code has issued all necessary EOIs. Because pic will not
 3096    necessarily get control immediately after an EOI, another EOI (for
 3097    another interrupt) could occur. This external stack is kept strictly
 3098    synchronized with the actions of the dos code to avoid any problems.
 3099    pic_push and pic_pop maintain the external stack.
 3100      _________________________________________________________________
 3101 
 3102 13. The Sound group of Modules
 3103 
 3104    The sound code provides emulation of the SB. The actual emulation
 3105    provided depends upon the support available from the kernel sound
 3106    driver. Because this is very OS dependant the driver code itself is
 3107    kept in architecture specifc files under
 3108    src/arch/osname/dosext/sound/. Communication is via a set of interface
 3109    functions and the device independant structures.
 3110      _________________________________________________________________
 3111 
 3112 13.1. Functions in dosext/sound/sound.c
 3113 
 3114    These are the functions defined in dosext/sound/sound.c.
 3115      _________________________________________________________________
 3116 
 3117 13.1.1. sb_io_read
 3118 
 3119    Arguments are:
 3120 
 3121      * port - The I/O port being read from.
 3122 
 3123    This handles all of the reads for the SB emulation. The value read is
 3124    returned. The value of 0xFF indicates an invalid read. (assumes the
 3125    ports float high when not pulled low by the hardware.)
 3126      _________________________________________________________________
 3127 
 3128 13.1.2. adlib_io_read
 3129 
 3130    Arguments are:
 3131 
 3132      * port - The I/O port being read from.
 3133 
 3134    This handles all of the reads for the adlib (FM) emulation. The value
 3135    read is returned. The value of 0xFF indicates an invalid read.
 3136    (assumes the ports float high when not pulled low by the hardware.)
 3137    The FM emulation is not written yet. The current plan is to use the
 3138    midi emulation where available as this is the most common use for the
 3139    FM sound.
 3140      _________________________________________________________________
 3141 
 3142 13.1.3. mpu401_io_read
 3143 
 3144    Arguments are:
 3145 
 3146      * port - The I/O port being read from.
 3147 
 3148    The MPU-401 functionality is primarily provided by 'midid' - a
 3149    standalone program. This makes most of the MPU-401 code simply a
 3150    pass-through driver.
 3151      _________________________________________________________________
 3152 
 3153 13.1.4. sb_io_write
 3154 
 3155    Arguments are:
 3156 
 3157      * port - The I/O port being written to.
 3158      * value - The value being output.
 3159 
 3160    This handles the writes for the SB emulation. Very little of the
 3161    processing is performed in this function as it basically consists of a
 3162    very large switch() statement. The processing here is limited to
 3163    trivial (1 line) items and distinguishing between the different
 3164    actions and responses that the different revisions of the SB series
 3165    give.
 3166      _________________________________________________________________
 3167 
 3168 13.1.5. sb_dsp_write
 3169 
 3170    Arguments are:
 3171 
 3172      * value - The value being written to the DSP.
 3173 
 3174    The SB DSP is a complete I/O system in itself controlled via a number
 3175    of data bytes. The number of bytes depends upon the function. The
 3176    function to be executed is determined by the first byte. If there is
 3177    no existing command then the command is stored. This then used in the
 3178    switch to identify the action to be taken. When the command has
 3179    supplied all of its arguments, or failed, then the command storage is
 3180    cleared. Each DSP function is responsible for clearing this itself.
 3181    Again, this function relies on other functions to do the real work,
 3182    and apart from storing details of the command and parameters is
 3183    basically a large switch statement.
 3184      _________________________________________________________________
 3185 
 3186 13.2. Remarks in dosext/sound/sound.c
 3187 
 3188    Write silence could probably be implemented by setting up a "DMA"
 3189    transfer from /dev/null - AM
 3190      _________________________________________________________________
 3191 
 3192 13.3. Items for Fixing in dosext/sound/sound.c
 3193 
 3194    The file header needs tidying up a _LOT_ ! */
 3195 
 3196    -----
 3197 
 3198    Adlib status reads are unimplemented */
 3199 
 3200    -----
 3201 
 3202    Advanced adlib reads are unimplemented */
 3203 
 3204    -----
 3205 
 3206    CMS Writes are unimplemented.
 3207 
 3208    -----
 3209 
 3210    DSP Status is unimplemented
 3211 
 3212    -----
 3213 
 3214    Adlib Waveform tests are unimplemented */
 3215 
 3216    -----
 3217 
 3218    Advanced Adlib register writes are unimplemented */
 3219 
 3220    -----
 3221 
 3222    Advanced Adlib data writes are unimplemented */
 3223 
 3224    -----
 3225 
 3226    SB Midi is Unimplemented
 3227 
 3228    -----
 3229 
 3230    Sine Generation is unimplemented
 3231 
 3232    -----
 3233 
 3234    AUX Status is Unimplemented
 3235      _________________________________________________________________
 3236 
 3237 13.4. Remarks in base/dev/dma/dma.c
 3238 
 3239    **** WARNING **** This Code _HAS_ changed.
 3240 
 3241    -----
 3242 
 3243    The Emulated DMA channels are provided by using files and writes. This
 3244    means that they are easy to track. It might cause problems when
 3245    attempting to interface to the REAL DMA controller. (Necessary to talk
 3246    to hardware which uses DMA.)
 3247 
 3248    Note that DMA controller 2 uses word granular addressing and
 3249    controller 1 uses byte granular address ... this simplifies the code !
 3250      _________________________________________________________________
 3251 
 3252 13.5. Items for Fixing in base/dev/dma/dma.c
 3253 
 3254    : Cascade Mode Reads are not supported
 3255 
 3256    -----
 3257 
 3258    : The Verify Mode is not supported
 3259 
 3260    -----
 3261 
 3262    : The Invalid Mode is not supported (!)
 3263      _________________________________________________________________
 3264 
 3265 14. The FileAccess group of Modules
 3266 
 3267    This hold all kind of accessing files on a Unix filesysten from DOS.
 3268      _________________________________________________________________
 3269 
 3270 14.1. Remarks in dosext/mfs/mfs.c
 3271 
 3272    The msdos_dir_ent structure has much more than 28 bytes. Is this
 3273    significant?
 3274 
 3275    -----
 3276 
 3277    Added compares to device so that newer versions of Foxpro which test
 3278    directories using xx\yy\device perform closer to whats DOS does.
 3279      _________________________________________________________________
 3280 
 3281 14.2. Items for Fixing in dosext/mfs/mfs.c
 3282 
 3283    We probably should use llseek here for file > 2 GBytes
 3284 
 3285    -----
 3286 
 3287    returned size of struct dir_ent seems wrong at 28 bytes. */
 3288      _________________________________________________________________
 3289 
 3290 15. And Finally ...
 3291 
 3292    The Following items are used to delimit the text used to create this
 3293    file. Whilst it is not necessary to know this, they are included
 3294    because they may be useful for searching, as they are (at least at the
 3295    moment) reasonably unique.
 3296 
 3297    DANG_BEGIN_MODULE / DANG_END_MODULE This will bracket a description of
 3298    the file (normally at the start). Within this you may have the keyword
 3299    'Maintainer:' followed by a list (one line each) of maintainers for
 3300    this packet. These will be turned into URLs.
 3301 
 3302    DANG_BEGIN_FUNCTION / DANG_END_FUNCTION This brackets a description of
 3303    functions (good this, isn't it!) Not every function needs to be
 3304    described in this way - just the major ones. Within this you may have
 3305    the keywords: `arguments:', `return:' and `description:', which will
 3306    sort out the information following it to build proper lists.
 3307 
 3308    DANG_BEGIN_STRUCT / DANG_END_STRUCT This brackets a description of
 3309    structures and data definitions Not every structure needs to be
 3310    described in this way - just the major ones. Within this you may have
 3311    the keywords: `elements:', and `description:', which will sort out the
 3312    information following it to build proper lists. Also, you may bracket
 3313    the structur definition of real C-code, given you have one element per
 3314    line. In this case comments (/*...*/) behind the element will be
 3315    inserted properly into the formatted list while the C-code itself is
 3316    still compilable.
 3317 
 3318    DANG_BEGIN_REMARK / DANG_END_REMARK This brackets descriptions of
 3319    obscure items, like data structures and architecture.
 3320 
 3321    DANG_FIXTHIS This is a one line item, indicating a an area requiring a
 3322    fix, or redesign.
 3323 
 3324    DANG_BEGIN_NEWIDEA / DANG_END_NEWIDEA New Ideas Start Here! As Ideas
 3325    are proposed, that get added with their description, so that future
 3326    generations can laugh at or code the ideas ..... These bracket the
 3327    idea description.
 3328 
 3329    DANG_BEGIN_CHANGELOG / DANG_END_CHANGELOG Changelogs - very useful for
 3330    bug fixing, and avvailable for use with DPR (or that's the theory)
 3331 
 3332    In addition there are some keywords, that are recognized within a
 3333    bracket.
 3334 
 3335    VERB ... /VERB This formats the enclosed text verbatim. This is valid
 3336    within *_MODULE, *_REMARK, *_STRUCT, *_FUNCTION
 3337 
 3338    REMARK ... /REMARK This is only valid within *_MODULE and also can
 3339    contain VERB brackets. Its useful to when you want to have a global
 3340    modul description
 3341 
 3342    PROTO ... /PROTO This is only valid within *_FUNCTION and takes a
 3343    C-function prototype as `verbatim' until either a `{' or a /PROTO is
 3344    seen. After this all input is `skipped' until the next PROTO or a
 3345    /SKIP.
 3346 
 3347    SKIP ... /SKIP This is only valid within *_FUNCTION and skips
 3348    formatting until either PROTO or /SKIP is seen.