IoCallDriver doc is wrong and function returns undocumented status

According to the documentation for the IoCallDriver function, it is supposed
to return either the NTSTATUS value the lower driver set in the I/O Status
Block or STATUS_PENDING.

However, I have a case where the lower driver is clearly setting the
NTSTATUS in the I/O Status Block to STATUS_SUCCESS, yet the IoCallDriver
function is returning a STATUS_WAIT_2 !!!!!!!!!

Better yet, there is absolutely NO documentation on what the heck a
STATUS_WAIT_2 even means!!!!!!!!!!!!!!!!!!!!!!!!

Does anyone out there know what a STATUS_WAIT_0, STATUS_WAIT_1,
STATUS_WAIT_2, or STATUS_WAIT_3 means?

Anyone have any idea why the IoCallDriver function decides it knows better
than the underlying driver and changes the return status from what the
driver attempted to return?

Bill
Tue Dec 09 11:39:02 CST 2003

This is a DriverVerifier status. DriverVerifier is checking to make sure
you are not altering an IRP's completion status where you ought not be
altering it. This should not cause you any problems unless you are doing
something wrong, or depending upon something you ought not be depending on.

--
Bill McKenzie
Compuware Corporation
Watch your IRPs/IRBs/URBs/SRBs/NDIS pkts with our free WDMSniffer tool:
http://frontline.compuware.com/nashua/patches/utility.htm


"Del Fredricks" <im.sick.of.spam@ask.i.might.tell> wrote in message
news:#W8MgdnvDHA.2444@TK2MSFTNGP12.phx.gbl...
> According to the documentation for the IoCallDriver function, it is
supposed
> to return either the NTSTATUS value the lower driver set in the I/O Status
> Block or STATUS_PENDING.
>
> However, I have a case where the lower driver is clearly setting the
> NTSTATUS in the I/O Status Block to STATUS_SUCCESS, yet the IoCallDriver
> function is returning a STATUS_WAIT_2 !!!!!!!!!
>
> Better yet, there is absolutely NO documentation on what the heck a
> STATUS_WAIT_2 even means!!!!!!!!!!!!!!!!!!!!!!!!
>
> Does anyone out there know what a STATUS_WAIT_0, STATUS_WAIT_1,
> STATUS_WAIT_2, or STATUS_WAIT_3 means?
>
> Anyone have any idea why the IoCallDriver function decides it knows better
> than the underlying driver and changes the return status from what the
> driver attempted to return?
>
>

Ray
Tue Dec 09 11:46:50 CST 2003

It looks to me like the documentation is wrong (except by convention).
As far as I understand (and slide 19 of Adrian Oney's "Irp Voodoo"
WinHEC 2003 presentation seems to corroborate this), IoCallDriver
returns whatever value was *returned* by the lower level driver from
it's dispatch routine.

This is *supposed* to always be the same as what they set in the I/O
status block, but again, that's just a convention. I will say, though,
that I didn't actually go and write a test driver to experimentally
prove this assertion, so I might be wrong :-).

So, I think there are likely to be roughly 3 major possible sources of
this behavior (nothing like a definite maybe :-):

1) the lower level driver is returning the wrong value from its dispatch
routine.
2) your driver isn't looking in the right place of the I/O status block.
3) a stack corruption bug of some sort has occurred that is of a nature
that doesn't cause a blue-screen.

STATUS_WAIT_2 has the actual *value* 2, which seems like a reasonably
likely incorrect return value or stack corruption value, so I can't
really guess what the most likely cause might be.

Try stepping through in the debugger :-)...

Del Fredricks wrote:

> According to the documentation for the IoCallDriver function, it is supposed
> to return either the NTSTATUS value the lower driver set in the I/O Status
> Block or STATUS_PENDING.
>
> However, I have a case where the lower driver is clearly setting the
> NTSTATUS in the I/O Status Block to STATUS_SUCCESS, yet the IoCallDriver
> function is returning a STATUS_WAIT_2 !!!!!!!!!
>
> Better yet, there is absolutely NO documentation on what the heck a
> STATUS_WAIT_2 even means!!!!!!!!!!!!!!!!!!!!!!!!
>
> Does anyone out there know what a STATUS_WAIT_0, STATUS_WAIT_1,
> STATUS_WAIT_2, or STATUS_WAIT_3 means?
>
> Anyone have any idea why the IoCallDriver function decides it knows better
> than the underlying driver and changes the return status from what the
> driver attempted to return?
>
>

--
../ray\..

Ray
Tue Dec 09 12:02:37 CST 2003

Wow... you learn something new every day. Is this documented anywhere? I
hate to think of how many drivers out there might be doing something
equivalent to:

status = IoCallDriver(...)
if (status == STATUS_SUCCESS) { // yes you're supposed to use NT_SUCCESS
// Do something significant, but not obvious
}

Bill McKenzie wrote:

> This is a DriverVerifier status. DriverVerifier is checking to make sure
> you are not altering an IRP's completion status where you ought not be
> altering it. This should not cause you any problems unless you are doing
> something wrong, or depending upon something you ought not be depending on.
>
> --
> Bill McKenzie
> Compuware Corporation
> Watch your IRPs/IRBs/URBs/SRBs/NDIS pkts with our free WDMSniffer tool:
> http://frontline.compuware.com/nashua/patches/utility.htm
>
>
> "Del Fredricks" <im.sick.of.spam@ask.i.might.tell> wrote in message
> news:#W8MgdnvDHA.2444@TK2MSFTNGP12.phx.gbl...
>
>>According to the documentation for the IoCallDriver function, it is
>
> supposed
>
>>to return either the NTSTATUS value the lower driver set in the I/O Status
>>Block or STATUS_PENDING.
>>
>>However, I have a case where the lower driver is clearly setting the
>>NTSTATUS in the I/O Status Block to STATUS_SUCCESS, yet the IoCallDriver
>>function is returning a STATUS_WAIT_2 !!!!!!!!!
>>
>>Better yet, there is absolutely NO documentation on what the heck a
>>STATUS_WAIT_2 even means!!!!!!!!!!!!!!!!!!!!!!!!
>>
>>Does anyone out there know what a STATUS_WAIT_0, STATUS_WAIT_1,
>>STATUS_WAIT_2, or STATUS_WAIT_3 means?
>>
>>Anyone have any idea why the IoCallDriver function decides it knows better
>>than the underlying driver and changes the return status from what the
>>driver attempted to return?
>>
>>
>
>
>

--
../ray\..

Del
Tue Dec 09 12:19:51 CST 2003

See below:

"Ray Trent" <rat@synaptics.com.spamblock> wrote in message
news:%23vK8txnvDHA.2880@tk2msftngp13.phx.gbl...
> It looks to me like the documentation is wrong (except by convention).
> As far as I understand (and slide 19 of Adrian Oney's "Irp Voodoo"
> WinHEC 2003 presentation seems to corroborate this), IoCallDriver
> returns whatever value was *returned* by the lower level driver from
> it's dispatch routine.
>

Yes, in fact Driver Verifier WILL bugcheck if it does not.

>
> This is *supposed* to always be the same as what they set in the I/O
> status block, but again, that's just a convention. I will say, though,
> that I didn't actually go and write a test driver to experimentally
> prove this assertion, so I might be wrong :-).
>
> So, I think there are likely to be roughly 3 major possible sources of
> this behavior (nothing like a definite maybe :-):
>
> 1) the lower level driver is returning the wrong value from its dispatch
> routine.
>

No, I single stepped through the lower driver and the IRP status is set to
the return status (actual code is "return IRP->IoStatus.Status" just to be
safe) both of which are STATUS_SUCCESS.

>
> 2) your driver isn't looking in the right place of the I/O status block.
>

My driver is not looking at the I/O Status block, because the lower level
driver completes the IRP. It is looking at the return status from the
IoCallDriver function call.

>
> 3) a stack corruption bug of some sort has occurred that is of a nature
> that doesn't cause a blue-screen.
>
> STATUS_WAIT_2 has the actual *value* 2, which seems like a reasonably
> likely incorrect return value or stack corruption value, so I can't
> really guess what the most likely cause might be.
>
> Try stepping through in the debugger :-)...
>

Already did that, that's how I verified that the values in the debug prints
were valid.

Scott
Tue Dec 09 12:20:40 CST 2003

> Does anyone out there know what a STATUS_WAIT_0, STATUS_WAIT_1,
> STATUS_WAIT_2, or STATUS_WAIT_3 means?

The STATUS_WAIT_X values are documented with KeWaitForMultipleObjects.
You'll only get them if you specify WaitAny, and the _X indicates which
object in the passed in array satisfied the wait (they map to WAIT_OBJECT_X
in UM)

-scott

--
Scott Noone
Software Engineer
OSR Open Systems Resources, Inc.
http://www.osronline.com

Del
Tue Dec 09 12:28:18 CST 2003


That's interesting, because it is the only thing I can see which would cause
the delete device request to fail.

What I am troubleshooting is a problem when I try to delete an individual
lower level device or the higher level pseudo bus device (i.e. a
Multi-function or in this case Multi-Port Serial adapter). Either of these
delete device requests results in a device could not be removed, but yet the
device is actually removed from the system anyhow. If the removal of the
lower port device is initiated by a removal of the parent device, the dialog
actual states that a lower level device refused to be removed, but again the
first child devnode is removed, but there is no callbacks to remove, or even
query the removal of, the sibling child devnodes.

Enabling the NTOSPNP and PNPMGR masks for full PnP debug does not reveal why
the removal request is seen as a denial when the driver is attempting to
return STATUS_SUCCESS wit the exception of the STATUS_WAIT_2 coming back
from the IoCallDriver function, which is why I was exploring whether that is
causing the problem or simply revealing that some system function is
prohibiting the full removal.

All of it is odd because the device is really removed from the system (i.e.
HKLM\System\CurrentControlSet\Enum has the previous PnP entry for the device
deleted from the Registry)..

"Bill McKenzie" <bill.mckenzie@compuware.com> wrote in message
news:O2R8MrnvDHA.1888@TK2MSFTNGP10.phx.gbl...
> This is a DriverVerifier status. DriverVerifier is checking to make sure
> you are not altering an IRP's completion status where you ought not be
> altering it. This should not cause you any problems unless you are doing
> something wrong, or depending upon something you ought not be depending
on.
>
> --
> Bill McKenzie
> Compuware Corporation
> Watch your IRPs/IRBs/URBs/SRBs/NDIS pkts with our free WDMSniffer tool:
> http://frontline.compuware.com/nashua/patches/utility.htm
>

Doron
Tue Dec 09 12:32:27 CST 2003

status_wait_2 *is* being returned by the lower driver. when you enable
verifier in this manner, it sits in between your driver and the device it
has attached to. it catches completed irps and does the status changes.
there is no corruption here.

d

--
This posting is provided "AS IS" with no warranties, and confers no rights.
"Ray Trent" <rat@synaptics.com.spamblock> wrote in message
news:%23vK8txnvDHA.2880@tk2msftngp13.phx.gbl...
> It looks to me like the documentation is wrong (except by convention).
> As far as I understand (and slide 19 of Adrian Oney's "Irp Voodoo"
> WinHEC 2003 presentation seems to corroborate this), IoCallDriver
> returns whatever value was *returned* by the lower level driver from
> it's dispatch routine.
>
> This is *supposed* to always be the same as what they set in the I/O
> status block, but again, that's just a convention. I will say, though,
> that I didn't actually go and write a test driver to experimentally
> prove this assertion, so I might be wrong :-).
>
> So, I think there are likely to be roughly 3 major possible sources of
> this behavior (nothing like a definite maybe :-):
>
> 1) the lower level driver is returning the wrong value from its dispatch
> routine.
> 2) your driver isn't looking in the right place of the I/O status block.
> 3) a stack corruption bug of some sort has occurred that is of a nature
> that doesn't cause a blue-screen.
>
> STATUS_WAIT_2 has the actual *value* 2, which seems like a reasonably
> likely incorrect return value or stack corruption value, so I can't
> really guess what the most likely cause might be.
>
> Try stepping through in the debugger :-)...
>
> Del Fredricks wrote:
>
> > According to the documentation for the IoCallDriver function, it is
supposed
> > to return either the NTSTATUS value the lower driver set in the I/O
Status
> > Block or STATUS_PENDING.
> >
> > However, I have a case where the lower driver is clearly setting the
> > NTSTATUS in the I/O Status Block to STATUS_SUCCESS, yet the IoCallDriver
> > function is returning a STATUS_WAIT_2 !!!!!!!!!
> >
> > Better yet, there is absolutely NO documentation on what the heck a
> > STATUS_WAIT_2 even means!!!!!!!!!!!!!!!!!!!!!!!!
> >
> > Does anyone out there know what a STATUS_WAIT_0, STATUS_WAIT_1,
> > STATUS_WAIT_2, or STATUS_WAIT_3 means?
> >
> > Anyone have any idea why the IoCallDriver function decides it knows
better
> > than the underlying driver and changes the return status from what the
> > driver attempted to return?
> >
> >
>
> --
> ../ray\..

Doron
Tue Dec 09 12:32:45 CST 2003

that is exactly the bug the verifier is attempting to expose.

d

--
This posting is provided "AS IS" with no warranties, and confers no rights.
"Ray Trent" <rat@synaptics.com.spamblock> wrote in message
news:%23UACi6nvDHA.1744@TK2MSFTNGP12.phx.gbl...
> Wow... you learn something new every day. Is this documented anywhere? I
> hate to think of how many drivers out there might be doing something
> equivalent to:
>
> status = IoCallDriver(...)
> if (status == STATUS_SUCCESS) { // yes you're supposed to use NT_SUCCESS
> // Do something significant, but not obvious
> }
>
> Bill McKenzie wrote:
>
> > This is a DriverVerifier status. DriverVerifier is checking to make
sure
> > you are not altering an IRP's completion status where you ought not be
> > altering it. This should not cause you any problems unless you are
doing
> > something wrong, or depending upon something you ought not be depending
on.
> >
> > --
> > Bill McKenzie
> > Compuware Corporation
> > Watch your IRPs/IRBs/URBs/SRBs/NDIS pkts with our free WDMSniffer tool:
> > http://frontline.compuware.com/nashua/patches/utility.htm
> >
> >
> > "Del Fredricks" <im.sick.of.spam@ask.i.might.tell> wrote in message
> > news:#W8MgdnvDHA.2444@TK2MSFTNGP12.phx.gbl...
> >
> >>According to the documentation for the IoCallDriver function, it is
> >
> > supposed
> >
> >>to return either the NTSTATUS value the lower driver set in the I/O
Status
> >>Block or STATUS_PENDING.
> >>
> >>However, I have a case where the lower driver is clearly setting the
> >>NTSTATUS in the I/O Status Block to STATUS_SUCCESS, yet the IoCallDriver
> >>function is returning a STATUS_WAIT_2 !!!!!!!!!
> >>
> >>Better yet, there is absolutely NO documentation on what the heck a
> >>STATUS_WAIT_2 even means!!!!!!!!!!!!!!!!!!!!!!!!
> >>
> >>Does anyone out there know what a STATUS_WAIT_0, STATUS_WAIT_1,
> >>STATUS_WAIT_2, or STATUS_WAIT_3 means?
> >>
> >>Anyone have any idea why the IoCallDriver function decides it knows
better
> >>than the underlying driver and changes the return status from what the
> >>driver attempted to return?
> >>
> >>
> >
> >
> >
>
> --
> ../ray\..

Ray
Tue Dec 09 13:29:00 CST 2003

That's more or less what I thought... but the question still stands...
Is this documented anywhere?

If not (and it was a bit tricky for me to find even a second-hand
reference with Google), then what it's really doing it causing poor
newbies to spend a ton of time tracking down some subtle bug in their
code to the point where they find out that IoCallDriver is returning
STATUS_WAIT_2, and then to spend an additional large amount of time
trying to figure out why that's happening (especially if they are in
control of the behavior of the lower level driver too and can verify
that it did the right thing).

In the absence of documentation, it has the same appearance as a really
annoying and tricky to find stack bug.

Not that this is *your* fault or anything :-) ;-).

Also, I'm just curious (and too lazy to test it for myself :-): is my
reading of Adrian's presentation correct? Under normal, non-Verifier,
circumstances does IoCallDriver actually return what was returned from
the lower driver's dispatch routine?

Doron Holan [MS] wrote:

> that is exactly the bug the verifier is attempting to expose.
>
> d
>

--
../ray\..

Doron
Tue Dec 09 21:44:42 CST 2003

> Also, I'm just curious (and too lazy to test it for myself :-): is my
> reading of Adrian's presentation correct? Under normal, non-Verifier,
> circumstances does IoCallDriver actually return what was returned from
> the lower driver's dispatch routine?

yes, in the non verifier case you get what the lower driver returned. like
i said before, in the verifier case, iocalldriver still returns what the
lower driver returned ... BUT in the verifier case, a driver that is lower
then you changes the status (which is legal in all cases).

d

--
This posting is provided "AS IS" with no warranties, and confers no rights.
"Ray Trent" <rat@synaptics.com.spamblock> wrote in message
news:eo1MzqovDHA.1576@TK2MSFTNGP11.phx.gbl...
> That's more or less what I thought... but the question still stands...
> Is this documented anywhere?
>
> If not (and it was a bit tricky for me to find even a second-hand
> reference with Google), then what it's really doing it causing poor
> newbies to spend a ton of time tracking down some subtle bug in their
> code to the point where they find out that IoCallDriver is returning
> STATUS_WAIT_2, and then to spend an additional large amount of time
> trying to figure out why that's happening (especially if they are in
> control of the behavior of the lower level driver too and can verify
> that it did the right thing).
>
> In the absence of documentation, it has the same appearance as a really
> annoying and tricky to find stack bug.
>
> Not that this is *your* fault or anything :-) ;-).
>
> Also, I'm just curious (and too lazy to test it for myself :-): is my
> reading of Adrian's presentation correct? Under normal, non-Verifier,
> circumstances does IoCallDriver actually return what was returned from
> the lower driver's dispatch routine?
>
> Doron Holan [MS] wrote:
>
> > that is exactly the bug the verifier is attempting to expose.
> >
> > d
> >
>
> --
> ../ray\..