




                             DANG


                 DOSEMU Altering Novice's Guide 

                          Version .11
                        18th March 1994


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

This Guide was concieved and originally written by "Corey Sweeney"
<corey@amiganet.chi.il.us>. I've only modified it. Special thanks to
"James B. MacLean" <jmaclean@fox.nstn.ns.ca> for supplying the original
information. (It was mostly ripped out of a mail message.)

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


The files:

termio.c - Includes the keyboard routines.
        Partially looks after the different keyboard modes that dosemu
        can run in, either 'xlate', or 'raw'. 'Raw' receives scan codes
        directly from Linux while 'xlate' receives ascii codes as are
        transmitted over serial lines. Termio.c also works out the
        mapping between the directly updated screen addresses and the
        actual screen being viewed when NOT in console video mode. 


keymaps.c - the definitions of which keys are related to which
        scancodes in raw keyboard mode.
        Basicallly the scan code of x on a US keyboard may be a
        scancode of Y on a German keyboard. This way all types of
        keyboards can be represented under dosemu.... I think 8-).
        Also, as an example, the right alt key on many keyboards is
        actually another function key altogether. 


*video.c - The video stuff (raw & character)
        All emulated video interrupts are here, int10 that is. All
        efforts being made to properly save and restore the video
        state between VC's, and some effort into controlling updates
        to the VC while switched away are all here. Any new video
        cards to be supported need to have their own set of
        save/restore routines added here. The actual mmaping of the
        absolute screen memory is programmed here also.
        If you need to use a cards own bios then the parameter
        graphics must added to the video statment in /etc/dosemu/config.
        Then DOSEMU will attempt to execute the card initialization
        routine which is supposed to be located at address c000:0003.


*xms.c - The XMS memory routines
        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 allocating UMB's, so they are also
        included as part of this file. The amount of xms memory
        returned to DOS programs via XMS requests, or int15 fnc88 is
        set in /etc/dosemu/config via the XMS parameter.


**mfs.c - This file along with ./drivers/emufs.S are the device
        redirector for dosemu. When emufs.sys is loaded under DOS, it
        basically opens a channel up for requests to be handled by
        mfs.c. DOS sends most file requests through emufs.sys, where the
        driver either handles the request, or lets DOS know that it
        did not handle the request.
        FCB read/write is not working.


cmos.c - (emulation of or access to) the cmos settings?
        It is believed that access to port 0x70 and 0x71 will utilize
        this code.


**emu.c - This appears to be the main routine,  it seems to manage
        initialisation, speakers, memory, serial, cassette (Does OS/2 do
        this ?), and everything else. Here's an explanation :

        First we grab all the signals needed (in vm86 mode, many
        interupts cause signals. A good example is the interrupt
        instruction (cd) which causes a -sigsegv signal. Set all the
        interrupt vectors to point to the f000 seg where our int
        instructions await. This allows interrupts caught by SIGSEGV to
        tell dosemu that they came from the f000 segment. ie they are
        being  handled by dosemu, but haven't been redirected yet. Any
        extra interrupt vector relations are added here. (eg. the inline
        interrupts 16 & 9)

        Then load the bootstrap at the appropriate place. (Realize that
        part of the neat programming at this part has left the first
        meg+128k of the dosemu process unused). Start pushing any code
        you want executed in the stack space being used. For example,
        calling VGA, or printing the banner. The second process is
        started around here. This process is used to poll for any I/O services
        needing attention.

        Jump into the cs:ip by entering vm86 mode and hold onto your
        hat. From here on, every blessed thing that warrants signal
        attention throws dosemu out of real mode and into protected
        mode, where it handles the exception. 

        >DOSEMU was at one point two processes, but is now all one again. As
	>such, this file may have changed a lot.

*cpu.c - Contains code to handle special cpu circumstances (ya, that's the
        ticket :-) ) like interrupts, I/O to ports that are not currently
        allowed, iret's, etc... When a signal hits, if it's a legal
        instruction for protected mode but not vm86 mode, the sigsegv()
        funtion is called, where the offending instruction is paired up
        to a routine to emulate its funtion, or prepare to pass to a
        routine that will. If it can't be emulated yet, dosemu will
        stop, resulting in a General Protection Error message in your
        debug output.
        If an illegal instruction is encountered, sigill() funtion will be
        called. Currently this routine is very limited in its ability to
        handle possible O.K. situations like attempts to use a mathco when
        one does not exist.


*Bios_emm.c -  contains all the EMS calls and currently uses the
        /proc file system to mmap its own memory for use in the EMS
        window. This will make EMS slower, but easier for those
        just starting with dosemu.


many of these files have usefull comments at the top. most do not.

* = source code contains minimal docs

** = source code contains extensive docs



The best approach to learning how dosemu works probably starts with
reading the texinfo document written by bob.  Once you've finished that
you will probably want to look through emu.c.  See what parts you can
recognize.  Then try to find the section of the code that does what
you want to change.


Alistair

am20@unix.york.ac.uk


