Re: [Simh] fprint_sym and parse_sym limitation

2015-09-23 Thread Mark Pizzolato - Info Comm 
On Wednesday, September 23, 2015 at 8:31 AM, Paul Koning wrote:
> > On Sep 22, 2015, at 7:59 PM, Mark Pizzolato - Info Comm
>  wrote:
> >
> > On Monday, September 14, 2015 at 6:20 AM, Paul Koning wrote:
> >> ...
> >> Ok.  This is another example of something undocumented.
> >
> > True.
> >
> > Meanwhile, I was thinking this over one more time  and I realized that I had
> forgotten that there are already 2 user/device specific void pointers in the 
> UNIT
> structure:
> >
> > uptr->up7
> > uptr->up8
> >
> > Do with them as you wish.
> 
> Thanks.
> 
> That prompted me to look in sim_defs.h to see if there are other gems hiding.
> There are.
> 
> I'm going to make a stab at updating simh.doc with what I can see, and
> description of what I understand or TBS for what I see but don't know how to
> document.

Great!

Please start from the latest simh.doc from the github repo.  

Please come back with your TBS list and we'll flesh out what is needed.

- Mark

___
Simh mailing list
Simh@trailing-edge.com
http://mailman.trailing-edge.com/mailman/listinfo/simh

Re: [Simh] fprint_sym and parse_sym limitation

2015-09-23 Thread Paul Koning 

> On Sep 22, 2015, at 7:59 PM, Mark Pizzolato - Info Comm  
> wrote:
> 
> On Monday, September 14, 2015 at 6:20 AM, Paul Koning wrote:
>> ...
>> Ok.  This is another example of something undocumented.
> 
> True.  
> 
> Meanwhile, I was thinking this over one more time  and I realized that I had 
> forgotten that there are already 2 user/device specific void pointers in the 
> UNIT structure:
> 
>   uptr->up7
>   uptr->up8
> 
> Do with them as you wish.

Thanks.

That prompted me to look in sim_defs.h to see if there are other gems hiding.  
There are.  

I'm going to make a stab at updating simh.doc with what I can see, and 
description of what I understand or TBS for what I see but don't know how to 
document.

paul


___
Simh mailing list
Simh@trailing-edge.com
http://mailman.trailing-edge.com/mailman/listinfo/simh

Re: [Simh] fprint_sym and parse_sym limitation

2015-09-23 Thread Paul Koning 

> On Sep 23, 2015, at 11:39 AM, Mark Pizzolato - Info Comm  
> wrote:
> 
> On Wednesday, September 23, 2015 at 8:31 AM, Paul Koning wrote:
>> ...
>> I'm going to make a stab at updating simh.doc with what I can see, and
>> description of what I understand or TBS for what I see but don't know how to
>> document.
> 
> Great!
> 
> Please start from the latest simh.doc from the github repo.  

Done.  I sent a pull request.  This is my first, so if I'm doing this wrong, 
please give me directions on how to do it right.

> 
> Please come back with your TBS list and we'll flesh out what is needed.

There are three: in DEVICE, the "description" field; in UNIT, the "iostarttime" 
field; and for REG_UNIT the way in which the address of the data is computed.

By the way, the existence of REG_UNIT contradicts the statement earlier in the 
doc that only devices have registers...

paul

___
Simh mailing list
Simh@trailing-edge.com
http://mailman.trailing-edge.com/mailman/listinfo/simh

Re: [Simh] fprint_sym and parse_sym limitation

2015-09-14 Thread Tom Morris 
On Mon, Sep 14, 2015 at 10:33 AM, Mark Pizzolato - Info Comm <
m...@infocomm.com> wrote:

> On Monday, September 14, 2015 at 6:20 AM, Paul Koning wrote:
>
> > ...  Or is there another way to submit
> > work?
>
> If you are already a git user, then working directly from the github
> repository and submitting pull requests is the way to go.  Non git users
> can merely send me (m...@infocomm.com) complete changed files along with
> a description (as verbose as you want) of what and/or why changes were
> made.  I'll commit the changes to the repo on your behalf.
>

I'd strongly encourage everyone who wants to contribute to SIMH to get a
Github account, because it makes the patch & review workflow much easier
and provides you with permanent attribution for your changes.  Git is just
another version control system and isn't that difficult to learn if you
already know one (or more).  Additionally, simple edits, like fixing typos
in a README, can be easily done through the online editor on the web site
which will automatically generate a patch and associated pull request for
the repository owners (ie Mark) to review.

Try it, you'll like it!

Tom

p.s. Unfortunately, the core SIMH documentation is in Microsoft Word .doc
format which is a binary format that doesn't play well with version control
systems, in addition to its other downsides.  Has there been any
consideration to converting it to RST or some other text-based markup
language which would work well with git/Github?  Even .docx instead of .doc
would be a step forward.  It's not only more modern, so likely to be
supported longer, but it would also allow Github-based diff and preview
using the pandoc -based solution describe here:
http://blog.martinfenner.org/2014/08/25/using-microsoft-word-with-git/
___
Simh mailing list
Simh@trailing-edge.com
http://mailman.trailing-edge.com/mailman/listinfo/simh

Re: [Simh] fprint_sym and parse_sym limitation

2015-09-14 Thread Kevin Handy 
Doxygen has some limitations, it is more of a reference than a tutorial for
example, but it does have a lot of useful features when done properly.
- It generates LaTeX, HTML, and RTF from the sources, and other formats are
available from these (like ps and pdf).
- If you copy one source file as the basis for annother device for ecample,
the documentation is already mostly done for you.
- The documentation keeps up with the source better than seperate files.
Software developers never seem to update the documentation unless it's
staring them in the face as they make their changes.
- References to structures in a parameter list are automatically cross
linked.

As documentation for how to write code, it isn't that great because it's
mostly just a list of available functions, but does give you several views
of what edists. including links to the source code.

I don't think it works as the sole source of documentation, but it does
provide a lot of useful information even if you don't have any comments
coded in.

(I just tried playing with it) As a first try at using it. just install
doxygen (and graphviz for extra credit), type 'doxygen -g' ay the top level
simh directory, edit the generated 'Doxygen' configuration file, and list
all of the subdirectories under the 'INPUT' option (along with a '.' for
the top level directory), and then run 'doxygen'. Point your browser to
'./html/index.html' and brouse around. With the Graphviz, you also get
relationship diagrams for structures.

On Mon, Sep 14, 2015 at 1:20 PM, Christian Gauger-Cosgrove <
captainkirk...@gmail.com> wrote:

> On 14 September 2015 at 14:34, Mark Pizzolato - Info Comm
>  wrote:
> > That said, I've got a back-burner project which will migrate most of the
> simulator specific documentation to a more generic format which can
> leverage various display/output formats.  When that finally sees the light
> of day, we'll look at the remaining documents.
> >
> I know the discussion mentioned doxygen; but I'd been feeling it might
> be "nice" to transfer the SIMH documentation to LaTeX. Especially
> since it works very nicely with a version control system. And the
> documentation is kept separate from the source code.
>
> Then again, doxygen is a de facto standard in documenting software
> with annotated source code, but would require a large scale project to
> add all that information into the sources.
>
> Regards,
> Christian
> --
> Christian M. Gauger-Cosgrove
> STCKON08DS0
> Contact information available upon request.
> ___
> Simh mailing list
> Simh@trailing-edge.com
> http://mailman.trailing-edge.com/mailman/listinfo/simh
>
___
Simh mailing list
Simh@trailing-edge.com
http://mailman.trailing-edge.com/mailman/listinfo/simh

Re: [Simh] fprint_sym and parse_sym limitation

2015-09-14 Thread Mark Pizzolato - Info Comm 
On Monday, September 14, 2015 at 9:24 AM, Tom Morris wrote:
> On Mon, Sep 14, 2015 at 10:33 AM, Mark Pizzolato - Info Comm 
>  wrote:
>>On Monday, September 14, 2015 at 6:20 AM, Paul Koning wrote:

>> ...  Or is there another way to submit
>> work?
> 
> If you are already a git user, then working directly from the github 
> repository 
> and submitting pull requests is the way to go.  Non git users can merely send 
> me (m...@infocomm.com) complete changed files along with a description 
> (as verbose as you want) of what and/or why changes were made.  I'll commit 
> the changes to the repo on your behalf.
>
> I'd strongly encourage everyone who wants to contribute to SIMH to get a 
> Github account, because it makes the patch & review workflow much easier 
> and provides you with permanent attribution for your changes.  Git is just 
> another version control system and isn't that difficult to learn if you 
> already 
> know one (or more).  Additionally, simple edits, like fixing typos in a 
> README,
> can be easily done through the online editor on the web site which will
> automatically generate a patch and associated pull request for the repository
> owners (ie Mark) to review.
> 
> Try it, you'll like it!

I agree completely, however I'm happy to take input from everyone with minimal 
barriers.  Several of our most significant contributors do not use a source 
control system.
 
> p.s. Unfortunately, the core SIMH documentation is in Microsoft Word .doc 
> format which is a binary format that doesn't play well with version control 
> systems, in addition to its other downsides.  Has there been any 
> consideration 
> to converting it to RST or some other text-based markup language which 
> would work well with git/Github?  Even .docx instead of .doc would be a 
> step forward.  It's not only more modern, so likely to be supported longer, 
> but it would also allow Github-based diff and preview using the 
> pandoc-based solution describe here: 
> http://blog.martinfenner.org/2014/08/25/using-microsoft-word-with-git/

Well, I agree that the Microsoft Word .doc format can't be usefully displayed 
in the github web UI.  

However, I manage, comment on, and eventually merge all changes submitted to 
the repo in local copies of the repo on my desktop or laptop system.  The local 
git graphical UI I use is GitExtensions which leverages kdiff3 for viewing as a 
merge tool.  This tool has absolutely no problems interpreting and showing 
changes in .doc format files, on the other hand it can't handle .docx format 
files.  Since things have been working just fine for these activities, there 
has been no motive to change the document formats at all.

That said, I've got a back-burner project which will migrate most of the 
simulator specific documentation to a more generic format which can leverage 
various display/output formats.  When that finally sees the light of day, we'll 
look at the remaining documents.

- Mark
___
Simh mailing list
Simh@trailing-edge.com
http://mailman.trailing-edge.com/mailman/listinfo/simh

Re: [Simh] fprint_sym and parse_sym limitation

2015-09-14 Thread Mark Pizzolato - Info Comm 
On Monday, September 14, 2015 at 11:03 AM, khandy2...@gmail.com wrote:
> Has any thought been given to using doxygen for the techbical stuff? It would 
> make it easier to keep  the docs current with the sources.

Well, not yet.  If someone who is familar with doxygen and some details of the 
simh framework is willing to make the changes to the source, I'd be glad to 
merge the results.  Any such project would need to embrace these doxygen 
additions for essentially all of the source in the top level simh directory.

- Mark
___
Simh mailing list
Simh@trailing-edge.com
http://mailman.trailing-edge.com/mailman/listinfo/simh

Re: [Simh] fprint_sym and parse_sym limitation

2015-09-13 Thread Paul Koning 

> On Sep 12, 2015, at 12:24 AM, J. David Bryan  wrote:
> 
> On Friday, September 11, 2015 at 20:17, Paul Koning wrote:
> 
>> I'd do: if (cpu_reg[addr].flags & REG_IR) ...
> 
> OK, that's a reasonable approach.
> 
> You might wish to write an implementation of your idea.  I recall trying it 
> myself when I was first looking into the issue, but it turned out to be 
> reasonably complicated -- more so than passing register flags, which 
> required changing only two of the fprint_sym calls as I have outlined while 
> maintaining backward compatibility with existing simulators.

I wonder if it would make sense to create new functions, with cleaner calling 
conventions, and a global simulator flag that the init code can set (or set at 
compile time) to tell the mainline which calling convention to use.
> 
> You mentioned getting the register array by working back from the UNIT 
> pointer, but unfortunately, uptr is NULL in some cases, e.g., when called 
> from ex_reg.  ex_reg receives a REG pointer but neither a unit pointer or a 
> device pointer.  It could be added, of course.
> 
> Also, it's not clear how to derive the register index in ex_reg.  It's 
> known in find_reg, but it's not passed back out.  It could be rediscovered 
> by a second scan of the register array, though, to match the REG pointer.
> 
> Even when passing a register index and unit pointer, or a register pointer, 
> there's still the problem of identifying how that register is to be handled 
> within fprint_sym.  I think that something within the REG structure itself 
> needs to be the identifier, as identifying via the index or REG address 
> leads to maintenance issues, as I've noted earlier.
> 
> As an aside, I've not looked carefully, but I suspect that the 
> sim_vm_parse_addr and sim_vm_fprint_addr routines are just special cases of 
> this more general problem of knowing which register is being passed so that 
> you then know how to handle its parsing or printing.  It'd be nice if a 
> general solution could be found that would fold these in as well.

parse_addr and fprint_addr are another area that gave me surprises.  They don't 
see the switches, so there isn't any way for command switches to affect the 
address printing, which is what I wanted to be able to do.

In general, and that ties to my earlier comment, the SIMH calling conventions 
and structure layouts show lines of long evolution without a common model.  We 
have flags in some places but not others, switches passed in some cases but not 
others.  There are functions to format stuff that aren't told what it is they 
are formatting.  We have a context pointer in the device, but not in the unit 
(I ended up having to abuse the filebuf for that).  I wonder if a more general 
rationalization of interfaces and structures -- possibly one that means 
adjusting the existing VMs to use the new stuff -- is worth doing.

paul


___
Simh mailing list
Simh@trailing-edge.com
http://mailman.trailing-edge.com/mailman/listinfo/simh

Re: [Simh] fprint_sym and parse_sym limitation

2015-09-13 Thread J. David Bryan 
On Sunday, September 13, 2015 at 13:55, Paul Koning wrote:

> I wonder if it would make sense to create new functions, with cleaner
> calling conventions, and a global simulator flag that the init code
> can set (or set at compile time) to tell the mainline which calling
> convention to use. 

I'd argue no, because I think it'd make an already complicated situation 
worse.  Consider that ex_reg (e.g.) currently does:

  if REG_VMAD
then call sim_vm_fprint_addr
  else if REG_VMIO
then call fprint_sym
  else
call fprint_val

Adding a conditional fourth value-printing routine in front of those three 
seems to me to be going the wrong way.  I prefer your later suggestion.


> I wonder if a more general rationalization of interfaces and structures
> -- possibly one that means adjusting the existing VMs to use the new
> stuff -- is worth doing.

If changing existing simulators is deemed OK, then it seems to me that 
having just one VM-provided print (and one parse) routine would be the way 
to go.  If the simulator designer didn't want the default formatter, then a 
custom formatter could be invoked in its place.  Those routines would have 
to receive some unequivocal indication of what they were printing (or 
parsing) -- a memory address, a memory value, a specific register value, 
etc.  They'd also want to be called from every place where default printing 
or parsing would otherwise take place.

That said, given that every simulator has to provide symbolic print and 
parse routines, every simulator would require changes to accommodate new 
calling sequences.  That was the primary reason I implemented my suggested 
changes the way I did; it seemed to be the least disruptive way to get 
positive IDs to the print and parse routines.

  -- Dave

___
Simh mailing list
Simh@trailing-edge.com
http://mailman.trailing-edge.com/mailman/listinfo/simh

Re: [Simh] fprint_sym and parse_sym limitation

2015-09-11 Thread J. David Bryan 
On Friday, September 11, 2015 at 15:32, Paul Koning wrote:

> Not quite.  It would break existing simulators that use the addr field
> for register radix without masking it. 

But existing simulators wouldn't be passing any user-defined REG_* flags, 
so "(rptr->flags & REG_UFMASK) | rdx" would be equal to "rdx", and they'd 
receive the radix just as before.


> If you want to disregard that case, would it not be just as simple,
> but more powerful, to pass the index into the registers array as
> "addr"?  Then all you need is to find the regs vector from the UNIT
> pointer, and index that with addr, and you have all the information you
> might want about that register -- its flags, name, or the register
> number if you want to use that. 

Assume that I have three CPU registers that I want to format identically.  
How do I tell if I've been called for one of these?  If I receive the 
index, then I'd have to do:

  if (addr == 3 || addr == 7 || addr == 12) ...

or:

  if (strcmp (cpu_reg [addr].name, "CIR") == 0 ||
  strcmp (cpu_reg [addr].name, "NIR") == 0 ||
  strcmp (cpu_reg [addr].name, "XIR") == 0) ...

whereas with a user-defined flag, it's:

  if (addr & REG_IR) ...

When I first ran into the problem two years ago, I had done what you 
suggested, i.e., pass the register index.  But in addition to being more 
complicated, the problem with using register numbers or names is that it's 
fragile.  The register definitions are (typically) in cpu.c, but the above 
usage is in sys.c.  If I rearrange the register order or insert a new 
register or change the names in cpu.c without correcting the usage in 
sys.c, things fail silently.


> True, but if you can see the register array entry, then you can test the
> flag from that entry, which is just as general.

I'd argue the other way around.  :-)  If you need the index number, you can 
define a flag field to hold it.

  -- Dave

___
Simh mailing list
Simh@trailing-edge.com
http://mailman.trailing-edge.com/mailman/listinfo/simh

Re: [Simh] fprint_sym and parse_sym limitation

2015-09-11 Thread Paul Koning 

> On Sep 11, 2015, at 3:05 PM, J. David Bryan  wrote:
> 
> On Friday, September 11, 2015 at 14:01, Paul Koning wrote:
> 
>> It may be desirable to format or parse values differently for
>> different registers.  As it stands, that's not possible because the
>> function can't tell which register it's formatting.  [...] 
>> 
>> Ideally one of the argments, for the register case, should point to
>> the REG entry for the register in question.
> 
> I've run into this same problem with a new simulator I'm developing.  I've 
> solved it (unofficially) by passing a set of user-defined register flags in 
> the upper 16 bits of the radix parameter, i.e.:
> 
> -(fprint_sym (ofile, rdx, , NULL, sim_switches | SIM_SW_REG) > 0))
> +(fprint_sym (ofile, (rptr->flags & REG_UFMASK) | rdx, ,
> + NULL, sim_switches | SIM_SW_REG) > 0))
> 
> ...and the same for parse_sym.  It also needs this in sim_defs.h:
> 
> +#define REG_V_UF16   /* device specific */
> +#define REG_UFMASK  (~((1u << REG_V_UF) - 1))
> 
> I considered passing a register pointer, but this method has two 
> advantages:
> 
> - it's backward compatible, so no changes to calls in existing simulators
>   are needed

Not quite.  It would break existing simulators that use the addr field for 
register radix without masking it.  Those may not be common.  

If you want to disregard that case, would it not be just as simple, but more 
powerful, to pass the index into the registers array as "addr"?  Then all you 
need is to find the regs vector from the UNIT pointer, and index that with 
addr, and you have all the information you might want about that register -- 
its flags, name, or the register number if you want to use that.

> 
> - it allows groups of registers to be handled easily
> 
> As an example, I have a "current instruction register" and a "next 
> instruction register" that both need the same special treatment.  I tag 
> both register definitions with a used-defined REG_IR value, and then in 
> fprint_sym I need only test for the one flag value rather than two separate 
> register-pointer values.

True, but if you can see the register array entry, then you can test the flag 
from that entry, which is just as general.

paul

___
Simh mailing list
Simh@trailing-edge.com
http://mailman.trailing-edge.com/mailman/listinfo/simh

Re: [Simh] fprint_sym and parse_sym limitation

2015-09-11 Thread J. David Bryan 
On Friday, September 11, 2015 at 20:17, Paul Koning wrote:

> I'd do: if (cpu_reg[addr].flags & REG_IR) ...

OK, that's a reasonable approach.

You might wish to write an implementation of your idea.  I recall trying it 
myself when I was first looking into the issue, but it turned out to be 
reasonably complicated -- more so than passing register flags, which 
required changing only two of the fprint_sym calls as I have outlined while 
maintaining backward compatibility with existing simulators.

You mentioned getting the register array by working back from the UNIT 
pointer, but unfortunately, uptr is NULL in some cases, e.g., when called 
from ex_reg.  ex_reg receives a REG pointer but neither a unit pointer or a 
device pointer.  It could be added, of course.

Also, it's not clear how to derive the register index in ex_reg.  It's 
known in find_reg, but it's not passed back out.  It could be rediscovered 
by a second scan of the register array, though, to match the REG pointer.

Even when passing a register index and unit pointer, or a register pointer, 
there's still the problem of identifying how that register is to be handled 
within fprint_sym.  I think that something within the REG structure itself 
needs to be the identifier, as identifying via the index or REG address 
leads to maintenance issues, as I've noted earlier.

As an aside, I've not looked carefully, but I suspect that the 
sim_vm_parse_addr and sim_vm_fprint_addr routines are just special cases of 
this more general problem of knowing which register is being passed so that 
you then know how to handle its parsing or printing.  It'd be nice if a 
general solution could be found that would fold these in as well.

  -- Dave

___
Simh mailing list
Simh@trailing-edge.com
http://mailman.trailing-edge.com/mailman/listinfo/simh