Compiling a Driver Sample with IBM DDK on ArcaOS 5.0.1

From EDM2
Jump to: navigation, search

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" [1]. I recommend reading it.

Compiling Driver1

For the moment my goal was to build "driver1.zip" from the Frank Meilinger 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. [2]

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

set path=H:\ddk\toolkits\msc60\binp;H:\ddk\toolkits\MASM\binp;H:\ddk\toolkits\MASM\binb;H:\ddk\tools;h:\ddk\base\tools;%path%
set include=h:\ddk\base\h;h:\ddk\base\inc;%include%'
set lib=h:\ddk\toolkits\msc60\lib;h:\ddk\base\lib;%lib%

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.

Driver1-001.png

Run env2.cmd.

Driver1-002.png

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

Driver1-003.png

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

Driver1-004.png

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.