Compiling KLH10

Introduction

This is a brief guide to compiling Ken Harrenstien's KLH10 PDP-10 simulator. It was written on an AMD64 Gentoo machine with 2GB RAM and gcc 4.5.3-r1. The author currently has a bad cold, so please excuse any mistakes/foolishness caused by light-headedness.

I was satisfied with using SIMH to run MIT's ITS operating system, but there was an annoying bug: the reported time of the system looped endlessly over three hours, and did not seem to keep proper time. Was the clock running too fast? It seemed to be okay, but something was amiss with the way that ITS reads the clock. In an effort to narrow down the cause, I decided to get KLH10 running and see if it exhibited the same problem. I have not found an answer yet.

Useful links

1. Viktor Björn's tutorial 'Some notes on setting up an ITS system'
2. 'Setting up an ITS system today'

Requirements

This tutorial assumes that you are running a Linux system with a modern version of gcc. Some of these instructions will not apply to your system, or may differ. I am using a current Gentoo system, as of February 2012. The system has been configured as a 'multilib' configuration, with a mixture of 32- and 64-bit. By default, gcc compiles for 64-bit.

Compilation

Step 1: obtaining the KLH-10 source. There are two places that you can get the source, but I recommend using the Panda source, which you can download at [1]. As mentioned in Mr. Björn's tutorial, if you are using gcc 4.x or later (I am!) you need to apply this patch. I needed to apply some additional patches of my own - see later.

Step 2: unpack the source - easy: 'tar -xzf panda-dist.tar.gz'

Step 3: compile the source. I admit that here was where I got lost! The instructions (panda-dist/klh10-2.0h/doc/install.txt) tell you to:

1. Unpack the main distribution, and the auxiliary distribution (I didn't, as I don't need it yet).
2. Configure for the native platform. Again, I didn't do anything here. Perhaps I should have.
3. 'Build a KN10 from sources'. Here, I was stumped. Which sources? Where? How? (Remember, I have a cold and my brain is a bit woolly.)

The example shows:

       $ cd <distrib>/bld/<platform>
       $ make base-kl          ;;; or base-ks or base-ks-its

On my system, '<distrib>' is 'klh10-2.0h' and '<platform>' is 'lnx86' (Linux, x86) - so, I did:

       $ cd klh10-2.0h/bld/lnx86

.. but was dismayed to find a solitary file in this directory:

       -rwxr-xr-x 1 lex root 70 Feb 21  2005 00build

This contains a 'make' command:

       #!/bin/sh
       make base-kl CONFFLAGS_AUX=-DKLH10_I_CIRC=1 LDFLAGS=-static

Predictably, executing it causes make to output an error, because there is no Makefile.

       make: *** No rule to make target `base-kl'.  Stop.

Eventually, I decided to copy the command from the '00build' file, but source the Makefile.mk in the 'src' directory, two levels up (../../src/). This gave me this command:

       make -f ../../src/Makefile.mk base-kl CONFFLAGS_AUX=-DKLH10_I_CIRC=1 LDFLAGS=-static

I was happy that at this point, gcc compiled some code before aborting with a syntax error in ../../cenv.h. This was easily-fixed: edit cenv.h and find line 270.

       #   define _FILE_OFFSET_BITS=64 /* Use 64-bit file ops */

Change that to:

       #   define _FILE_OFFSET_BITS 64 /* Use 64-bit file ops */

I.e. change the '=' to a space.

Repeating the 'make base-kl ...' command should cause compilation to progress a bit further, before it aborts with an undefined reference to 'lites_init'. That function is in src/dvlites.c, and is an addition that the Panda team added: it sends the processor status over the parallel port, where it is displayed by a custom bit of hardware (a microcontroller, as designed by Spare Time Gizmos). I have almost all of the parts for this device, but alas! My computer doesn't have a parallel port, and no serial port either. I'll have to think of another way to display the CPU status, and I have thought of a few:

1. Display the CPU status as a window on the screen.
2. Send it to a file, or a pipe (to be interpreted by another application).
3. Send it over the network, to be displayed by other hardware.
4. Display it on standard PC hardware - e.g. the keyboard LEDs. Problem: there aren't many LEDs, and XKB might not take too kindly to my app stealing its control.

I've decided on '2' at present, but might do the window thing first, as I am trying to learn to program with SDL.

Back to the patching of the KLH10 code. My next edit was to add an 'extern int' declaration to src/klh10.c, edit src/dvlites.c and change '#include <asm/io.h>' to '#include <sys/io.h>', having determined that it's using the functions ioperm() and outb() to write to the parallel port.

The addition to klh10.c is at the top: find the section marked '/* Imported functions */' and add this line after the final 'extern int' of the block:

       extern int lites_init(unsigned int prt);

After one more command, the klh10 executable should compile.

       make -f ../../src/Makefile.mk base-kl CONFFLAGS_AUX="-DKLH10_I_CIRC=1 -DKLH10_DEV_LITES=1" LDFLAGS="-static"

The '-DKLH10_DEV_LITES=1' definition is required, and is also needed for other targets ('base-ks' and 'base-ks-its').

To compile all of the binaries, I used a loop that cycled through the build/clean process and at the end of the pass, copied the executables to a temporary dir ('/dev/shm/klh10_bins/'). I'm sure that there's a more-elegant way of doing this.

       for BUILD in base-{kl,ks,ks-its}; do
           make -f ../../src/Makefile.mk clean ${BUILD} CONFFLAGS_AUX="-DKLH10_I_CIRC=1 -DKLH10_DEV_LITES=1" LDFLAGS="-static"
           for a in *; do
                file "${a}" | grep -q "executable" && [ "${a}" != "00build" ] && mv ${a} /dev/shm/klh10_bins/
           done
           echo "Finished building ${BUILD}.  Press Enter to continue."
           read a
       done
       rm -f *.o

Diff files (output of 'patch -u')

The Wiki may edit these if I paste them verbatim, so I have made [them] available on my webserver (I was not able to upload them due to browser difficulties). There are four patches to files cenv.h, dvlites.c, klh10.c and kn10def.h. These include the kn10def.c patch. [Please verify]

The next stage is to create a klh10 configuration file, which the install.txt file describes as 'semi-optional'. The remaining steps are quite straightforward, so I will not list them here. The binaries are copied to $KLH10_HOME and kn10-kl (or kn10-ks) are started up, with the config file as an optional argument. If you wish to use the networking facilities of KL and KS-ITS, making dpni20 and dpimp 'setuid root' is required - see the 'INSTALLING BINARIES' section of install.txt.

Lexthehex 22:41, 25 February 2012 (PST)