Intravision/reactos
1
0
Fork 0
mirror of https://github.com/reactos/reactos.git synced 2024-09-28 05:26:58 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add new documentation

Browse source 
svn path=/trunk/; revision=174
This commit is contained in:
David Welch 1999-01-17 17:17:09 +00:00
parent ed27871348
commit 512966336f
5 changed files with 888 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

22
reactos/doc/DIRS Normal file
View file

@ -0,0 +1,22 @@
DIRECTORIES
system : compiled versions of the various system components and
libraries
ntoskrnl : kernel source
ntoskrnl/hal : hardware abstraction layer source
ntoskrnl/mm : memory managment subsystem source
ntoskrnl/io : IO manager subsystem source
ntoskrnl/ke : kernel source
include : win32 headers
include/internal : kernel private header files
include/ntdll : system library private header files
include/kernel32 : system library private header files
include/ddk : header files for modules
lib/ntdll : NT dll source
lib/kernel32 : kernel32 source
doc : documentation
loaders/dos : DOS based loader
loaders/boot : boot loader
services : various services (device drivers, filesystems etc)
services/dd : device drivers
services/fs : file systems

130
reactos/doc/HACKING Normal file
View file

@ -0,0 +1,130 @@
* Introduction
Having successfully built ReactOS and been amazed by what it does, you're
now desperate to fill in some of the omissions, this document shows you how.
* Prerequisites
A working knowledge of NT driver development is useful for understanding the
kernel and some of its abstractions. The NT4 ddk is available for free
download from http://www.microsoft.com/hwdev/. The Windows 98 and Windows
2000 DDKs are also available but the NT4 one is the most useful. See
Legal Stuff below however.
There are a number of books on NT driver development, I would recommend
'Windows NT Device Driver Development' (http://www.osr.com/book/) since OSR
seem to know their stuff. There is only one book on NT filesystem
development 'Windows NT File System Internals'. Please don't buy any of
these books unless you need to, and can afford it.
These mailing lists and newsgroups are useful for NT internals related
questions,
ntfsd@atria.com, ntdev@atria.com
(subscribe by email to majordomo@atria.com)
comp.os.????
microsoft.public.????
* Style
There is no coding style used for ReactOS, however the following guidelines
make things easier
Include information at the top of a module about its purpose, contact
information for its programmer and any useful notes.
Include a comment by each non-trival function describing its arguments,
purpose and any other notes.
Update the documentation in this directory
These guidelines are an ideal, no one manages to implement them all the
time, straightforward working code is probably just as good.
* Debugging
Debugging kernel-mode code is tricky, these are some snippets
DbgPrint writes a message to the console using a printf style format
string. The DPRINT macro (defined in internal/debug.h) expands to
DbgPrint unless NDEBUG is defined, this is useful for having copious
output from a module only when a problem is being debugging. DPRINT
also prefixes the message with the file and line number to make it
easier to see where output is coming from. DbgPrint can be used at any
point including in interrupt handlers.
There are options in ntoskrnl/hal/x86/printk.c for copying DbgPrint
output to a serial device (parallel support should also be added). This
can be useful if a lot of output is being generated.
It should be possible to include support for debugging the kernel with
gdb over a serial line. Bochs (a shareware CPU emulator) is also useful
for debugging the kernel, I wrote some patches to allow capture of console
output from within bochs to file and for debugging a kernel running
under bochs with gdb. Contact me (welch@cwcom.net) if you're are
interested.
If CPU reports an exception not handled by the kernel (any page fault
not part of virtual memory support or any other exception) the kernel
will display output like this and halt
General Protection Fault Exception: 13(0)
CS:EIP xxxxxxxx:xxxxxxx
DS xxxx ES xxxx FS xxxx GS xxxxx
EAX: xxxx EBX: xxxx
....
EDI: xxxx EFLAGS: xxxx ESP: xxxx
cr2: xxxx
Stack: xxxx xxxx xxxx ...
....
Frames: xxxx xxxx xxxx ...
....
The fault type will usually be either 'General Protection' or
'Page Fault', see your Intel manual for the more exotic types. The
'EIP' number is the address of the faulting instruction. If the 'CS'
number is 0x20 then the exception occured in kernel mode, if it is 0x11
then the exception occurred in user mode. 'cr2' is the address that the
faulting instruction was trying to access, if the exception was a page
fault. The number printed after 'Frames' are any addresses on the stack
that look like function addresses.
If the kernel detects a serious problem that it will bug check, displaying
output like this
Bug detected (code x, param x x x x)
Frames: xxx xxxx xxxx
....
Again the numbers printed after 'Frames' are any addresses on the stack
that look like function addresss. Usually the kernel will also print a
message describing the problem in more detail, the bug check code isn't
very useful at the moment.
* Contacts
There is a mailing list for kernel development,
ros-kernel@sid-dis.com
The main developers use a cvs account to coordinate changes, ask
rex (rex@lvcablemodem.com) for an account if you are going to be adding
a lot of code. Smaller patches can go to the mailing list or to the
relevant developer (usually the comment at the top of a module will have
an email address). Regular snapshots are made available for download,
see the mailing list for announcements.
* Legal stuff
The ReactOS project is GPL'ed, please make sure any code submitted is
compatible with this.
The NT4 ddk license agreement allows its usage for developing nt drivers
only. Legally therefore it can not be used to develop ReactOS, neither the
documentation or the sample code. I'm not a lawyer, but I doubt the
effiacy of 'shrinkwrap licenses' particularly on freely downloadable
software. The only precendent I know of, in a Scottish court, didn't
upload this type of license.
Also the 'fair use' section of copyright law allows the 'quoting' of small
sections from copyrighted documents, e.g. Windows API or DDK documentation

6
reactos/doc/INDEX Normal file
View file

@ -0,0 +1,6 @@
HACKING: Some notes for adding code to ReactOS
DIRS: Explanation of directory layout
INTERNALS: Some notes on kernel internals
TODO: Bugs and omissions, big and little things that need to be done
NOTES: Unsorted material, some of it is redundant
BUGLIST: Known bugs, please update when you find one

43
reactos/doc/INTERNALS Normal file
View file

@ -0,0 +1,43 @@
A collection of articles on kernel internals, please add to this
------------------------------------------------------------------------------
IRQ level
------------------------------------------------------------------------------
IRQ level (IRQL) is a per-processor state in ReactOS used to coordinate
execution between ISRs and between threads. There are several levels
PASSIVE_LEVEL, APC_LEVEL: The normal level for user mode and most
kernel mode code. At the moment APC_LEVEL is unused.
DISPATCH_LEVEL: At this level all irqs are still allowed but thread
rescheduling on the current processor is disabled. This is used by
the spinlock synchronization primitive to implement its uniprocessor
semantics (multiprocessor is more complex). It is also used for some
other forms of synchronization, DPCs for example. Many APIs are
unavailable at this IRQL, usually those that might have to wait. It
is recommended that you don't spend too much time at this IRQL
otherwise system responsiveness will be reduced.
> DISPATCH_LEVEL: Each irq is assigned a priority (which will be
greater than DISPATCH_LEVEL). At an irq's priority level that irq,
lower priority irqs and thread rescheduling are disabled. Higher
priority irqs can still run. Very few APIs are available at IRQLs
greater than DISPATCH_LEVEL.
HIGH_LEVEL: All irqs are disabled.
-------------------------------------------------------------------------------
DPCs
-------------------------------------------------------------------------------
It is a design goal not to spend too much time in ISRs, for this reason
ISRs should postpone most processing till it can run at a lower IRQL. The
mechanism for this is a Delayed Procedure Call (DPC). When a DPC object is
created, it is associated with a function. The DPC object can then be inserted
in the DPC queue from an ISR. If the IRQL on return from the ISR is less than
DISPATCH_LEVEL the DPC queue will be drained, otherwise this will happen when
the IRQL level drops below DISPATCH_LEVEL or the processor becomes idle. When
the DPC queue is drained each DPC object is removed and the associated
function is called at DISPATCH_LEVEL. A DPC object can only be inserted once,
further insertions before it is removed will have no effect.

687
reactos/doc/notes Normal file
View file

@ -0,0 +1,687 @@
*** This file contains messages I've culled off the net as well
as previous discussions all of which have useful info on fixes
that need to be added to ReactOS. messages are between five
dashes on a line by themselves. If you implement the fix
reffered to in a message, feel free to delete it from the file.
Rex ***
-----
Yes with DPCs, KeDrainDpcQueue should go to HIGH_LEVEL because
it needs to synchronize with KeInsertDpcQueue. Also the idle thread
should run at DISPATCH_LEVEL and regularly drain the dpc queue, that
way if an irq happens and the dpc can't be executed immediately it
will be executed as soon as the processor is idle rather than
waiting for the next timer tick
-----
About the console driver, I think it might be quite useful to have a simple
way for apps to print to the screen for debugging. But when the kernel is more
stable, console handling should be moved to user level because console printing
needs to know about windows and so on which can only be done at user level.
-----
Subject: Re: IMSAMP-how to avoid rebooting?
Date: 9 Nov 1998 00:40:32 -0000
From: Charles Bryant <n51190709.ch@chch.demon.co.uk>
Newsgroups: comp.os.ms-windows.programmer.nt.kernel-mode
References: 1, 2 , 3 , 4
In article <un264wzle.fsf@xxx.yyy.zzz>, David C. <qqqq@xxx.yyy.zzz> wrote:
>The reason it won't unload when something is bound to it is the same
>reason you can't unload any other driver that has an open client. If
>you install any driver, and have a user program (or another driver) open
>a handle to it, and then give the "net stop" command to unload it,
>you'll find that the unload will be delayed until the user program
>closes its handle.
When developing a driver I found this to be a considerable nuisance.
Frequently a bug would leave an IRP stuck in the driver and I
couldn't unload and reload a fixed version. While reading NTDDK.H I
found a suspicious constant and discovered that the Flags field in
the device (the one which you OR in DO_BUFFERED_IO or DO_DIRECT_IO)
has a bit called DO_UNLOAD_PENDING. By experiment I confirmed that
this bit is set when you do 'net stop', so a driver can check it
periodically (e.g. from a timer DPC every ten seconds) and cancel all
queued IRPs if it is found to be set.
Since this is not documented anywhere that I can find, it might be
unwise to rely on it for production code, but it is very useful for
debugging. Maybe someone with internals knowledge can comment on the
reliability of it.
-----
Subject: Re: Kernel bugs
Date: Fri, 23 Oct 1998 12:08:36 -0700
From: rex <rex@lvcablemodem.com>
To: Jason Filby <jasonfilby@yahoo.com>
References: 1
Jason Filby wrote:
> Hi,
>
> Ok -- here's most of what I get when I press a key:
>
> Page fault detected at address 1fd4 with eip c042f794
> Recursive page fault detected
> Exception 14(2)
> CS:EIP 20:c042f794
>
> Rex -- do you know of anyway to find out which function in what file
> is causing the exception? I know that for problems in the kernel, you
> just look in the ntoskrnl\kernel.sym file and find the EIP value which
> matches the one given in the exception debug text. But what about
> modules? How can we track exceptions that occur in functions in modules?
>
I know this is a little belated, but I thought I'd take astab at answering
this anyway. add an option to the
makefile for the module to generate a listing file with
symbol information. Then, on a boot test, note the
address that the module is loaded at, and subtract
this from the EIP value. add any offset used in the
module link specification (I dont think there currently
is one), and look for the last symbol with a lower
address offset.
Brian, I have an idea on how to make this exception
dump information a little more useful. We should
have the load information for the load modules
in memory somewhere. Perhaps the exception
dump could check offending addresses to see if
they lie in the kernel or in a module, and if they
lie in a module the proper offset could be subtracted
and this number could be displayed seperately. If
I get a chance today, I'll make this change and send
it to ya.
Rex.
-----
Subject: [ros-kernel] Pet peeve of the week
Resent-Date: Sun, 25 Oct 1998 11:57:40 -0600
Resent-From: ros-kernel@sid-dis.com
Date: Sun, 25 Oct 1998 09:53:48 -0800
From: rex <rex@lvcablemodem.com>
Reply-To: <ros-kernel@sid-dis.com>
To: ReactOS Kernel Forum <ros-kernel@sid-dis.com>
Hi all,
I guess it's about time to start another mailstorm
on the list. :)
I have a suggestion for a change to the kernel.
It not a very big change, and I hope everyone
will agree that it makes sense.
There is a structure used in many places in the
kernel called LARGE_INTEGER. the is also
a version called ULARGE_INTEGER, but it
is not used at all as far as I can tell. this structure
is equivalent to a long long int. You can literally
cast a pointer to a LARGE_INTEGER to a
long long int and all manipulation will work
seemlessly. My suggestion is that we replace the
use of this structure with long long ints. Even
microsoft, in their infinite wisdom, has made this
suggestion in the DDK documentation. If you're
wondering where, look at the RTL functions
that manipulate LARGE_INTEGER structs.
Replacing LI's with long long ints will work
because they are binary compatable. All software
compiled to use LI's will manipulate long long ints
correctly and vice versa. There is one problem
with this suggestion: the LARGE_INTEGER type
is a structure containing 2 members. Any code
that accesses the structure by members will break.
I think the kernel side impact is minimal, and is
worth the change. However, the structure is used
in several of the Win32 API functions, and needs
to remain there. I think we build a conditionally
compiled version of the LARGE_INTEGER type.
In kernel mode code (the kernel proper and drivers)
the LARGE INTEGER will be the following:
typedef long long int LARGE_INTEGER,
*PLARGE_INTEGER;
typedef unsigned long long int ULARGE_INTEGER,
*PULARGE_INTEGER;
and in user mode code it will expand out to the
current definition (which by the way, is not
strictly correct, but can't be because it uses a
MS compiler extension).
Brian, I would be willing to make the conversion
to those kernel modules that needed it, and of
course to the IDE driver if we want to go forward
with the change.
Lastly, I'll mention what made me consider this.
I was fixing the timer routines, and two of the
three problems turned out to be related to LI
conversion problems.
Rex.
-----
Subject: Re: [ros-kernel] Pet peeve of the week
Date: Thu, 29 Oct 1998 19:10:37 +0100
From: Boudewijn <ariadne@xs4all.nl>
To: rex@lvcablemodem.com
References: 1
Hai Rex
I think it is a good idea to wrap a makro around the member access
to large integers.
I haven't tested this, but do you think this is a good sugestion ?
#ifdef COMPILER_LARGE_INTEGERS
#define GET_LARGE_INTEGER_HIGH_PART(LargeInteger) ( ( LargeInteger >>
32) )
#define GET_LARGE_INTEGER_LOW_PART(LargeInteger) ( (LargeInteger &
0xFFFFFFFF) )
#define SET_LARGE_INTEGER_HIGH_PART(LargeInteger,Signed_Long) (
LargeInteger |= ( ((LARGE_INTEGER)Signed_Long) << 32 ) )
#define SET_LARGE_INTEGER_LOW_PART(LargeInteger,Unsigned_Long) (
LargeInteger |= Unsigned_Long )
#else
#define GET_LARGE_INTEGER_HIGH_PART(LargeInteger) ( (
LargeInteger.HighPart) )
#define GET_LARGE_INTEGER_LOW_PART(LargeInteger) (
(LargeInteger.LowPart) )
#define SET_LARGE_INTEGER_HIGH_PART(LargeInteger,Signed_Long) (
LargeInteger.HighPart= Signed_Long )
#define SET_LARGE_INTEGER_LOW_PART(LargeInteger,Unsigned_Long) (
LargeInteger.LowPart = Unsigned_Long )
#endif
Boudewijn
-----
Subject: Re: Question on "Sending buffers on the stack to asynchronous DeviceIoControl with buffered I/O"
Date: Mon, 16 Nov 1998 11:24:57 -0800
From: "-Paul" <paulsan@microsoftSPAM.com>
Organization: Microsoft Corp.
Newsgroups: microsoft.public.win32.programmer.kernel, comp.os.ms-windows.programmer.nt.kernel-mode
References: 1
Radu, I post the following information occassionally for questions such as
yours. I hope it helps.
-Paul
Here is an explanation of buffers and DeviceIoControl.
First, here are the parameters,
BOOL DeviceIoControl(
HANDLE hDevice, // handle to device of interest
DWORD dwIoControlCode, // control code of operation to perform
LPVOID lpInBuffer, // pointer to buffer to supply input data
DWORD nInBufferSize, // size of input buffer
LPVOID lpOutBuffer, // pointer to buffer to receive output data
DWORD nOutBufferSize, // size of output buffer
LPDWORD lpBytesReturned, // pointer to variable to receive output byte
count
LPOVERLAPPED lpOverlapped // pointer to overlapped structure for
asynchronous operation
);
METHOD_BUFFERED
user-mode perspective
lpInBuffer - optional, contains data that is written to the driver
lpOutBuffer - optional, contains data that is read from the driver after
the call has completed
lpInBuffer and lpOutBuffer can be two buffers or a single shared buffer.
If a shared buffer, lpInBuffer is overwritten by lpOutBuffer.
I/O Manager perspective
examines nInBufferSize and nOutBufferSize. Allocates memory from non-paged
pool and puts the address of this pool in Irp->AssociatedIrp.SystemBuffer.
The size of this buffer is equal to the size of the larger of the two
bufferes. This buffer is accessible at any IRQL.
copies nInBufferSize to irpSp->Parameters.DeviceIoControl.InputBufferLength
copies nOutBufferSize to
irpSp->Parameters.DeviceIoControl.OutputBufferLength
copies contents of lpInBuffer to SystemBuffer allocated above
calls your driver
Device Driver perspective
you have one buffer, Irp->AssociatedIrp.SystemBuffer. You read input data
from this buffer and you write output data to the same buffer, overwriting
the input data.
Before calling IoCompleteRequest, you must
- set IoStatus.Status to an approriate NtStatus
- if IoStatus.Status == STATUS_SUCCESS
set IoStatus.Information to the
number of bytes you want copied
from the SystemBuffer back into
lpOutBuffer.
I/O Manager Completion Routine perspective
looks at IoStatus block, if IoStatus.Status = STATUS_SUCCESS, copies the
number of bytes specified by IoStatus.Information from
Irp->AssociatedIrp.SystemBuffer into lpOutBuffer
completes the request
METHOD_IN_DIRECT
user-mode perspective
lpInBuffer - optional, contains data that is written to the driver. This
buffer is used in the exact same fashion as METHOD_BUFFERED. To avoid
confusion, mentally rename this buffer to lpControlBuffer. This is
typically a small, optional buffer that might contain a control structure
with useful information for the device driver. This buffer is smal and is
double buffered.
lpOutBuffer - NOT OPTIONAL, This LARGE buffer contains data that is read by
the driver. To avoid confusion, mentally rename this buffer to
lpDataTransferBuffer. This is physically the same buffer that the device
driver will read from. There is no double buffering. Technically, this
buffer is still optional, but since you are using this buffering method,
what would be the point???
I/O Manager perspective
If lpInBuffer exists, allocates memory from non-paged pool and puts the
address of this pool in Irp->AssociatedIrp.SystemBuffer. This buffer is
accessible at any IRQL.
copies nInBufferSize to irpSp->Parameters.DeviceIoControl.InputBufferLength
copies nOutBufferSize to
irpSp->Parameters.DeviceIoControl.OutputBufferLength
copies contents of lpInBuffer to SystemBuffer allocated above
So far this is completely identical to METHOD_BUFFERED. Most likely
lpInBuffer (mentally renamed to lpControlBuffer) is very small in size.
For lpOutBuffer (mentally renamed to lpDataTransferBuffer), an MDL is
allocated. lpOutBuffer is probed and locked into memory. Then, the user
buffer virtual addresses are checked to be sure they are readable in the
caller's access mode.
The MDL is address is stored in Irp->MdlAddress.
Your driver is called.
Device Driver perspective
The device driver can read the copy of lpOutBuffer via
Irp->AssociatedIrp.SystemBuffer. Anything written by the device driver to
this buffer is lost. The I/O Manager does not copy any data back to the
user-mode buffers as it did in the completion routine for METHOD_BUFFERED.
Art Baker's book is wrong in this respect (page 168, "data going from the
driver back to the caller is passed through an intermediate system-space
buffer" and page 177, "When the IOCTL IRP is completed, the contents of the
system buffer will be copied back into the callers original output buffer".
The device driver accesses the Win32 buffer directly via Irp->MdlAddress.
The driver uses whatever Mdl API's to read the buffer. Usually, this
buffer is to be written to some mass storage media or some similar
operation. Since this is a large data transfer, assume a completion
routine is required.
mark the Irp pending
queue it
return status pending
Device Driver Completion Routine perspective
standard completion routine operations
set IoStatus.Status to an approriate NtStatus
IoStatus.Information is not needed
completete the request
I/O Manager Completion Routine perspective
standard I/O Manager completion routine operations
unmap the pages
deallocate the Mdl
complete the request
METHOD_OUT_DIRECT
user-mode perspective
lpInBuffer - optional, contains data that is written to the driver. This
buffer is used in the exact same fashion as METHOD_BUFFERED. To avoid
confusion, mentally rename this buffer to lpControlBuffer. This is
typically a small, optional buffer that might contain a control structure
with useful information for the device driver. This buffer is smal and is
double buffered.
lpOutBuffer - NOT OPTIONAL, This LARGE buffer contains data that is written
by the driver and read by the wer-mode application when the request is
completed. To avoid confusion, mentally rename this buffer to
lpDataTransferBuffer. This is physically the same buffer that the device
driver will write to. There is no double buffering. Technically, this
buffer is still optional, but since you are using this buffering method,
what would be the point???
I/O Manager perspective
If lpInBuffer exists, allocates memory from non-paged pool and puts the
address of this pool in Irp->AssociatedIrp.SystemBuffer. This buffer is
accessible at any IRQL.
copies nInBufferSize to irpSp->Parameters.DeviceIoControl.InputBufferLength
copies nOutBufferSize to
irpSp->Parameters.DeviceIoControl.OutputBufferLength
copies contents of lpInBuffer to SystemBuffer allocated above
So far this is completely identical to METHOD_BUFFERED. Most likely
lpInBuffer (mentally renamed to lpControlBuffer) is very small in size.
For lpOutBuffer (mentally renamed to lpDataTransferBuffer), an MDL is
allocated. lpOutBuffer is probed and locked into memory. Then the user
buffer's addresses are checked to make sure the caller could write to them
in the caller's access mode.
The MDL is address is stored in Irp->MdlAddress.
Your driver is called.
Device Driver perspective
The device driver can read the copy of lpOutBuffer via
Irp->AssociatedIrp.SystemBuffer. Anything written by the device driver to
this buffer is lost.
The device driver accesses the Win32 buffer directly via Irp->MdlAddress.
The driver uses whatever Mdl API's to write data to the buffer. Usually,
this buffer is to be read from some mass storage media or some similar
operation. Since this is a large data transfer, assume a completion
routine is required.
mark the Irp pending
queue it
return status pending
Device Driver Completion Routine perspective
standard completion routine operations
set IoStatus.Status to an approriate NtStatus
IoStatus.Information is not needed
completete the request
I/O Manager Completion Routine perspective
standard I/O Manager completion routine operations
unmap the pages
deallocate the Mdl
complete the request
METHOD_NEITHER
I/O Manager perspective
Irp->UserBuffer = lpOutputBuffer;
IrpSp->Parameters.DeviceIoControl.Type3InputBuffer = lpInputBuffer;
No comments here. Don't use METHOD_DIRECT unless you know what you are
doing. Simple rule.
If your IOCtl involves no data transfer buffers, then METHOD_NEITHER is the
fastest path through the I/O Manager that involves an Irp.
Final Comment
Don't touch Irp->UserBuffer. This is a bookmark for the I/O Manager. Two
major problems can occur. 1 - page fault at high IRQL, or 2 - you write
something to Irp->UserBuffer and the I/O Manager overwrites you in its
completion routine. File systems access Irp->UserBuffer, but FSD writers
know all of the above and know when it is safe to touch Irp->UserBuffer.
Radu Woinaroski wrote in message <364F8F6E.2434B010@scitec.com.au>...
>Hello,
>
>I have a kernel-mode device driver that accepts a number of IoControl
>commands that use buffered data transfer (METHOD_BUFFERED).
>
>A user mode API provides a higher level access then the DeviceIoControl
>function.
>
>The function is implemented like that
>
>BOOL
Something(
> HANDLE hDevice ,
> int param1,
> int param2,
> DWORD * pReturn,
> LPOVERLAPPED pOverlapped)
>{
> // here a data buffer on the stack sent to asynchronous DeviceIoControl
>call
> int aDataIn[2];
> aDataIn[0] = param1;
> aDataIn[1] = param2;
>
> return DeviceIoControl(
> hDevice,
> DO_SOMETHING_IO,
> aDataIn,
> sizeof(int)*2,
> pReturn,
> sizeof(DWORD),
> pOverlapped);
>}
>
>The aDataIn buffer will not exist after DeviceIoControl returns (and
>when the I/O operation terminates). I know that for buffered IO the
>input data buffer is copyed by de IOManager to a nonpaged-pool area
>before passing the request to driver dispatch routine (DeviceControl).
>At the point of calling the dispatch routine (DeviceControl) the driver
>runs in the context of the calling thread so DeviceIoControl hasn't
>returned yet (?? or so I think) so aDataI
n will still be valid at the
>time IOManager copyes it to its buffer. So, this apears to work ok (at
>least in my opinion).
>
>Does I/O Manager use the Input buffer from the call to the Win32
>DeviceIoControl any where else after the first copy ?
>
>Is there any reason why this approach (passing a buffer on the stack to
>a asynchronous DeviceIoControl that uses buffered I/O) wouldn't work ?
>
>Allocating buffers from heap and deleting them on IO completion while
>managing asynchronous IO seems too much work ;-) .
>
>Thanks in advance for your opinions
>Radu W.
>
>--
>Radu Woinaroski
>Scitec
>Sydney, Australia
>Radu.Woinaroski@scitec.com.au
-----
Subject: Re: PCI ISR problem
Date: Fri, 20 Nov 1998 18:04:48 GMT
From: jeh@cmkrnl.com (Jamie Hanrahan)
Organization: Kernel Mode Systems, San Diego, CA
Newsgroups: comp.os.ms-windows.programmer.nt.kernel-mode
References: 1
On Thu, 19 Nov 1998 15:46:13 -0600, Eric Gardiner
<eric.gardiner@natinst.com> wrote:
>I'm having problems with NT4 not hooking the interrupt line indicated by
>a PCI device. Here's what I'm doing:
>
>1) Enumerating the PCI buses on the system (using HalGetBusData) until
>I find my device.
>2) Once my device is found, I read the "Interrupt Line Register" in the
>device's PCI config space to determine what interrupt level to pass to
>HalGetInterruptVector.
Whups! No. Call HalAssignSlotResources and look at the returned
CM_RESOURCE_LIST to find the vector, level, port addresses, etc., for
your device. (Then pass the returned CM_RESOURCE_LIST to ExFreePool.)
See Knowledge Base article Q152044.
--- Jamie Hanrahan, Kernel Mode Systems, San Diego CA (jeh@cmkrnl.com)
Drivers, internals, networks, applications, and training for VMS and Windows NT
NT kernel driver FAQ, links, and other information: http://www.cmkrnl.com/
Please post replies, followups, questions, etc., in news, not via e-mail.
-----
Subject: Re: IRP canceling
Date: Mon, 23 Nov 1998 09:05:47 -0500
From: Walter Oney <waltoney@oneysoft.com>
Organization: Walter Oney Software
Newsgroups: comp.os.ms-windows.programmer.nt.kernel-mode
References: 1
Seol,Keun Seok wrote:
> But, if the IRP was the CurrentIrp of the Device Object,
> the Driver's Start I/O routine will try to process the IRP.
> In the DDK help, the Start I/O routine MUST check the current IRP's
> Cancel bit.
> If set, Start I/O routine must just return.
>
> But I think that the IRP already completed should not be accessed.
You're absolutely right. I recommend the following code in a standard
StartIo routine to avoid the problem you point out:
VOID StartIo(PDEVICE_OBJECT DeviceObject, PIRP Irp)
{
KIRQL oldirql;
IoAcquireCancelSpinLock(&oldirql);
if (Irp != DeviceObject->CurrentIrp || Irp->Cancel)
{
IoReleaseCancelSpinLock(oldirql);
return;
}
else
{
IoSetCancelRoutine(Irp, NULL);
IoReleaseCancelSpinLock(oldirql);
}
. . .
}
This dovetails with a standard cancel routine:
VOID CancelRoutine(PDEVICE_OBJECT DeviceObject, PIRP Irp)
{
if (DeviceObject->CurrentIrp == Irp)
{
IoReleaseCancelSpinLock(Irp->CancelIrql);
IoStartNextPacket(DeviceObject, TRUE);
}
else
{
KeRemoveEntryDeviceQueue(&DeviceObject->DeviceQueue,
&Irp->Tail.Overlay.DeviceQueueEntry);
IoReleaseCancelSpinLock(Irp->CancelIrql);
}
Irp->IoStatus.Status = STATUS_CANCELLED;
Irp->IoStatus.Information = 0;
IoCompleteRequest(Irp, IO_NO_INCREMENT);
}
You need to remember that the C language specification requires that
evaluation of boolean operators short circuit when the result is known.
So, if StartIo discovers that the Irp it got as an argument is not the
same as CurrentIrp, it will not attempt to evaulate Irp->Cancel.
Now, as to why this works: StartIo gets called either by IoStartPacket
or IoStartNextPacket. Each of them will grab the cancel spin lock and
set CurrentIrp, then release the spin lock and call StartIo. If someone
should sneak in on another CPU and cancel this very same IRP, your
cancel routine will immediately release the spin lock and call
IoStartNextPacket. One of two things will then happen. IoStartNextPacket
may succeed in getting the cancel spin lock, whereupon it will nullify
the CurrentIrp pointer. If another IRP is on the queue, it will remove
it from the queue, set CurrentIrp to point to this *new* IRP, release
the spin lock, and call StartIo. [You now have two instances of StartIo
running on two different CPUs for two different IRPs, but it's not a
problem because they won't be able to interfere with each other.]
Meanwhile, your original instance of StartIo gets the cancel spin lock
and sees that CurrentIrp is not equal to the IRP pointer it got as an
argument, so it gives up.
The second way this could play out is that StartIo gets the cancel lock
before IoStartNextPacket does. In this case, CurrentIrp is still
pointing to the IRP that's in the process of being cancelled and that
StartIo got as an argument. But this IRP hasn't been completed yet (the
CPU that's running your cancel routine is spinning inside
IoStartNextPacket and therefore hasn't gotten to calling
IoCompleteRequest yet), so no-one will have been able to call IoFreeIrp
to make your pointer invalid.
People may tell you that you should be using your own queues for IRPs so
you can avoid bottlenecking the system on the global cancel spin lock.
That's true enough, but doing it correctly with Plug and Play and Power
management things in the way is gigantically complicated. There's a
sample in the NT 5 beta-2 DDK called CANCEL that shows how to manage
your own queue if you don't worry about PNP and POWER. I hear tell of an
upcoming MSJ article by a Microsoft developer that may solve the
complete problem.
-----
Subject: ANNOUNCE: ALINK v1.5
Date: 16 Nov 1998 16:36:05 GMT
From: anthony_w@my-dejanews.com
Organization: Deja News - The Leader in Internet Discussion
Newsgroups: comp.os.ms-windows.programmer.win32, comp.lang.asm.x86, comp.os.msdos.programmer
ALINK is a freeware linker, creating MSDOS COM and EXE files and Win32 PE EXE
and DLL files from OMF format OBJ and LIB files, win32-COFF format OBJ files,
and win32 RES files.
NEW for version 1.5:
Win32 COFF object file support.
Download it now from my home page.
Anthony
--
anthony_w@geocities.com
http://www.geocities.com/SiliconValley/Network/4311/index.html
-----------== Posted via Deja News, The Discussion Network ==----------
http://www.dejanews.com/ Search, Read, Discuss, or Start Your Own
-----