This commit was generated by cvs2svn to compensate for changes in r10,
[reactos.git] / reactos / doc / faq.txt
1 Kernel Development FAQ (for v0.0.7)
2
3 This attempts to answer some of the common questions people developing for
4 the kernel might want to ask (or at least what I think they should ask).
5 Obviously I can only detail those parts which I have written so other
6 developers please fill in the gaps.
7
8 Q: What is this, what are you people, what's going on
9 A: This is the ReactOS, an operating system intended as a clone of windows
10 NT. See the project website (http://www.sid-dis.com/reactos/) for more details.
11
12 Q: Why ReactOS
13 A: To condemn Bill Gates to penury.
14
15 Q: What do I need to compile the kernel
16 A: DJGPP, get it from http://www.delorie.com/djgpp
17
18 Q: How do I compile the kernel
19 A: Unpack the zip. It is important not to install the kernel in the same
20 directory as a previous version, this has caused a bit of confusion in the
21 past. Edit the makefile in the top level directory, in particular select the
22 correct host to build from. Then run make in the top directory
23
24 Q: What files are created when I make the kernel
25 A: The following files are created in the kernel directory
26 kimage = the kernel as a coff executable
27 kimage.bin = the kernel as a raw binary image
28 kernel.sym = a list of the kernel symbols
29
30 Q: How do I load the kernel
31 A: Run the boot.bat batch file.
32
33 Q: Does it boot from disk
34 A: Not at the moment.
35
36 Q: When I run the kernel it crashes
37 A: The kernel (at the moment) can only be loaded from a clean system. That
38 is one without EMM386 or any version of windows loaded. A quick way to
39 ensure this (if you have windows 95) is to set the program to run in msdos
40 mode and specify an empty config.sys and autoexec.bat. See the windows help
41 for more information.
42
43 If you do that and the problem persists then contact the kernel team
44 (ros-kernel@sid-dis.com) as it is probably a bug in the kernel
45
46 Q6: How do I load a module with the kernel
47 A: Add the names of any modules to be loaded to the command line of boot.bat.
48
49 Q7: I want to add code to the kernel, how do I get it to be compiled
50 A: You will need to edit the Makefile in kernel directory. There should be
51 a statement like this
52
53 OBJECTS = hal/head.o hal/exp.o kernel/vsprintf.o \
54 ....
55 kernel/irqhand.o hal/page.o mm/virtual.o kernel/error.o \
56 kernel/exports.o kernel/module.o
57
58 Add the name of the object file (the file produced when your code is
59 compiled) to the end of the statement (in this case after kernel/module.o).
60 If you need to go onto a new line then add a slash to the end of the
61 previous line. It is also very important to use an editor which preserves
62 tabs.
63
64 Q8: I want to add code to the kernel, how do I make it official
65 A: Contact the kernel mailing list ros-kernel@sid-dis.com or our coordinator
66 dwinkley@whitworth.edu. If it is for a specific section then the kernel
67 website (http://www.geocities.com/SiliconValley/Peaks/1957) has a list of
68 those working on individual areas, you might what to contact one of them
69 instead.
70
71 Q9: What header files should I use
72 A: Don't include the usual DJGPP headers like stdio.h unless you are using
73 something compiler based like stdargs.h. To use the DJGPP headers requires
74 linking with libc which is useless in kernel mode.
75
76 All the header files are in the top-level include directory which is laid
77 out like this
78 include = general win32 api declarations
79 include/internal = private kernel headers
80 include/internal/hal = HAL headers
81 include/ddk = header files with declarations for modules
82
83 There should be a file called api.txt which documents all of the functions
84 (and which header files they need).
85
86 Q11: I want to export my function for modules to use, how do I do that
87 A: Add the function to the list in kernel/exports.lst, then remake the
88 kernel. Note the function must be declared as extern "C".
89
90 Q12: I want to make my functions part of the kernel interface to user mode,
91 A: That section isn't finished yet, though it will probably mean adding a
92 pointer to the function and the size of its parameters to a internal table
93 somewhere.
94
95 Q14: I want to write a module, what are the guidelines
96 A: See modules.txt in this directory
97
98 Q15: I want to write an ISR (interrupt service routine)
99 A: See irq.txt in this directory
100
101 Q16: I want to use DMA
102 A: Firstly this answer covers only DMA via the dma chips *not*
103 busmaster DMA.
104
105 To program the dma chip use the functions in internal/dma.h (look in api.txt
106 for details). PC DMA can only go to memory with a physical address below
107 1mb (or 16mb on some systems), use the get_dma_page to allocate this kind
108 of memory.
109
110 Q17: You haven't answered my question
111 A: Send your questions to ros-kernel@sid-dis.com
112
113
114 - David Welch (welch@mcmail.com)