--- /dev/null
+* 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/kd/kdebug.c for copying DbgPrint output
+ to a serial device or bochs logging port (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@reactos.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
projects / reactos.git / blobdiff