Inline assembly with Watcom

In a previous post, I’d started talking about the Open Watcom compiler and its usage in the DOS environment. In today’s post, I’m going to walk through writing assembly code inside of your C/C++ that you’ll compile with the Watcom compiler.

Using the DOS api

When it comes to basic interrupt invocation or I/O port work, there’s no reason why the API provided by the dos.h header won’t suffice. It’s allows you to write C code, but directly invoke I/O ports and interrupts. Once you want to perform some custom logic, you’ll be reaching for planting assembly code directly into your code.

Here’s an example using the dos.h api. In this example, we’re going to request a key press from the user using keyboard service’s int 16h and print out the captured scan and ascii codes:

#include <stdio.h>
#include <dos.h>

int main(int argc, char *argv[]) {

  union REGS r;

  /* ah = 00h, int 16h "read key stroke" */
  r.x.eax = 0x0000;
  int386(0x16, &r, &r);

  /* write the results to stdout */
  printf("scan code = %d\n", r.h.ah);
  printf("ascii     = %d\n", r.h.al);

  return 0;
}

The call to int386 takes a register set as inputs and outputs, so that we can see the CPU state after the interrupt was executed.

Inlined

So, what does that look like inlined?

#include <stdio.h>

int read_key_stroke();
#pragma aux read_key_stroke = \
"int 0x16"                    \
value [eax];

int main(int argc, char *argv[]) {

  int key = read_key_stroke();
 
  /* extract the ascii & scan code */
  int ascii = key & 0xff,
      scan = key >> 8 & 0xff;

  /* write the results to stdout */
  printf("scan code = %d\n", scan);
  printf("ascii     = %d\n", ascii);

  return 0;
}

Without needing to manage the registers anymore, we’ve cleaned up a little bit of the code. There is a little bit of alien syntax to deal with though.

#pragma aux

The basic structure of an inline assembly function using the #pragma aux syntax goes like this:

#pragma aux name_of_your_function =
. . . assembly code in here . . .
modify [ regs ]
value [ reg ]
parm [ regs ]

You start your function off optionally with a header definition. It’s been omitted in this example, but I’ve added one above for read_key_stroke.

The assembly code itself gets quoted and then terminates with three optional instructions.

modify allows you to tell the compiler which registers are going to get clobbered when the function runs. This is so it can do the appropriate save management of these registers to the stack.

modify [ eax ebx ecx ]

This line says that eax, ebx and ecx all get clobbered when this function runs.

value allows you to nominate which register has the return value in it.

value [ eax ]

This line says that the return value is in eax. As with read_key_stroke above, the value of eax is then fed into the int return value for the function.

parm allows you to nominate registers that will take the values of parameters passed in.

parm [ eax ] [ ebx ] [ ecx ]

If we were to implement a function that performs addition, we’d need two arguments to be passed in:

int add_ints(int a, int b);
#pragma aux add_ints =  \
"add  eax, ebx"         \
parm  [ eax ] [ ebx ]   \
value [ eax ];

Passing parameters is fairly straight forward. You’re free to use EAX, EBX, ECX, EDX, EDI and ESI but you are not able to use EBP.

Building libraries using Open Watcom

Being able to bundle blocks of your code (and data to some extent) into library files is quite a productive step forward when developing applications. Being able to port these pieces around means a higher level of code-reuse, and a less number of times you’ll spend re-writing the same stuff.

In today’s post, I’ll take you through creating a very minimal library. We’ll create a library module from this code and I’ll also show you how to consume it.

Howdy!

Our example library will expose one function, called greet. greet will take in a person’s name and will print a greeting to the console. Here’s the header:

/* greeter.h */

#ifndef __greeter_h_
#define __greeter_h_

#include <stdio.h>

void greet(const char *name);

#endif 

The implementation is basic. It doesn’t even really matter, but is included for completeness:

/* greeter.c */

#include "greeter.h"

void greet(const char *name) {
  printf("Greetings, %s!", name);
}

Make me a library

Making a library is all about compiling your code to produce object files and then bundling your object files into a library file. So, the first step is to compile greeting.c into an object file:

C:\SRC> wcc386 greeter.c

After this, you’ll now have GREETER.OBJ in your project folder. You can turn this into a library with the following:

C:\SRC> wlib greeter +greeter

The command itself says invoke wlib to create (or modify) a library called greeter (the .lib extension is handled for us). Finally the +greeter says that we want to add greeter.obj into the library. We’ll now have a .LIB file that we can link against.

Consuming the library

Writing code that actually uses the library is as easy as including the header and calling functions. Here’s a test:

/* test.c */

#include "greeter.h"

int main(int argc, char *argv[]) {
  greet("Joe");
  return 0;
}

Converting this into a callable executable is achieved with `wcl386’.

C:\SRC> wcl386 test.c greeter.lib

That’s all there is to it.

32bit DOS Development with Open Watcom

The Watcom Compiler is an open source C & C++ compiler that has a very successful history when it was discovered that the DOOM developers were using it. That was a very long time ago, but that shouldn’t stop us having a go!

Installation

I’ve grabbed the dos bundle from the Open Watcom FTP site and installed it into DosBox. The only problem with this setup, it that I much prefer to use a text editor that’s outside of the DOS environment (like emacs/sublime, etc.) DosBox sometimes has a bit of difficulty picking up file system changes that have been mounted in.

Shift + Ctrl + F4 (documented as just Ctrl + F4) forces DosBox to refresh its mounts.

Very handy.

The Tools

There are a bucket of binaries that are bundled with the installation.

For convenience, we’ll use wcl386.exe as this will perform the compilation and linking step in one for us.

Compiling and Linking

Prior to compilation and linking, things will go a lot smoother if you’ve prepared your environment variables correctly.

SET PATH C:\WATCOM\BINW;%PATH%;
SET INCLUDE=C:\WATCOM\H;
SET WATCOM=C:\WATCOM
SET EDPATH=C:\WATCOM\EDDAT
SET WIPFC=C:\WATCOM\WIPFC

Open up your favorite editor and create a hello world application, called hello.cpp.

#include <stdio.h>

int main(int argc, char *argv[]) {
  printf("Hello, world!\n");
  return 0;
}

Now build it with wcl386.exe:

C:\SRC> wcl386 hello.cpp
Open Watcom C/C++32 Compile and Link Utility Version 1.9
Portions Copyright (c) 1988-2002 Sybase, Inc. All Rights Reserved.
Source code is available under the Sybase Open Watcom Public License.
See http://www.openwatcom.org/ for details.
  wpp386 HELLO.CPP 
DOS/4GW Protected Mode Run-time  Version 1.97
Copyright (c) Rational Systems, Inc. 1990-1994 
Open Watcom C++32 Optimizing Compiler Version 1.9
Portions Copyright (c) 1989-2002 Sybase, Inc. All Rights Reserved.
Source code is available under the Sybase Open Watcom Public License.
See http://www.openwatcom.org/ for details.
HELLO.CPP: 7 lines, included 1160, no warnings, no errors
  wlink @__wcl__.lnk
DOS/4GW Protected Mode Run-time  Version 1.97
Copyright (c) Rational Systems, Inc. 1990-1994 
Open Watcom Linker Version 1.9
Portions Copyright (c) 1985-2002 Sybase, Inc. All Rights Reserved.
Source code is available under the Sybase Open Watcom Public License.
See http://www.openwatcom.org/ for details.
loading object files
searching libraries
creating a DOS/4G executable

We can now run our application:

C:\SRC> hello.exe
DOS/4GW Protected Mode Run-time  Version 1.97
Copyright (c) Rational Systems, Inc. 1990-1994 
Hello, world

What is DOS/4GW?

To a lot of us, the DOS/4GW is a very familiar banner that we saw when we’d fire up one of our favorite games. But, what is it?

Wikipedia’s article defines its role pretty well:

DOS/4G is a 32-bit DOS extender developed by Rational Systems (now Tenberry Software). It allows DOS programs to eliminate the 640 KB conventional memory limit by addressing up to 64 MB of extended memory on Intel 80386 and above machines.

It’s the resident binary that gets packaged with your compiled application that facilitates access to the computers’ full array of resources. Without it, you’d be stuck with what DOS provides you by default.

Conclusion

Well, it’s always nice to go over this old stuff. In my next posts, I’ll cover inline assembly and mode 13/x to get a head start on writing DOS games in the 90’s!

Using FreeTDS to connect to MSSQL

In today’s post, I’ll outline the steps required to connect to a Microsoft Sql Server database from within an Ubuntu Linux environment using FreeTDS and ODBC.

Get the software

Using apt-get, we can satisfy all of the system-level requirements (libraries):

sudo apt-get install freetds-dev freetds-bin unixodbc-dev tdsodbc

FreeTDS now needs to be defined as a driver in the /etc/odbcinst.ini file.

[FreeTDS]
Description=FreeTDS Driver
Driver=/usr/lib/odbc/libtdsodbc.so
Setup=/usr/lib/odbc/libtdsS.so

Hitting the can

Now that we’ve got a driver up and running, we can use a library like sqlalchemy to run some queries. Before we can do that though, we need to install python’s odbc bindings pyodbc.

pip install pyodbc sqlalchemy

We can now start running some queries.

import urllib
import sqlalchemy as sa

cstr = urllib.quote_plus('DRIVER=FreeTDS;SERVER=host;PORT=1433;DATABASE=db;UID=user;PWD=password;TDS_Version=8.0;')

engine = sa.create_engine('mssql+pyodbc:///?odbc_connect=' + cstr)
    
for row in engine.execute('SELECT 1 AS Test;'):
    print row.Test

Using resource files in your masm projects

In a previous post we built a boilerplate program that we can start to work with. For today’s post, we’re going to go through the development of a resource file that you can incorporate into your own projects.

What are resource files?

You can use resource files to organise your external resources (images, audio, text, etc.) into a compilable (and ultimately linkable) resource. The items that you add to your resource file are then statically added to your resulting executable, ready for you to reference.

From the Microsoft site:

You should place every element of the user interface that needs to be localized in a Windows resource file, including pictures, strings, messages, menus, dialog boxes, and version information. The table below lists the individual resource elements defined by Windows.

What does a resource file look like?

The .RC file itself is just text. There are IDs that are defined throughout that you can create symbolic constants for in your code, just so you’re not doing so much “magic number” work. Here’s a simple menu:

600 MENUEX MOVEABLE IMPURE LOADONCALL DISCARDABLE
BEGIN
    POPUP "&File", , , 0
    BEGIN
        MENUITEM "&Exit", 1000
    END
    POPUP "&Help", , , 0
    BEGIN
        MENUITEM "&About", 1900
    END
END

600 in this example is the ID of the menu. Referencing this menu in your code is as simple as passing 600 to the menu name parameter of a LoadMenu call:

invoke LoadMenu, hInstance, 600
invoke SetMenu, hWnd, eax

How do I compile one?

rc.exe is the resource compiler that comes along with masm32. You give it your resource script and it’ll give you back a compiled .RES file.

rc /v rsrc.rc

You then take the .RES file that was output; in this case it was rsrc.res and feed it into another utility cvtres.exe.

cvtres /machine:ix86 rsrc.res

This utility converts your compiled .RES file into object code. It produces you an .OBJ file that you can then link into your exe.