.. index:: Jacobs-DeArras;instructions
.. index:: HP;instructions
.. index:: instructions;HP, instructions;Jacobs-DeArras

================
Instruction sets
================

Both the HP and Jacobs-DeArras instruction sets are supported. The
tools will use HP by default.

The reason for that there are two popular instruction sets is that HP
did not originally publish its instruction set. Based on available
fragments of information and a tremendous work by the user community,
the instruction set was figured out.

Jim DeArras even went on to document the disassembled listings of the
HP-41 firmware and when HP realized that the community was succeeding,
they released the original listings.

However, the momentum was ongoing and we ended up with two popular
instruction sets.

Why choose one over the other? The main reason to choose the HP
instruction set is that it makes it easier to read the available
source code listings. The main reason to choose the Jacobs-DeArras
instruction set is that it is very popular.

No matter which you choose, you will most likely end up having a
decent knowledge of the other instruction set as well.
This section will take you through the main differences.


Non-local jumps
---------------

The 64K conditional jump and jump to subroutine instructions are named
differently.

.. table:: Non-local jumps
 :widths: 1 1
 :column-dividers: none single none

 +----------------+----------------+
 |HP              |Jacobs-DeArras  |
 +================+================+
 |``gosub``       |``?ncxq``       |
 +----------------+----------------+
 |``gsubc``       |``?cxq``        |
 +----------------+----------------+
 |``golong``      |``?ncgo``       |
 +----------------+----------------+
 |``golc``        |``?cgo``        |
 +----------------+----------------+

HP uses variants ``gsubnc`` and ``golnc`` which typically used after a
test instruction (that sets carry) to say that we *do* care about the
carry here *not* to be set. The ``gosub`` and ``golong`` variants are
used when we know the carry will be clear and the instruction is meant
to be unconditional (the carry auto-resets after each instruction that
does otherwise affect it).


Local branches
--------------

Short branches also have different names.

.. table:: Local branches
 :widths: 1 1
 :column-dividers: none single none

 +----------------+----------------+
 |HP              |Jacobs-DeArras  |
 +================+================+
 |``goto``        |``jnc``         |
 +----------------+----------------+
 |``goc``         |``jc``          |
 +----------------+----------------+

Similar to non-local jumps, the ``gonc`` instruction is used after a
test when we want to make it clear that we branch on carry not set.


Other jump and subroutine instructions
--------------------------------------

.. table:: Subroutine related
 :widths: 1 1
 :column-dividers: none single none

 +----------------+----------------+
 |HP              |Jacobs-DeArras  |
 +================+================+
 |``gotoc``       |``gotoadr``     |
 +----------------+----------------+
 |``stk=c``       |``pushadr``     |
 +----------------+----------------+
 |``c=stk``       |``popadr``      |
 +----------------+----------------+
 |``spopnd``      |``xq>go``       |
 +----------------+----------------+
 |``rtnnc``       |``?ncrtn``      |
 +----------------+----------------+
 |``rtnc``        |``?crtn``       |
 +----------------+----------------+


Page relocatable jumps
----------------------

.. table:: Page relative jumps
 :widths: 1 1
 :column-dividers: none single none

 +----------------+----------------+
 |HP              |Jacobs-DeArras  |
 +================+================+
 |``gsbp``        |``rxq``         |
 +----------------+----------------+
 |``golpc``       |``rgo``         |
 +----------------+----------------+
 |``gsb41c``      |``rxq``         |
 +----------------+----------------+
 |``gol41c``      |``rgo``         |
 +----------------+----------------+



Pointer instructions
--------------------

.. table:: Pointer related
 :widths: 1 1
 :column-dividers: none single none

 +----------------+----------------+
 |HP              |Jacobs-DeArras  |
 +================+================+
 |``selp``        |``slctp``       |
 +----------------+----------------+
 |``selq``        |``slctq``       |
 +----------------+----------------+
 |``decpt``       |``r=r-1``       |
 +----------------+----------------+
 |``incpt``       |``r=r+1``       |
 +----------------+----------------+
 |``pt=``         |``r=``          |
 +----------------+----------------+
 |``?pt=``        |``?r=``         |
 +----------------+----------------+



Arithmetic instructions
-----------------------

These are mostly the same in both the instruction sets. There are a
couple of differences as follows:

.. table:: Arithmetics
 :widths: 1 1
 :column-dividers: none single none

 +----------------+----------------+
 |HP              |Jacobs-DeArras  |
 +================+================+
 |``abex``        |``a<>b``        |
 +----------------+----------------+
 |``acex``        |``a<>c``        |
 +----------------+----------------+
 |``bcex``        |``c<>b``        |
 +----------------+----------------+
 |``c=-c``        |``c=0-c``       |
 +----------------+----------------+

HP favors alphabetic order in the exchange instructions, while
Jacobs-DeArras favors the more versatile register first.

The operand field to the arithmetic instructions shows more variation:

.. table:: Arithmetic operand fields
 :widths: 1 1
 :column-dividers: none single none

 +----------------+----------------+
 |HP              |Jacobs-DeArras  |
 +================+================+
 |``pt``          |``@r``          |
 +----------------+----------------+
 |``x``           |``s&x``         |
 +----------------+----------------+
 |``wpt``         |``r<-``         |
 +----------------+----------------+
 |``w``           |``all``         |
 +----------------+----------------+
 |``pq``          |``p-q``         |
 +----------------+----------------+
 |``xs``          |``xs``          |
 +----------------+----------------+
 |``m``           |``m``           |
 +----------------+----------------+
 |``s``           |``ms``          |
 +----------------+----------------+

HP has the benefit of using only letters, which makes it easier to
parse them as register fields in expressions (used in the debugger).


Flag instructions
-----------------

This is a significant areas where the instruction sets differ. Also
note that ``st=0`` exists in both instruction sets, but are
used for different instructions.

.. table:: Flags
 :widths: 1 1
 :column-dividers: none single none

 +----------------+----------------+
 |HP              |Jacobs-DeArras  |
 +================+================+
 |``st=0``        |``crlf``        |
 +----------------+----------------+
 |``s5=0`` etc    |``clrf  5``     |
 +----------------+----------------+
 |``st=1``        |``setf``        |
 +----------------+----------------+
 |``s5=1`` etc    |``setf  5``     |
 +----------------+----------------+
 |``?st=1``       |``?fset``       |
 +----------------+----------------+
 |``st=1?``       |``?fset``       |
 +----------------+----------------+
 |``?s5=1`` etc   | ``?fset 5``    |
 +----------------+----------------+
 |``clrst``       |``st=0``        |
 +----------------+----------------+
 |``cstex``       |``c<>st``       |
 +----------------+----------------+


Data memory
-----------

This is another area of significant differences in naming.

.. table:: Data memory
 :widths: 1 1
 :column-dividers: none single none

 +----------------+----------------+
 |HP              |Jacobs-DeArras  |
 +================+================+
 |``dadd=c``      |``ramslct``     |
 +----------------+----------------+
 |``data=c``      |``writedata``   |
 +----------------+----------------+
 |``c=data``      |``readdata``    |
 +----------------+----------------+
 |``regn=c``      |``writ``        |
 +----------------+----------------+
 |``c=regn``      |``read``        |
 +----------------+----------------+


Keyboard
--------

.. table:: Keyboard
 :widths: 1 1
 :column-dividers: none single none

 +----------------+----------------+
 |HP              |Jacobs-DeArras  |
 +================+================+
 |``rstkb``       |``clrkey``      |
 +----------------+----------------+
 |``chkkb``       |``?key``        |
 +----------------+----------------+
 |``c=keys``      |``c=key``       |
 +----------------+----------------+
 |``gokeys``      |``gtokey``      |
 +----------------+----------------+



Miscellaneous
-------------

Here are the remaining instructions that differs.

.. table:: Miscellaneous
 :widths: 1 1
 :column-dividers: none single none

 +----------------+----------------+
 |HP              |Jacobs-DeArras  |
 +================+================+
 |``cxisa``       |``fetch``       |
 +----------------+----------------+
 |``lc``          |``ld@r``        |
 +----------------+----------------+
 |``selpf``       |``selp``        |
 +----------------+----------------+
 |``?flg=1``      |``?fi``         |
 +----------------+----------------+
 |``cnex``        |``c<>n``        |
 +----------------+----------------+
 |``cmex``        |``c<>m``        |
 +----------------+----------------+
 |``cgex``        |``c<>g``        |
 +----------------+----------------+
 |``f=sb``        |``t=st``        |
 +----------------+----------------+
 |``sb=f``        |``st=t``        |
 +----------------+----------------+
 |``fexsb``       |``st<>t``       |
 +----------------+----------------+
 |``?lld``        |``?lowbat``     |
 +----------------+----------------+
 |``clrabc``      |``a=b=c=0``     |
 +----------------+----------------+
 |``pfad=c``      |``prphslct``    |
 +----------------+----------------+
 |``disoff``      |``dspoff``      |
 +----------------+----------------+
 |``distog``      |``dsptog``      |
 +----------------+----------------+
