-------------------------------------------------------------------------------
Free42 is a software clone of the Hewlett-Packard 42S calculator. If you know
how to use an HP-42S, you know how to use Free42.
If you're new to the HP-42S and its clones, you may want to take a peek at the
manual. You can find documentation at https://thomasokken.com/free42/#doc

The remainder of this README file covers some miscellaneous tidbits that I had
no other decent place to put.


-------------------------------------------------------------------------------
Binary vs. Decimal
Free42 can be built with binary or with decimal floating point. The Windows,
MacOS, iOS, and Android projects all contain separate targets for Decimal and
Binary builds; for the Linux version, the selection is made using the BCD_MATH
environment variable.
When switching between building the decimal and binary version for Linux, be
sure to do "make clean", to avoid linking the wrong objects.


-------------------------------------------------------------------------------
Building on Raspbian 10

# apt install libgtk-3-dev
# apt install libasound2-dev
$ git clone https://github.com/thomasokken/free42.git
$ cd free42/gtk
$ make BCD_MATH=1 AUDIO_ALSA=1


-------------------------------------------------------------------------------
Creating Free42 build environment in FreeBSD

Create VirtualBox VM (using VirtualBox 5.2.22)
Install FreeBSD-12.0-RELEASE-amd64-dvd1.iso

then:

pkg install gnome3
pkg install xorg
pkg install virtualbox-ose-additions

in /etc/fstab, added:
proc           /proc       procfs  rw  0   0

in /etc/rc.conf, added:
vboxguest_enable="YES"
vboxservice_enable="YES"
dbus_enable="YES"
hald_enable="YES"
gdm_enable="YES"
gnome_enable="YES"

That brings up the desktop.
Now, some more stuff:

pkg install devel/pkgconf
pkg install devel/gmake


-------------------------------------------------------------------------------
Adding types:

When adding a type 'foo', you need to define an appropriate vartype_foo struct,
create a new_foo() function (constructor), and add support for the new type in
* dup_vartype()
* free_vartype()
* vartype2string()
* persist_vartype()
* unpersist_vartype()
* vartype_equals()
* core_copy() and core_paste()
  (Note that even if you choose not to support copying and pasting objects of
  the new type by themselves, you should always support copying and pasting
  them as part of a list, by adding the appropriate code in serialize_list()
  and deserialize_list().)


-------------------------------------------------------------------------------
clang optimizer weirdness

In recent versions of clang (not sure starting when; I noticed it in early
April 2023), the compiler pursues an aggressive optimization strategy that can
cause it to emit provably incorrect code. Specifically:

In tb_print_current_program() (core_display.cc), the 'if (line > 0) { ... }'
block is executed even the first time through the loop, when line is still 0.
Why? Apple tech support explained it like this: when line == 0, the local
variable orig_num is uninitialized when it is passed to prgmline2buf(). The
compiler considers this an error, but instead of emitting an error or a
warning, it jumps to the conclusion that line > 0 must always be true, since
that is the only way orig_num would always be initialized.

I find this explanation completely idiotic. You're taking code that is legal C,
and because of a point of arguably poor coding style, you generate clearly
incorrect code, by executing the 'if (line > 0)' block even when line == 0. I
could understand making the compiler emit a warning, or even an error, for this
kind of code, although I would also expect there to be an option to disable
this check, since this is legal C code. But as it is, the compiler insists on
generating bad code. Rather than do the Apple-recommended fix of adding an
initializer to the declaration of orig_num, and then hope that no other
undiscovered problems like this exist elsewhere (remember: NO WARNING!), I
chose to use a less aggressive optimization level. The option -O1 is the
highest optimization level that avoids the problem, so that's what I'll stick
with until the issue is resolved, either by Apple removing this moronic
behavior from their compiler, or by them adding a warning so at least I'll know
exactly *what* to fix.

Note: the same code pattern exists in several places in core_display.cc,
specifically, all places where orig_num is used.
Also note: it's not even clear what is the exact condition when the compiler
goes nuts like this. The 'cmd' variable is also passed without being
initialized, but apparently, that is not a problem.
Finally note: this appears to be specific to Apple's clang, affecting the iOS
and MacOS versions. If this brain-damage should spread to other compilers, you
can tell when Copy in PRGM mode skips line 01.

UPDATE: I ran into another clang optimizer bug; this one causes ASSIGN ""
(Shift 1 ENTER ENTER) to fail, when building with -O1. The second ENTER isn't
handled correctly. I can't be bothered to find out where exactly the optimizer
messes up; this is the third time I've had a buggy release thanks to Apple's
clang. I've had it. I'm going with -O0 for all MacOS and iOS builds from now
on.


-------------------------------------------------------------------------------
About the character sets:
('bigchars' and 'smallchars' arrays in core_display.c)

The top half of the 256 character codes are like the bottom half,
with these exceptions:
0x80: thin colon (':') (looks different than regular colon),
      while 0x00 is a calculator-style divide sign (superposition
      of ':' and '-')
0x81: small 'Y'; 0x01: multiply sign
0x8a: displays 'LF' character (small 'L' and small 'F',
      slightly offset, squeezed into one character cell);
      0x0a: actual linefeed (move to next line of display).

The bigchars array contains 130 characters, in 5x8 pixel cells,
corresponding to codes 0-129. Char 10 is the 'LF' ligature.

Note: the 'x:' and 'y:' legends for the standard X and Y register display
are built from 0x78 (lowercase x), 0x81 (small 'Y'), and 0x80 (thin ':').
Note: 0x01 (multiply) is different than 0x78 (lowercase x) (it is 1 pixel
higher).


-------------------------------------------------------------------------------
HP-42S bugs that I found:

If you activate the CUSTOM menu in KEYASN mode, go to its third row, and then
switch to LCLBL mode, you get a menu row with labels "L", "M", "N", "O", "@",
"XEQ"; these keys activate the commands XEQ ST Z, XEQ ST Y, XEQ ST X, XEQ ST L,
XEQ 117, XEQ 118.
These commands do actually work, but entering the corresponding labels into a
program is a bit tricky...

->POL and ->REC with a real number in X reject a string in Y (good), accept a
real number in Y (good), accept a complex number in Y but only use its real
part (undocumented and not very useful), and accept real and complex matrices
in Y with weird results. I'd say the complex and matrix cases are all bugs,
resulting from a missing parameter type check.

If MATA, MATB, or MATX is the indexed matrix, and SIMQ resizes it to a smaller
size, IJ aren't set to (1, 1) as they usually are when the indexed matrix is
resized (though DIM or SIZE). As a result, IJ can end up pointing outside the
allocated elements, and RCLEL and STOEL can then produce wacky results.

HP-42S bugs that others have found:

When COMB or PERM are invoked with bad arguments (e.g. X > Y), "Invalid Data"
is returned (good), but all subsequent invocations of those two functions also
yield that message, even if the parameters are now correct (bad). This
condition can be cleared up by performing an operation that affects LASTx (but
not STO ST L). Apparently some rev. B models do not have this bug; I have read
that the original problem was a hardware bug, for which rev. B introduced a
software workaround; somewhere in the rev. B production run the hardware bug
was fixed, but now the software workaround would *cause* the bug. The bug also
exists in all rev. C models, apparently (it does in mine, and in Emu42 when run
with a rev. C ROM!).
I'm curious as to why a couple of basic, straightforward instructions like COMB
and PERM would be sensitive to a hardware bug (and *only* they, apparently),
but who am I to question what I've heard others report? I'm not about to spend
weeks poring over ROM disassemblies to make sure...

In LINΣ mode, summing a matrix is buggy. I have seen it sum only the first row,
and report a bogus value back in X (8.47216900137e-489), and also seen it say
Insufficient Memory when that clearly wasn't true; I have heard a report from
someone else about the machine even locking up to the point where it needs a
hard reset.

In some versions, in LINΣ mode, Σ+ and Σ- do not update LASTx. I read about
this in a manual addendum from HP; however, I cannot reproduce this, neither on
my real HP-42S nor on Emu42 (both rev. C ROM).

I have also heard a report that FCSTX is buggy in PWRF mode; I have not been
able to confirm this yet but there appears to be more I have to read about it.
Probably depends on your ROM version; I tested with rev. C but it seemed fine.

Not sure if this is a bug or not:

When KEYX or KEYG are used to reprogram the ▲ and ▼ keys, it would be nice if
the user would be alerted to this by the ▼▲ annunciator in the display turning
on. The manual does not mention this behavior, but older editions of the
Programming Examples and Techniques book do (page 34, bottom). It doesn't work
on the actual calculator, at least not on any that I've heard of.
Free42 does turn on the ▼▲ annunciator. Although my general rule is to mimic
the HP-42S as closely as possible, I felt that this was a nice feature and that
it's pretty unlikely to break anything. :-)


-------------------------------------------------------------------------------
[MIN], [MAX], and [FIND]: undocumented HP-42S matrix functions

[MIN] finds the lowest element of the current column, starting at the current
row, of the indexed matrix, and returns the element to X and the row where it
was found to Y; [MAX] is like [MIN] except it finds the highest element; if the
minimum or maximum is not unique (it is found in more than one row), the
highest matching row is returned. [MIN] and [MAX] require the indexed matrix to
be a real matrix, and they do not allow string elements in the column being
searched.

[FIND] locates a specific value, searching the indexed matrix left to right and
top to bottom. The function works as a conditional: when a program is running,
the following instruction is executed if a match is found, and skipped if a
match is not found; when executed interactively, the display shows "Yes" if a
match is found and "No" if not.
Also, if a match is found, I and J are set to point to it.
The indexed matrix may be real or complex, and the search value may be real,
complex, or string; real or string values are only found in real matrices, and
complex values are only found in complex matrices; in other words, 5 is not
considered equal to 5 + 0i -- mathematically speaking this is wrong, but on the
other hand it is consistent with the behavior of the X=Y? and X≠Y? functions.


-------------------------------------------------------------------------------
Differences between the Free42 printer emulation and the HP-42S/82240

Free42 prints programs differently in NORM or TRACE modes: in NORM mode, the
listing is right-justified, and in TRACE mode, the listing is compact (multiple
commands per line). The HP42S does not do this; Free42 "inherited" this
behavior from the HP-82143 printer, which the author remembers fondly. :-)

When the HP-42S has to print a line that is too long to fit on one physical
printer line (i.e., more than 24 characters), it takes no special action.
Whether the printer prints the overflow left- or right-justified remains to be
found out. I should check the 82240 specs to see how it behaves.
Free42 usually prints the overflow left-justified; the only exceptions are PRP
and LIST in NORM mode.