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

[Paul Koning]

> On Jan 5, 2016, at 10:13 AM, Armistead, Jason BIS <Jason.Armistead at otis.com> 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.
>  
> 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” ?
>  
> 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 ?

Not sure.  DDCMP is directly relevant of course.  The other DECnet manuals are not; given that pdp11_dmc conforms to the DDCMP spec, the rest just works.  (This is true for DECnet though not for most other protocols: the specs are usually sufficiently well written that conformance actually implies interoperability.  Not only is that rarely true elsewhere; a lot of protocol designers don't even want to admit that it should be a requirement of a good protocol spec!)

As for the internal details of why things are designed a certain way, it's rare to see that documented well in any software product.  Yes, that includes "professional/commercial" products.  To the extent that design specs exist at all -- rare enough, unfortunately -- they concentrate on what was done, not so much on why, and less still on what was considered and rejected, or done in the past and then changed.

For design details that can be a source of problems -- as in the one that triggered this discussion -- it would certainly be a good idea to have a paragraph comment in the source code mentioning it.

	paul