The DOSEMU Alterer Novices Guide DANG Alistair MacDonald, am20@unix.york.ac.uk For DOSEMU v pl This Document is the DOSEMU Alterer Novices Guide. It is known as the DANG. 1. Introduction This document is the preliminary draft of a manual to help people understand the inner workings of dosemu. It is the goal of this document to create new dosemu hackers. This concept was inspired by the linux kernel hackers guide. This Guide was concieved and originally written by "Corey Sweeney" . It has been completely revised. It is now generated automatically directly from the source code. Special thanks to "James B. MacLean" for supplying the original information. (It was mostly ripped out of a mail message.) "Jochen Hein" has made many useful comments & suggestions. At the end if this document is a section detailing how this guide is put together. This may help you when trying to locate the relevant pieces of code. If you add new code, it would be useful if the relevant markers are added where appropriate. This file is a collective effort. If you don't like one of the explanations, or want to add anything, please send me something! 2. The Main group of Modules These files are used to start DOSEMU as well as hold globally called functions and global vars. 2.1. dos.c Information Initial program executed to run DOSEMU. Gets access to libdosemu and sets international character parms. Finally calls entry point of DOSEMU emulate() function which is loaded above the usual DOS memory area from 0 - 1meg. Emulate() is in emu.c. 2.1.1. Functions in dos.c These are the functions defined in dos.c. 2.1.1.1. dosemu o argc - Count of argumnents. o argc - Actual arguments. Function created by entry point into libdosemu. Called to jump into the emulate function of DOSEMU. 2.1.2. Remarks in dos.c Apparently, no-one has anything interesting to say about dos.c. 2.1.3. Items for Fixing in dos.c Apparently, nothing needs fixing in dos.c. 2.1.4. New Ideas for dos.c Apparently, there are no new ideas for dos.c. 2.2. emu.c Information Here is where DOSEMU gets booted. From emu.c external calls are made to the specific I/O systems (video/keyboard/serial/etc...) to initialize them. Memory is cleared/set up and the boot sector is read from the boot drive. Many SIGNALS are set so that DOSEMU can exploit things like timers, I/O signals, illegal instructions, etc... When every system gives the green light, vm86() is called to switch into vm86 mode and start executing i86 code. The vm86() function will return to DOSEMU when certain `exceptions` occur as when some interrupt instructions occur (0xcd). The top level function emulate() is called from dos.c by way of a dll entry point. 2.2.1. Functions in emu.c These are the functions defined in emu.c. 2.2.1.1. jmp_emulate call the emulate function by way of the dll headers. Always make sure that this line is the first of emu.c and link emu.o as the first object file to the lib 2.2.1.2. run_vm86 which also has the registers that it will be called with. It will stop vm86 mode for many reasons, like trying to execute an interrupt, doing port I/O to ports not opened for I/O, etc ... 2.2.1.3. SIG_int Requires the sig/sillyint.o driver loaded (using NEW modules package), or a kernel patch (implementing sig/int.c driver). The IRQ numbers to monitor are taken from config.sillyint, each bit corresponding to one IRQ. The higher 16 bit are defining the use of SIGIO 2.2.1.4. emulate prepare it for running in vm86 mode. This involves catching signals, preparing memory, calling all the initialization functions for the I/O subsystems (video/serial/etc...), getting the boot sector instructions and calling vm86(). 2.2.1.5. io_select_init NON-SIGIO. 2.2.1.6. add_to_io_select o Specifiy whether you want SIGIO (1) if it's available, or not (0). whether the kernel can handle SIGIO. 2.2.1.7. remove_from_io_select o Specifiy whether you used SIGIO (1) if it's available, or not (0). on whether the kernel can handle SIGIO. 2.2.2. Remarks in emu.c DOSEMU must not work within the 1 meg DOS limit, so start of code is loaded at a higher address, at some time this could conflict with other shared libs. If DOSEMU is compiled statically (without shared libs), and org instruction is used to provide the jump above 1 meg. ----- At this time we have to use SIGALRM in addition to SIGIO I don't (yet) know why the SIGIO signal gets lost sometimes (once per minute or longer). But if it happens, we can retrigger this way over SIGALRM. Normally SIGIO happens before SIGALARM, so nothing hurts. (Hans) 2.2.3. Items for Fixing in emu.c Apparently, nothing needs fixing in emu.c. 2.2.4. New Ideas for emu.c Apparently, there are no new ideas for emu.c. 2.3. include/emu.h Information There appears to be no MODULE information for this file. 2.3.1. Functions in include/emu.h These are the functions defined in include/emu.h. 2.3.1.1. NEWSETQSIG o sig - the signal to have a handler installed to. o fun - the signal handler function to install All signals that wish to be handled properly in context with the execution of vm86() mode, and signals that wish to use non- reentrant functions should add themselves to the SIGNALS_THAT_QUEUE define and use SETQSIG(). To that end they will also need to be set up in an order such as SIGIO. 2.3.2. Remarks in include/emu.h The `vm86_struct` is used to pass all the necessary status/registers to DOSEMU when running in vm86 mode. ----- We assume system call restarting... under linux 0.99pl8 and earlier, this was the default. SA_RESTART was defined in 0.99pl8 to explicitly request restarting (and thus does nothing). However, if this ever changes, I want to be safe ----- DOSEMU keeps system wide configuration status in a structure called config. ----- The var `fatalerr` can be given a true value at any time to have DOSEMU exit on the next return from vm86 mode. 2.3.3. Items for Fixing in include/emu.h Apparently, nothing needs fixing in include/emu.h. 2.3.4. New Ideas for include/emu.h Apparently, there are no new ideas for include/emu.h. 3. The Clients group of Modules One of the long term aims of the DOSEMU development team is to provide a client-server based system. This will allow people to add different display systems in more simply. Those in current development are detailed in this section. 3.1. clients/ncurses.c Information There appears to be no MODULE information for this file. 3.1.1. Functions in clients/ncurses.c We appear to have no information on the functions in clients/ncurses.c. 3.1.2. Remarks in clients/ncurses.c Apparently, no-one has anything interesting to say about clients/ncurses.c. 3.1.3. Items for Fixing in clients/ncurses.c Apparently, nothing needs fixing in clients/ncurses.c. 3.1.4. New Ideas for clients/ncurses.c Apparently, there are no new ideas for clients/ncurses.c. 4. The DPMI group of Modules DPMI is Lutz's Baby. It's a really important part of the Emulator as far as we are concerned, since it will allow us to run so many more programs and, most importantly, bcc. This is the one thing that the WINE developers want that we haven't been able to give them. Now that Dong has come on mainstream, these two gurus are creating patches hand over fist as we approach being able to run Windows 3.1 If you think you can help .... "Away you Go!" (Sorry to those non-UK folks ... Thats a reference to a UK kids sports programme from my youth ... anyway ... enough of this banter. You'll be wanting to know that this is all about DPMI ...) 4.1. dpmi/dpmi.c Information dpmi.c DOS Protected Mode Interface allows DOS programs to run in the protected mode of 2345..86 processors 4.1.1. Functions in dpmi/dpmi.c These are the functions defined in dpmi/dpmi.c. 4.1.1.1. dpmi_control This function is similar to the vm86() syscall in the kernel and switches to dpmi code. 4.1.1.2. run_pm_int This routine is used for running protected mode hardware interrupts and software interrupts 0x1c, 0x23 and 0x24. run_pm_int() switches to the locked protected mode stack and calls the handler. If no handler is installed the real mode interrupt routine is called. 4.1.1.3. do_default_cpu_exception This is the default CPU exception handler. Exceptions 0, 1, 2, 3, 4, 5 and 7 are reflected to real mode. All other exceptions are terminating the client (and may be dosemu too :-)). 4.1.1.4. do_cpu_exception This routine switches to the locked protected mode stack, disables interrupts and calls the DPMI client exception handler. If no handler is installed the default handler is called. 4.1.1.5. dpmi_fault This is the brain of DPMI. All CPU exceptions are first reflected (from the signal handlers) to this code. Exception from nonpriveleged instructions INT XX, STI, CLI, HLT and from WINDOWS 3.1 are handled here. All here unhandled exceptions are reflected to do_cpu_exception() 4.1.2. Remarks in dpmi/dpmi.c We are caching ldt here for speed reasons and for Windows 3.1. I would love to have an readonly ldt-alias (located in the first 16MByte for use with 16-Bit descriptors (WIN-LDT)). This is on my wish list for the kernel hackers (Linus mainly) :-))))))). ----- DPMI is designed such that the stack change needs a task switch. We are doing it via an SIGSEGV - instead of one task switch we have now four :-(. Arrgh this is the point where I should start to include DPMI stuff in the kernel, but then we could include the rest of dosemu too. Would Linus love this? I don't :-((((. Anyway I would love to see first a working DPMI port, maybe we will later (with version 0.9 or similar :-)) start with it to get a really fast dos emulator............... ----- Handling of the virtuell interruptflag is still not correct and there are many open questions since DPMI specifications are unclear in this point. An example: If IF=1 in protected mode and real mode code is called which is disabling interrupts via cli and returning to protected mode, is IF then still one or zero? I guess I have to think a lot about this and to write a small dpmi client running under a commercial dpmi server :-). 4.1.3. Items for Fixing in dpmi/dpmi.c We shouldn't return to dosemu code if IF=0, but it helps - WHY? ----- we should not change registers for hardware interrupts 4.1.4. New Ideas for dpmi/dpmi.c Simulate Local Descriptor Table for MS-Windows 3.1 must be read only, so if krnl386.exe/krnl286.exe try to write to this table, we will bomb into sigsegv() and and emulate direct ldt access 5. The Video group of Modules All of the Video handling code is in the "video" subdirectory. There is one file for each video card or chipset and the master file. To Add a new card, it needs a set of save & restore routines putting in a file here. 5.1. video/vc.c Information Here's all the calls to the code to try and properly save & restore the video state between VC's and the attempts to control updates to the VC whilst the user is using another. We map between the real screen address and that used by DOSEMU here too. Attempts to use a cards own bios require the addition of the parameter "graphics" to the video statement in "/etc/dosemu.conf". This will make the emulator try to execute the card's initialization routine which is normally located at address c000:0003. This can now be changed as an option. 5.1.1. Functions in video/vc.c We appear to have no information on the functions in video/vc.c. 5.1.2. Remarks in video/vc.c Apparently, no-one has anything interesting to say about video/vc.c. 5.1.3. Items for Fixing in video/vc.c Apparently, nothing needs fixing in video/vc.c. 5.1.4. New Ideas for video/vc.c Apparently, there are no new ideas for video/vc.c. 5.2. video/video.c Information There appears to be no MODULE information for this file. 5.2.1. Functions in video/video.c These are the functions defined in video/video.c. 5.2.1.1. video_init Set pointer to correct structure of functions to initialize, close, etc... video routines. 5.2.2. Remarks in video/video.c Here the sleeping lion will be awoken and eat much of CPU time !!! The result of setting VM86_SCREEN_BITMAP (at state of Linux 1.1.56): Each vm86 call will set 32 pages of video mem RD-only (there may be 1000000 per second) Write access to RD-only page results in page-fault (mm/memory.c), which will set a bit in current->screen_bitmap and calls do_wp_page() which does __get_free_page(GFP_KERNEL) but frees it immediatly, because copy-on-write is not neccessary and sets RD/WR for the page. (this could happen 32000000 per second, if the CPU were fast enough) It would be better to get the DIRTY-bit directly from the page table, isn't it? A special syscall in emumodule could do this. ----- reserve_video_memory() This procedure is trying to eke out all the UMB blocks possible to maximize your memory under DOSEMU. If you know about dual monitor setups, you can contribute by putting in the correct graphics page address values. 5.2.3. Items for Fixing in video/video.c Apparently, nothing needs fixing in video/video.c. 5.2.4. New Ideas for video/video.c Apparently, there are no new ideas for video/video.c. 5.3. video/X.c Information There appears to be no MODULE information for this file. 5.3.1. Functions in video/X.c We appear to have no information on the functions in video/X.c. 5.3.2. Remarks in video/X.c Apparently, no-one has anything interesting to say about video/X.c. 5.3.3. Items for Fixing in video/X.c Apparently, nothing needs fixing in video/X.c. 5.3.4. New Ideas for video/X.c Apparently, there are no new ideas for video/X.c. 5.4. video/console.c Information There appears to be no MODULE information for this file. 5.4.1. Functions in video/console.c We appear to have no information on the functions in video/console.c. 5.4.2. Remarks in video/console.c Apparently, no-one has anything interesting to say about video/console.c. 5.4.3. Items for Fixing in video/console.c Apparently, nothing needs fixing in video/console.c. 5.4.4. New Ideas for video/console.c Apparently, there are no new ideas for video/console.c. 5.5. video/dualmon.c Information The dual monitor support files to use a monochrome card as second video subsystem. Usefull with for example Borland Turbo Debugger and Turbo Profiler, HelpPC. Supported cards are: - MDA (Monochrome Display Adapter) - Hercules Graphics Card (_the_ Hercules card) - Hercules Graphics Card Plus (a.k.a. Hercules RamFont) - Hercules InColor (the "color monochrome card"). 5.5.1. Functions in video/dualmon.c These are the functions defined in video/dualmon.c. 5.5.1.1. MDA_init o returns: nothing Initializes the monochrome card. First detects which monochrome card is used, because the Hercules RamFont and the Hercules InColor need one more register to be initialized. If there is no monochrome card at all, we just think there is one and poke an peek in the void. After the detection the card is initialized. 5.5.2. Remarks in video/dualmon.c After MDA_init() the VGA is configured, something in video.c or console.c "reprograms" the monochrome card again in such a way that I always have to run hgc.com before I can use any program that uses the monochrome card. I've spent a day trying to find it, but I can't figure out. Something is writing to one of the following ports: 0x3b4, 0x3b5, 0x3b8, 0x3b9, 0x3ba, 0x3bb, 0x3bf. The problem occurs at (at least) the following 2 systems: - AMD 386DX40, Trident 9000/512Kb ISA, Hercules Graphics Card Plus - Intel 486DX2/66, Cirrus Logic 5426/1Mb VLB, Hercules clone The problem doesn't occur when I start dosemu from a telnet connection or from a VT100 terminal. (Erik Mouw, jakmouw@et.tudelft.nl) 5.5.3. Items for Fixing in video/dualmon.c Apparently, nothing needs fixing in video/dualmon.c. 5.5.4. New Ideas for video/dualmon.c Apparently, there are no new ideas for video/dualmon.c. 5.6. video/et4000.c Information There appears to be no MODULE information for this file. 5.6.1. Functions in video/et4000.c We appear to have no information on the functions in video/et4000.c. 5.6.2. Remarks in video/et4000.c Apparently, no-one has anything interesting to say about video/et4000.c. 5.6.3. Items for Fixing in video/et4000.c Apparently, nothing needs fixing in video/et4000.c. 5.6.4. New Ideas for video/et4000.c Apparently, there are no new ideas for video/et4000.c. 5.7. video/hgc.c Information There appears to be no MODULE information for this file. 5.7.1. Functions in video/hgc.c We appear to have no information on the functions in video/hgc.c. 5.7.2. Remarks in video/hgc.c Apparently, no-one has anything interesting to say about video/hgc.c. 5.7.3. Items for Fixing in video/hgc.c Apparently, nothing needs fixing in video/hgc.c. 5.7.4. New Ideas for video/hgc.c Apparently, there are no new ideas for video/hgc.c. 5.8. video/int10.c Information There appears to be no MODULE information for this file. 5.8.1. Functions in video/int10.c We appear to have no information on the functions in video/int10.c. 5.8.2. Remarks in video/int10.c Apparently, no-one has anything interesting to say about video/int10.c. 5.8.3. Items for Fixing in video/int10.c Apparently, nothing needs fixing in video/int10.c. 5.8.4. New Ideas for video/int10.c Apparently, there are no new ideas for video/int10.c. 5.9. video/s3.c Information There appears to be no MODULE information for this file. 5.9.1. Functions in video/s3.c We appear to have no information on the functions in video/s3.c. 5.9.2. Remarks in video/s3.c Apparently, no-one has anything interesting to say about video/s3.c. 5.9.3. Items for Fixing in video/s3.c Apparently, nothing needs fixing in video/s3.c. 5.9.4. New Ideas for video/s3.c Apparently, there are no new ideas for video/s3.c. 5.10. video/terminal.c Information There appears to be no MODULE information for this file. 5.10.1. Functions in video/terminal.c We appear to have no information on the functions in video/terminal.c. 5.10.2. Remarks in video/terminal.c Apparently, no-one has anything interesting to say about video/terminal.c. 5.10.3. Items for Fixing in video/terminal.c Apparently, nothing needs fixing in video/terminal.c. 5.10.4. New Ideas for video/terminal.c Apparently, there are no new ideas for video/terminal.c. 5.11. video/trident.c Information There appears to be no MODULE information for this file. 5.11.1. Functions in video/trident.c We appear to have no information on the functions in video/trident.c. 5.11.2. Remarks in video/trident.c Apparently, no-one has anything interesting to say about video/trident.c. 5.11.3. Items for Fixing in video/trident.c Apparently, nothing needs fixing in video/trident.c. 5.11.4. New Ideas for video/trident.c Apparently, there are no new ideas for video/trident.c. 5.12. video/vga.c Information There appears to be no MODULE information for this file. 5.12.1. Functions in video/vga.c We appear to have no information on the functions in video/vga.c. 5.12.2. Remarks in video/vga.c Apparently, no-one has anything interesting to say about video/vga.c. 5.12.3. Items for Fixing in video/vga.c Apparently, nothing needs fixing in video/vga.c. 5.12.4. New Ideas for video/vga.c Apparently, there are no new ideas for video/vga.c. 6. The Keyboard group of Modules All of the Keyboard handling code is in the "keyboard" subdirectory. Latest addition is SLANG. 6.1. keyboard/termio.c Information There appears to be no MODULE information for this file. 6.1.1. Functions in keyboard/termio.c We appear to have no information on the functions in keyboard/termio.c. 6.1.2. Remarks in keyboard/termio.c Apparently, no-one has anything interesting to say about keyboard/termio.c. 6.1.3. Items for Fixing in keyboard/termio.c Apparently, nothing needs fixing in keyboard/termio.c. 6.1.4. New Ideas for keyboard/termio.c Apparently, there are no new ideas for keyboard/termio.c. 6.2. keyboard/Xkeyb.c Information There appears to be no MODULE information for this file. 6.2.1. Functions in keyboard/Xkeyb.c We appear to have no information on the functions in keyboard/Xkeyb.c. 6.2.2. Remarks in keyboard/Xkeyb.c Apparently, no-one has anything interesting to say about keyboard/Xkeyb.c. 6.2.3. Items for Fixing in keyboard/Xkeyb.c Apparently, nothing needs fixing in keyboard/Xkeyb.c. 6.2.4. New Ideas for keyboard/Xkeyb.c Apparently, there are no new ideas for keyboard/Xkeyb.c. 6.3. keyboard/keymaps.c Information These are definitions, giving which key is related to which scancode in raw keyboard mode. Basically, the code of 'x' on a US keyboard may be that of a 'Y' on a German keyboard. This way, all types of keyboard can be represented under DOSEMU. Also, the right ALT-key is often a function key in it's own right. 6.3.1. Functions in keyboard/keymaps.c We appear to have no information on the functions in keyboard/keymaps.c. 6.3.2. Remarks in keyboard/keymaps.c Apparently, no-one has anything interesting to say about keyboard/keymaps.c. 6.3.3. Items for Fixing in keyboard/keymaps.c Apparently, nothing needs fixing in keyboard/keymaps.c. 6.3.4. New Ideas for keyboard/keymaps.c Apparently, there are no new ideas for keyboard/keymaps.c. 6.4. keyboard/slang-termio.c Information There appears to be no MODULE information for this file. 6.4.1. Functions in keyboard/slang-termio.c We appear to have no information on the functions in keyboard/slang- termio.c. 6.4.2. Remarks in keyboard/slang-termio.c Apparently, no-one has anything interesting to say about keyboard/slang-termio.c. 6.4.3. Items for Fixing in keyboard/slang-termio.c Apparently, nothing needs fixing in keyboard/slang-termio.c. 6.4.4. New Ideas for keyboard/slang-termio.c Apparently, there are no new ideas for keyboard/slang-termio.c. 7. The Misc group of Modules These are the remaining important files, that do not really fit into another group. These should not be dismissed as unimportant - rather, they are often amongst the most important. 7.1. dosemu/bios_emm.c Information There appears to be no MODULE information for this file. 7.1.1. Functions in dosemu/bios_emm.c We appear to have no information on the functions in dosemu/bios_emm.c. 7.1.2. Remarks in dosemu/bios_emm.c Apparently, no-one has anything interesting to say about dosemu/bios_emm.c. 7.1.3. Items for Fixing in dosemu/bios_emm.c Apparently, nothing needs fixing in dosemu/bios_emm.c. 7.1.4. New Ideas for dosemu/bios_emm.c Apparently, there are no new ideas for dosemu/bios_emm.c. 7.2. dosemu/xms.c Information Currently the XMS 3.0 spec is covered in this file. XMS is fairly simple as it only deals with allocating extended memory and then moving it around in specific calls. This spec also includes the allocation of UMB's, so they are also included as part of this file. The amount of xms memory returned to DOS programs via the XMS requests, or int15 fnc88 is set in "/etc/dosemu.conf" via the XMS paramter. 7.2.1. Functions in dosemu/xms.c We appear to have no information on the functions in dosemu/xms.c. 7.2.2. Remarks in dosemu/xms.c Apparently, no-one has anything interesting to say about dosemu/xms.c. 7.2.3. Items for Fixing in dosemu/xms.c Apparently, nothing needs fixing in dosemu/xms.c. 7.2.4. New Ideas for dosemu/xms.c Apparently, there are no new ideas for dosemu/xms.c. 7.3. dosemu/sigsegv.c Information There appears to be no MODULE information for this file. 7.3.1. Functions in dosemu/sigsegv.c These are the functions defined in dosemu/sigsegv.c. 7.3.1.1. inb INB is used to do controlled emulation of input from ports. 7.3.1.2. vm86_GP_fault All from the kernel unhandled general protection faults from V86 mode are handled here. This are mainly port IO and the HLT instruction. 7.3.1.3. dosemu_fault All CPU exceptions (except 13=general_protection from V86 mode, which is directly scaned by the kernel) are handled here. 7.3.2. Remarks in dosemu/sigsegv.c In a properly functioning emulator :-), sigsegv's will never come while in a non-reentrant system call (ioctl, select, etc). Therefore, there's really no reason to worry about them, so I say that I'm NOT in a signal handler (I might make this a little clearer later, to show that the purpose of in_sighandler is to stop non-reentrant system calls from being reentered. I reiterate: sigsegv's should only happen when I'm running the vm86 system call, so I really shouldn't be in a non-reentrant system call (except maybe vm86) - Robert Sanders 7.3.3. Items for Fixing in dosemu/sigsegv.c Apparently, nothing needs fixing in dosemu/sigsegv.c. 7.3.4. New Ideas for dosemu/sigsegv.c Apparently, there are no new ideas for dosemu/sigsegv.c. 7.4. include/int.h Information There appears to be no MODULE information for this file. 7.4.1. Functions in include/int.h We appear to have no information on the functions in include/int.h. 7.4.2. Remarks in include/int.h Apparently, no-one has anything interesting to say about include/int.h. 7.4.3. Items for Fixing in include/int.h Apparently, nothing needs fixing in include/int.h. 7.4.4. New Ideas for include/int.h Apparently, there are no new ideas for include/int.h. 7.5. include/ports.h Information There appears to be no MODULE information for this file. 7.5.1. Functions in include/ports.h We appear to have no information on the functions in include/ports.h. 7.5.2. Remarks in include/ports.h Apparently, no-one has anything interesting to say about include/ports.h. 7.5.3. Items for Fixing in include/ports.h Apparently, nothing needs fixing in include/ports.h. 7.5.4. New Ideas for include/ports.h Apparently, there are no new ideas for include/ports.h. 7.6. dosemu/dosio.c Information There appears to be no MODULE information for this file. 7.6.1. Functions in dosemu/dosio.c We appear to have no information on the functions in dosemu/dosio.c. 7.6.2. Remarks in dosemu/dosio.c Apparently, no-one has anything interesting to say about dosemu/dosio.c. 7.6.3. Items for Fixing in dosemu/dosio.c Apparently, nothing needs fixing in dosemu/dosio.c. 7.6.4. New Ideas for dosemu/dosio.c Apparently, there are no new ideas for dosemu/dosio.c. 7.7. dosemu/serial.c Information There appears to be no MODULE information for this file. 7.7.1. Functions in dosemu/serial.c These are the functions defined in dosemu/serial.c. 7.7.1.1. serial_init The following is the master serial initialization function called externally (from this serial.c module) during DOSEMU startup. It initializes all the configured serial ports. 7.7.2. Remarks in dosemu/serial.c Apparently, no-one has anything interesting to say about dosemu/serial.c. 7.7.3. Items for Fixing in dosemu/serial.c Apparently, nothing needs fixing in dosemu/serial.c. 7.7.4. New Ideas for dosemu/serial.c Apparently, there are no new ideas for dosemu/serial.c. 7.8. dosemu/disks.c Information There appears to be no MODULE information for this file. 7.8.1. Functions in dosemu/disks.c These are the functions defined in dosemu/disks.c. 7.8.1.1. disk_init Test by opening all floppies/hardrives configured. 7.8.2. Remarks in dosemu/disks.c Apparently, no-one has anything interesting to say about dosemu/disks.c. 7.8.3. Items for Fixing in dosemu/disks.c Apparently, nothing needs fixing in dosemu/disks.c. 7.8.4. New Ideas for dosemu/disks.c Apparently, there are no new ideas for dosemu/disks.c. 7.9. dosemu/cpu.c Information CPU/V86 support for dosemu 7.9.1. Functions in dosemu/cpu.c These are the functions defined in dosemu/cpu.c. 7.9.1.1. cpu_init Setup initial interrupts which can be revectored so that the kernel does not need to return to DOSEMU if such an interrupt occurs. 7.9.2. Remarks in dosemu/cpu.c Apparently, no-one has anything interesting to say about dosemu/cpu.c. 7.9.3. Items for Fixing in dosemu/cpu.c Apparently, nothing needs fixing in dosemu/cpu.c. 7.9.4. New Ideas for dosemu/cpu.c Apparently, there are no new ideas for dosemu/cpu.c. 7.10. dosemu/lpt.c Information There appears to be no MODULE information for this file. 7.10.1. Functions in dosemu/lpt.c These are the functions defined in dosemu/lpt.c. 7.10.1.1. printer_init Initialize printer control structures 7.10.2. Remarks in dosemu/lpt.c Apparently, no-one has anything interesting to say about dosemu/lpt.c. 7.10.3. Items for Fixing in dosemu/lpt.c Apparently, nothing needs fixing in dosemu/lpt.c. 7.10.4. New Ideas for dosemu/lpt.c Apparently, there are no new ideas for dosemu/lpt.c. 8. The Mouse group of Modules All of the Mouse handling code is in the "mouse" subdirectory. There are only 2 main files, mouse.c and mouseint.c. 8.1. mouse/mouse.c Information There appears to be no MODULE information for this file. 8.1.1. Functions in mouse/mouse.c These are the functions defined in mouse/mouse.c. 8.1.1.1. mouse_init Initialize internal mouse. 8.1.2. Remarks in mouse/mouse.c Apparently, no-one has anything interesting to say about mouse/mouse.c. 8.1.3. Items for Fixing in mouse/mouse.c Apparently, nothing needs fixing in mouse/mouse.c. 8.1.4. New Ideas for mouse/mouse.c Apparently, there are no new ideas for mouse/mouse.c. 9. The Bios group of Modules All of the Bios code is in the "bios" subdirectory. DOSEMU requires certain code to be coded in assembler and also code to be located in the F000 segment. This is where all such code should be put. 9.1. bios/bios.S Information There appears to be no MODULE information for this file. 9.1.1. Functions in bios/bios.S We appear to have no information on the functions in bios/bios.S. 9.1.2. Remarks in bios/bios.S Apparently, no-one has anything interesting to say about bios/bios.S. 9.1.3. Items for Fixing in bios/bios.S Apparently, nothing needs fixing in bios/bios.S. 9.1.4. New Ideas for bios/bios.S Apparently, there are no new ideas for bios/bios.S. 10. The PIC group of Modules All of the PIC handling code is in the "PIC" subdirectory. 10.1. pic/pic.c Information pic.c is a fairly co,plete emulation of both 8259 Priority Interrupt Controllers. It also includes provision for 16 lower level interrupts. This implementation supports the following i/o commands: ICW1 bits 0 and 1 number of ICWs to expect ICW2 bits 3 - 7 base address of IRQs ICW3 no bits accepted but ignored ICW4 no bits accepted but ignored OCW1 all bits sets interrupt mask OCW2 bits 7,5-0 EOI commands only OCW3 bits 0,1,5,6 select read register, select special mask mode Reads of both pic ports are supported completely. An important concept to understand in pic is the interrupt level. This is a value which represents the priority of the current interrupt. It is used to identify interrupts, and IRQs can be mapped to these levels(see pic.h ). The currently active interrupt level is maintained in pic_ilevel, which is globally available, A pic_ilevel of 32 means no interrupts are active; 0, the highest priority, represents the NMI. IRQs 0 through 15 are mapped, in priority order, to values of 1-15 (there is no IRQ2 in an AT). Values of 16 - 31 represent additional interrupt levels available for internal dosemu usage. More detail is available in the file README.pic 10.1.1. Functions in pic/pic.c These are the functions defined in pic/pic.c. 10.1.1.1. write_pic0 write_pic_0() and write_pic1() implement dos writes to the pic ports. They are called by the code that emulates inb and outb instructions. Each function implements both ports for the pic: pic0 is on ports 0x20 and 0x21; pic1 is on ports 0xa0 and 0xa1. These functions take two arguements: a port number (0 or 1) and a value to be written. 10.1.1.2. read_pic0 read_pic0 and read_pic1 return the values for the interrupt mask register (port 1), or either the in service register or interrupt request register, as determined by the last OCW3 command (port 0). These functions take a single parameter, which is a port number (0 or 1). They are called by code that emulates the inb instruction. 10.1.1.3. pic_mask The pic maintains an additional interrupt mask which is not visible to the DOS process. This is normally cleared (enabling an interrupt) when an interrupt is initialized, but dosemu code may choose to use this mask internally. One possible use is to implement the interrupt gate controlled by the OUT2 bit of the 16550A UART's Modem Control Register. This mask is cleared by pic_unmaski() and set by pic_maski() 10.1.1.4. pic_seti pic_seti is used to initialize an interrupt for dosemu. It requires three parameters. The first parameter is the interrupt level, which man select the NMI, any of the IRQs, or any of the 16 extra levels (16 - 31). The second parameter is the dosemu function to be called when the interrupt is activated. This function should call do_irq() if the DOS interruptis really to be activated. If there is no special dosemu code to call, the second parameter can specify do_irq(), but see that description for some special considerations. 10.1.1.5. run_irqs run_irqs, which is initiated via the macro pic_run, is the "brains" of the pic. It is called from the vm86() loop, checks for the highest priority interrupt requested, and executes it. This function is written in assembly language in order to take advantage of atomic (indivisible) instructions, so that it should be safe for a two process model, even in a multiple CPU machine. A c language version was started, but it became impossible, even with in-line assembly macros, because such macros can only return a single result. If I find a way to do it in c, I will, but don't hold your breath. 10.1.1.6. do_irq do_irq() calls the correct do_int(). It then executes a vm86 loop until an outb( end-of-interrupt) is found. For priority levels 0 and >15 (not real IRQs), vm86 executes once, then returns, since no outb20 will come. Returns: 0 = complete, 1 = interrupt not run because it directly calls our "bios" See run_timer_tick() in timer.c for an example To assure notification when the irq completes, we push flags, ip, and cs here and fake cs:ip to PIC_SEG,OFF, where there is a hlt. This makes the irq generate a sigsegv, which calls pic_iret when it completes. pic_iret then pops the real cs:ip from the stack. This routine is RE-ENTRANT - it calls run_irqs, which which may call an interrupt routine, which may call do_irq(). Be Careful! !!!!!!!!!!!!!!!!!! No single interrupt is ever re-entered. 10.1.1.7. pic_request pic_request triggers an interrupt. There is presently no way to "un- trigger" an interrupt. The interrupt will be initiated the next time pic_run is called, unless masked or superceded by a higher priority interrupt. pic_request takes one arguement, an interrupt level, which specifies the interrupt to be triggered. If that interrupt is already active, the request will be queued until all active interrupts have been completed. The queue is only one request deep for each interrupt, so it is the responsibility of the interrupt code to retrigger itself if more interrupts are needed. 10.1.1.8. pic_iret pic_iret is used to sense that all active interrupts are really complete, so that interrupts queued by pic_request can be triggered. Interrupts end when they issue an outb 0x20 to the pic, however it is not yet safe at that time to retrigger interrupts, since the stack has not been restored to its initial state by an iret. pic_iret is called whenever interrupts have been enabled by a popf, sti, or iret. It determines if an iret was the cause by comparing stack contents with cs and ip. If so, it decrements a count of interrupts on the stack (set by do_irq()). If the count is then zero, pic_iret moves all queued interrupts to the interrupt request register. It is possible for pic_iret to be fooled by dos code; for this reason active interrupts are checked, any queued interrupts that are also active will remain queued. Also, some programs fake an iret, so that it is possible for pic_iret to fail. See pic_watch for the watchdog timer that catches and fixes this event. 10.1.1.9. pic_watch pic_watch is a watchdog timer for pending interrupts. If pic_iret somehow fails to activate a pending interrupt request for 2 consecutive timer ticks, pic_watch will activate them anyway. pic_watch is called by do_irq0, the timer interrupt routine. 10.1.1.10. do_irq0 This is the routine for timer interrupts. It simply calls pic_watch(), then triggers IRQ0 via do_irq(). 10.1.2. Remarks in pic/pic.c Apparently, no-one has anything interesting to say about pic/pic.c. 10.1.3. Items for Fixing in pic/pic.c Apparently, nothing needs fixing in pic/pic.c. 10.1.4. New Ideas for pic/pic.c Apparently, there are no new ideas for pic/pic.c. 10.2. pic/pic.h Information There appears to be no MODULE information for this file. 10.2.1. Functions in pic/pic.h We appear to have no information on the functions in pic/pic.h. 10.2.2. Remarks in pic/pic.h Apparently, no-one has anything interesting to say about pic/pic.h. 10.2.3. Items for Fixing in pic/pic.h Apparently, nothing needs fixing in pic/pic.h. 10.2.4. New Ideas for pic/pic.h Apparently, there are no new ideas for pic/pic.h. 11. The Shared group of Modules All code being created to allow sharing of DOSEMU related information between separate running process is found here. This is headed in the direction of supporting DOSEMU in a client/server format. 11.1. dosemu/shared.c Information Memory areas needed to be shared between the DOSEMU process and other clients. 11.1.1. Functions in dosemu/shared.c These are the functions defined in dosemu/shared.c. 11.1.1.1. shared_qf_memory_init Setup all memory areas to be shared with clients. 11.1.2. Remarks in dosemu/shared.c Set to 0 all client request area ----- Output info required for client activity 11.1.3. Items for Fixing in dosemu/shared.c Apparently, nothing needs fixing in dosemu/shared.c. 11.1.4. New Ideas for dosemu/shared.c Apparently, there are no new ideas for dosemu/shared.c. 12. And Finally ... The Following items are used to delimit the text used to create this file. Whilst it is not necessary to know this, they are included because they may be useful for searching, as they are (at least at the moment) reasonably unique. DANG_BEGIN_MODULE / DANG_END_MODULE This will bracket a description of the file (normally at the start). DANG_BEGIN_FUNCTION / DANG_END_FUNCTION This brackets a description of functions (good this, isn't it!) Not every function needs to be described in this way - just the major ones.