Initial revision

svn path=/trunk/; revision=2

reactos/boot.bat

@@ -0,0 +1 @@
+loaders\dos\loadros kernel\kimage.bin %1 %2 %3 %4

reactos/doc/api.txt

@@ -0,0 +1,140 @@
+This file attempts to document the functions made publically available by
+the various subsystems.
+
+* Formatted I/O operations *
+
+NAME: int vsprintf(char *buf, const char *fmt, va_list args)
+NAME: int sprintf(char* buf, const char* fmt, ...)
+WHERE: internal/kernel.h
+FUNCTION: The same as the standard c library versions
+
+* PIO operations *
+
+NAME: in[b/w/l](port)
+WHERE: internal/io.h
+FUNCTION: Read an IO port of the specified size (byte/word or long)
+RETURNS: The value read
+
+NAME: out[b/w/l](port,val)
+WHERE: internal/io.h
+FUNCTION: Write an IO port of the specified size (byte/word or long)
+
+NAME: in_p[b/w/l](port)
+WHERE: internal/io.h
+FUNCTION: Read an IO port of the specified size (byte/word or long) with
+        a pause
+RETURNS: The value read
+
+NAME: out_p[b/w/l](port,val)
+WHERE: internal/io.h
+FUNCTION: Write an IO port of the specified size (byte/word or long) with
+        a pause
+
+* Bit operations *
+
+NAME: int set_bit(int nr, void* addr)
+NAME: int clear_bit(int nr, void* addr)
+NAME: int change_bit(int nr, void* addr)
+WHERE: internal/bitops.h>
+FUNCTION: Operate on a bit in the word pointed to by addr
+RETURN: 0 if the bit was cleared before the operations
+        non-zero otherwise
+
+* Debugging functions *
+
+NAME: DPRINT(fmt,....)
+WHERE: internal/debug.h
+FUNCTION: Outputs a string to the console if NDEBUG isn't defined before
+including internal/debug.h, a NOP otherwise
+ARGUMENTS: The same as printf
+
+NAME: printk
+WHERE: internal/kernel.h
+FUNCTION: Outputs a string to the console
+ARGUMENTS: The same as printf
+
+* Memory managment functions *
+
+NAME: unsigned int physical_to_linear(unsigned int paddr)
+WHERE: hal/page.h
+FUNCTION: Converts a physical address to a linear one
+RECEIVES:
+        paddr = the physical address to convert
+RETURNS: A virtual address where the memory at that physical address can be 
+accessed
+
+NAME: void* ExAllocatePool(unsigned int size, unsigned int type = 0);
+WHERE: internal/pool.h
+FUNCTION: Allocates a block of memory
+RECEIVES:
+        size = the size of the block to allocate
+        type = will be whether to allocate pagable memory
+RETURNS: The address of the block
+NOTE: This isn't interrupt safe
+
+NAME: void ExFreePool(void* block)
+WHERE: internal/pool.h
+FUNCTION: Frees a block of memory
+
+NAME: void free_page(unsigned int physical_base, unsigned int nr = 1)
+WHERE: internal/mm.h
+FUNCTION: Adds a continuous range of physical memory to the free list
+
+NAME: unsigned int get_free_page(void)
+WHERE: internal/mm.h
+FUNCTION: Gets a free page
+RETURNS: Its physical address
+
+NAME: unsigned int get_page_physical_address(unsigned int vaddr)
+WHERE: internal/mm.h
+FUNCTION: Gets the physical address of a page
+
+NAME: void mark_page_not_writable(unsigned int vaddr)
+WHERE: internal/mm.h
+FUNCTION: Prevent writing the page
+
+* DMA functions *
+
+NAME: unsigned int get_dma_page(unsigned int max_address)
+WHERE: internal/mm.h
+FUNCTION: Gets a page with a restricted physical address i.e. suitable for
+          dma
+RETURNS: The physical address of the page
+
+NAME: void disable_dma(unsigned int dmanr)
+WHERE:    internal/dma.h
+FUNCTION: Disables the specified dma channel
+
+NAME: void enable_dma(unsigned int dmanr)
+WHERE:    internal/dma.h
+FUNCTION: Enables the specified dma channel
+
+NAME: void clear_dma_ff(unsigned int dmanr)
+WHERE: internal/dma.h
+FUNCTION: Clear the dma flip-flop
+
+NAME: void set_dma_mode(unsigned int dmanr, char mode)
+WHERE: internal/dma.h
+FUNCTION: Sets the type of dma transfer
+
+NAME: void set_dma_page(unsigned int dmanr, char pagenr)
+WHERE: internal/dma.h
+FUNCTION: Set only the page register bits of the transfer address
+
+NAME: void set_dma_addr(unsigned int dmanr, unsigned int a)
+WHERE: internal/dma.h
+FUNCTION: Set the transfer address for dma
+NOTE: Assumes flip-flop is clear
+
+NAME: void set_dma_count(unsigned int dmanr, unsigned int count)
+WHERE: internal/dma.h
+FUNCTION: Sets the size of the transfer
+ARGUMENTS:
+        count = the number of bytes to transfer
+NOTE: Count must be even for channels 5-7
+
+NAME: int get_dma_residue(unsigned int dmanr)
+WHERE: internal/dma.h
+FUNCTION: Gets the residue remaining after a dma transfer on the channel
+
+

reactos/doc/buglist

@@ -0,0 +1,2 @@
+* Kernel bugs not fixed
+

reactos/doc/faq.txt

@@ -0,0 +1,114 @@
+Kernel Development FAQ (for v0.0.7)
+
+This attempts to answer some of the common questions people developing for
+the kernel might want to ask (or at least what I think they should ask).
+Obviously I can only detail those parts which I have written so other
+developers please fill in the gaps.
+
+Q: What is this, what are you people, what's going on
+A: This is the ReactOS, an operating system intended as a clone of windows
+NT. See the project website (http://www.sid-dis.com/reactos/) for more details.
+
+Q: Why ReactOS
+A: To condemn Bill Gates to penury.
+
+Q: What do I need to compile the kernel
+A: DJGPP, get it from http://www.delorie.com/djgpp
+
+Q: How do I compile the kernel
+A: Unpack the zip. It is important not to install the kernel in the same
+directory as a previous version, this has caused a bit of confusion in the 
+past. Edit the makefile in the top level directory, in particular select the
+correct host to build from. Then run make in the top directory
+
+Q: What files are created when I make the kernel
+A: The following files are created in the kernel directory
+        kimage = the kernel as a coff executable
+        kimage.bin = the kernel as a raw binary image
+        kernel.sym = a list of the kernel symbols
+
+Q: How do I load the kernel
+A: Run the boot.bat batch file.
+
+Q: Does it boot from disk
+A: Not at the moment.
+
+Q: When I run the kernel it crashes
+A: The kernel (at the moment) can only be loaded from a clean system. That
+is one without EMM386 or any version of windows loaded. A quick way to
+ensure this (if you have windows 95) is to set the program to run in msdos
+mode and specify an empty config.sys and autoexec.bat. See the windows help
+for more information.
+
+If you do that and the problem persists then contact the kernel team
+(ros-kernel@sid-dis.com) as it is probably a bug in the kernel 
+
+Q6: How do I load a module with the kernel
+A: Add the names of any modules to be loaded to the command line of boot.bat.
+
+Q7: I want to add code to the kernel, how do I get it to be compiled
+A: You will need to edit the Makefile in kernel directory. There should be
+a statement like this 
+
+    OBJECTS = hal/head.o hal/exp.o kernel/vsprintf.o \
+              ....
+	      kernel/irqhand.o hal/page.o mm/virtual.o kernel/error.o \
+	      kernel/exports.o kernel/module.o
+
+Add the name of the object file (the file produced when your code is
+compiled) to the end of the statement (in this case after kernel/module.o).
+If you need to go onto a new line then add a slash to the end of the
+previous line. It is also very important to use an editor which preserves
+tabs.
+
+Q8: I want to add code to the kernel, how do I make it official
+A: Contact the kernel mailing list ros-kernel@sid-dis.com or our coordinator
+dwinkley@whitworth.edu. If it is for a specific section then the kernel
+website (http://www.geocities.com/SiliconValley/Peaks/1957) has a list of
+those working on individual areas, you might what to contact one of them
+instead.
+
+Q9: What header files should I use
+A: Don't include the usual DJGPP headers like stdio.h unless you are using
+something compiler based like stdargs.h. To use the DJGPP headers requires
+linking with libc which is useless in kernel mode.
+
+All the header files are in the top-level include directory which is laid
+out like this
+         include  = general win32 api declarations
+	 include/internal = private kernel headers
+	 include/internal/hal = HAL headers
+	 include/ddk = header files with declarations for modules
+
+There should be a file called api.txt which documents all of the functions
+(and which header files they need).
+
+Q11: I want to export my function for modules to use, how do I do that
+A: Add the function to the list in kernel/exports.lst, then remake the
+kernel. Note the function must be declared as extern "C".
+
+Q12: I want to make my functions part of the kernel interface to user mode,
+A: That section isn't finished yet, though it will probably mean adding a
+pointer to the function and the size of its parameters to a internal table
+somewhere.
+
+Q14: I want to write a module, what are the guidelines
+A: See modules.txt in this directory
+
+Q15: I want to write an ISR (interrupt service routine)
+A: See irq.txt in this directory
+
+Q16: I want to use DMA
+A: Firstly this answer covers only DMA via the dma chips *not*
+busmaster DMA.
+
+To program the dma chip use the functions in internal/dma.h (look in api.txt
+for details). PC DMA can only go to memory with a physical address below
+1mb (or 16mb on some systems), use the get_dma_page to allocate this kind
+of memory.
+
+Q17: You haven't answered my question
+A: Send your questions to ros-kernel@sid-dis.com
+
+
+- David Welch (welch@mcmail.com)

reactos/doc/internal/mm.txt

@@ -0,0 +1,10 @@
+This document describes the implementation of the memory managment
+
+
+* ReactOS memory map
+
+0x00000000 - 0xc0000000 = User memory 
+0xc0000000 - 0xd0000000 = Kernel memory 
+0xd0000000 - 0xffffffff = Identify map of physical memory
+
+*