Well, there is always room for improvement I guess !!!
Result:: Compare the current doc to say nt4.0 ddk doc. And few simple
samples would always help.
Context:: I’m from algorithm area, so what I learned ( and the bias went in
my head 
) is that when you are at a tough
decision, you have to weigh and show that there is nothing better exist
first, and then you go on to prove that it is inherently complex or
unsolvable
History:: When I first saw *nix man page, I did not like it a bit. A troff
formatted tarse and terrible document for commands and some apis. And I
asked some other guys who were from Systems area, hacked University systems
for 4+ years ( and lack of better things to do at that point in life :-),
they said it is all easy, so I took some inhouse course and also found
somewhat easy ( but I heardly ever use most of the stuff in those man
pages ). – My conclusion is that anyone take a course/training would have
a higher speed than if some one just try to jump in to a new framework.
History:: When MFC/OWL came in the early 90s, people has the same ( sort of)
problem and often attacked global name space ( using :: ), though often it
was not much of a performance improvement but lack of finding the right
class and corresponding methods. In your case, it has some similarities
(timer and dpc using native API).
History:: Way too many bugs relates to calling convention, parameter passing
etc. So ASL notations or explicitly saying UNREFERENCED_PARAMETER is not
really a bad thing, sure there is an asthetic issue here, and if the
compiler guys think that they would flag as an error ( unless some
suppression is used by the developer ), it would come as a normal thing for
newbies. PAGED_CODE() etc. could be used with a comment to say it is not
necessary, but online doc search should also state the same.
For the rest of the stuff (INF, KMDF version incompatibilites etc), sure
everyone should report those. And there should be some channels to use for
reporting. These are important areas, and I think you can connect to people
at Microsoft using any such channels… For example, on the NDIS 6.0 front,
I was successful in getting lot of feedbacks, actually way lot more than I
could digest. Also we have to keep in mind that those devs/support/doc
people are busy too ( and I know that this not a way to excuse but hard
fact ), and often someone would say I can’t promise, but will escalate.
Finally, I think no one likes to debug others code, but that is
unfortunately that is the part of life for lot of people. At Microsoft,
people also find lot of hardware bugs ( and that delays projects, and cause
frustrations that I’ve seen too ).
-pro
----- Original Message -----
From: “Alberto Moreira”
To: “Windows System Software Devs Interest List”
Sent: Saturday, January 12, 2008 6:33 AM
Subject: Re: RE:[ntdev] New to Drivers
>I find that MS documents and samples sometimes have too much fat for my
>taste, and that’s not good to a beginner. I may be wrong, but it looks to
>me like MS sometimes tries to use a sample or a tutorial document to push
>their own favorite techniques and functionality, and that overloads the
>reader with things that he or she might not need to bother about at an
>early stage.
>
> For example, when I first went around learning WDF - and I’m no beginner,
> mind you - I quickly got irritated with the amount of peripheral fat added
> to the samples. First I wanted a sample that had a DriverEntry, and
> AddDevice and a board start function, and nothing else - no WMI, no C
> #pragmas, maybe no KdPrints, no PAGED_CODE( ) directives, no
> UNREFERENCED_PARAMETERS, no WMI, no power management: something straight
> to the point, which shows me precisely what needs to be done to make the
> OS talk to a driver, and no extra fluff. I got even more irritated when I
> was trying to find out a sample that handled interrupts in a
> straightforward way, and after a while I bumped into the PLX sample,
> which has a pretty decent interrupt code in isrdpc.c, although you still
> need to extricate the PLX unique code (guys, couldn’t you maybe put it in
> a “go_handle_your_hardware( )” function ?) from the WDF mainstream code.
>
> Introductory documentation and code isn’t the place to do any of that.
> There’s time for it later, after the principles have been explained and
> illustrated, and after the developer has a clue about what the framework
> is all about!
>
> The other issue was, I had to spend time figuring out what I needed to
> change in my driver, and what could stay as it was. MS emphasizes a fair
> amount of WDF calls which aren’t but duplications of the functionality
> already existing in the OS itself. So, for example, I have a timer with a
> DPC, which I implemented through the standard Ntoskrnl calls, and I had to
> actually experiment to convince myself that I didn’t need to rewrite it
> with WDF calls. The same thing happened with my interrupt code, at first I
> wanted to leave it as is, because it sat on top of the OS API itself and
> I’m a minimalist - I do not like intermediaries. However, I got a
> bluescreen at device cleanup time, and the mere presence of the WDF
> discouraged me from trying to figure out what was going on: I really
> detest debugging somebody else’s code. That’s when I searched the samples,
> found the PLX driver, extricated the interrupt code, I massaged it to my
> objectives, and presto, I had a working driver in less than 10 minutes. I
> wish MS would have told us the exact relationship between WDF and Ntoskrnl
> interrupt code ?
>
> The very same issue happened with my PCI bus initialization code, and
> again, I had to actually experiment to see what needed to be done.
>
> The INF files is another area. I found that I could keep my existing INF
> file under Vista (I barely use XP anymore), so, several written notices by
> MS that “you need to have this or that in your INF file” proved to be
> unnecessary in Vista. I haven’t tried XP yet, but the tone of the
> documentation urged me to add those lines to the INF file (again, thanks
> to the PLX driver), but it’d be nice to know whether they’re really
> required. The same happened to the “sources” file, MS documentation
> warnings went unheeded and so far I haven’t seen any problem.
>
> There’s an MS “versioning” paper out in the WHDC web site that’s really
> scary. It adds a string between driver and library that shouldn’t exist.
> Versioning should be as simple as automatically imprinting the driver
> somewhere with the DDK build number, say, 6000 or 6001, and being strict
> about maintained backward compatibility. Installing a WDK should also
> install those two library drivers and the coinstaller dll, so that every
> driver build automatically carried those three items, and who needs
> explicit KMDF versions anywhere. KISS, guys, KISS. There’s no “dll hell”
> on kernel side, no need to complicate things. In fact, Microsoft, would
> you consider synchronizing WDK releases with Windows releases ? And, while
> doing that, guarantee backward compatibility ? So that KMDF 1.6 doesn’t
> break drivers written for KMDF 1.5 ? So that WDK 60xx is usable and we
> don’t need to stick to WDK 6000 because of back-compatibility issues ?
> That would make life much easier on our side.
>
> Again, the key is, I would like a set of samples that show me what
> actually needs to be done, and that doesn’t have any functionality that
> doesn’t need to be there. The moment you use a document or a sample as a
> sales platform, we developers have a problem!
>
> Alberto.
>
>
> ----- Original Message -----
> From: “Prokash Sinha”
> To: “Windows System Software Devs Interest List”
> Sent: Friday, January 11, 2008 11:03 PM
> Subject: Re: RE:[ntdev] New to Drivers
>
>
>> Okay Anton, you get two brownie points, and Toby gets one
>>
>> Sure the scope of MS documents are larger than Toby’s document, so sure
>> if there is any imprecision, it is bad. But Peter is a teacher and he
>> mentioned the other day that lets fix the document first. That post is
>> only couple days old.
>>
>> I found the articles, and the book fundamentally clear/concise and gives
>> a very very good foundations. Some of the articles are old and are being
>> modified ( so you can see that once a teacher always a teacher ). If
>> something goes against intuition, it is good to be pointed out. This is a
>> good thing for Toby to fix, and take a second look !!!
>>
>> C’mon this is only the first month of this year. Pls move on to good
>> stuff!
>>
>> -pro
>>
>> ----- Original Message -----
>> From:
>> To: “Windows System Software Devs Interest List”
>> Sent: Friday, January 11, 2008 7:05 PM
>> Subject: RE:[ntdev] New to Drivers
>>
>>
>>>> … imagined bugs that result from misreading what might be in the WDK
>>>> documentation
>>>> – if that’s indeed what you mean by “MSDN”.
>>>
>>> By “MSDN” I mean any official documentation that comes from MSFT.
>>> Ironically, WDK seems to have finally fixed the particular bug that I
>>> had described in my previous post. However, both W2K and XP DDKs had it.
>>>
>>> In actuality, the consequences that I have described are far from being
>>> imaginary. Furthermore, the term “misread” does not really apply here -
>>> it is not about “misunderstanding” the text. Instead, it is all about
>>> understanding exactly what the text says. I even remember reading some
>>> clarification document, saying that the documentation was a bit
>>> imprecise - it said that, in actuality, “DPC routine is invoked when
>>> IRQL is about to drop below DPC level” (which, ironically, is a bit
>>> imprecise as well, but at least it made it clear that DPC routine itself
>>> runs at DISPATCH_LEVEL). It is obvious that this clarification document
>>> was written in response to, apparently, numerous complaints…
>>>
>>> Probably, my argument is, indeed, a bit of a “straw man” one, but still
>>> you haven’t answered my question - does the official documentation, in
>>> your opinion, do more harm or good??? In case of the latter, why should
>>> its “imprecisions” be treated more leniently than the ones in Toby’s
>>> articles ???
>>>
>>> Anton Bassov
>>>
>>> —
>>> NTDEV is sponsored by OSR
>>>
>>> For our schedule of WDF, WDM, debugging and other seminars visit:
>>> http://www.osr.com/seminars
>>>
>>> To unsubscribe, visit the List Server section of OSR Online at
>>> http://www.osronline.com/page.cfm?name=ListServer
>>
>>
>> —
>> NTDEV is sponsored by OSR
>>
>> For our schedule of WDF, WDM, debugging and other seminars visit:
>> http://www.osr.com/seminars
>>
>> To unsubscribe, visit the List Server section of OSR Online at
>> http://www.osronline.com/page.cfm?name=ListServer
>
>
> —
> NTDEV is sponsored by OSR
>
> For our schedule of WDF, WDM, debugging and other seminars visit:
> http://www.osr.com/seminars
>
> To unsubscribe, visit the List Server section of OSR Online at
> http://www.osronline.com/page.cfm?name=ListServer