John Poltorak wrote in a message to Mike Bilow:

 hl>> "Blain et al" and "Mastrianni" did get good
reviews in this
 hl>> echo.

 MB> calling the DevHelp API from C -- when IBM provides, at no additional
 MB> cost, their own DHCALLS.LIB as part of the DDK.

 MB> Mastrianni also decides to do things in ways directly opposite to the IBM
 MB> docs for no particular reason that I can understand.  For example,
 MB> Mastrianni says that DevHelp_VerifyAccess should be called before
 MB> DevHelp_Lock, while IBM says to call DevHelp_Lock before calling
 MB> DevHelp_VerifyAccess.  Using Mastrianni's method will cause a pointer
 MB> error in the application to pull Trap D, and will also run the risk of
 MB> verifying a selector that gets swapped out between the call to
 MB> DevHelp_VerifyAccess and the call to DevHelp_Lock.  The only reasonable
 MB> interpretation is that Mastrianni is clearly wrong, but he takes pains to
 MB> emphasize that he really does mean to contradict the IBM docs.

 JP> Is this Steve Mastrianni? I just came across an article by
 JP> him in Developer Connection News Vol 7. which is published
 JP> by IBM, so I would have thought IBM would have vetted him as
 JP> a reliable source of info... 

Corporate IBM thinks of him as the definitive expert on writing OS/2 device
drivers, but you will get a radically different impression if you talk to
the people who actually write the device drivers.

Nearly everyone who wants to write an OS/2 device driver buys Mastrianni's
book, "Writing OS/2 2.1 Device Drivers in C."  Among other
issues, his book is the only one available on the subject.  Then everyone
attempts to read the book and begins thinking that the subject must be
beyond them, because no one ever actually understands Mastrianni's book. 
Some people probably give up, but other people fight their way through.

Eventually, some people manage to get to the point where they can write
perfectly serviceable OS/2 device drivers.  I invested a lot of time in
reading the official IBM docs that come with the DDK, and I also spent a
lot of time tracing through the source code to the real OS/2 device drivers
provided on the DDK.  I also spent a lot of time learning things the hard
way, watching my drivers trap out and go nuts, methodically using the
debugging kernel to figure out why.

The opinions I formed in due course are these:

1.  Mastrianni's book is totally useless.  Much of it is an abbreviated
regurgitation of the official IBM docs, but the parts chosen to be
regurgitated have no rhyme or reason.  For example, the virtual device
helper API is explored in excruciating detail, but nowhere does Mastrianni
ever explain true fundamentals such as the difference between a
"virtual" and a "linear" address.

2.  The official IBM docs are remarkably good.  They are in reference form,
but they have very few inaccuracies and are quite reliable.

3.  There are several books which device driver writers would find useful,
and these are not obvious.  (I should probably sit down and compile a
list.)  For example, the most readable explanation of the protected mode
architecture is in Robert Hummel's "The Processor and
Coprocessor," usually considered a very specialized book aimed at
assembly language programmers.

4.  A lot of Mastrianni's popularity is pure economics.  When the IBM DDK
first came out (as the DDSK), it cost about US$300 per year.  IBM justified
this, believe it or not, by saying that they only expected to sell about
1000 subscriptions per year, and they had to recover costs somehow.  When
reason finally prevailed and the DDK became available as a US$75 add-on to
a DevCon subscription, Mastrianni's book ceased to be such a relative
bargain.  People buying Mastrianni's book as a cheaper alternative to the
IBM DDK are making a huge mistake.

5.  If someone ever does write a device driver book, they need to
concentrate on an architectural overview of OS/2 internals, not on the
DevHelp API.  How does memory work?  When and how do you lock and unlock
memory?  What are you really looking at with the debugging kernel?  What
arbitrary conventions are used inside OS/2?  What happens from the driver
point of view whan an application calls DosOpen(), DosRead(),
DosDevIOCtl(), and so on?  This is the stuff that is either lacking or
buried in the IBM docs.

-- Mike


---