[reactos.git] / reactos / media / doc / HACKING
1 * Introduction
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.
6 * Prerequisites
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.
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.
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.????
27 * Style
29 There is a coding style used for ReactOS, it's described in a ReactOS's Wiki
30 page called Coding Style: http://www.reactos.org/wiki/index.php/Coding_Style
32 However, not all codebase complies with the rules outlined in that page, so
33 if you need to hack some code which has not been yet formatted, it's wise
34 to keep the kind of formatting it already has, to make it looking good until
35 it receives a formatting patch.
38 * Debugging
40 Debugging kernel-mode code is tricky, these are some snippets
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.
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.
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.
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
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 ....
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.
87 If the kernel detects a serious problem that it will bug check, displaying
88 output like this
90 Bug detected (code x, param x x x x)
91 Frames: xxx xxxx xxxx
92 ....
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.
99 * Contacts
101 There is a mailing list for kernel development,
103 ros-dev@reactos.org
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.
112 * Legal stuff
114 The ReactOS project is GPL'ed, please make sure any code submitted is
115 compatible with this.
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.
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