KMDF 1.1 WdfIoTargetSendIoctlSynchronously describes parameters incorrectly

OSR_Community_User · June 23, 2006, 12:37pm

The prototype is

NTSTATUS
WdfIoTargetSendIoctlSynchronously(
IN WDFIOTARGET IoTarget,
IN OPTIONAL WDFREQUEST Request,
IN ULONG IoctlCode,
IN OPTIONAL PWDF_MEMORY_DESCRIPTOR InputBuffer,
IN OPTIONAL PWDF_MEMORY_DESCRIPTOR OutputBuffer,
IN OPTIONAL PWDF_REQUEST_SEND_OPTIONS RequestOptions,
OUT OPTIONAL PULONG_PTR BytesReturned
);

and the descriptions of InputBuffer and OutputBuffer are

InputBuffer
A pointer to a caller-allocated WDF_MEMORY_DESCRIPTOR structure that describes
a buffer that will receive data from the I/O target. For more information, see
the following Comments section. This parameter is optional and can be NULL
if the request does not receive data.

OutputBuffer
A pointer to a caller-allocated WDF_MEMORY_DESCRIPTOR structure that describes
a buffer that will be written to the I/O target. For more information, see
the following Comments section. This parameter is optional and can be NULL
if the request does not send data.

These definitions are from the point of view of the caller: fair enough I suppose. There
was a slight jar because the output parameter of the function is placed before the
input parameter, but that’s probably an insignificant (personal) style issue: I like
parameters to read from left to right with input before output.

Unfortunately, OutputBuffer is what receives the reply. If you only supply an InputBuffer
(which is what I did at first, because there was no data sent to the lower driver), the
call to WdfRequestRetrieveOutputBuffer (which is where the lower driver wants to put the
answer) fails.

The only way I could get this to work was to use the OutputBuffer parameter, which would be
correct if the names of the parameters were from the POV of the callee not the caller.

I then tried different values in the InputBuffer and OutputBuffer. My lower driver received
the values that were specified in the InputBuffer. This also matches the POV of the callee.

The IOCTL in question is METHOD_BUFFERED with FILE_WRITE_DATA and FILE_READ_DATA.

I suspect WdfIoTargetSendInternalIoctlSynchronously() has the same problem.

Don

Doron_Holan · June 23, 2006, 1:03pm

WdfRequestRetrieveInput/OuputBuffer are for the current stack location,
not for buffers you formatted a request with. Not sure if that is the
point of confusion, but I wanted to point that out.

WdfRequestRetrieveInput/OuputBuffer refer to the operation on the memory
as described by the current stack location. For an IOCTL, these map
directly to the input/output buffer provided by the sender of the
request. The input/output buffer nomenclature gets confusing for reads
and writes though b/c the read’s buffer is an output and a write’s
buffer is an input, but read indicates an input operation to most folks
and writes indicate an output operation.

From the POV of the caller, all WdfIoTargetSendXxx are described
properly. DeviceIoControl follows the same pattern so I don’t see a
disjoint. I am not sure where you see the output buffer coming before
the input buffer in SendIoctl b/c for both the formatter and receiver of
the request, an IOCTL input buffer is an input buffer for both.

…or maybe I am missing the point here completely…

d

-----Original Message-----
From: xxxxx@lists.osr.com
[mailto:xxxxx@lists.osr.com] On Behalf Of Don Ward
Sent: Friday, June 23, 2006 9:29 AM
To: Windows System Software Devs Interest List
Subject: [ntdev] KMDF 1.1 WdfIoTargetSendIoctlSynchronously describes
parameters incorrectly

The prototype is

NTSTATUS
WdfIoTargetSendIoctlSynchronously(
IN WDFIOTARGET IoTarget,
IN OPTIONAL WDFREQUEST Request,
IN ULONG IoctlCode,
IN OPTIONAL PWDF_MEMORY_DESCRIPTOR InputBuffer,
IN OPTIONAL PWDF_MEMORY_DESCRIPTOR OutputBuffer,
IN OPTIONAL PWDF_REQUEST_SEND_OPTIONS RequestOptions,
OUT OPTIONAL PULONG_PTR BytesReturned
);

and the descriptions of InputBuffer and OutputBuffer are

InputBuffer
A pointer to a caller-allocated WDF_MEMORY_DESCRIPTOR structure that
describes a buffer that will receive data from the I/O target. For more
information, see the following Comments section. This parameter is
optional and can be NULL if the request does not receive data.

OutputBuffer
A pointer to a caller-allocated WDF_MEMORY_DESCRIPTOR structure that
describes a buffer that will be written to the I/O target. For more
information, see the following Comments section. This parameter is
optional and can be NULL if the request does not send data.

These definitions are from the point of view of the caller: fair enough
I suppose. There was a slight jar because the output parameter of the
function is placed before the input parameter, but that’s probably an
insignificant (personal) style issue: I like parameters to read from
left to right with input before output.

Unfortunately, OutputBuffer is what receives the reply. If you only
supply an InputBuffer (which is what I did at first, because there was
no data sent to the lower driver), the call to
WdfRequestRetrieveOutputBuffer (which is where the lower driver wants to
put the
answer) fails.

The only way I could get this to work was to use the OutputBuffer
parameter, which would be correct if the names of the parameters were
from the POV of the callee not the caller.

I then tried different values in the InputBuffer and OutputBuffer. My
lower driver received the values that were specified in the InputBuffer.
This also matches the POV of the callee.

The IOCTL in question is METHOD_BUFFERED with FILE_WRITE_DATA and
FILE_READ_DATA.

I suspect WdfIoTargetSendInternalIoctlSynchronously() has the same
problem.

Don

Questions? First check the Kernel Driver FAQ at
http://www.osronline.com/article.cfm?id=256

To unsubscribe, visit the List Server section of OSR Online at
http://www.osronline.com/page.cfm?name=ListServer

OSR_Community_User · June 23, 2006, 1:14pm

Doron,

DeviceIoControl is not desribed the same way. This is from the VC6 docs
for DeviceIoControl:

lpInBuffer
Pointer to a buffer that contains the data required to perform the
operation.
This parameter can be NULL if the dwIoControlCode parameter specifies an
operation that does not require input data.

nInBufferSize
Size, in bytes, of the buffer pointed to by lpInBuffer.
lpOutBuffer
Pointer to a buffer that receives the operation’s output data.

Beverly

-----Original Message-----
From: xxxxx@lists.osr.com
[mailto:xxxxx@lists.osr.com] On Behalf Of Doron Holan
Sent: Friday, June 23, 2006 1:01 PM
To: Windows System Software Devs Interest List
Subject: RE: [ntdev] KMDF 1.1 WdfIoTargetSendIoctlSynchronously
describes parameters incorrectly