Notes on IBM 7094 emulator implementation and source code.

This file contains some notes on the accompanying source code files.

As of July, 2017, the source code of B7094 has been converted to
build and run using the free Lazarus IDE [v1.8.0RC3] and the
Free Pascal Compiler [v3.0.2].  Most of the commentary here applies
equally to the commercial Delphi IDE/compiler and the free Lazarus/FP IDE/compiler.
There are some notes at the end of this document specifically
describing the installation of Lazarus/Free Pascal and the installation
of the design-time package (B709Cmps.pas/B709Cmps_package.pas/B709Cmps_package.res/B709Cmps_package.lpk)
to the Lazarus components palette.

The last section (before the Lazarus-specific instructions) describes some aspects of Borland Delphi (Lazarus/Free Pascal)
for those unfamilar with the language used to write the emulator.

The code was originally developed (during 2001-2004) using Borland Delphi, Version 5.
Later versions should work, 3 & 4 may, versions 1 & 2 won't.
If you wish to compile the code, remember to load the components to the Delphi (Lazarus)
palette before loading the project (from B709Cmps*), otherwise Delphi (Lazarus) will screw
up the forms for you.


*** First make it work - Then make it fast.
Apart from the hashing function used for opcode table lookup, very little effort
has been made to achieve high emulation performance. It's fast enough for what
it can do now, and there is plenty of room for improvement should that become
neccessary in the future.

*** PUN intended, but not implemented.
As yet, no 7094 code has been run on the emulator that requires the card punch
device, and therefore this has not yet been implemented. Work was directed to
other functions that were required more immediately.

*** FP-DP Ops not tested.
Mike Hore has developed the floating point code for the emulator, but the double
precision part of this has not yet been tested.

*** Comments in the source code.
Most of the code is reasonably well commented, especially those areas that deal
intimately or directly with 7094 functions. Others parts, which simply involve
the mechanics of a Delphi (Lazarus)/Windows application may be more sparsely documented.

Some code snippets have been "commented out" but remain in the code.
For the most part, they are probably junk that can removed, but they may indicate
an area of uncertainty, and could provide clues for future development and
debugging.

*** Convoluted transfer of control in device object hierachy.
Just a general observation.
Especially in the I/O device implementations, use has been made of the inheritance
and polymorphism aspects of Object-Oriented Programming. This can be quite hard
to follow as functions are invoked downwards into ancestor objects, and sideways
into associated objects. This sort of thing becomes a bit clearer when the code
is loaded into the Delphi (Lazarus) IDE, but even then it can still be quite confusing.

*** Instruction Command table.
The 7094 instructions and some of their attributes are loaded into a large table
at initialization time. This information makes it easier to decode and dispatch
instructions during fetch and execute, and helps with writing meaningful trace
entries. But the format of 7094 instructions, and the design aim of having many
of the instruction table entries be autogenerated, together with other opcode
decoding issues, makes this section more complex than might be expected.

*** Source files (Lazarus/Free Pascal equivalents in parens) :-
B7094.DPR (B7094.lpi [+ B7094.lpr, converted from Delphi) - Main project file
B709Main.pas - Main form - console window
B709Spls.pas - Splash screen
B709Core.pas - Core Storage display form
B709DRDR.pas - Reader display form
B709DLST.pas - Printer display form
B709TapF.pas - Tape drive display form
B709DTAP.pas - Tape cluster display form - holds instances of the above
B709Cnfg.pas - Configuration display form
B709Stop.pas - Address stops display form
B709Trce.pas - Trace display form
B709Eror.pas - Error display form
B709OCLD.pas - Scripting display form
B709OCLE.pas - Script editor display form

All the above have associated .DFM (.lfm) files of the same name

B709Defs.pas - Global definitions
B709Misc.pas - Miscellaneous functions
B709CPU.pas  - CPU main control functions
B709Chan.pas - Channel and basic device operations
B709IBIS.pas - Instruction emulation - Basic instructions
B709IINA.pas - Instruction emulation - Fixed point arithmetic
B709IFPA.pas - Instruction emulation - Floating point arithmetic
B709IIOC.pas - Instruction emulation - Input/Output
B709IEPS.pas - Instruction emulation - Extended performance set
B709Inst.pas - Instruction Control Table
B709OCLI.pas - Scripting interpreter
B709Cmps.pas - Specialized display components for console and unit record


*** The following are a few notes for readers unfamiliar with Delphi (Lazarus/Free Pascal) ***

*** DPR (lpi [+ lpr]), DFM (lfm) and PAS files
These are the three main types of source file in Delphi (Lazarus/Free Pascal).

The DPR (lpi, [+ lpr]) file is the main project file that links all the others together, and
initiates execution of the application. There is only one DPR (lpi, [+ lpr]) file in a project.

The PAS files contain actual Object Pascal code. Each defines a "unit" which is
compiled separately and then linked together with all others. The guts of the
code lies in the "implementation" part of the unit, and is generally private to
the unit. However, items within a unit can be exposed for access by other units
by placing their declaration information in the "interface" part of the code at
the start of the unit. The interface part also contains a "uses" clause that
specifies the names of other units that have exposed items which this unit needs
access to.

DFM (lfm) files are descriptions of the "Forms" (or windows) that make up the visible
part of the application. This code is rarely edited directly by the programmer.
Delphi (Lazarus/Free Pascal) maintains these files as the programmer edits the
form layout using graphical editing facilities. Each DFM (lfm) defines exactly
one form or window, and is always associated with a PAS file that contains the
code for responding to user events coming from the form, and for updating the
form display to the user.


*** Private, Protected and Public areas in Delphi objects.
These keywords delineate which fields and methods of an object are visible, and
to what other entities they are visible.
Private is known only to the methods of the object itself.
Protected is known only to the object, and its descendants.
Public is visible to all.


*** Properties in Delphi (Lazarus/Free Pascal).
An object may control how its fields are externally accessed by the use of
properties. The property specifier in the public section of the object definition
may simply link to the name of the underlying data field (defined in the private
part), or may exercise more control by linking to a function for read access
and/or a procedure for write access. By convention, the underlying field variable
name is prefixed with the letter "F", and the read function/write procedure names
are the name of the variable, prefixed with "get" and "set" respectively.


*** Delphi is a single-pass compiler.
And therefore all items must be defined before they are referenced.
This leads to higher level procedures being placed towards the end of the code
in a unit, after any sub procedures and data items that they reference.
This is less true for object methods, which are all declared in the object
definition, and so may be placed freely anywhere after that.


*** Some notes on building B7094 from source using the Lazarus IDE
    in conjunction with the Free Pascal compiler.
You can read about the history of Lazarus and Free Pascal on Wikipedia:
https://en.wikipedia.org/wiki/Lazarus (IDE)
https://en.wikipedia.org/wiki/Free Pascal

Download the Win32 and/or Win64 installers from
https://sourceforge.net/projects/lazarus/files
The Windows installers are, e.g.,
lazarus-1.8.0RC3-fpc-3.0.1-win32.exe
lazarus-1.8.0RCS-fpc-3.0.1-win64.exe
(As currently constituted, the B7094 project requires 1.8.0RC3.
You'll get a fatal error [unknown identifier Application.Scaled]
if you try to build with the stable release 1.6.4.)

Note for Linux/Mac OSX users: B7094 was originally written for a Windows
environment using the Delphi VCL (Visual Component Library), and
has Windows dependencies baked into it.  The Lazarus/Free Pascal version of
B7094 uses the LCL (the Lazarus/FP equivalent of the VCL), and retains
these Windows dependencies.  Both 32-bit and 64-bit builds of B7094
using Lazarus/FP (or Delphi, for that matter) will run on Linux under
Wine (or, presumably, Mac OSX under Darwine).  Lazarus/FP (and B7094) will
run on versions of Windows ranging from 32-bit Windows XP (SP3)
through contemporary 64-bit Windows 10.

The installer puts Lazarus/FP by default in the directory C:\lazarus.
The first time you start the Lazarus IDE, you'll get a screen asking
you to confirm the default configuration.  Just click on "Start IDE".
The IDE starts up with an empty (skeleton) project, including an empty
"Form1", etc.  Click File->Close All to dismiss this.

After you've installed Lazarus/FP using one of the Windows installers,
before building B7094.exe you need to install the custom components package
(comprising files B709Cmps.pas/B709Cmps_package.pas/B709Cmps_package.res/B709Cmps_package.lpk)
to the Lazarus design-time palette.  Click Package->Open Package File (.lpk)
and navigate to the directory containing the B7094 source code.  Select B7094_Cmps_package.lpk
A window "Package B709Cmps_package V0.0" will open.  Click on B709Cmps.pas and
make sure that in the "File Properties" panel the "Register unit" checkbox is checked.
Click the "Compile" button.  This will create a "lib" subdirectory in the B7094 source directory with the
compiled components package inside it.  When the green-highlighted message
"Compile package B709Cmps_package 0.0: Success, ..." appears in the Messages (View->Messages) window
(ignore any warnings), the package has been successfully compiled.
To install the package, click Use->Install on the package window.
Click the Yes button on the "Rebuild Lazarus?" confirmation window.
The Lazarus IDE will now be rebuilt.  When the build process is finished, the
IDE will restart automatically.

Once again, dismiss the skeleton project by clicking File->Close All.
Then click Project->Open Project ..., navigate to the B7094 source-code directory, and
select the project file B7094.lpi.  Answer the query window "Save changes to
project project1?" by clicking the No button.  You can also now close the "Package B709Cmps_package V0.0"
window.  Note: B7094.lpi is the actual project file under Lazarus.  There is also,
however, a B7094.lpr file corresponding to, and converted from, the B7094.dpr
file under Delphi.  However, this B7094.lpr file now counts as "Unit0",
rather than the actual project file.

The B709Main.pas unit will be displayed in the Source Editor window.  If it isn't, or to see
the main form (or any other form) and its components, type Shift-F12 to bring up the View Project Forms
window, select MainForm, and click OK.  You can toggle the form graphics display
on and off by typing F12 (without the Shift).

To build the simulator, click on Run->Build.  When you see the green-highlighted
"...Compile Project, Target: B7094.exe: Success, ..." message in the Messages
window, you should have a runnable B7094.exe.  You can ignore any warning
messages.

Note: Under Project->Project Options, in the "Compiler Options" half of the tree
in the left pane, there's a "Debugging" entry.  These options have all been
deselected to minimize the size of the executable.
