doc/HACKING

   1 * Introduction
   2
   3 Having successfully built ReactOS and been amazed by what it does, you're
   4 now desperate to fill in some of the omissions, this document shows you how.
   5
   6 * Prerequisites
   7
   8 A working knowledge of NT driver development is useful for understanding the
   9 kernel and some of its abstractions. The NT4 ddk is available for free
  10 download from http://www.microsoft.com/hwdev/. The Windows 98 and Windows
  11 2000 DDKs are also available but the NT4 one is the most useful. See
  12 Legal Stuff below however.
  13
  14 There are a number of books on NT driver development, I would recommend
  15 'Windows NT Device Driver Development' (http://www.osr.com/book/) since OSR
  16 seem to know their stuff. There is only one book on NT filesystem
  17 development 'Windows NT File System Internals'. Please don't buy any of
  18 these books unless you need to, and can afford it.
  19
  20 These mailing lists and newsgroups are useful for NT internals related
  21 questions,
  22            ntfsd@atria.com, ntdev@atria.com
  23                             (subscribe by email to majordomo@atria.com)
  24            comp.os.????
  25            microsoft.public.????
  26
  27 * Style
  28
  29 There is no coding style used for ReactOS, however the following guidelines
  30 make things easier
  31
  32      Include information at the top of a module about its purpose, contact
  33      information for its programmer and any useful notes.
  34
  35      Include a comment by each non-trival function describing its arguments,
  36      purpose and any other notes.
  37
  38      Update the documentation in this directory
  39
  40 These guidelines are an ideal, no one manages to implement them all the
  41 time, straightforward working code is probably just as good.
  42
  43 * Debugging
  44
  45 Debugging kernel-mode code is tricky, these are some snippets
  46
  47     DbgPrint writes a message to the console using a printf style format
  48     string. The DPRINT macro (defined in internal/debug.h) expands to
  49     DbgPrint unless NDEBUG is defined, this is useful for having copious
  50     output from a module only when a problem is being debugging. DPRINT
  51     also prefixes the message with the file and line number to make it
  52     easier to see where output is coming from. DbgPrint can be used at any
  53     point including in interrupt handlers.
  54
  55     There are options in ntoskrnl/kd/kdebug.c for copying DbgPrint output
  56     to a serial device or bochs logging port (parallel support should also
  57     be added). This can be useful if a lot of output is being generated.
  58
  59     It should be possible to include support for debugging the kernel with
  60     gdb over a serial line. Bochs (a shareware CPU emulator) is also useful
  61     for debugging the kernel, I wrote some patches to allow capture of console
  62     output from within bochs to file and for debugging a kernel running
  63     under bochs with gdb. Contact me (welch@cwcom.net) if you're are
  64     interested.
  65
  66     If CPU reports an exception not handled by the kernel (any page fault
  67     not part of virtual memory support or any other exception) the kernel
  68     will display output like this and halt
  69
  70             General Protection Fault Exception: 13(0)
  71             CS:EIP  xxxxxxxx:xxxxxxx
  72             DS xxxx ES xxxx FS xxxx GS xxxxx
  73             EAX: xxxx EBX: xxxx
  74             ....
  75             EDI: xxxx EFLAGS: xxxx ESP: xxxx
  76             cr2: xxxx
  77             Stack: xxxx xxxx xxxx ...
  78                    ....
  79             Frames: xxxx xxxx xxxx ...
  80                    ....
  81
  82     The fault type will usually be either 'General Protection' or
  83     'Page Fault', see your Intel manual for the more exotic types. The
  84     'EIP' number is the address of the faulting instruction. If the 'CS'
  85     number is 0x20 then the exception occured in kernel mode, if it is 0x11
  86     then the exception occurred in user mode. 'cr2' is the address that the
  87     faulting instruction was trying to access, if the exception was a page
  88     fault. The number printed after 'Frames' are any addresses on the stack
  89     that look like function addresses.
  90
  91
  92     If the kernel detects a serious problem that it will bug check, displaying
  93     output like this
  94
  95            Bug detected (code x, param x x x x)
  96            Frames: xxx xxxx xxxx
  97                    ....
  98
  99     Again the numbers printed after 'Frames' are any addresses on the stack
 100     that look like function addresss. Usually the kernel will also print a
 101     message describing the problem in more detail, the bug check code isn't
 102     very useful at the moment.
 103
 104 * Contacts
 105
 106     There is a mailing list for kernel development,
 107
 108             ros-kernel@reactos.com
 109
 110     The main developers use a cvs account to coordinate changes, ask
 111     rex (rex@lvcablemodem.com) for an account if you are going to be adding
 112     a lot of code. Smaller patches can go to the mailing list or to the
 113     relevant developer (usually the comment at the top of a module will have
 114     an email address). Regular snapshots are made available for download,
 115     see the mailing list for announcements.
 116
 117 * Legal stuff
 118
 119     The ReactOS project is GPL'ed, please make sure any code submitted is
 120     compatible with this.
 121
 122     The NT4 ddk license agreement allows its usage for developing nt drivers
 123     only. Legally therefore it can not be used to develop ReactOS, neither the
 124     documentation or the sample code. I'm not a lawyer, but I doubt the
 125     effiacy of 'shrinkwrap licenses' particularly on freely downloadable
 126     software. The only precendent I know of, in a Scottish court, didn't
 127     upload this type of license.
 128
 129     Also the 'fair use' section of copyright law allows the 'quoting' of small
 130     sections from copyrighted documents, e.g. Windows API or DDK documentation