[Simh] The minutiae of hardware/software interactions affecting SIMH

[Mark Pizzolato]

On Tuesday, January 5, 2016 at 7:13 AM, Armistead, Jason BIS wrote:
> On the topic of Configuring DMC11 Devices, while discussing wait delays 
> Mark Pizzolato recently wrote:
> 
> > Sounds reasonable.  I've got to see if I can find the reason the delay was 
> > initially added and make sure a change like this is compatible.

As it turns out, I added that functionality while getting the DMC and DMR emulation 
working with internal DDCMP implemented in the code.  Rob Jarratt started
the initial work on implementing the DMC and he fleshed out the initial register 
interactions, but the approach he took merely connected two DMCs and passed 
the data they were presented directly across a TCP circuit without any 
consideration of speaking DDCMP on the wire.  This wasn't useful to talk to 
anything else but itself (i.e. couldn't talk to RSX using a DUP or a PDP10 using a 
KDP/DUP).  With the goal of providing DECnet connectivity between all of the 
available simulators using the devices that they were designed to use, I took on
the massive rewrite to build DDCMP into this simulator.  Timothe Litt was a great 
help with many details of the protocol and the subtleties of interacting with the 
simulator registers.  The delay in question here was specifically provided since
the general model for all simh simulated devices is that devices don't really 
complete their activities in the same instruction that initiated it.  Many operating 
system device drivers don't work if devices respond too quickly.  Having the delay
is essentially standard for all devices.

> What is the "SIMH strategy" for documenting such requirements ? i.e. where 
> does this behavior get called out in the source code (or elsewhere) in a way 
> that will allow future generations of SIMH users and maintainers to understand 
> "why things are the way they are" or "why things need to be the way they are" ?

Well, in general, I would probably/usually add explicit comments in the code and 
if not there, in the commit comments relating to a change which was done to meet
the expectations of some software which ran on the real hardware.  Clearly, that 
software worked, so the behavior it expects needs to be accommodated.

Git "Blame" can be used to look at particular lines of code to 

> There is one reference to the DDCMP protocol manual in the source of 
> pdp11_dmc.c, but that's about it.  Should references to other documents be added ?

There are other documents which are implicit when discussing the pdp11_dmc.c module.
Specifically, these are the DMC11, DMR11, DMP11 and DMV11 manuals which are all
available in the BitSavers Document archive.

> Reconstructing and understanding history is easy when people familiar with 
> the subject matter (especially those who lived it, in this case, at DEC) are still 
> around to ask, but gets progressively harder as years go by without leaving a 
> good trail of "breadcrumbs" for others to follow.

Breadcrumbs are always most useful when they're found close to the loaf they 
relate to.  Discussions here in the simh list are OK since hopefully there are 
archives, but locating and correlating problems and solutions can require 
difficult digging.

However, when there are detailed problems with some simulator behavior it is
absolutely best to discuss these in the github issue system.  This allows the
details to be recorded along with pointers to the specific changes that the 
discussion invokes.  Commits related to specific issues merely mention the 
issue in the commit comments and the discussion points back to those commits.

- Mark