by Michael S. Kaplan, published on 2007/07/29 10:11 -04:00, original URI: http://blogs.msdn.com/b/michkap/archive/2007/07/29/4117994.aspx
It was about a year ago that someone was looking at the Windows Developer Kit documentation and had a question.
They were comparing RtlUpcaseUnicodeChar/RtlUpcaseUnicodeString/RtlUpperChar/RtlUpperString versus RtlUpcaseUnicodeStringToCountedOemString, in particular wondering why the first four were documented as requiring IRQL = PASSIVE_LEVEL while the latter was documented as requiring IRQL < DISPATCH_LEVEL.
Apparently they were just confused as to the difference.
To me it made some sense that RtlUpcaseUnicodeStringToCountedOemString, which is part of the IFS (Installable File System) document set and the kind of function (uppercase and convert to the OEM charset) that is most likely to be even possibly needed at APC_LEVEL anyway.
I decided not to say anything at the time (I was mostly cured of desire to clarify at this level after all the back-story in the research that came up in the comments of Ready... set... Reboot!), and someone else from the team pointed out the obvious fact that the documentation was really not so far off from the truth anyway.
Though to be honest all five of them could be called at APC_LEVEL if needed. It is just that most of them would not be. So perhaps no change was really needed.
As Doron pointed out last Spring in not entirely unrelated comments to String buffers and IRQL:
APC_LEVEL is probably OK since you can handle paging i/o at that IRQL, i don't think there is anything special in the NLS tables that would preclude APC_LEVEL. I don't mention APC_LEVEL much because for a non FS related driver, you don't deal with APC_LEVEL much, so talking about it leads to more confusion then if we just talk about IRQL as PASSIVE_LEVEL, DISPATCH_LEVEL, or DIRQL.
Anyway, they made changes to the documentation after this conversation, with the former four functions now being documented as requiring IRQL <= APC_LEVEL and the latter requiring IRQL < DISPATCH_LEVEL (the latter did not change, while the former four did).
Which to me is weird, since the two directives are essentially identical, though the one that is theoretically more likely to find APC_LEVEL interesting given functionality requirements makes no mention of APC_LEVEL, while the four that probably are not going to need it explicitly mention it.
Not a big deal, and maybe not even worth changing, since a difference that makes no difference, makes no difference.
It just seems weird to me....
This post brought to you by ๆ (U+0e46, a.k.a. THAI CHARACTER MAIYAMOK)
referenced by