Document FIRST_TTY_BUF_PAGEX, dn355 DCWs, and IO page tables

[Eric Swenson]

In debugging ibm 3227 support in the emulator, a lot of time was wasted not understanding what the value of FIRST_TTY_BUF_PAGEX (dn355_data.incl.pl1) represented, what the value of tty_buf.absorig was used for, and how dn355 (and others) use DCWs passed through mailboxes and interpreted not by the IOM but by the FNP.

It would be good to add some comments in dn355_data.incl.pl1 to document FIRST_TTY_BUF_PAGEX and in tty_buf.cds to document tty_buf.absorig. In the logic that uses tty_buf.absorig in computing addresses for DCWs passed through mailboxes to the FNP, some documentation would be helpful.

[canthony]

Some specifics:

MSC uses io_page_table to map the tty_buf$ segment to an I/O address space.

The io_page_table address space is laid out:

page # mapped to
0 (null)
1 page 1 (mailbox access)
2 page 2 (mailbox access)
3 page 3 (mailbox access)
4 (null)
...
64 page 257 (page 0 of tty_buf$)
65 page 258 (page 1 of tty_buf$)
...
255 page 258 (page 191 of tty_buf$)

Note that this scheme imposes a 192 page limit on the size of tty_buf$ that the FNP can access.

FIRST_TTY_BUF_PAGEX defines that start page (64) of tty_buf$ in io_page_table.
tty_buf.absorig defines the start address (FIRST_TTY_BUF_PAGEX*page_size) of tty_buf$ in iopage_table.

It is thought that this scheme arose when a fixed size tty_buf$ starting at page 64 was relocated to page 256 (out of the valuable lower 256K) and made variable size.

It might be possible to expand the 192 page limit by setting FIRST_TTY_BUF_PAGEX to 4, but that may break some hidden assumptions.

The MCS accept_input code (dn355.pl1$process_accept_input) places pseudo-dcws in a mailbox with the expectation that the FNP will use the channel control program's provided pointer to io_page_table to do the address mapping, but that is not mentioned in the source or in AN85.