mirror of
https://github.com/reactos/reactos.git
synced 2024-06-27 16:31:30 +00:00
Removed obsolete documentation
svn path=/trunk/; revision=175
This commit is contained in:
David Welch
parent
512966336f
commit
8551dc320b
|
|
@ -1,140 +0,0 @@
|
|||
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
|
||||
|
||||
|
||||
|
|
@ -1,2 +0,0 @@
|
|||
* Kernel bugs not fixed
|
||||
|
||||
|
|
@ -1,32 +0,0 @@
|
|||
- Cache Manager
|
||||
|
||||
This document describes the current implementation of the cache manager.
|
||||
|
||||
- Description
|
||||
|
||||
In its current state the CM (cache manager) only includes primitives to
|
||||
cache disk blocks, this is useful for filesystem metadata but it requires an
|
||||
additional copy operation when reading files from cache. This will be fixed.
|
||||
|
||||
Each disk drive with data in the cache has an associated DCCB (Device Cache
|
||||
Control Block) which details all the blocks from the device in memory. If a
|
||||
filesystem requires cache services for a device it must call CbInitDccb to
|
||||
initialize this structure.
|
||||
|
||||
Each block with data from a device has an associated CCB (Cache Control
|
||||
Block) with a pointer to the physical memory used to hold the block, and
|
||||
various state and locking information. When a filesystem requires a block
|
||||
from the device it calls CbAcquireForRead or CbAcquireForWrite which ensure
|
||||
the data for the block is uptodate (loading it from disk if necessary) and
|
||||
return a pointer to the associated CCB. When a filesystem has finished with
|
||||
a block it calls CbReleaseFromRead or CbReleaseFromWrite, it is important to
|
||||
call these functions because the CM can only release blocks from the cache
|
||||
if they have no active readers or writers. The CM also enforces cache
|
||||
consistency by ensuring that while multiple threads can be reading a block
|
||||
simultaneously, there is only ever one active writers.
|
||||
|
||||
The CM provides no support for deadlock prevention/detection as it has no
|
||||
knowledge of the layout of a a filesystem (nor should it have).
|
||||
|
||||
- TODO
|
||||
|
||||
|
|
@ -1,24 +0,0 @@
|
|||
This is a list of the functions documented in the ddk that have been
|
||||
implemented
|
||||
|
||||
IoAllocateController
|
||||
IoFreeController
|
||||
IoCreateController
|
||||
IoDeleteController
|
||||
IoStartNextPacket
|
||||
IoStartNextPacketByKey
|
||||
IoStartPacket
|
||||
IoSizeOfIrp
|
||||
IoMarkIrpPending
|
||||
IoFreeIrp
|
||||
IoConnectInterrupt
|
||||
IoDisconnectInterrupt
|
||||
IoGetCurrentIrpStackLocation
|
||||
IoGetNextIrpStackLocation
|
||||
IoRequestDpc
|
||||
IoInitializeDpc
|
||||
IoInitializeTimer
|
||||
IoStartTimer
|
||||
IoStopTimer
|
||||
IoCreateDevice
|
||||
IoCallDriver
|
||||
|
|
@ -1,19 +0,0 @@
|
|||
Some notes on debugging the ReactOS kernel
|
||||
------------------------------------------
|
||||
|
||||
* Interpreting crashes
|
||||
|
||||
If the kernel causes a fatal cpu fault then it will print out a message and
|
||||
halt. This message contains important information for debugging the problem,
|
||||
look for these lines
|
||||
|
||||
Exception: xx(yy)
|
||||
CS:EIP 20:zzzzzzzzzzzz
|
||||
|
||||
Here xx is the type of error, usually either 14 or 13 and yy is the error
|
||||
code. Generally error codes 13 and 14 both mean the kernel tried to access
|
||||
some memory in an invalid way. zzzzzzzzz is the address of the erronous
|
||||
instruction.
|
||||
|
||||
* Debugging with bochs
|
||||
|
||||
|
|
@ -1,114 +0,0 @@
|
|||
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)
|
||||
|
|
@ -1,10 +0,0 @@
|
|||
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
|
||||
|
||||
*
|
||||
File diff suppressed because it is too large
Load diff
|
|
@ -1,2 +0,0 @@
|
|||
This contains documentation describing the internals of the various kernel
|
||||
subsystems and a few other useful bits of information.
|
||||
|
|
@ -1,135 +0,0 @@
|
|||
** Introduction
|
||||
|
||||
This attempts to document the ReactOS irq handling. As of v0.0.8 this has
|
||||
changed to be more nt like, I will attempt to summarize the new
|
||||
implementation for those unavailable with nt device driver writing. Note,
|
||||
ReactOS doesn't have an exact implementation but the omissions are, except
|
||||
where noted, not user visible.
|
||||
|
||||
** Steps in grabbing an irq vector
|
||||
|
||||
* Call HalConnectInterrupt
|
||||
|
||||
PROTOTYPE:
|
||||
|
||||
ULONG HalGetInterruptVector(INTERFACE_TYPE InterfaceType,
|
||||
ULONG BusNumber,
|
||||
ULONG BusInterruptLevel,
|
||||
ULONG BusInterruptVector,
|
||||
OUT PKIRQL Irql,
|
||||
OUT PKAFFINITY Affinity)
|
||||
|
||||
PURPOSE:
|
||||
|
||||
Translates a bus dependant interrupt vector to a system vector
|
||||
|
||||
ARGUMENTS:
|
||||
|
||||
InterfaceType = Type of bus to which the device to receive interrupts
|
||||
from is connected to. Currently only 'Internal' is
|
||||
recognized
|
||||
BusNumber = Number of the bus the device is connected to
|
||||
(currently ignored)
|
||||
BusInterruptLevel = Bus specific interrupt level (currently ignored)
|
||||
BusInterruptVector = Bus specific vector. Currently this is the same
|
||||
as the normal vector (09 is the keyboard vector
|
||||
for example)
|
||||
Irql = On return contains the DIRQL for the vector
|
||||
Affinity = On return contains the affinity mask for the vector
|
||||
(currently unimplemented)
|
||||
|
||||
RETURNS:
|
||||
The system mapped vector
|
||||
|
||||
* Call IoConnectInterrupt
|
||||
|
||||
PROTOTYPE:
|
||||
|
||||
NTSTATUS IoConnectInterrupt(OUT PKINTERRUPT* InterruptObject,
|
||||
PKSERVICE_ROUTINE ServiceRoutine,
|
||||
PVOID ServiceContext,
|
||||
PKSPIN_LOCK SpinLock,
|
||||
ULONG Vector,
|
||||
KIRQL Irql,
|
||||
KIRQL SynchronizeIrql,
|
||||
KINTERRUPT_MODE InterruptMode,
|
||||
BOOLEAN ShareVector,
|
||||
KAFFINITY ProcessorEnableMask,
|
||||
BOOLEAN FloatingSave)
|
||||
|
||||
PURPOSE:
|
||||
|
||||
Connect a service routine to an interrupt vector
|
||||
|
||||
ARGUMENTS:
|
||||
|
||||
InterruptObject = Points to an object describes the interrupt on
|
||||
return
|
||||
ServiceRoutine = Function to be called when the device interrupts
|
||||
ServiceContext = Parameters to be passed to the service routine
|
||||
SpinLock = Should be NULL
|
||||
Vector = System mapped vector returned from HalGetInterruptVector
|
||||
Irql = DIRQL returned from HalGetInterruptVector
|
||||
SynchronizeIrql = Should be the same as Irql
|
||||
InterruptMode = Device interrupt type (currently ignored)
|
||||
ShareVector = True if the interrupt vector can shared
|
||||
ProcessorEnableMask = Currently ignored
|
||||
FloatingSave = Should be false
|
||||
|
||||
RETURNS: Status
|
||||
|
||||
* Sample code for snarfing an interrupt vector
|
||||
|
||||
|
||||
void grab_my_irq()
|
||||
{
|
||||
ULONG MappedIrq;
|
||||
KIRQL Dirql;
|
||||
KAFFINITY Affinity;
|
||||
PKINTERRUPT IrqObject;
|
||||
|
||||
MappedIrq = HalGetInterruptVector(Internal,
|
||||
0,
|
||||
0,
|
||||
MY_VECTOR,
|
||||
&Dirql,
|
||||
&Affinity);
|
||||
IoConnectInterrupt(&IrqObject,
|
||||
my_irq_service_routine,
|
||||
my_context,
|
||||
NULL,
|
||||
MappedIrq,
|
||||
Dirql,
|
||||
Dirql,
|
||||
0,
|
||||
FALSE, // Not sharable
|
||||
Affinity,
|
||||
FALSE);
|
||||
}
|
||||
|
||||
** Designing an interrupt service routine
|
||||
|
||||
An interrupt service routine should have the following prototype
|
||||
|
||||
BOOLEAN my_irq_service_routine(PKINTERRUPT Interrupt,
|
||||
PVOID ServiceContext);
|
||||
|
||||
ARGUMENTS:
|
||||
|
||||
Interrupt = The same as the object returned from the
|
||||
IoConnectInterrupt
|
||||
ServiceContext = A user defined parameters
|
||||
(passed to IoConnectInterrupt)
|
||||
|
||||
RETURNS:
|
||||
|
||||
True if it handled the interrupt, false if it should be passed onto
|
||||
other devices sharing the same vector
|
||||
|
||||
NOTES:
|
||||
|
||||
While an isr is executing all devices of a lower or equal priority
|
||||
can't interrupt. For this reason it is important that an isr
|
||||
should complete in a short an interval as possible. The set of
|
||||
routines an isr can call is also restricted.
|
||||
|
||||
|
|
@ -1,21 +0,0 @@
|
|||
This document describes the state of a uniprocessor PC at each of the IRQ
|
||||
levels supported by the ReactOS kernel
|
||||
|
||||
PASSIVE_LEVEL: IF bit clear in the processor flags
|
||||
All irqs umasked at the PIC
|
||||
|
||||
APC_LEVEL: Unknown
|
||||
WAKE_LEVEL: Unknown
|
||||
|
||||
DISPATCH_LEVEL: IF bit clear in the processor flags
|
||||
All irqs umasked at the PIC
|
||||
Thread dispatching disabled
|
||||
|
||||
DIRQL (Device specific IRQ level):
|
||||
IF bit clear in the processor flags
|
||||
Device's irq and all lower priority irqs masked at the PIC
|
||||
Thread dispatching disabled
|
||||
|
||||
HIGH_LEVEL: IF bit set in the processor flags
|
||||
All irqs masked at the PIC
|
||||
Thread dispatching disabled
|
||||
|
|
@ -1,33 +0,0 @@
|
|||
** Introduction
|
||||
|
||||
This is (an incomplete) guide to writing device drivers (and other kernel
|
||||
extensions) for ReactOS.
|
||||
|
||||
** Setting up the build environment
|
||||
|
||||
Create a new subdirectory in the modules directory and copy one of the
|
||||
existing module makefiles into it. Customize the makefile to compile the
|
||||
source files for the module. Note: generally it is not necessary to specify
|
||||
the compiler or compiler flags to use.
|
||||
|
||||
** Initializing a module
|
||||
|
||||
On loading the kernel will call the module function
|
||||
|
||||
PROTOTYPE:
|
||||
|
||||
NTSTATUS ModuleEntry(PDRIVER_OBJECT DriverObject,
|
||||
PUNICODE_STRING RegistryPath)
|
||||
|
||||
PURPOSE:
|
||||
|
||||
Initializing the module
|
||||
|
||||
ARGUMENTS:
|
||||
|
||||
DriverObject = Pointer to an object describing the driver
|
||||
RegistryPath = Currently NULL
|
||||
|
||||
RETURNS:
|
||||
|
||||
STATUS_SUCCESS = If the module initialized successfully
|
||||
|
|
@ -1,16 +0,0 @@
|
|||
subject wstring.zip
|
||||
author Boudewijn Dekker
|
||||
date 06-06-98
|
||||
|
||||
|
||||
I wrote some inline wide character string functions. It are modified version
|
||||
of the ones in string.h. I added four more function nl stricmp, strnicmp,
|
||||
wcsicmp, and wcsnicmp. These are the case insensitive variants of
|
||||
strcmp, strncmp and wcscmp, wcsncmp. I tested all the functions but I
|
||||
would urge anyone to tested again. I removed an extern specifier
|
||||
__wcstok and strtok cause I it caused an compilation error when
|
||||
using strtok or wcstok. Please could someone see if this correct.
|
||||
I also used these string functions in lstring api functions.
|
||||
|
||||
|
||||
Boudewijn Dekker
|
||||
Loading…
Reference in a new issue