Compiling a Driver Sample with IBM DDK on ArcaOS 5.0.1

By 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 bit 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". 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 IBM DDK package and install it.
 * Unzip the driver1.zip from the tutorial.

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: 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: The rest of the files like driver1.sys, obj, cod, lst, sym and map are generated during the build process, you may move them some other place or delete those for the moment.
 * driver1.c
 * driver1.def
 * makefile
 * startup.asm

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 and env2.cmd file like this: 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 a 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 an 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.



Run env2.cmd.



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

You will get a message like:  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 (R) Segmented-Executable Linker Version 5.10.005 Copyright (C) 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  You will find the new files that had been generated:
 * driver1.sys
 * driver1.map
 * driver1.sym
 * driver1.obj
 * driver1.cod
 * startup.lst
 * startup.obj



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



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 analyze it a little 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.  $(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  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.