--------------------
                              Expanded MTAB Access
                              --------------------


The modifier structure (MTAB) used by the device- and unit-specific SET and SHOW
commands provides a simple and elegant method of manipulating the 16 bits of the
user portion of the UNIT flags field -- the regular MTAB.  For other modifier
targets or to modify numeric value fields, the extended MTAB mechanism offers
complete flexibility, albeit at the cost of the simplicity of regular MTABs.

The main cost is that extended MTABs require the use of validation and print
routines.  Often those routines are trivial, doing nothing more than setting or
clearing a flag in the DEVICE flags field, or printing a word if the flag bit is
set.  If the extended SET takes a numeric value parameter, then the validation
routine must parse the parameter, validate against any minimum and maximum
value restrictions, mask the target, and insert the new value.  If several
fields are to be set, then several validation and print routines must be
written, each of which is only slightly different than the others.

The extra work to use extended MTABs to manipulate DEVICE flags creates the
temptation to use a UNIT flag for an option that is logically part of the device
(e.g., a strap on the controller card) rather than part of the connected
peripheral (e.g., a strap on the drive).  For devices with single units,
distinguishing between the device and the unit is usually not needed.  For
devices with multiple units, though, this blurs the distinction between them,
potentially creating confusion for the user when issuing SET or SHOW commands
("Do I specify the device name or the unit name?").

It would be helpful to have a mechanism that combines the ease of use of regular
MTABs with the flexibility of extended MTABs.

This is a proposal for such a mechanism -- the expanded MTAB.  The goal is to
eliminate the need for validation and print routines in the majority of cases,
or, if elimination is not possible, then to reduce the code in such routines to
just the unique processing required.

Expanded MTABs work with SET/SHOW <device> and SET/SHOW <unit> commands to
modify:

  - The user portion of the "flags" field of the DEVICE or UNIT structure.

  - Any portion of a user field (e.g., "u4") of the UNIT structure (or of the
    DEVICE structure, should one be added in the future).  For units, the
    field designated in unit 0 identifies the field that will be modified when
    another unit is specified (e.g., a command specifying unit 3 modifies the
    indicated field in the fourth UNIT in the units array).

  - Any portion of a global "uint32" scalar variable for a device command or a
    global "uint32" array element corresponding to the unit number for a unit
    command.

The modifications may apply to:

  - A flag or set of flags indicated by a "SET <device/unit> <option>" command.

  - A numeric value field indicated by a "SET <device/unit> <option>=<value>"
    command.

None of these operations require the use of validation or print routines,
although they may be employed if desired.


Overview
~~~~~~~~

A flag modifier operates just like a regular MTAB, except the target is not
limited to the user portion of the "flags" field.  It processes commands of the
form:

  SET <device> <option>
  SET <unit> <option>

...where <option> matches the "mstring" field.

If defined, the validation and display routines are passed the "match" value to
decide whether the value should be stored or printed.  The routines return
SCPE_OK to confirm the action or an SCPE error code to deny the action and print
the associated error message.  The routines may also return -1 to deny the
action but return success.  This special return is used when the routine wants
to store or print the value itself.  As an option, the "mask" field rather than
the "match" field may be passed to the routines.  This is useful if the routine
is validating or printing a flag that is being cleared, as in this case the
"match" field is zero.

A value modifier operates by parsing the supplied numeric value and modifying
the target as directed.  It processes commands of the form:

  SET <device> <option>=<value>
  SET <unit> <option>=<value>

...where <option> matches the "mstring" field and <value> is an unsigned number.
Typically, this accepts numbers in the range 0-N and places the result in the
target field.  Parsing and modification may be altered in these optional ways:

  - The parsing radix may be specified.

  - An upper numeric bound may be enforced.

  - A lower numeric bound may be enforced.

  - The stored value may be biased to zero by subtracting the lower bound (so,
    e.g., the range 9-12 may be stored in a two-bit field as 0-3 and then
    reconstituted as 9-12 when it is displayed).

  - The stored value may be represented as a bit in a set of bits, positioned by
    the supplied value, with the bits numbered from right-to-left or optionally
    from left-to-right, and with the bit numbers optionally biased by the lower
    bound.

  - The stored value may be printed only if named explicitly in the command.

  - The stored value may be designated read-only, disallowing the SET command.

These options are activated by specifying expanded modifier flags in the MTAB
entry.


Background
~~~~~~~~~~

The current MTAB structure looks like this:

  - mask    = bit mask for testing the unit.flags field
  - match   = value to be stored (SET) or compared (SHOW)
  - pstring = pointer to character string printed on a match (SHOW), or NULL
  - mstring = pointer to character string to be matched (SET), or NULL
  - valid   = address of validation routine (SET), or NULL
  - disp    = address of display routine (SHOW), or NULL
  - help    = 4.0 dummy

The "mask" field has two interpretations.  If bit 31 = 0, then the entry is a
regular modifier for the UNIT "flags" field, and bits 30-0 provide a mask for
that field (implying that only 15 of the 16 "user flag bits" are available).  If
bit 31 = 1 (MTAB_XTD), then the entry is an extended modifier, and bits 5-0
provide additional flags that configure the entry.


Implementation
~~~~~~~~~~~~~~

The existing MTAB structure is augmented by adding a new "uint32 expander" field
to the end of the current definition.  If this field is zero, which it will be
for all existing simulators, then the entry is not an expanded MTAB, and the
existing interpretation as a regular or extended MTAB is used, depending on bit
31 of the "mask" field.

Bits within the "expander" field control the expanded operation, as follows:

   31  30  29  28  27  26  25  24  23  22  21  20  19  18  17  16
  +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
  | user reserved | - | - | - | N | R | L | P | B | M | G | U | D |
  +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
  |             minimum value             |         radix         |
  +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
   15  14  13  12  11  10   9   8   7   6   5   4   3   2   1   0

Where:

  D = the modifier applies to devices
  U = the modifier applies to units
  G = the modifier applies to a global variable
  M = the mask instead of the match field is supplied to the validation routine
  B = the user-supplied value is biased by the minimum
  T = the user-supplied value is converted to a bit position
  L = the bit position number increases from left to right
  R = target is read-only; only SHOW is allowed
  N = SHOW only if the option is named in the command

An entry is expanded if either the D or U bit is set.  Unused bits are
reserved for future use.

The value in the "radix" field determines whether the MTAB operation is a flag
modifier or a value modifier.  If the radix is zero, then the operation modifies
a flag and uses the "SET <dev/unit> <option>" command form with the existing
regular MTAB "mask" and "match" semantics.  If the radix is greater than zero,
the operation modifies a value and uses the "SET <dev/unit> <option>=<value>"
command form.

In the following descriptions, the "target" indicates the destination of the
modified value or the source of the displayed value.  The target may be located
in the DEVICE or UNIT flags field, in a specified field within a DEVICE or UNIT
structure, or within a uint32 global variable (for SET/SHOW <device>) or a
uint32 element in a global array (for SET/SHOW <unit>) corresponding to the unit
number.

The G, D, and U bits, plus the "desc" field, determine the target, as follows:

  Bits Set   desc    Target
  --------  -------  -------------------------------------------------------
     D      NULL     The user flags part of the DEVICE "flags" field
     U      NULL     The user flags part of the UNIT "flags" field
     D      pointer  The DEVICE field addressed by "desc"
     U      pointer  The UNIT field addressed by "desc" in unit 0
   D + G    pointer  The global scalar addressed by "desc"
   U + G    pointer  The global array element addressed by "desc" and unit #

Setting the G bit indicates that a global variable is modified or displayed,
rather than a field in the DEVICE or UNIT structure.

Setting the D bit requires a device name to be specified in the SET or SHOW
command.  If the "desc" field is NULL, then the "flags" field of the DEVICE
structure is the target.  If the "desc" field is not NULL, then it points at the
target field in the DEVICE structure if the G bit is clear, or it points at a
uint32 scalar variable if the G bit is set.

Setting the U bit requires a unit name to be specified in the SET or SHOW
command.  If the "desc" field is NULL, then the "flags" field of the UNIT
structure is the target.  If the "desc" field is not NULL, then it points at the
target field in the UNIT structure of unit 0 if the G bit is clear, or it points
at a uint32 array variable if the G bit is set.  In these cases, the target is
adjusted to the UNIT field or array element corresponding to the specified unit
number.

If the D and U bits are both specified, or if the G bit is specified and the
"desc" field is NULL, then an "Internal error" failure occurs.

Setting the M bit supplies the mask field instead of the match field as the
"value" parameter to the optional validation routine.  This is required when
validating that a flag may be cleared, as the match field is zero for such
entries.

The B, T, L, and N bits pertain only to value modifiers.  If the radix field is
zero, i.e., the entry is a flag modifier, these bits are ignored.

The "radix" field is used to parse the value parameter, which is an unsigned
integer, and the "mask" field specifies a set of contiguous bits that identifies
the field within the indicated item to modify or display.  For a SET command, if
the "minimum value" field is non-zero, then the supplied value is rejected if it
is less than the specified minimum.  If the MTAB "match" field is non-zero, then
it is interpreted as a maximum value, and the supplied value is rejected if it
is greater than the specified maximum.  If the value passes the constraints, it
is stored in the target.  A SHOW command will extract the value from the target
and display it in the specified radix.

Setting the B bit biases the stored value by the specified minimum value, which
shifts the stored range from <min> to <max> to the range 0 to <max> minus <min>.
The bias is automatically removed when the value is displayed.  This allows a
field to be wide enough to contain the value's range without requiring the width
needed to hold the maximum value.  For example, a modifier specifying the B bit
with a range of 9-12 would require only two bits in the target field.  Without
the B bit, four bits would be required.  This also allows, e.g., the values A-D
to be stored in two bits by specifying the radix as 16 and the minimum value as
10.

Setting the T bit converts the numeric value into a bit whose position
corresponds to the value, counting from right to left, where the LSB is bit 0.
The bit position is converted back into an integer when the value is displayed.

Setting the L bit in addition to the T bit converts the numeric value into a bit
whose position corresponds to the value, counting from left to right, where the
LSB is the bit corresponding to the maximum value.

If the B bit is also set, then the value is biased as above before converting
into bit.  If the L bit is set and the T bit is clear, then the L bit is
ignored.

Setting the R bit rejects SET commands.  Only SHOW commands are allowed.

Setting the N bit suppresses the display of the target value unless the option
is explicitly given in the SHOW command.  This corresponds to the similar
operation provided for extended MTABs.

For numeric and bit-positional modifiers, the value is left-shifted to the
location of the least-significant bit of the mask value, masked, and deposited
into the target location.

The four "user reserved" bits are reserved for user interpretation.  Example
uses might be to indicate how the "desc" field should be adjusted for multiple
instances, or to indicate that special additional actions must be taken by the
validation or display routines.

For SET, an expanded MTAB entry is interpreted as follows:

 1. Test to see if the mstring entry exists.

 2. Test to see that the SET option matches the mstring.

 3. Test to see if SET is allowed for the entry (not read-only).

 4. Test to see if the entry is valid for the type of SET being done (device or
    unit).

 5. Determine the target location for the value.

 6. If a radix is defined, parse the value specified after the option name and
    verify that it is within the range allowed; convert to a positioned bit if
    requested.  If a radix is not defined, then the match field (or the mask
    field if the M bit is set) supplies the value.

 7. Call the validation routine, if any.

 8. If a radix is defined and the entry specifies biasing, subtract the
    specified minimum from the numeric value or right-shift the positioned bit.
    Then left-shift the value to align with the mask field.

 9. Apply the mask value to the target location and then merge the value into
    the location.

For SHOW, an expanded MTAB entry is interpreted as follows:

 1. Test to see if the pstring and mstring entries exist.

 2. If an option is specified, test to see that it matches the mstring and that
    a radix is defined, as named commands are allowed only for numeric values.
    If an option is not specified, and the entry requires a named command,
    return without displaying anything.

 3. Test to see if the entry is valid for the type of SET being done (device or
    unit).

 4. Determine the source location of the value.

 5. Apply the mask value to the source value.

 6. If a radix is defined, right-shift the value to right-align it and remove
    any applied bias.  If a radix is not defined, test to see that the masked
    value equals the match value.

 7. Call the display routine, if any.

 8. If a radix is defined, convert from a positioned bit back to a bit number if
    specified and then print the pstring and the value in the specified radix.
    If a radix is not defined, print the pstring by itself.


Validation and Display Routines
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The validation routine, declared as:

  t_stat validation_routine (UNIT *uptr, int32 value, char *cptr, void *desc)

...confirms that the target location can be set to "value".  The display
routine, declared as:

  t_stat display_routine (FILE *st, UNIT *uptr, int value, void *desc)

...confirms that the source value should be displayed.  For these routines, the
parameters they receive for the various expanded modifiers, are determined by
the D, U, and G bits, and the content of the "radix" and "desc" fields, as
follows:

  ----- Modifier Entry -----  ---- Routine Parameters ----
  D  U  G  rdx  desc field    uptr    value  cptr  desc     Destination or Source
  -  -  -  ---  ------------  ------  -----  ----  -------  ---------------------
  0  1  0   0   NULL          unit N  match  NULL  device   UNIT flags field
  0  1  0   0   UNIT field    unit N  match  NULL  ufield   UNIT user field
  0  1  1   0   array of N    unit N  match  NULL  element  array element

  1  0  0   0   NULL          unit 0  match  NULL  device   DEVICE flags field
  1  0  0   0   DEVICE field  unit 0  match  NULL  dfield   DEVICE user field
  1  0  1   0   uint32        unit 0  match  NULL  scalar   scalar variable

  0  1  0   n   NULL          unit N  num    parm  device   UNIT flags field
  0  1  0   n   UNIT field    unit N  num    parm  ufield   UNIT user field
  0  1  1   n   array of N    unit N  num    parm  element  array element

  1  0  0   n   NULL          unit 0  num    parm  device   DEVICE flags field
  1  0  0   n   DEVICE field  unit 0  num    parm  dfield   DEVICE user field
  1  0  1   n   uint32        unit 0  num    parm  scalar   scalar variable

On entry to the display routine, the "stream" parameter is always the open
output stream, and the "value" parameter is always the source value.  The "uptr"
and "desc" parameters are as above.  On entry to the validation routine for a
flag modifier, the "mask" field is substituted for the "match" field if the M
bit is set.  On entry to the validation routine for a value modifier, "cptr"
points at the value parameter string, and "value" will be the parsed value or -1
if parsing fails.

The return value from the routines is SCPE_OK if the value may be stored or
displayed, or another SCPE error code if the value must not be stored or
displayed due to an error, or -1 to indicate success but inhibit storing or
displaying the value because the routine itself has already done it.

An example of a validation routine that sets the value itself is one used to
validate a channel switch value that ranges from 0-7 but also has an OFF
position.  If the user had entered a SET MT CHANNEL=OFF command, then the
routine would be entered with the "value" parameter set to -1 and the "cptr"
parameter pointing at the "OFF" string.  The routine would then take the
appropriate action for the OFF setting and return -1; this is treated as
success, except that the value will not be set after returning.


Summary
~~~~~~~

Expanded MTAB entries won't address all of a simulator's modification and
display issues, but it should reduce the complexity substantially for those
actions that essentially duplicate existing SCP field modification actions.


Extensions
~~~~~~~~~~

It might be useful to add "userflags" fields to the DEVICE and UNIT structures.
The current arrangement has both system flags and user flags contending for the
same 32-bit space, and a few device simulators use all or almost all of the
available user flags.  If in the future the system set must expand, it runs the
risk of reducing the user field beyond the requirements of those devices.  Also,
the user flags field is partly occupied by the magnetic tape library flags, and
if the latter must expand, the former may overflow.  If expansion forces a
device to move some user flags to one of the user fields (i.e., u3 through u6),
and those fields are already committed, a substantial rewrite of the device
simulation may be required.

Appending a "userflags" field to the end of the existing DEVICE and UNIT
structures would not require any changes to existing simulators, but it would
allow devices with extensive option settings to maintain them in single
locations that would be unaffected by any system flags expansion.  Manipulation
of such new fields could be easily accomplished by adding an MTAB_EUF modifier
to expanded MTAB processing to provide for a "userflags" target.