KMDF USB Sample code question

I’ve just started reading KMDF documentation and sample code and I have
a question regarding the Read and Write completion routines in bulkrwr.c
from the DDK (C:\WINDDK\WDF\KMDF10\src\kmdf\osrusbfx2\sys\final).
The comment for the function states:
This is the completion routine for reads/writes. If the irp completes
with success, we check if we need to recirculate this irp for another
stage of transfer.
However it doesn’t appear that the code actually does what the comment
indicates that it will do. Here is an edited snippet of the code:
VOID EvtRequestReadCompletionRoutine(…)
{
NTSTATUS status;
size_t bytesRead = 0;
PWDF_USB_REQUEST_COMPLETION_PARAMS usbCompletionParams;
status = CompletionParams->IoStatus.Status;
usbCompletionParams = CompletionParams->Parameters.Usb.Completion;
bytesRead = usbCompletionParams->Parameters.PipeRead.Length;
if (NT_SUCCESS(status)){
TraceEvents(TRACE_LEVEL_INFORMATION, DBG_READ,
“Number of bytes read: %I64d\n”, (INT64)bytesRead);

} else {
TraceEvents(TRACE_LEVEL_ERROR, DBG_READ,
“Read failed - request status 0x%x UsbdStatus 0x%x\n”,

status, usbCompletionParams->UsbdStatus);
}
WdfRequestCompleteWithInformation(Request, status, bytesRead);
return;
}
Isn’t this function just completing the request regardless of how much
data was actually transferred? I looked at the OSR FX2 WDM driver and
the equivalent function appears to detect that the transfer is not
complete and schedules additional transfers.

From what I’ve read in the KMDF documentation this situation (too much
data to transfer in a single request) is not handled by the framework.
To handle this situation a driver can create additional request objects
that are used to break up the transfer into multiple transfers.
The DDK shows two techniques to break up a large request. One is to
create a single new request and send it synchronously and in the
completion callback reuse the request to send the additional data.
The second technique described is to create multiple smaller requests (I
assume that the number of requests is TotalTransferSize /
MaxTransferSize + 1) and send them asynchronously. Once all the data is
transferred then the request is completed. Isn’t there a potential for
a very large number of outstanding requests to be created (hundreds or
thousands) using this technique?

The first technique seems to be the simplest but I have a concern. When
the user application performs an asynchronous Read or Write operations
will that operation occur asynchronously from the caller’s point of
view? That is will the read or write call return immediately even
though the underlying driver is performing the operation synchronously?
If not then this technique may not be suitable for our needs.
Thanks,

  • Steve -

Whitman, Steve wrote:

I’ve just started reading KMDF documentation and sample code and I
have a question regarding the Read and Write completion routines in
bulkrwr.c from the DDK
(C:\WINDDK\WDF\KMDF10\src\kmdf\osrusbfx2\sys\final).

The comment for the function states:

This is the completion routine for reads/writes. If the irp
completes with success, we check if we need to recirculate this irp
for another stage of transfer.

However it doesn’t appear that the code actually does what the comment
indicates that it will do.

No, it doesn’t. If you look back at OsrFxEvtIoRead, you’ll see that it
fails any read request larger than the transfer size, so for this
particular sample, recirculation is not required.

In my opinion, which I never hesitate to share :), the “final” sample is
somewhat misnamed. The name seems to imply that, “of the six osrusbfx2
samples, this is unconditionally the best one.” That is not the case.
Some of the intermediate “step” drivers do things in a slightly
different (and often simpler) way, and will make a better basis for many
drivers.


Tim Roberts, xxxxx@probo.com
Providenza & Boekelheide, Inc.

I realized that OsrFxEvtIoRead checks to verify that the transfer is not
larger than TEST_BOARD_TRANSFER_BUFFER_SIZE otherwise the request is
failed. What wasn’t clear when I first read the code and the comment in
the callback lead me to believe is if the WdfRequestSend sends this
entire buffer as multiple USB transactions or if it invoked the callback
at the end of each USB transaction. If it sends the entire transfer as
multiple USB transactions then there isn’t any need to recirculate the
request. If on the other than the WdfRequestSend only sends only one
USB transaction then recirculation is required.

Based on additional reading I believe the WdfRequestSend will cause
multiple USB packets to be sent until the full buffer is transferred at
which time the callback will be invoked. In this case recirculation is
not required and the comment should be removed.

I spent a little time looking at the other examples. Each of these
“step” drivers provides a nice sample of how the framework should be
used and I like the “step” approach as it makes it much easier to
understand how to use the framework to put together a driver. But I
didn’t find an example where a “step” driver was better than the “final”
driver. Actually I think that using the “step” driver as a starting
point for a new driver could be a mistake since much of the
simplification seems to come from the removal of error handling, some
setup steps that probably should be performed and comments. Could you
point out an example of where a “step” driver is better than the “final”
driver because I couldn’t find it?

Thanks,

  • Steve -

-----Original Message-----
From: xxxxx@lists.osr.com [mailto:bounce-239859-
xxxxx@lists.osr.com] On Behalf Of Tim Roberts
Sent: Wednesday, February 15, 2006 12:50 PM
To: Windows System Software Devs Interest List
Subject: Re: [ntdev] KMDF USB Sample code question

Whitman, Steve wrote:

> I’ve just started reading KMDF documentation and sample code and I
> have a question regarding the Read and Write completion routines in
> bulkrwr.c from the DDK
> (C:\WINDDK\WDF\KMDF10\src\kmdf\osrusbfx2\sys\final).
>
> The comment for the function states:
>
> This is the completion routine for reads/writes. If the irp
> completes with success, we check if we need to recirculate this irp
> for another stage of transfer.
>
> However it doesn’t appear that the code actually does what the
comment
> indicates that it will do.
>

No, it doesn’t. If you look back at OsrFxEvtIoRead, you’ll see that
it
fails any read request larger than the transfer size, so for this
particular sample, recirculation is not required.

In my opinion, which I never hesitate to share :), the “final” sample
is
somewhat misnamed. The name seems to imply that, “of the six
osrusbfx2
samples, this is unconditionally the best one.” That is not the case.
Some of the intermediate “step” drivers do things in a slightly
different (and often simpler) way, and will make a better basis for
many
drivers.


Tim Roberts, xxxxx@probo.com
Providenza & Boekelheide, Inc.


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

You are currently subscribed to ntdev as: xxxxx@cognex.com
To unsubscribe send a blank email to xxxxx@lists.osr.com

WdfRequestSend in this case will only send one URB once down the stack,
all request recirculation (e.g. staging a transfer) must be done in the
driver.

d

– I can spell, I just can’t type.
-----Original Message-----
From: xxxxx@lists.osr.com
[mailto:xxxxx@lists.osr.com] On Behalf Of Whitman, Steve
Sent: Wednesday, February 15, 2006 12:22 PM
To: Windows System Software Devs Interest List
Subject: RE: [ntdev] KMDF USB Sample code question

I realized that OsrFxEvtIoRead checks to verify that the transfer is not
larger than TEST_BOARD_TRANSFER_BUFFER_SIZE otherwise the request is
failed. What wasn’t clear when I first read the code and the comment in
the callback lead me to believe is if the WdfRequestSend sends this
entire buffer as multiple USB transactions or if it invoked the callback
at the end of each USB transaction. If it sends the entire transfer as
multiple USB transactions then there isn’t any need to recirculate the
request. If on the other than the WdfRequestSend only sends only one
USB transaction then recirculation is required.

Based on additional reading I believe the WdfRequestSend will cause
multiple USB packets to be sent until the full buffer is transferred at
which time the callback will be invoked. In this case recirculation is
not required and the comment should be removed.

I spent a little time looking at the other examples. Each of these
“step” drivers provides a nice sample of how the framework should be
used and I like the “step” approach as it makes it much easier to
understand how to use the framework to put together a driver. But I
didn’t find an example where a “step” driver was better than the “final”
driver. Actually I think that using the “step” driver as a starting
point for a new driver could be a mistake since much of the
simplification seems to come from the removal of error handling, some
setup steps that probably should be performed and comments. Could you
point out an example of where a “step” driver is better than the “final”
driver because I couldn’t find it?

Thanks,

  • Steve -

-----Original Message-----
From: xxxxx@lists.osr.com [mailto:bounce-239859-
xxxxx@lists.osr.com] On Behalf Of Tim Roberts
Sent: Wednesday, February 15, 2006 12:50 PM
To: Windows System Software Devs Interest List
Subject: Re: [ntdev] KMDF USB Sample code question

Whitman, Steve wrote:

> I’ve just started reading KMDF documentation and sample code and I
> have a question regarding the Read and Write completion routines in
> bulkrwr.c from the DDK
> (C:\WINDDK\WDF\KMDF10\src\kmdf\osrusbfx2\sys\final).
>
> The comment for the function states:
>
> This is the completion routine for reads/writes. If the irp
> completes with success, we check if we need to recirculate this irp
> for another stage of transfer.
>
> However it doesn’t appear that the code actually does what the
comment
> indicates that it will do.
>

No, it doesn’t. If you look back at OsrFxEvtIoRead, you’ll see that
it
fails any read request larger than the transfer size, so for this
particular sample, recirculation is not required.

In my opinion, which I never hesitate to share :), the “final” sample
is
somewhat misnamed. The name seems to imply that, “of the six
osrusbfx2
samples, this is unconditionally the best one.” That is not the case.
Some of the intermediate “step” drivers do things in a slightly
different (and often simpler) way, and will make a better basis for
many
drivers.


Tim Roberts, xxxxx@probo.com
Providenza & Boekelheide, Inc.


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

You are currently subscribed to ntdev as: xxxxx@cognex.com
To unsubscribe send a blank email to xxxxx@lists.osr.com


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

You are currently subscribed to ntdev as: unknown lmsubst tag argument:
‘’
To unsubscribe send a blank email to xxxxx@lists.osr.com