KCT Passthru Interface Standard

Must Be Art > Software > DISPANG > KCT Passthru


Updated: March 1, 2002

1. Introduction

The Kansas City Tracker (KCT) by Brooks Van Pelt, KB2CST, defined a hardware-independent programming interface specification (1988) for application programs to communicate with antenna rotator drivers running under MS-DOS. This interface has been adopted by other rotator drivers and is widely used by application programs such as InstantTrack.

Paul Williamson, KB5MU, has published a number of programs (starting with the OrbitDRV TSR that is part of the InstantTrack package) that are installed on top of the KCT RotorDRV to add functions to the interface. This document describes a standardized way of doing so, in such a way that application programs can still find every TSR in the stack.

2. Technical Details 

2.1. Function Code Allocation

The standard KCT interface works through calls made to a single software interrupt vector, typically INT 63H. The function invoked is controlled by the contents of the AH register when the interrupt call is made. The following table allocates the 256 available values of the AH register:

00 - 14 hex Defined by KCT 1988 specification
15 - 3F Reserved for KCT expansion
40 - 77 Available (rotor-related extensions)
78 - 7F KB5MU extensions (FlipDRV)
80 - EF Available (extensions)
F0 - FF OrbitDRV INTSPEC by KB5MU 

Programmers using new values of AH not defined above are requested to contact KB5MU to obtain a coordinated allocation. The authoritative version of this document can be found at http://www.mustbeart.com/software/KCT-passthru.html

Extensions that install between the antenna driver and the application program should pass through all function calls, unless their purpose is to intercept that function call. In particular, unrecognized AH function codes must be passed through without change.

2.2. Identification Signatures

2.2.1. KCT-Standard Signatures

The KCT specification requires that the eight-byte (unterminated) string "RotorDRV" must appear at offset 10 (decimal) from the address pointed to by the interrupt vector. This string is used by application programs to verify that a valid RotorDRV is installed at the vector before relying on its services. In table form:

Offset (hex)

Description

00 JMP opcode
01 - 03 Destination address for JMP instruction
04 - 09 unused
0A - 11 "RotorDRV"
12 and up available for program code and variables

Or, in a typical assembly language TSR, you might find the following code:

isr:	jmp	dispatch

	ORG	isr + 10
	DB	"RotorDRV"	; signature string

dispatch proc	near
	(code to dispatch by AH code goes here)

2.2.2. Adding Version Information

Antenna drivers (or pseudo-drivers like DUMMYKCT) can add version information, which can be displayed by applications aware of this convention.

To include version information on a non-passthru driver, extend the signature as follows:

Offset (hex)

Description

00 JMP opcode
01 - 03 Destination address for JMP instruction
04 - 09 unused
0A - 11 "RotorDRV"
12 " " (space) character to introduce version information
13 - nn Short ASCII text string giving version information, e.g. "1.0.2"
nn+1 00 (null) character to terminate the version string
nn+2 and up available for program code and variables

2.2.3. Signature for a Passthru TSR

A TSR that is installed between an antenna driver and the application program should extend the signature as follows:

Offset (hex)

Description

00 JMP opcode
01 - 03 Destination address for JMP instruction
04 - 07 Address of previous TSR, copied from the interrupt vector table before installing our own address there
08 - 09 unused
0A - 11 "RotorDRV"
12 "+" (plus sign) character to introduce extension signature
13 - 13+L L-byte unique signature for your extension, e.g. "FlipDRV"
13+L+1 " " (space) character to introduce version information
13+L+2 - nn Short ASCII text string giving version information, e.g. "1.0.2"
nn+1 00 (null) character to terminate the version string
nn+2 and up available for program code and variables

Here is typical assembly language code:

isr:    jmp     dispatch

        ORG     isr + 4
old_isr DD      ?                         ; old RotorDRV address

        ORG     isr + 10
sig:    DB      "RotorDRV+FlipDRV 1.2.3"  ; substitute signature string
        DB      0

dispatch proc   near
	(code to dispatch by AH code goes here)

The installation code for the TSR would store the old vector in the location labeled old_isr, as follows:

        mov     ah, 35h                   ; get vector service
        mov     al, vector
        int     21h
        mov     WORD PTR old_isr,bx       ; save it for passthru
        mov     WORD PTR old_isr+2,es

Note that the installation code should then check that the "RotorDRV" signature is present at offset 0A from the address in ES:BX, to verify that the old ISR was in fact a valid KCT-compatible driver. If that signature is not found, the program should not install itself.

2.2.3. OrbitDRV Extensions

The OrbitDRV background tracking TSR provided with InstantTrack is a special case, because InstantTrack checks for it explicitly before enabling certain features. InstantTrack does not follow the chain of installed TSRs while making this check (though it probably should). It expects OrbitDRV to be the last TSR installed on the vector.

Most extensions should be installed between the antenna rotator driver and OrbitDRV, so there would be no problem. If an extension needs to intercept calls to OrbitDRV, however, it must be installed after OrbitDRV. Here is a kludgey but compatible way to do that:

Offset (hex)

Description

00 JMP opcode
01 - 03 Destination address for JMP instruction
04 - 07 Address of previous TSR, copied from the interrupt vector table before installing our own address there
08 - 09 unused
0A - 1A "RotorDRV+OrbitDRV"
1B "+" (plus sign) character to introduce extension signature
1C - 1C+L L-byte unique signature for your extension, e.g. "StrangeDRV"
1C+L+1 " " (space) character to introduce version information
1C+L+2 - nn Short ASCII text string giving version information, e.g. "1.0.2"
nn+1 00 (null) character to terminate the version string
nn+2 and up available for program code and variables

However, this method is less than ideal. It doesn't scale well, and it hides OrbitDRV's version information from InstantTrack. If you are creating an extension that installs on top of OrbitDRV, please contact me. I will fix InstantTrack and ITRACK so you don't need to use this ugly scheme.


Copyright 2002 Paul Williamson. Comments to kb5mu@amsat.org