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