Compiler-Specific C Extensions

Extensions to the C and C++ languages take many forms, depending on what the extenders have in mind. The ANSI C committee includes the Numerical C Extensions Group, whose task it is to define numerical extensions to the language beyond the ones already built in. Other language extensions support particular development platforms. For example, Borland's Object Windows Library uses an extension to C++ class definition that supports the declaration of a message-response member function.

The Borland C++ compiler includes a number of other extensions to the C language that support DOS systems programming, that branch of programming that includes device drivers, memory-resident programs, and other low-level activities. To illustrate the use of the extensions, I'll describe TSRPLUS, a public-domain swapping terminate-and-stay-resident (TSR) driver that compiles with all versions of Borland and Turbo C. It is the resident part of a TSR application that swaps the memory of the interrupted program for the TSR application's image, executes the TSR application, and swaps the original program back in. The source code includes the TSRPLUS driver and a brief application program to serve as an example. Because of its length, the source to TSRPLUS is not printed in this issue, but is available electronically under the filename TSRPLUS.ARC.

Note that this article is not a treatise on portable code. The code that you write with these techniques is completely nonportable to other computer architectures and other operating systems. It is mostly nonportable to other compiler products. And in some rare cases, it is potentially nonportable to past and future versions of Borland C (BC). When you do systems programming this close to the hardware and operating system, portability is the least of your concerns. Similarly, this discussion does not address how TSRs work. There are a number of good works on this subject. An understanding of what allows a TSR to pop up and what rules it must obey is helpful here but not necessary. Where I discuss those issues, it is only to illustrate how I have used the language extensions of Borland C++ to solve their problems. You can learn about TSRs in several of my books and in Andrew Schulman's more recent and comprehensive Undocumented DOS (Addison-Wesley, 1990).

Most of the BC systems-programming extensions have been in the compiler since the first version of Turbo C. They provide the programmer with close access to the hardware, BIOS, and operating system. The extensions include register pseudovariables, inline functions, the interrupt function type, and inline assembly code. With them, a programmer can avoid most of the assembly language functions that systems programs normally must call when standard C can neither reach the hardware nor meet the timing performance requirements of the problem at hand.

BC and other compilers include functions that support access to BIOS and DOS in their runtime libraries. These include such functions as int86, bioskey, getvect, and so on. There is no standard for the types, names, and parameters of these functions, but the BC library includes versions compatible with their earlier compilers as well as versions compatible with Microsoft C. Why use language extensions instead of the library functions? In most cases you can achieve the same results by using the language extensions, and you will have smaller, faster code. Sometimes you want to do something for which there is no library function. Some library functions reference other functions or global variables that force other object modules to be linked as a side effect, if not in the latest version of the compiler, then perhaps in a future version. This can cause the executable code to be larger than it needs to be. Using the language extensions can bypass such side effects. Some library functions depend on features provided by the start-up code, such as stack, heap, and environment variable pointers. Later, we'll replace the startup code to get the smallest possible program, and we will not use those things. Calling some library functions from this program would result in unresolved references when you link.

BC's register pseudovariables are fixed variables that directly address the microprocessor's registers. Their names include _AX, _BX, _ES, _FLAGS, and so on. You can assign an integral value--including address segments and offsets--to one of these pseudovariables, which puts the value into the corresponding hardware register. You can use a pseudovariable in an expression, and its contents are treated as if they came from an unsigned int.

When would you want to use register pseudovariables? A common use is to send parameters to interrupts and to read the results that interrupts return in registers. We will do some of that later. But you must be careful. The compiler assumes not only that you know what you are doing but that you know what it is doing as well. The compiler itself uses registers in many different ways. Your use of a register and the compiler's use of the same register must not conflict. In some cases, the compiler is smart enough to see that you are using registers and it will avoid their use. For example, the compiler can use hardware registers for automatic variables. If you use the corresponding register pseudovariables, the compiler will decide not to use them and will put the automatic variables on the stack frame or in registers that you do not use.

  (a)
  _AX = 123;
  _ES = _DS;

  (b)
  mov ax,123
  push ds
  pop es

  (c)

  mov ax,123
  mov ax,ds
  mov es,ax

  (d)
  _ES = _DS;
  _AX = 123;

BC has several macros that generate inline code. With them you can directly access memory, interrupts, and hardware devices. The compiler generates inline code for the machine instructions that perform the tasks of the macros.

  _AH = 0x48;             // Allocate memory function
  _BX = 10;               // # of paragraphs to allocate
  geninterrupt (0x21);    // call DOS
  if ((_FLAGS & 1) == 0)  // test carry bit
      segment = _AX;      // segment of the allocated block
  else
      // ... error ...

The inport, inportb, outport, and outportb macros read and write hardware I/O ports. Their most common use is to access the interrupt controller and read the keyboard port. If you are using BC to write a device driver for a custom hardware device, you could make extensive use of these macros.

  disable();
  _SS = oldss;   // interrupts must not occur now
  _SP = oldsp;   // otherwise SS and SP will be wrong
  enable();

There are macros that allow you to retrieve and write the contents of memory by direct access to the memory address. They are the peek, poke, peekb, and pokeb macros. With them you specify the segment and offset of the address. The peek and peekb macros return the contents of the memory word or byte. The poke and pokeb macros accept a word- or byte-value parameter that they write into the memory location. You will use these macros primarily to read and write video memory and the BIOS data areas. There are other far locations that you will need to read and write, such as DOS memory blocks, and you will usually use far pointers or the movedata function to access them.

  (a)
  void interrupt (*oldISR)(void);
  oldISR = getvect(VECTOR);
  setvect(VECTOR, newISR);

  (b)
  (*oldISR)();

  (c)
  setvect(VECTOR, oldISR);

The interrupt-function type tells the compiler to compile the function as an ISR. An interrupt function assumes that it is being called as the result of an interrupt, perhaps from an unrelated process. It may assume nothing about the values of registers. Therefore, upon entry, the interrupt function pushes all the registers on the stack, initializes the DS register to point to the program's DGROUP segment, and sets up the stack frame in the BP register. Upon exit, the interrupt function pops all registers from the stack and executes the iret machine instruction to return to the interrupted location.

Often an ISR needs to read the values of registers to get its parameters and needs to return its results in registers. Up to a point, you can read the parameters with the register pseudovariables. This works only as long as the compiler does not use the same registers itself. You cannot return values from the ISR by writing to the register pseudovariables because the interrupt function pops the original values into the registers just before it returns.

  (a)
  typedef struct {
      int bp,di,si,ds,es,dx,cx,bx,ax,ip,cs,fl;
  } IREGS;

  (b)
  void interrupt newISR(IREGS ir)
  {
     // ...
  }

  (c)
  if (ir.ax == 5)
      // ....

  (d)
  ir.ax = 3;    // return 3 in ax
  ir.fl |= 1;   // return the carry bit on

When the return sequence pops the values back into the registers, these new values will go from the structure on the stack frame into the machine registers.

  (a)
  void interrupt newISR(IREGS ir)
  {
     // do some processing that might change registers
     _AX = ir.ax; // restore the registers that the old ISR needs
     _BX = ir.bx;
    (*oldISR)();  // chain to the old isr
  }

  (b)
  void interrupt newISR(IREGS ir)
  {
     (*oldISR)();          // chain to the old isr
     ir.ax = _AX;          // caller will get ax
     ir.fl = _FLAGS;       // and the flags
  }

  (c)
  void interrupt newISR(IREGS ir)
  {
     void interrupt (*tmpISR)();
     tmpISR = oldISR; // use function pointer on the stack
     _DS = ir.ds;     // reset DS
     (*tmpISR)();      // chain to the old isr through tmp ptr
  }

  (d)
  void interrupt newISR(IREGS ir)
  {
     void interrupt (*tmpISR)();
     int oldds = _DS; // save ISR's DS
     tmpISR = oldISR; // use function pointer on the stack
     _DS = ir.ds;     // reset DS
     (*tmp ISR)();    // chain to the old isr through tmp ptr
     _DS = oldds;     // reset DS
     // ... do further processing
  }

BC recognizes the asm keyword, which tells it that the statement is an assembly language instruction. The compiler inserts the instruction into the object code. You can use the names of C variables in these instructions, and the compiler will generate the proper references. You may not use the asm keyword to declare a variable or access things like DGROUP. As with register pseudovariables, you must know what you are doing when you use inline assembly code.

Now we will put these techniques to use. The accompanying program is an example that uses the principles we have been discussing. It is a swapping TSR driver program called TSRPLUS. I originally developed its concept in 1989 and published it in a book called Extending Turbo C Professional. Since then, I have modified the program several times and used it in many programs. There are several versions of TSRPLUS, each of which handles the swapping problem differently. This version installs a 5K TSR driver program that swaps in a much bigger pop-up application when the user presses the hot key.

A swapping TSR consists of two pieces: the permanently resident TSR driver and the transient pop-up application image. The resident part watches the keyboard interrupt for the hot key and manages memory swapping. The transient part does the job of the pop-up application. The swap file can be any mass storage medium. If you can use EMS, XMS, or a RAM disk, the swapping operation is faster. If you use a disk file, the swapping operation will take longer, depending on the sizes of the pop-up application image and interrupted program.

The pop-up application image and the swapped-out interrupted program include copies of the interrupt vectors. This is because an interrupt vector might have been hooked by and point into the program that you are going to temporarily replace. If you do not restore the interrupt vectors to a condition compatible with the pop-up program and the hooked interrupt occurs, the system will crash.

The pop-up application program is a normal DOS program that does not use any of the DOS functions from 0 to 12 and does not spawn other programs by calling DOS. It links with a module that allows it to register itself with the TSR driver program as a pop-up program. The module supplies the program's main function. The program must provide three functions: one for any initialization code that the program needs and that calls the register function; one to be executed upon pop-up from the hot key; and one to be executed if the user runs the pop-up program from the command line without the TSR driver being resident.

Other than those differences, the pop-up application program looks like any other DOS program. It is an .EXE file that will execute as a command-line program or that can be a pop-up.

You load the swapping TSR program into memory by running the TSR driver program. It sets itself up to be a TSR and then calls DOS to execute the pop-up program. DOS loads the pop-up program into memory just above the TSR driver. The pop-up program does its initialization and then calls into the TSR driver to register itself. The registration includes a far pointer to the application's pop-up entry address. The TSR driver writes the pop-up program's image and the current interrupt vectors to the swap file. The driver returns to the pop-up program, which exits, returning to the TSR driver. The TSR driver terminates, declaring itself resident.

When the user presses the hot key, the TSR driver handles all the tests and context switching necessary to pop up a TSR. Then it swaps the interrupted program from memory to the swap device, reads the pop-up application image into memory, and calls the pop-up application to execute. When the pop-up application returns to the TSR driver, the driver reads the swapped image of the interrupted program back into memory and returns to the interrupted location.

There are two ways to swap memory. One way swaps just as much memory as the pop-up program needs. This method leaves the DOS memory control block chain in disarray as long as the pop-up program is running. The pop-up program cannot allocate any DOS memory when you use this technique. The other way swaps the entire memory-control block chain-out. If you are at the DOS command line when you press the hot key, very little memory swaps out. If you are running a large program, a lot of memory swaps out. The pop-up program loads up to and including its terminating MCB. It can, therefore, allocate and deallocate DOS memory while it is resident. The example program uses this strategy.

When the pop-up program first runs, it tests to see if the TSR driver is resident. If so, the pop-up program registers itself in the manner just described. If not, it can run as a DOS command line program. To the user, the only difference is the way that the program is executed. This approach allows the same .EXE file to work in the TSR environment, from the command line, or in a window of a multitasking environment such as Desqview or Windows.

The memory organization of a C program and the memory requirements of a TSR are incompatible. The typical C program consists of all the code, followed by all the data, followed by the heap and stack. A TSR contains initialization code and resident code. Ideally , you would release the memory occupied by the initialization code to DOS when the TSR issues the terminate-and-stay-resident function call. TSRs written in assembly language can do that with little trouble. To get the same effect in C requires some manipulation of the startup code and the order in which things link.

Borland C's startup code does a lot of things for you. It sets up the heap, the stack, the global variables, the divide-by-zero handler, the pointer to the environment variables, the arguments to main, the file-handle table, and the external uninitialized data space. After everything is set up, the startup code calls your main function. When the main function returns, the startup code cleans every thing up, tests for null-pointer assignments, and returns to DOS. In the process of doing all this, the startup code declares some public variables and procedures and refers to some others from the runtime library.

You get the source code to the startup code with the compiler. It is in a file named C0.ASM. Most of what it does is not necessary for the TSR-driver program. The TSR driver does not use a heap, parses its own command-line arguments, and finds its own environment variables. Therefore, the TSR driver uses a highly modified version of the startup code, C0T.ASM. The modified startup code declares the program's starting address, sets up the segment registers and the global _psp variable, sets the external uninitialized data space to 0s, and calls the main function. That's all it does, because that is all the TSR driver needs in the way of startup code.

The TSR executes its initialization code and retains only the resident part when it becomes a resident program. This is not so easy because the compiler and linker organize all the code ahead of the data. To separate the initialization code from the resident code and retain the data segment for the resident program, you must first change the order in which the linker builds the segments. You need the stack and data to come ahead of the code. That way you can truncate the initialization code without losing any of the data space.

The linker determines the order of segments based on the order of their declaration in the first object file it encounters. Remember that we changed the startup code. That code will not be the first module seen by the linker because the startup code is toward the end of the code segment so that its memory is returned to DOS.

  _data    segment para public 'data'
  _data    ends
  _bss     segment word public 'bss'
  _bss     ends
  _bssend  segment byte public 'bss'
  _bssend  ends
  _stack   segment stack 'stack'
  _stack   ends
  _text    segment byte public 'code'
  _text    ends

  tsr.exe : tsr.obj emm.obj xms.obj int2f.obj tsrinit.lib
    tlink /m /s int2f emm xms tsr,tsr.exe,tsr,$(CLIB) tsrinit

  tsrinit.lib : c0t.obj tsrinit.obj emminit.obj xmsinit.obj init.obj
    tlib tsrinit +tsrinit.obj +c0t.obj +emminit.obj +xmsinit.obj +init.obj

The makefile says that the TSR.EXE program depends on the object files that constitute the resident part of the TSR driver program and the tsrinit.lib library file. The TSRINIT.LIB file contains the object files for the TSR driver's initialization code. The TSRINIT.OBJ file must be first, and the INIT.OBJ file must be last in this library. These files, besides anything else they might contain, have the addresses of the beginning and end of the initialization code.

The tlink command links the resident code first, then searches the C runtime library, and finally searches the TSRINIT library. This sequence arranges the source modules in the code segment the way we want them.

You run the TSR driver program from the command line and it loads the swapping pop-up application. The TSR driver has several command line switches that modify its behavior. These are: -x, don't use XMS for the swap file; -e, don't use EMS for the swap file; and +p<path>, the DOS path for the disk swap file.

If you use -x and -e and do not specify a path, the TSR driver will write the swap file to the subdirectory specified by the TEMP environment variable.

  (a)
  if (_CS > 0xa000) {
      dispstr("\a\r\nCannot loadhigh");
      return;
  }

  (b)
  EXTERN struct vectors {
      int vno;
      void (interrupt **oldvect) (void);
      void (interrupt *newvect) (void);
  } vectors[] =    {
          {TIMER,      &oldtimer,  (void interrupt (*)())newtimer},
          {INT28,      &old28,     (void interrupt (*)())new28},
          {KYBRD,      &oldkb,     (void interrupt (*)())newkb},
          {DISK,       &olddisk,   (void interrupt (*)())newdisk},
          {VIDEO       &oldvideo,  (void interrupt (*)())newvideo},
          {TSRPLUSINT, &old2f,     (void interrupt (*)())new2f},
          {0,          NULL,       NULL}};

  #define newvectors(vecs)                   \
  {                                          \
      register struct vectors *vc = vecs;    \
      while (vc->vno)    {                   \
          *(vc->oldvect) = getvect(vc->vno); \
          setvect(vc->vno, vc->newvect);     \
          vc++;                              \
      }                                      \
  }

There is an equivalent oldvectors macro that restores interrupt vectors from the table. The program uses another table to hook and restore the critical interrupt, break, and ctrl+c interrupt vectors.

  /* ------ compute program size ------- */
  highmemory = _CS + ((unsigned)&codeend / 16);
  sizeprogram = highmemory - _psp;

  /* ------ adjust MCB for TSRPLUS ------- */
  _ES = _psp;
  _BX = sizeprogram;
  _AX = 0x4a00;
  geninterrupt(DOS);

The program computes its new size by adding the paragraph address of the codeend label--the last entry in the code segment--to the value in the code-segment register. That value is the segment address of the top of the program. By subtracting the address of the PSP from the high address, the program computes the minimum paragraph size in which it can execute. By telling DOS to reduce itself to that size, the program assures that the next program run will load as close to it as possible.

Next, the TSR-driver program uses the DOS 0x4b function to execute the pop-up application program. The pop-up application program was linked with the tsrbuild.c code, which calls the TSR-driver program with a 0x2f interrupt to register itself. It passes the address of a structure that contains its entry point and PSP address. The TSR-driver program records this information and makes a copy of the pop-up program's interrupt vectors and program image on the swap file. It returns to the pop-up application which terminates, returning control to the TSR-driver program.

  (a)
  sizeprogram = _CS+((unsigned) main >> 4)-_psp;
  if ((unsigned) main % 4)
      sizeprogram++;

  (b)
  _DX = sizeprogram;
  _AX = 0x3100;
  geninterrupt(DOS);

  /* ----- keyboard ISR ------ */
  static void interrupt newkb(void)
  {
      unsigned char kbval = inportb(0x60);
      if (!hotkeyhit && !running)    {
          if (Keymask && (peekb(0, 0x417) & 0xf) == Keymask)
              if (Scancode == 0 || Scancode == kbval)
                  hotkeyhit = TRUE;
          if (hotkeyhit)    {
              /* --- reset the keyboard ---- */
              kbval = inportb(0x61);
              outportb(0x61, kbval | 0x80);
              outportb(0x61, kbval);
              outportb(0x20, 0x20);
              return;
          }
      }
      (*oldkb)();
  }

  intsp = _SP;
  intss = _SS;
  _SP = tsrsp;
  _SS = tsrss;

To swap the interrupted program and the pop-up application program, the TSR driver uses this sequence: It writes the interrupted program's memory to the swap file. Then it writes the system-interrupt vector table to the swap file. Next it reads the pop-up application program's interrupt vector table. Finally it reads the pop-up application program's program memory. This sequence is critical. The swapping input/output operations could enable interrupts. If the new code is in memory along with the old interrupt vectors, an unexpected interrupt could jump to the wrong place.

After the pop-up application program is swapped into memory, the TSR-driver program executes it by calling through the far interrupt pointer that holds the address of the application's entry location. That code is in the source file tsrbuild.c that the application links with. It does a similar context switch between the stacks, DTAs, and PSPs of itself and the TSR-driver program, and then it executes its application. When the application returns, the program switches the context back and returns to the TSR-driver program.

When the pop-up application returns to the TSR-driver program, the driver swaps the interrupted program back in, swapping the code first and then the interrupt vectors. Once again, this sequence is critical. The code for the interrupted program's ISRs must be in place before any interrupt vectors point to it. Next, the TSR driver switches the context of the PSP, DTA, and the stack, and returns to the interrupted program.

The pop-up application program decides when to unload itself. It calls the TSR driver through the 0x2f interrupt with a function code that says the driver should unload itself. The driver sets a flag. When the pop-up application returns to pop down and after the driver has swapped the interrupted program back in, the driver tests to see if it can unload itself. That test makes sure that all the interrupt vectors are the same as they were when the TSR driver declared itself resident, and that there is no program loaded above the TSR driver in memory. In other words, the TSR-driver program can unload only when the TSR was popped up from the DOS command line and only when no other TSR programs are loaded above it. The test uses the peek and peekb macros to walk the DOS memory-control block chain and uses getvect to compare the contents of the interrupt vectors with their earlier values.

Sometimes you cannot get by without some assembly language. We've already discussed the startup code. There are two other assembly language modules that the TSR driver uses. You saw how the INT2F module controls the placement of segments. It also provides the ISRs for the 0x10 and 0x2f interrupts. These interrupts use registers in ways incompatible with the interrupt function. The assembly language ISRs chain to the old ISRs without disturbing register integrity.

The INIT module provides the _code-end variable, and it provides a function that copies the chained 0x10 and 0x2f interrupt vector contents into interrupt-function pointers in the code segment's address space. This allows the TSR driver's assembly language ISRs to chain without needing data-segment references to the pointers.

You debug the pop-up application program as a DOS command-line program by using the source-level debugger. I debugged the TSR driver by using Turbo Debugger with the load and execute of the overlaid pop-up application stubbed out. I debugged those parts in the old way--by displaying messages on the screen at critical places in the program. It was slow, but sometimes that's the best or only way.

Finally, the TSRPLUS source code includes an example pop-up application program. It is a simple D-Flat application, which means that it uses the user-interface library that I have been publishing in Dr. Dobb's Journal for the past year. Its purpose is to show you how to use the TSRPLUS driver. It doesn't do anything other than pop up and down and let you remove it from memory with a menu selection. Link it with the D-Flat library, version 12 or greater.

Copyright © 1992, Dr. Dobb's Journal