I did not see the link, but it won’t be the first time Microsoft has
published something hideously wrong. Many of the MFC samples seem to have
been projects by summer interns who had learned Windows programming in
their first week, and wrote the example in the second week. I once saw a
$500,000 project die because it had been based on the Microsoft
“Multithreaded sockets” example, which was OK, if you ignored the fact
that it got threading wrong, sockets wrong, and asynchronous operations
wrong. And lots of minor errors. I did manage to get that article, and
their article on how to prevent multiple instances of code from running
(the Win16 technique, GUARANTEED to fail in Win32!) killed. One of the
other MFC MVPs referred to Microsoft’s examples as “works of fiction”.
Like the one that had a statement of the form
if(void_returning_function(…args here…) ) {…stuff to do…}
How something like this made it into the docs at all escaped us. (The
issue arose when a newbie complained that it wouldn’t compile, but didn’t
know enough to know what was wrong).
Said MVP posted an equivalent of a “Peter Pontificates” essay on this,
which was both absolutely true and hilariously funny.
joe
On, not “contradictory” at all! Rather it simply felt like you were very
determined to use these threaded IRPs when we were consistently telling
you that you didn’t need to.
And now I know why.
I thank you for providing the title to and quoting that article. That
article is very, very, depressingly, hideously, and embarrassingly wrong.
Please erase everything you read in it from your memory.
The people who write White Papers like the one you cited are not the same
people as those who write the Windows Driver Kit documentation. The
quality and accuracy of those papers varies widely. Some are great and
show terrific insight. Most are OK, if lacking in practical insight.
Some are truly terrible.
It seems you found one of those that are truly terrible.
As soon as I finish this post, I’m going to send a note to a colleague at
Microsoft and begging to have it removed.
In any case… please don’t hesitate to continue to ask questions here.
We’re happy to help. And I’m PARTICULARLY happy to know about that White
Paper.
On, not “contradictory” at all! Rather it simply felt like you were very determined to use these threaded IRPs when we were consistently telling you that you didn’t need to.
And now I know why.
I thank you for providing the title to and quoting that article. That article is very, very, depressingly, hideously, and embarrassingly wrong. Please erase everything you read in it from your memory.
This is a subject that has always confused me as well. Consider the
three IRP-building routines:
IoBuildAsynchronousFsdRequest
IoBuildDeviceIoControlRequest
IoBuildSynchronousFsdRequest
The documentation for IoBuildDeviceIoControlRequest specifically says it
creates “a synchronously processed device control request”, and the very
names of the other routines include the words “synchronous” and
“asynchronous”. However, the usage of those terms here doesn’t match
the usage I’m accustomed to. In my mind, the sync/async distinction is
made after I call IoCallDriver. If I immediately call
KeWaitForSingleObject, then it’s a synchronous request. If I don’t,
then it’s an asynchronous request. Nothing in the setup of the IRP has
any impact on that.
I’ve often wondered whether the names should have been
IoBuildThreadedFsdRequest and IoBuildArbitraryFsdRequest, or something
similar.
–
Tim Roberts, xxxxx@probo.com
Providenza & Boekelheide, Inc.
Perhaps I can shed some light on this confusing situation, particularly for IoBuildAsyncFsdReq and IoBuildSyncFsdRequest.
These functions are among the oldest in the I/O Manager. I believe the motive for creating them was to make it easy for File Systems (and drivers too) to built IRPs without having to know the details of the IRP structure. I guess today we could equate these functions to the constructor for an IRP… giving callers the ability to construct an IRP the contents of which should be (at least partially) opaque.
IoBuildAsync and IoBuildSync differ in exactly one argument, and that argument is a PKEVENT. If you walk into IoBuildSync you’ll see that it calls IoBuildAsync, puts the provided PKEVENT into Irp->UserEvent, and then puts the IRP on the current thread’s IRP list.
So, the differences between IoBuildAsync and IoBuildSync are (a) the sync flavor builds an IRP that CAN be used synchronously by a driver with no extra processing… the caller just calls IoBuildSync, IoCallDriver, and KeWaitForSingle. The provided event which will be set by the I/O Manager when the IRP is completed, and (b) in the synchronous variety, the IRP is “threaded” (that is, put on the current thread’s IRP list). I have absolutely no idea why the IRP is threaded. I have never understood this.
Note that in both cases, the IRP’s Tail.Overlay.Thread field is set to whatever the current thread is. This underscores the original intent (along with the name itself) that these functions were initially intended to be used by File Systems.
There has ALWAYS been a good amount of secret squirrel monkey magic in IRP handling, especially in the completion path. The developers had the right idea with creating helper functions to build IRPs for folks. I suspect (just a guess) that the detailed operation of these functions was not initially documented to try to keep some of those details opaque. However, as time has gone by, it has turned out we’ve all had to learn a lot more about the the mystery of IRPs then anyone would prefer. Thus, the lack of clear and complete documentation about precisely what these functions do and how they should be used, coupled with their unusual names, has done more harm than good at this point.
Thank you all for your input. Informative as always. It is such a PITA trying to track down good doco so it’s great to have you guys to draw on as a resource.
Cheers,
BJW
A quick follow-up and status update regarding the following:
Mr. Ben wrote:
To which I (in part) replied:
As promised, I beseeched a good friend on the doc team.
I am happy to say said whitepaper is GONE as of today. Deleted. At least from micrsooft.com. I personally verified this by attempting to download it myself.
Mr. Ben… even though you had to struggle, you wound up doing a great service to the community. I hope you are at least pleased that your misdirection by that white paper, and your discussions here, have ensured that nobody will ever been plagued by that work again.