em.1

'\" t
.\" em.1, Boone, 03/13/20
.\" Man page for Jim Wilcoxson's Prime 50-Series emulator
.\" ---------------------------------------------------------------------------
.TH em 1 "2020-06-23" "Jim Wilcoxson" "50-Series Emulator"
.\" ---------------------------------------------------------------------------
.SH NAME
em \- Emulator for Prime 50-Series systems
.\" ---------------------------------------------------------------------------
.SH SYNOPSIS
.B em [options]
.\" ---------------------------------------------------------------------------
.SH DESCRIPTION
.PP
.I em
is an emulator for the Prime 50-Series minicomputer family.  Prime's
original systems were compatible with Honeywell x16 systems.  Prime
heavily extended the architecture.  The emulator supports:
.IP \(bu
all Prime CPU modes: 16S, 32S, 32R, 64R, 64V, 32I
.IP \(bu
all Prime models, from the P400 to P6550
.IP \(bu
up to 512MB of memory, depending on the Primos rev and CPU
.IP \(bu
a system console
.IP \(bu
128 incoming telnet terminal connections
.IP \(bu
8 disk controllers, 8 drives each
.IP \(bu
support for all 25 disk drives sold by Prime
.IP \(bu
a tape controller, 4 drives, using the .TAP format
.IP \(bu
a PNC controller emulating RingNet over TCP/IP
.IP \(bu
two sync serial controllers supporting up to 8 lines
.IP \(bu
a bypass for Primos system serial number checks
.IP \(bu
Unix utilities to read/write physical tapes & Magsav tapes
.\" ---------------------------------------------------------------------------
.SH OPTIONS
.PP
If no options are specified, the resulting behavior is equivalent to
\fBem -boot 14114\fR.
.PP
\fB-boot \fIprogram [ss [ds]]\fR
.IP
Instructs
.B em
to directly boot the .SAVE-format program in host file
.IR program .
This is most useful for running standalone utilities such
as diagnostics or MAKE.  The sense and data switch registers may
optionally be set.  These register values are specified in octal.
.PP
\fB-boot \fIprogram ["regs"]\fR
.IP
As above, but set the initial values of the A, B, X and K registers
from the RVEC area of the program file.  The word "regs" is literally
specified on the command line, without the quotes.
.PP
\fB-boot \fIss [ds]\fR
.IP
Boot the machine based on the front panel interpretation of the
specified sense and data switch settings.
.PP
\fB-boot help\fR
.IP
Provide a summary of booting options and exit.
.PP
\fB-cpuid \fIidno|modelname\fR
.IP
Sets the CPU model which will be emulated.  This may be specified
using either the id number as returned by the
.B STPM
processor instruction, or using the name of the model.  A list of
id numbers and model names appears in the CPU MODELS section below.
.PP
\fB-ds \fIdataswitches\fR
.IP
Specify the settings of the emulated front panel data switches.
.PP
\fB-map|-maps \fIfilename...\fR
.IP
Specify the name of one or more PRIMOS load maps to read.  Symbols are
extracted from the map and used to enhance halt and trace output.
.PP
\fB-mem \fImemsize\fR
.IP
If support for setting memory size is compiled in, set the size of
emulated main RAM, in megabytes.  The default is 512 MB.  Not all
CPU models support this much RAM, but will instead detect a smaller
size.
.PP
\fB-naddr \fIpnclistenaddr\fR
.IP
Set the IP address of the network interface on which
.IR em 's
Prime Network Controller will listen for connections from other
emulated PNCs.  If no external emulated systems will be included
in the ring network, it may be more secure to use 127.0.0.1 for
this.  The default is 0.0.0.0 (accept connections via any interface
on the host).
.PP
\fB-nport \fIpnclistenport\fR
.IP
Set the TCP port on which
.IR em 's
PNC emulation will listen for connections from other emulated PNCs.
If not specified, PNC emulation will be disabled, and error.log will
report:

.EX
-nport is zero, PNC not started
.EE
.PP
\fB-ss \fIsenseswitches\fR
.IP
Specify the settings of the emulated front panel sense switches.  The
default sense switch setting is 14114.
.PP
\fB-tport \fIamlclistenport\fR
.IP
Sets the TCP port on which
.IR em 's
AMLC emulation will listen for incoming telnet connections.
If not specified, AMLC emulation will be disabled and error.log
will report:

.EX
-tport is zero, AMLC devices not started
emulator: device '53 failed initialization - device removed
emulator: device '54 failed initialization - device removed
.EE
.PP
\fB-trace \fItracetype(s)\fR
.IP
If support for tracing is compiled in, select trace types which
will be enabled.  Trace elements are written to
.I trace.log
on the host.  Multiple trace types may be listed, separated by
spaces.  Tracing may be initially turned off by including the
.I off
trace type.
.PP
\fB-dolineclear\fR
.IP
Inject an XON (DC1, 0221) character and a line kill character into the
input buffers each time an AMLC line receives an incoming connection.
The system's configured line kill character is fetched from the
DEFKIL field of FIGCOM, at address 14(0)/705.  This behavior helps
counteract lines which have been blocked by internet vulnerability
scanners injecting non-telnet data streams.
.\" ---------------------------------------------------------------------------
.SH FILES
.TP
\fR.lock
Prevents multiple instances of the emulator from simultaneously
accessing disk and tape files in this directory.  Created by
.IR em .
.TP
amlc.cfg
Used to associate amlc lines with specific hardware devices, to map
incoming telnet sessions from specific IP addresses to specific line
numbers, or to configure outbound socket connections.  Optional.
Example:

.EX
6 /dev/ttyUSB0       # Real device
7 192.168.10.3       # Map incoming telnet to a specific line
8 192.168.10.4:9000  # Outbound socket connection e.g. for spooler
.EE
.TP
smlc.cfg
Used to associate outbound sync serial (MDLC or HSSMLC) lines with destination
IP addresses and port numbers, or to associate inbound sync serial lines
with port numbers.  An outbound line corresponds to an RJE site defined as a
SLAVE site, and an inbound line corresponds to an RJE site defined as a MASTER
site.  Optional.  Comments work the same as amlc.cfg.  Example:

.EX
0 10.1.1.3:2554      # Connect to TCP port 2554 of host 10.1.1.3 for outbound line 0
1 9951               # Listen on TCP port 9951 for inbound line 1
.EE
.TP
console.log
All console output is also written to this file.  It is overwritten
at each invocation.  Created by
.IR em .
The
.B runem
script included with the samples arranges to preserve console.log
files in the
.B logs
subdirectory with datestamped names.
.TP
diskCCuU.TYPE
A disk image file, or a symlink to such a file.
.I CC
indicates the octal address of the controller to which this emulated
drive is attached.
.I U
indicates the unit number of the drive on that controller.
.I TYPE
indicates the drive model, and thus its size and geometry.  A list of
supported drive types appears in the DRIVE TYPE section below.
.TP
error.log
Errors are written to this file during operation.  It is overwritten
at each invocation.  Created by
.IR em .
.TP
mtN
A tape image in
.IR simh .tap
format, or a symlink to such a file.
.I N
is a digit 0-3 indicating which tape drive unit.  An empty mtN file
will be created if it does not exist when the drive is first written.
.TP
ring.cfg
A list of nodes in the ring network.  Fields are node number (integer
1-249), ip address and port, unique ID (essentially a password, up to 16
non-space characters).  Only required if a ringnet is to be established.  
Example:

.EX
1 127.0.0.1:8001 1234567890123456   # comment
.EE
.TP
ring0.map
PRIMOS kernel load map for ring 0 routines.  Will be automatically
loaded by
.I em
if other filenames are not specified.  Symbols extracted from this file
are used to enhance halt and trace output.  Optional.  This may be
extracted from the
.B PRIRUN
directory.
.TP
ring3.map
PRIMOS kernel load map for ring 3 routines.  Will be automatically
loaded by
.I em
if other filenames are not specified.  Symbols extracted from this file
are used to enhance halt and trace output.  Optional.  This may be
extracted from the
.B PRIRUN
directory.
.TP
trace.log
Any selected trace output is written to this file.  It is overwritten
at each invocation.  Created by
.IR em .
.TP
ttymsg
The text in this file is sent on each newly accepted inbound telnet
connection.  Optional.
.\" ---------------------------------------------------------------------------
.SH TRACING
.PP
If tracing is compiled into the emulator, it may be enabled from
the command line.  Event types to log are selected via the
.B -trace
option.  Tracing may start enabled or disabled, depending on whether
the
.I off
trace type is supplied.  Tracing may be dynamically turned on and
off by typing the character ctrl-T on the console.  Trace files can
rapidly become very large, and incur a significant performance penalty
on the emulator.  The following trace types are supported:
.TS
tab(|);
rfB lfB
r l .
Trace type|What is traced
ear|R-mode effective address calculation
eav|V-mode effective address calculation
eai|I-mode effective address calculation
eas|S-mode effective address calculation
inst|Detailed instruction trace
flow|Summary instruction trace
mode|CPU mode changes
eaap|AP effective address calculation
dio|Disk I/O
map|Segmentation
pcl|Procedure calls
fault|Faults
px|Process exchange
tio|Tape I/O
term|Terminal output
rio|Ring network I/O
off|Start with tracing disabled
all|Everything
flush|Flush trace file after each write
tlb|STLB and IOTLB changes
smlc|MDLC/HSSMLC device I/O
OWNERL|Execution of this PCB
#instruction count|Begin after specified number of instructions
|(the leading # is literal)
octal segno|Execution in the given segment number
|(may interact poorly with "off")
process number|Execution of this user number
.TE
.\" ---------------------------------------------------------------------------
.SH CPU MODELS
.TS
tab(,) allbox;
lfB lfB
l l .
CPUID,MODEL
1,400
3,350
4,450
5,750
7,150
7,250
8,850
9,550
10,650
11,2250
15,9950
16,9650
17,2550
19,9750
21,2350
22,2655
23,9655
24,9955
25,2450
26,4050
27,4150
28,6350
29,6550
31,2755
32,2455
33,5310
34,9755
35,2850
36,2950
37,5330
38,4450
39,5370
40,6650
41,6450
42,6150
43,5320
44,5340
.TE
.\" ---------------------------------------------------------------------------
.SH DRIVE TYPES
.TS
tab(,) allbox;
lfB lFB lfB
l l l .
Suffix,Heads,Comments
80M,5,Storage Module
300M,19,Storage Module
CMD,1/3/5+1,Cartridge Module 32/64/96 MB
68M,3,Fixed Media Device
158M,7,Fixed Media Device
160M,10,Fixed Media Device
675M,40,Fixed Media Device
600M,40,Fixed Media Device
315M,19,MODEL_4475
84M,5,MODEL_4714
60M,4,MODEL_4711
120M,8,MODEL_4715
496M,24,MODEL_4735
258M,17,MODEL_4719
770M,23,MODEL_4845
1.1G,27,MODEL_4935
328A,12,MODEL_4721
328B,31,MODEL_4721 on 7210 SCSI controller
817M,15,MODEL_4860
673M,31,MODEL_4729
213M,31,MODEL_4730
421M,31,MODEL_4731
1.3G,31,MODEL_4732
1G,31,MODEL_4734
2G,31,MODEL_4736
.TE
.\" ---------------------------------------------------------------------------
.SH AUTHOR
.PP
This emulator was written by Jim Wilcoxson.  MDLC/HSSMLC support by
Kevin Jordan.  Man page by Dennis Boone.
.\" ---------------------------------------------------------------------------
.SH SEE ALSO
This project is hosted at
.UR https://github.com/prirun/p50em/
github
.UE .
.PP
A growing collection of Prime documentation and ephemera is hosted at
.UR https://sysovl.info/
.UE .
.PP
The simh tape format is described in
.UR http://simh.trailing-edge.com/docs/simh_magtape.pdf
.UE .
.\" ---------------------------------------------------------------------------