Leo III Intercode resurrection

Colin Tully kept printouts of Leo III system software, which his widow passed onto John Daines. The objective is the digital preservation of these pieces of software from Leo III, which have only survived as line-printer listings from the Intercode Translator. Here is a listing of all of John's listings. The aim is to preserve these pieces of software in files along with newly written software that allows the preserved software to be run in emulation and also browsed on current platforms. We also have made photographs of most of the printer listings and the microcode diagrams.

Summary of emulation facilities

There are the 3 downloadable demonstrations (also see immediately below):
       LeoIIIdemo.zip
       LeoIIIdemo2.zip
       LeoIIIdemo3.zip
There is also an on-line facility which allows you to type in an Intercode program, then translate and run it.

There is also an earlier demonstration kit which allows you to run the same emulations in a command window on your own machine.

Status - September 2019

We have now added a more realistic demonstration including an emulation of the Leo III console and also the lineprinter:
       LeoIIIdemo3.zip
This gives quite a realistic demonstration of operating a Leo III, and also shows fairly convincing Leo III characters on the printer. All is revealed in the readme.htm file in the ZIP file, which is also available on-line..
It is somewhat harder to drive than LeoIIIdemo2 as it requires some Leo III operator skills, which are explained in the readme.htm file, but it gives much more of a feel of a real Leo III.
Here is a screen shot of the demo running on Windows. It has also run on ubuntu and Raspberry Pi, and even Solaris. The different windows can be on different machines, and on different operating systems.

Status - September 2015

We have now produced two demonstrations showing the rescued Leo III software in action. The neatest one is at:
       LeoIIIdemo2.zip
This does contain 2 tape images which are binary files which just might upset some anti-malware software.

An earlier version of this demonstration generates everything from plain text files and is at:
       LeoIIIdemo.zip
Each ZIP file contains a readme.htm. The emulation software is written in C, and the source text is in each of the sets of files. A Windows binary is available via a link in the readme file. The demonstrations have been run successfully on various types of system, including:
       Intel Pentium: Windows 98SE, Windows 10, FreeBSD, GNU/Linux (ubuntu)
       ARM: GNU/Linux (Raspberry Pi)
       Mac: OSX on MacBook Pro
       SPARC: Solaris (using both gcc and cc compilers)

Status - 17 June 2015

We have so far worked on the Intercode Translator (08000), the Master Routine (09001), and the Master Routine Generator Programme (08004) which customises a master routine for a particular machine configuration. We have downloadable software which enables all three of these programmes to be seen in action on any computer with an implementation of C and also on most versions of Microsoft Windows. As new progress is made, the on-line sofware is updated to reflect the current state of play.

We have also developed an on-line offering with which a user can translate an Intercode program using the original Leo Translator, and then load and run the resulting binary program.

We are now certain that the three programmes that we have worked are slightly incompatible with each other. However, after a little bit of work-around we can now load an Intercode programme under the mater routine and start to execute it. Execution comes unstuck when we call on master routine facilities for access to the printer which our emulation cannot currently handle in master mode. It seems that the incompatibilities are not as severe as we first thought.

Documentation

In addition to the surviving line-printer listings, we have quite a quantity of printed documentation. This too is being preserved digitally in a form that can be browsed on current platforms. We have scanned all the documentation, and made searchable versions using OCR coupled with manual editing. There is a separate web page on the topic of the documentation here, with links to our on-line manuals.

Executable Software

The software listings were ‘digitised” by copy-typing in duplicate from phtographs of the originals. These listings are not in the form of source code, but output from the Translator, which modifies the submitted source text. The software was developed and maintained by an editing system that held the information on magnetic tape. We have created simulated magnetic tapes that we believe are very close to the originals.

Intercode Translator

A major part of this surviving software is the Intercode Translator itself which is written in Intercode, surely an early example of a language processor written in its own language. We have bootstrapped the Intercode Translator from the printer listing.

Master Routine

We now have the master routine copy typed, and when run through the Intercode Translator (the real one, not my plastic one) it produces a listing which compares very well with the paper listing from which we started.

It is now clear that we need the Master Routine Generator Programme to process the magnetic tape produced by translation of the Master Routine. We have now copy-typed this and are in the process of trying to use it to generate a usable master routine. You can see an example of the current state of play here. When you have generated your master routine it will be awaiting an operator command. Also it will have written a magnetic tape image in a file called MT-R02.leo, which is actually the tape used to start the machine on a real Leo III. Instructions for doing this are here.

Source Code Listings

As well as executing the software, we have post-processed the listings from the Leo III software to make them accessible to a web browser, and to include links between routines, to the listing of the generated machine code, and also to the photographs of the original listings.
     08000 is the official number by which the Intercode Translator was usually known
     09001 is the all-embracing Master Routine, which is processed by ...
     08004 the Generator Programme to produce ...
     a generated master for our machine.

Translator Bootstrap

The current state of play can be accessed via the link in the status section above, but our first major milestone was the creation of an executable Intercode Translator which successfully translates itself. We now have considerable experience of using this on the master routine and its generator program and it has proven very reliable.

Here is the story of the steps in this generation process (which is part of the example accessed from the status section above):
  1. Raw material is the line printer output saved by Colin Tully. This is the output listing produced by the Intercode Translator translating itself.
  2. This was photographed, and then copy-typed using spreadsheets to produce 08000.csv.
  3. This can be processed using a specially written translator (it.c) to produce a listing that is also a binary program: demo.htm.
    This can be run with the emulator (leo3.c) to translate Intercode programs in paper tape initial translation format, such as hello.txt:
                  leo3 -d demo.htm hello.txt
  4. The binary program generated by the Intercode Translator is on the output tape MT-A2.leo. This is in a form ready for the Master Routine’s loading process. We have yet to implement the Master Routine, but the program getbin.c extracts the program from this output tape and generates a binary program in a form suitable for our emulator (leo3.c). E.G. after translating hello.txt as above, it can be executed using the sequence:
                  getbin MT-A2.leo t.bin
                  leo3 -d t.bin
    The getbin program involves reading a tape for which we have only partial documentation, in effect reverse engineering the loading proess of the Master Routine that we have yet to implement. Consequently, it produces quite a lot of diagnostic commentary on the contents of the tape.
    The -d switch used with leo3.c sends its diagnostics to a file log.txt. If you omit this switch there is some extra output on your screen. Details of the diagnostic facilities are in a comment at the head of leo3.c.
  5. The Intercode Translator can be translated using the demo.htm version of itself. The original raw material (08000.csv) is first converted to paper tape initial translation format (08000.txt) using a program mkpt.c, before running demo.htm with the emulator:
                  leo3 -d demo.htm 08000.txt
    The Intercode Translator works slightly differently in translating itself, and as a result the binary program ends up on tape MT-A6.leo. Although the binary program is also on MT-A2.leo it seems to be in a slightly different format. The suspicion is that this is something to do with the overlay mechanism. A binary version of the self-translated Translator can be generated by
                  getbin -b5000 -b8192 -b160 MT-A6.leo t.bin
    The -b5000 -b8192 -b160 switches define the location in memory of chapters 1, 2 and 3 respectively. Chapter 3 is the extra chapter generated by the translator. Chapters 4 onwards are overlaid over chapter 2. Chapter 4 in the binary program corresponds to chapter 3 in the source code.
  6. The Intercode Translator is aware of its own issue number and its behaviour depends on this number, which is always zero for an initial translation from paper tape. So we have to rename the output file as the input file and do a null amendment to enable us to set the issue number to 8 using file NullAmend.txt:
                  move MT-A2.leo MT-A1.leo
                  leo3 -d demo.htm NullAmend.txt
  7. The result of this translation is a properly functioning issue 8 Intercode Translator (probably) written on MT-A6.leo. We can extract a binary program suitable for our emulator from this by
                  getbin -b5000 -b8192 -b160 MT-A6.leo ITi.bin
  8. We can substitute ITi.bin for demo.htm in the commands above, and even have it regenerate itself, see below: 
    F:\dh\leo>leo3 -d ITi.bin 08000.txt
 8257 LOG: 08000 PROG OUT  08000      0   +PTS
11450 LOG:   08000 MAKES PASS3 COPY ON  8000
ALARM *06 for operator
1
PROGRAMME UNLOADED: ADDRESS = 11616 after 31505788 instructions
**********************************

F:\dh\leo>move MT-A2.leo MT-A1.leo
F:\DH\LEO\MT-A2.leo => F:\DH\LEO\MT-A1.leo [ok]

F:\dh\leo>leo3 -d ITi.bin NullAmend.txt
 8940 LOG: 08000  AMEND  08000     0
 8257 LOG: 08000 PROG OUT  08000    801
11450 LOG:   08000 MAKES PASS3 COPY ON  8000
ALARM *06 for operator
1
PROGRAMME UNLOADED: ADDRESS = 11616 after 22861490 instructions
**********************************

F:\dh\leo>getbin -b5000 -b8192 -b160 MT-A6.leo t.bin
File: MT-A6.leo
    3 PASS3 marker for program 08000 found
   73 ALLOC block found
   Total chaps = 11 (init 3)  files(R) = 5  Transit Areas = 5
   Enter at address 41 in chapter 2
  112 File details block (5 routes)
   File D1 type 14 -- chap 6 annex at 598 length 394
    Annex 0 is in chapter 6 - reallocated to 3
   File B1 type 15 -- chap 4 annex at 6810 length 58
   File A1 type 7 -- chap 4 annex at 6868 length 154
   File A2 type 8 -- chap 4 annex at 7022 length 154
   File A6 type 7 -- chap 4 annex at 7176 length 154
Transit area 0 is in chapter 6 - reallocated to 3

Loading
  235 CHAPTer 1 start at 5000 (progid = 08000)
  242 CHAPTer 2 start at 8192 (progid = 08000)
  454 CHAPTer 3 start at 160 (progid = 08000)
Extra chapter 3 located at 361 (param = 3840)
  456 CHAPTer 4 start at 8192 (progid = 08000)
Overlaying chapter 2 by 4
  893 CHAPTer 5 start at 8192 (progid = 08000)
Overlaying chapter 4 by 5
 1329 CHAPTer 6 start at 8192 (progid = 08000)
Overlaying chapter 5 by 6
 1687 CHAPTer 7 start at 8192 (progid = 08000)
Overlaying chapter 6 by 7
 1942 CHAPTer 8 start at 8192 (progid = 08000)
Overlaying chapter 7 by 8
 2356 CHAPTer 9 start at 8192 (progid = 08000)
Overlaying chapter 8 by 9
 2538 CHAPTer 10 start at 8192 (progid = 08000)
Overlaying chapter 9 by 10
 2544 CHAPTer 11 start at 8192 (progid = 08000)
Overlaying chapter 10 by 11
Overlaying last chapter 11

F:\dh\leo>leo3 -d t.bin NullAmend.txt
 8940 LOG: 08000  AMEND  08000     0
 8257 LOG: 08000 PROG OUT  08000    801
11450 LOG:   08000 MAKES PASS3 COPY ON  8000
ALARM *06 for operator
1
PROGRAMME UNLOADED: ADDRESS = 11616 after 22861490 instructions
**********************************

Background

We have several listings and manuals which were preserved by the late Colin Tully. These are now in the possession of John Daines.
Here is a listing of all of John's listings. Foremost among these is the Intercode Translator, which we have now preserved in digital form, including the capability for execution. Intercode is the language in which most of the system software was written (including the Master Routine), and was translated into computer code (i.e. machine code), by the Intercode Translator, which is itself written in Intercode. We have the listing produced by the Intercode Translator and it has now been copy-typed from photographs of the listing. This was done in duplicate and the two copies consolidated. The resulting type-script was bootstrapped as described above.

By November 2013, we had a digital copy of the source, and had successfully translated it into Leo III computer code, which we can execute with our emulator. Here is the output from the translator as it translates itself. We have written a post processor (modernise.c) which takes this printer output and makes a version in HTML with hot links.

The modernised output has hot links for all of the references (except for a few specials) which point to the PROCR, TABLE or CONST section in the code. This means that one can follow execution paths, and use the back button to follow subroutine exits. The latter part of the listing consists of the generated machine code (computer code) shown on a PROCR-by-PROCR basis. The number of the PROCR in this part is a hot link back to the source code, where the PROCR number on the PROCR line is a hot link to the generated code. There are also links back to the photographs of the original listing.

Resources

Here is a listing of all of the photos of the Intercode Translator, and its flow charts, also the master routine at the very end.
Here is a listing of all of the photos of the Leo III microprogrammes.

The Leo III User Manuals are here.

We used an online reservation system for choosing which pages to type. Its output can be seen here. Individual volunteers had facilities for uploading their typescripts. This is now in use for copy-typing the Master Routine.

Click here for a picture of another team of Intercode typists at Joe Lyons.

Click here to see the memory map of the sections.

Development of the Bootstrap

We built three digital components:
        1. Our double-checked copy-typing of the original Leo III software.
        2. An emulator for Leo III computer.
        3. Our interim Intercode Translator (IIT).

All three evolved in parallel. Long before the copy-typing was complete we were able to present it to IIT, and steadily extend our repertoire of Intercode instructions that we could translate. The overlaid structure of the translator meant that once the first overlay was typed we could try executing the first pass of the translation, even though the copy-typing was nowhere near complete. It was not necessary for our IIT to translate all of the Intercode language, only those parts of the language used by those parts of the Intercode Translator which are involved in translating itself.

Our Copy-typing methodology is described below. Some of the techniques are rather specific to Intercode which consists almost entirely of numbers arranged in a giant table.

We use item 1 as input to IIT, which then produces a file listing consisting of three columns. The listing of the input is in the middle, with the computer code program on the left and the descriptions of the intercode actions on the right, just as an aid to reading the code. Our emulator reads this file, loading the computer code in the left-hand column into memory.

However, now that we have the bootstrap, IIT is pretty well redundant.

Master Routine and its Generator

The translation of the master routine (09001) proved very straightforward, and the summary data at the end of the listing exactly matches that on the surviving printer listing. Similarly, the generator programme (08004) was translated without much difficulty, although its intricate overlay pattern required some tricky coding int getbin.c to get the binary program in the right parts of the store.

Early in out attempts to run the generator programme, it became clear that it was expecting to process programme 09002, whereas we have 09001. A couple of tweaks to the binary program have made it accept 09001, and generate and load the master routine. However, attempts to load programmes under the master routine have not been successful. Moreover, the initial loading mag tape produced by the generator does not work either. It is clear that we have compatibility problems.

Methods

The IIT output and the diagnostic log from the emulation are available on-line:
        Here is the IIT output.
        Here is the emulator output.

The IIT output has hot links for all of the references (except for a few specials) which point to the PROCR, TABLE or CONST section in the code. For sections, the link points to a separate file which summarises all the comments against each location. This means that one can follow execution paths, and use the back button to follow subroutine exits.

The emulator output has a choice of verbosity levels, but the man instruction-by-instruction log shows one line for each instruction. There is the instruction itself, then the unmodified address value, then register contents. All shown as they were at the start of the instruction. (The results are on the next line.) The C-register column sometimes shows the supplementary modification value, where a star indicates suppression of the division address. A final column of figures shows the value held in the relevant modification register (and sometimes the value held in an irrelevant modification register).

All our volunteers make comment by e-mail, frequently making most useful suggestions.

An early requirement is the consolidation of the memory map, using the recollections of our volunteers.

Copy-typing methodology — Filename conventions, etc

Each photo should be produced as a spreadsheet with the column names in lower case as the first record. The columns can be in any order, and only the first letter of the heading is significant (serial no, action, reference, item, descriminant, modifier, literal, comment). If you want to put any comment of your own, please include a column headed queries -- especially if you had difficulty reading the printout. The spreadsheet should be saved as comma-separated-values.

One person types the primary copy, with the same filename as the photo, except .csv replacing .JPG.

A second person types the secondary copy, with the same name as above, except replacing the intial 'P' with 'S'. Do not include the comments in the secondary copy.

Even on PROCR lines etc, it is best if the comments all go in the comment column in the spreadsheet. Thee has been debate about the distinction between comments and notes. If you include a notes column its contents will be added in to the comment.

If there is something you cannot read put a little note in a column headed query over on the right.

The current state of play with intercode translation is available on this webpage — here, and the emulator output can be seen here,
It includes links to the relevant photos. The Q-files are all linked from the booking file. There is an example as Excel here. The keywords PROCR, CONST and TABLE go in the action column. The type number for CONST and TABLE go in the descriminant column.

The NOTES lines are still a bit of a mystery to me, but I would prefer that we keep them, although my current software ignores them, except for printing them out. Please put the word NOTES in the action column, with any RADIX in ref, and any B or other letter in item.

Typing conventions for CONSTs

The above conventions were designed for typing PROCR material, which is by far the greatest bulk of the material.

For CONSTant sections, just put the constant value in the reference column. So only the serial number and reference columns will not be blank on an S-file. The comments will be in the comment column as usual in a P-file.

Typing conventions for TABLEs

The actual TABLE line should be typed with the word TABLE in the action column, and the type number in the descriminant column.

After that, just copy the columns as they appear on the printout, with the serial number in column A, and the comment (P-files only) in column 15 (column O). The usual column headings are ignored in the body of a table. However, any comment/note on the line that is the TABLE directive should go in the normal column.

If you need to include a query, you will need a query heading on column P or Q or whewre you put it.

If a photo starts in the middle of a table, the first line should have the word “table” (lowercase) in column A. After the last line of the table, you then need to put the usual lowercase heading before the next directive, even if it is another table. “table” only ever replaces the normal column headings if and only if a photo starts mid way through a table. If a table starts in a photo - no changes are made to the normal column headings.

Typing conventions for non-ASCII characters

Values for constants and literals sometimes contain characters that are not part of the ASCII alphabet. Often these are actually hexadecimal characters destined for quartet values. You can choose either to use the ASCII version, or put a little 'x' at the start of the string and use the Hex values. We have implemented equivalent characters in ASCII.
 Leo IIIASCIIHex
tenpence10tA
elevenpence11eB
plus++C
colon::D
dot..E
pound£pF
arrow→-> or gn/a
The character £ also works on UK keyboards.

Processing of raw spreadsheets

Each of the people copy-typing Intercode has a personal directory on my local server (a Raspberry Pi in my study at home). I have written a program (called canon) which takes the .CSV file from the spreadsheet and orders the columns. It has two modes, one which omits all the comments, and one which includes everything and inserts a special line to generate a hot link to the image photo in the translator output. I have a comparison script that uses canon on each of the raw files (the P and the S versions) to produce two files which are then compared with windiff. I copy the P file to a Q file which I then edit by looking at the differences flagged by windiff and going back to the original photograph. The Q file is uploaded to the LeoCode directory. If a further version turns up, I use the same comparison technique against the Q file, and edit it again if anything shows up.

Using multiple calls of the canon program in its other mode, I generate a .CSV file of the whol thing so far, and offer it to my home-made translator. Some of the more verbose diagnostics are edited out of the output which is then uploaded to the LeoCode directory as:
                demo.htm
                                where you can always see a fairly up-to-date copy of the current state of play.

Experiments in Copy-typing

Some personal thoughts on technique.

I have used a spreadsheet (actually MS Works) for copy-typing the listing. You can download my Works spreadsheet with a right mouse click here, and there is an Excel version here.

Although the listing should be read line-by-line, I found it easier to copy-type in columns. I then saved the spreadsheet as comma-separated data in addition to the spreadsheet form, and this is what is read by my embryo Intercode Translator. The output from the translator looks like this.

Although the listing has the serial number at the left, I put it just before the comment column as I found it easier to be sure that I was at the right point. The first line of my spreadsheet is a heading which names the columns. The translator uses the initial letter of these headings to identify the columns. There may be value in having a second copy of the serial number column when typing. Its contents are created by formula.

Over in column M I originally put my own comments in lower case, but I have since arranged that any column can be used, and headed with a word starting with a lowercase 'q', e.g. query.

Comparing P and S versions to make Q

I have a tty window open on the webserver (Raspberry-Pi), in which I run a script that lists the versions of photos so I can easily see where we have both versions.

I have written a program canon.c which reads a spreadsheet file and makes a “canonical” form. It ignores the comments. I have a .BAT file comp.bat which runs canon on each file, invokes a differencing program windiff and then invokes my editor pfe32 on the P-version.

windiff lists the files on a white background where they are identical. Where two lines differ, the P version is against a red background and the S version against a yellow background. Here is an example. I have a web browser open on the bookings page, from where I can easily link to photos, or find out what is missing. Using the editor window, I rename the P-file as Q and edit in any changes by comparing the red and yellow versions with the photo.

If there are significant changes, I rerun the comp job between the Q version and the S version. I add a new line to the “make file”, see next section.

When I am really lucky (and it happens sometimes) I get a white listing from windiff and I only need to copy the P-file to make the Q-file.

Combining the Q versions to make a complete source

The canon program has a second mode of operation in which the comments are retained, and the output is in a comma separated form. I have a .BAT file mkmk.bat which runs this on each Q-file, appending the output to an output file. It is this file which is read by my embryo intercode translator it.c to generate an HTML listing, that I ususally call demo.htm.

I then usually run the binary program (which is in the left hand column of demo.htm, with the emulator leo3.c, to produce diagnostic output that I append in green to the demo file. I think that I will change that soon and put the two in different files.