* Introduction

Having successfully built ReactOS and been amazed by what it does, you're
now desperate to fill in some of the omissions, this document shows you how.

* Prerequisites

A working knowledge of NT driver development is useful for understanding the
kernel and some of its abstractions. The NT4 ddk is available for free
download from http://www.microsoft.com/hwdev/. The Windows 98 and Windows
2000 DDKs are also available but the NT4 one is the most useful. See
Legal Stuff below however.

There are a number of books on NT driver development, I would recommend
'Windows NT Device Driver Development' (http://www.osr.com/book/) since OSR
seem to know their stuff. There is only one book on NT filesystem
development 'Windows NT File System Internals'. Please don't buy any of
these books unless you need to, and can afford it. 

These mailing lists and newsgroups are useful for NT internals related 
questions,
           ntfsd@atria.com, ntdev@atria.com 
	                    (subscribe by email to majordomo@atria.com)
	   comp.os.????
	   microsoft.public.????
	   
* Style

There is no coding style used for ReactOS, however the following guidelines
make things easier

     Include information at the top of a module about its purpose, contact
     information for its programmer and any useful notes. 
     
     Include a comment by each non-trival function describing its arguments,
     purpose and any other notes.
     
     Update the documentation in this directory
     
These guidelines are an ideal, no one manages to implement them all the
time, straightforward working code is probably just as good.

* Debugging

Debugging kernel-mode code is tricky, these are some snippets

    DbgPrint writes a message to the console using a printf style format
    string. The DPRINT macro (defined in internal/debug.h) expands to
    DbgPrint unless NDEBUG is defined, this is useful for having copious
    output from a module only when a problem is being debugging. DPRINT
    also prefixes the message with the file and line number to make it
    easier to see where output is coming from. DbgPrint can be used at any
    point including in interrupt handlers.
    
    There are options in ntoskrnl/hal/x86/printk.c for copying DbgPrint
    output to a serial device (parallel support should also be added). This
    can be useful if a lot of output is being generated.
    
    It should be possible to include support for debugging the kernel with
    gdb over a serial line. Bochs (a shareware CPU emulator) is also useful
    for debugging the kernel, I wrote some patches to allow capture of console
    output from within bochs to file and for debugging a kernel running
    under bochs with gdb. Contact me (welch@cwcom.net) if you're are 
    interested.
    
    If CPU reports an exception not handled by the kernel (any page fault
    not part of virtual memory support or any other exception) the kernel 
    will display output like this and halt
    
            General Protection Fault Exception: 13(0)
	    CS:EIP  xxxxxxxx:xxxxxxx
	    DS xxxx ES xxxx FS xxxx GS xxxxx
	    EAX: xxxx EBX: xxxx
	    ....
	    EDI: xxxx EFLAGS: xxxx ESP: xxxx
	    cr2: xxxx
	    Stack: xxxx xxxx xxxx ...
	           ....
	    Frames: xxxx xxxx xxxx ...
	           ....
		   
    The fault type will usually be either 'General Protection' or
    'Page Fault', see your Intel manual for the more exotic types. The
    'EIP' number is the address of the faulting instruction. If the 'CS'
    number is 0x20 then the exception occured in kernel mode, if it is 0x11
    then the exception occurred in user mode. 'cr2' is the address that the
    faulting instruction was trying to access, if the exception was a page 
    fault. The number printed after 'Frames' are any addresses on the stack
    that look like function addresses. 
    
    
    If the kernel detects a serious problem that it will bug check, displaying
    output like this
    
           Bug detected (code x, param x x x x)
	   Frames: xxx xxxx xxxx
	           ....
		   
    Again the numbers printed after 'Frames' are any addresses on the stack
    that look like function addresss. Usually the kernel will also print a
    message describing the problem in more detail, the bug check code isn't
    very useful at the moment. 
    
* Contacts

    There is a mailing list for kernel development,
    
            ros-kernel@sid-dis.com
	    
    The main developers use a cvs account to coordinate changes, ask 
    rex (rex@lvcablemodem.com) for an account if you are going to be adding
    a lot of code. Smaller patches can go to the mailing list or to the
    relevant developer (usually the comment at the top of a module will have
    an email address). Regular snapshots are made available for download,
    see the mailing list for announcements.
    
* Legal stuff

    The ReactOS project is GPL'ed, please make sure any code submitted is
    compatible with this. 
    
    The NT4 ddk license agreement allows its usage for developing nt drivers
    only. Legally therefore it can not be used to develop ReactOS, neither the
    documentation or the sample code. I'm not a lawyer, but I doubt the
    effiacy of 'shrinkwrap licenses' particularly on freely downloadable 
    software. The only precendent I know of, in a Scottish court, didn't
    upload this type of license.
    
    Also the 'fair use' section of copyright law allows the 'quoting' of small
    sections from copyrighted documents, e.g. Windows API or DDK documentation
