View source for Compiling a Driver Sample with IBM DDK on ArcaOS 5.0.1

By [[User:Martini|Martin Iturbide]]

On the last days of 2017 and first days of 2018 I got the desire to know more about the procedure to compile a driver for the OS/2 and ArcaOS platform. For the moment my interest was only to understand a little more about the process of compiling a driver and not learning about how to code or programming a driver.

==Finding the right sample==
I got a suggestion at the OS2World forum to look at a driver sample created for a Warpstock 1999 workshop. The sample was created by [[Frank Meilinger]], and it is called "OS/2 Physical Device Driver Development. A workshop about OS/2 PDD development" [http://www.os2world.com/forum/index.php?action=dlattach;topic=1591.0;attach=2241]. I recommend reading it. 

==Compiling Driver1==
For the moment, my goal was to build "driver1.zip" from Frank Meilinger's samples. The goal is simple, from the source code that you have there you need to generate a "driver1.sys" that will work (show some text) when ArcaOS boots.

===Requirements===
* Install the OS/2 Toolkit - "yum install os2tk45*"
* Get the [[OS/2 Device Driver Kit On-Line|IBM DDK package]] and install it.
* Unzip the driver1.zip from the tutorial. [https://hobbes.nmsu.edu/download/pub/os2/dev/samples/drivers/Warpstock99_Workshop_1999-10-05.zip]

===Preparing the Environment===
There is are some work to do to prepare the environment for the first time. Since this is a 1999 driver, it uses the "classic" IBM and Microsoft tools to build a device driver. You will require:
* '''Microsoft [[nmake.exe]]''' from the IBM DDK. I was able to find the 2.001.000 Jan 28 1994 version. 
* '''Microsoft [[LINK.EXE (Microsoft Segmented-Executable Linker)|Link.exe]]:''' ArcaOS 5.0.1 shipped with version 5.10.005. It is already on C:\OS2.
* '''Microsoft [[mapsym.exe]]:''' I got it from the OS/2 Toolkit rpm package (os2tk45-utils)
* '''Microsoft [[masm.exe]]''' from the IBM DDK. It is the assembler (some driver source code is in assembly language)
* '''Microsoft [[cl.exe]]''' from the IBM DDK.

====Source Code====
The source code of the driver1 is composed by the following files:
* driver1.c
* driver1.def
* makefile
* startup.asm
The rest of the files like driver1.sys, obj, cod, lst, sym and map are generated during the build process, you may move them to some other place or delete those for the moment. 

====Environment Paths====
You need to update the '''env.cmd''' file to make sure you are pointing everything to the right places. In my case, I created an env2.cmd file like this:
<code>
 set ddk=H:\ddk
 set apath=%ddk%\toolkits\MASM
 set cpath=%ddk%\toolkits\msc60
 set path=%cpath%\binp;%apath%\binp;%apath%\binb;%ddk%\tools;%ddk%\base\tools;%path%
 set include=%ddk%\base\h;%ddk%\base\inc;%include%
 set lib=%cpath%\lib;%ddk%\base\lib;%lib%
</code>
I think it is almost self-explanatory where I put the stuff from the DDK, which is the complex thing to organize since it is not as easy as to install it from an RPM/YUM repository. 

Be sure to do not have a conflict path with "link.exe" since "H:\ddk\toolkits\MASM\binp" includes an old one. Just rename it to link.old.

===Let's Compile===
The makefile is just a script that make it easy to compile your project, even that it takes away the magic for compiling software, it is very useful once you only want to focus on the driver development instead of the compiling process.

So let's try it and see if it compiles:

From your driver1 directory, open an OS/2 command line session.

[[image:Driver1-001.png|400px]]

Run env2.cmd.

[[image:Driver1-002.png|400px]]

Run NMAKE. It will just grab the makefile file and start the compiling procedure.

You will get a message like:
<PRE>
	masm -Mx -e -t -l -N startup;
 Assembling: startup.asm
	cl -c -Asnw -Gs -G2 -Zl -Zp -Ox -Fadriver1.cod driver1.c
driver1.c
	link /nod /map /far startup.obj+driver1.obj,driver1.sys,driver1.map,dhcalls.lib+slibcep.lib+os2386.lib,driver1.def

Microsoft ® Segmented-Executable Linker Version 5.10.005
Copyright © Microsoft Corp 1984-1989.  All rights reserved.

	mapsym driver1.map

Operating System/2 Symbol File Generator
Version 4.00.000 Oct  4 2001
Copyright (C) IBM Corporation 1988-2001
Copyright (C) Microsoft Corp. 1988-1991.
All rights reserved.

No entry point, assume 0000:0100
</PRE>
You will find the new files that had been generated:
*driver1.sys
*driver1.map
*driver1.sym
*driver1.obj
*driver1.cod
*startup.lst
*startup.obj

[[image:Driver1-003.png|400px]]

If you install the driver1.sys on OS/2 you will see the following message at boot:

[[image:Driver1-004.png|400px]]

We have accomplished our goal to compile a driver, but I want to take some time to check the makefile file.

===Checking the Driver1 Sample Makefile===
It is good that you take some time to check the makefile file and analyse it a bit. This file is made to work with nmake.exe, so if you want to use a different make tool, you will have to change it.

Let's check some parts of the file:
 name = driver1
The name part looks easy, it defines the variable "name" that gives the "driver1" name to all the files we are generating.
<PRE>
$(name).sys: startup.obj $(name).obj
     link /nod /map /far startup.obj+$(name).obj,$(name).sys,$(name).map,dhcalls.lib+slibcep.lib+os2386.lib,$(name).def
     mapsym $(name).map
</PRE>
We have here the first action. It calls the Microsoft Linker to generate the "driver1.sys" files, but we need to put inside the .obj files that are not generated yet. It also has to links some .lib files that are necessary for the driver. That is why it is important to have the DDK files on the PATH (set lib=h:\ddk\toolkits\msc60\lib;h:\ddk\base\lib;%lib%)

It also has the mapsym to generates the driver1.sym file from the .map file.
 startup.obj: startup.asm
        masm -Mx -e -t -l -N startup;
Then it comes the generation of the startup.obj binary from the startup.asm assembler source code. It uses the masm.exe assembler.
 $(name).obj: $(name).c
        cl -c -Asnw -Gs -G2 -Zl -Zp -Ox -Fa$(name).cod $(name).c
And at the end, it uses the C compiler to create the driver.1.obj from the driver.c source code.

So this is the magic of compiling a driver.

[[Category:Driver Articles]]