Bugs in BitWordOps shift functions and documentation

[Nelson H. F. Beebe]

This note follows a previous list posting at

        https://lists.nongnu.org/archive/html/gm2/2024-02/msg00001.html

about a bug in the LowShort.fraction() implementation.

This message shows three problems with the bit-shift functions in
module BitWordOps and their documentation.  The bugs exists in gm2-13
and gm2-14 compilers up to the snapshots of mid-January 2024.

Here is a test program:

        % cat wordshiftbugs.mod
        MODULE wordshiftbugs;

        FROM NumberIO   IMPORT WriteHex, WriteInt;
        FROM RealInOut  IMPORT WriteShortReal;
        FROM StrIO      IMPORT WriteLn, WriteString;
        FROM BitWordOps IMPORT WordShl, WordShr;

        VAR k, x, y : CARDINAL;

        BEGIN
            WriteString('Demonstration of direction bug in WordShl() and 
WordShr()');
            WriteLn;
            WriteLn;

            x := 1;

            FOR k := 0 TO 35 DO
                y := WordShr(x, k);
                WriteString('WordShr(0x');       (* NB: LEFT shift here *)
                WriteHex(x, 0);
                WriteString(', ');
                WriteInt(k, 2);
                WriteString(') = 0x');
                WriteHex(y, 8);
                WriteLn
            END;

            WriteLn;

            WriteString('Demonstration of direction bug in WordShl()');
            WriteLn;
            WriteLn;

            x := 80000000H;

            FOR k := 0 TO 35 DO
                y := WordShl(x, k);
                WriteString('WordShl(0x');       (* NB: Right shift here *)
                WriteHex(x, 0);
                WriteString(', ');
                WriteInt(k, 2);
                WriteString(') = 0x');
                WriteHex(y, 8);
                WriteLn
            END;

            WriteLn;
            WriteString('Notice also that the shift count is reduced modulo the 
word size.');
            WriteLn;
            WriteString('While this is common in CPU hardware, it is not 
documented in the');
            WriteLn;
            WriteString('BitWordOps.{def,mod} files, and should be.');
            WriteLn
        END wordshiftbugs.

Here is its output:

        % gm2 wordshiftbugs.mod && ./a.out
        Demonstration of direction bug in WordShl() and WordShr()

        WordShr(0x1,  0) = 0x00000001
        WordShr(0x1,  1) = 0x00000002
        WordShr(0x1,  2) = 0x00000004
        WordShr(0x1,  3) = 0x00000008
        WordShr(0x1,  4) = 0x00000010
        WordShr(0x1,  5) = 0x00000020
        WordShr(0x1,  6) = 0x00000040
        WordShr(0x1,  7) = 0x00000080
        WordShr(0x1,  8) = 0x00000100
        WordShr(0x1,  9) = 0x00000200
        WordShr(0x1, 10) = 0x00000400
        WordShr(0x1, 11) = 0x00000800
        WordShr(0x1, 12) = 0x00001000
        WordShr(0x1, 13) = 0x00002000
        WordShr(0x1, 14) = 0x00004000
        WordShr(0x1, 15) = 0x00008000
        WordShr(0x1, 16) = 0x00010000
        WordShr(0x1, 17) = 0x00020000
        WordShr(0x1, 18) = 0x00040000
        WordShr(0x1, 19) = 0x00080000
        WordShr(0x1, 20) = 0x00100000
        WordShr(0x1, 21) = 0x00200000
        WordShr(0x1, 22) = 0x00400000
        WordShr(0x1, 23) = 0x00800000
        WordShr(0x1, 24) = 0x01000000
        WordShr(0x1, 25) = 0x02000000
        WordShr(0x1, 26) = 0x04000000
        WordShr(0x1, 27) = 0x08000000
        WordShr(0x1, 28) = 0x10000000
        WordShr(0x1, 29) = 0x20000000
        WordShr(0x1, 30) = 0x40000000
        WordShr(0x1, 31) = 0x80000000
        WordShr(0x1, 32) = 0x00000001
        WordShr(0x1, 33) = 0x00000002
        WordShr(0x1, 34) = 0x00000004
        WordShr(0x1, 35) = 0x00000008

        Demonstration of direction bug in WordShl()

        WordShl(0x80000000,  0) = 0x80000000
        WordShl(0x80000000,  1) = 0x40000000
        WordShl(0x80000000,  2) = 0x20000000
        WordShl(0x80000000,  3) = 0x10000000
        WordShl(0x80000000,  4) = 0x08000000
        WordShl(0x80000000,  5) = 0x04000000
        WordShl(0x80000000,  6) = 0x02000000
        WordShl(0x80000000,  7) = 0x01000000
        WordShl(0x80000000,  8) = 0x00800000
        WordShl(0x80000000,  9) = 0x00400000
        WordShl(0x80000000, 10) = 0x00200000
        WordShl(0x80000000, 11) = 0x00100000
        WordShl(0x80000000, 12) = 0x00080000
        WordShl(0x80000000, 13) = 0x00040000
        WordShl(0x80000000, 14) = 0x00020000
        WordShl(0x80000000, 15) = 0x00010000
        WordShl(0x80000000, 16) = 0x00008000
        WordShl(0x80000000, 17) = 0x00004000
        WordShl(0x80000000, 18) = 0x00002000
        WordShl(0x80000000, 19) = 0x00001000
        WordShl(0x80000000, 20) = 0x00000800
        WordShl(0x80000000, 21) = 0x00000400
        WordShl(0x80000000, 22) = 0x00000200
        WordShl(0x80000000, 23) = 0x00000100
        WordShl(0x80000000, 24) = 0x00000080
        WordShl(0x80000000, 25) = 0x00000040
        WordShl(0x80000000, 26) = 0x00000020
        WordShl(0x80000000, 27) = 0x00000010
        WordShl(0x80000000, 28) = 0x00000008
        WordShl(0x80000000, 29) = 0x00000004
        WordShl(0x80000000, 30) = 0x00000002
        WordShl(0x80000000, 31) = 0x00000001
        WordShl(0x80000000, 32) = 0x80000000
        WordShl(0x80000000, 33) = 0x40000000
        WordShl(0x80000000, 34) = 0x20000000
        WordShl(0x80000000, 35) = 0x10000000

        Notice also that the shift count is reduced modulo the word size.
        While this is common in CPU hardware, it is not documented in the
        BitWordOps.{def,mod} files, and should be.

-------------------------------------------------------------------------------
- Nelson H. F. Beebe                    Tel: +1 801 581 5254                  -
- University of Utah                                                          -
- Department of Mathematics, 110 LCB    Internet e-mail: beebe@math.utah.edu  -
- 155 S 1400 E RM 233                       beebe@acm.org  beebe@computer.org -
- Salt Lake City, UT 84112-0090, USA    URL: http://www.math.utah.edu/~beebe/ -
-------------------------------------------------------------------------------