[Libre-soc-dev] v3.0B spec, ambiguous definitions for "L" in X-Form

[Luke Kenneth Casson Leighton]

hi folks, i think i mentioned this before however it's come up again and is
causing issues / ambiguities, requiring further changes to the pseudo-code
and the field definitions that were extracted from the v3.0B spec PDF.

the problem is that the information in 1.6.15 is insufficient to identify -
on its own - which "L" is to be used.  there are therefore multiple
definitions of the *same* field "L".  (4 definitions, in fact, just for
X-Form alone).

all fine, right up until the point where one tries to actually use those in
an auto-generated parser, which creates a dictionary-of-dictionaries
containing the form-field bit ranges, at which point, when trying to select
*which* X-Form "L", the last one inserted by the parser into the X-Form
dictionary has "won".

the solution is to rename the L fields so that they are no longer ambiguous
(below)

* L for cmp operations (because it is shared with D-Form)
* L1 for mtmsr
* L2 for data cache block
* L3 for darn

the counterargument (case for *not* making such a spec change) is: each
instruction definition has the (correct) definition of the fields,
unambiguously listed (p85 cmpi has L defined as being bit 10 and so on),
and consequently we might reasonably assert "the information's there, deal
with it".

such a perspective unfortunately becomes unhelpful even when examining the
Reference Implementation of microwatt, which has insn_helpers.vhdl defining
"insn_l()" for example, as *specifically* being an accessor of bit 21
(LSB-numbering) aka bit 10 (MSB0 v3.0B spec numbering) of the instruction:

    function insn_l (insn_in : std_ulogic_vector) return std_ulogic is
    begin
        return insn_in(21);
    end;

through its naming alone that may confuse and mislead readers into
believing that *all* definitions of "L" are X-Form bit 10 and X-Form bit 10
only.

such a change to the spec however is... how can i put it best...
"intrusive", visually, and may lead readers to believe that these are
entirely new fields and so on.  however a thought there: subscripts could
be used to good effect, to identify the different ambiguous "versions" of
L, without giving the impression that it is a drastic change to the spec:
merely clarity.

i leave it with everyone, for discussion when the ISA WG is officially
formed / announced, i just wanted to make sure that there's a record of
this.

l.


# 1.6.7 X-FORM
   |0     |6 |7|8|9  |10  |11|12|13  |15|16|17     |20|21    |31  |
   | OPCD |       RS      |    ///   |L1|     ///     |   XO |  / | <- used
by mtmsr
   | OPCD |       TH      |    RA       |    RB       |   XO |  / |
   | OPCD |  BF  |/  | L  |    RA       |    RB       |   XO |  / |   <-
used by cmp ops
   | OPCD |  BF  |//      |   FRA       |   FRB       |   XO |  / |
   | OPCD |  BF  |//      | BFA | //    |     ///     |   XO |  / |
   | OPCD |  BF  |//      |    ///   |W |    U     |/ |   XO |Rc  |
   | OPCD |  BF  |//      |     ///     |     ///     |   XO |  / |
   | OPCD |       TH      |    RA       |    RB       |   XO |  / |
   | OPCD | /| CT         |     ///     |     ///     |   XO |  / |
   | OPCD | /| CT         |    RA       |    RB       |   XO |  / |
   | OPCD |  /// | L2     |    RA       |    RB       |   XO |  / | <- data
cache block
   | OPCD |  /// | L2     |     ///     |    RB       |   XO |  / |
   | OPCD |  /// | L2     |     ///     |     ///     |   XO |  / |
   | OPCD |  /// | L2     | /|     E    |     ///     |   XO |  / |

    L (9:10)
         Field used by the Data Cache Block Flush instruc-
         tion
         Formats: X
    L (10)
         Field used to specify whether a fixed-point Com-
         pare
         Field used by the Compare Range Byte instruction
         Formats: D, X
    L (15)
         Field used by the Move To Machine State Register
         Field used by the SLB Move From Entry VSID and
         Formats: X
    L (14:15)
         Field used by the Deliver A Random Number
         instruction (see Section 3.3.9, 'Fixed-Point Arith-
         metic Instructions') to choose the random number
         format.
         Formats: X
---
crowd-funded eco-conscious hardware: https://www.crowdsupply.com/eoma68