====
NEWT
====

.. index:: NEWT

The NEWT (Nut Enhanced With Turbo, also known as the HP-41CL) target
variant is supported by the tools. The main difference when
programming for the NEWT is that it uses speed annotation bits to
control the pace of timing loops. This is accomplished using 16-bit
words compared to the usual 10-bit words used by the Nut target.

In order to use 16-bit words in output you need to enable it using the
``--core=NEWT`` command line option, which is accepted by all tools
where it is relevant.

In addition to speed annotation, the ``--core=NEWT`` command line
option also enables recognition of the ``WCMD`` instruction.

.. index:: NEWT;speed annotation, 41CL; speed annotation, speed annotation

Speed annotation
----------------

Use NEWT directives to insert speed annotation bits in a fragment of
code where normal speed is to always to be obeyed:

.. code-block:: ca65

   nullTest:     ldi     200
                 .newt_timing_start
                 disoff
   72$:          rst kb
                 chk kb
                 gonc    73$
                 c=c-1   x
                 gonc    72$
                 distog
                 .newt_timing_end
                 gosub   NULTST

When compiled with ``--core=NEWT`` the list file shows the
generated 16-bit words:

.. code-block:: ca65

   0367  0049 013000c8 nullTest:     ldi     200
   0368                              .newt_timing_start
   0369  004b 32e0                   disoff
   0370  004c 33c8     72$:          rst kb
   0371  004d 33cc                   chk kb
   0372  004e 303b                   gonc    73$
   0373  004f 3266                   c=c-1   x
   0374  0050 33e3                   gonc    72$
   0375  0051 3320                   distog
   0376                              .newt_timing_end
   0377  0052 03190038               gosub   NULTST

Here you can see that generated words are four digits compared to the
usual three. ``0x3000`` is also added to each instruction inside the
NEWT timing annotated block.

Module files
------------

The traditional modules files (``.mod`` file extension) stores packed
10-bit words. There is no place for the speed annotation bits. Prior
to the ``.mod`` files the use of ``.rom`` files were common. These
are single separate files for a single page using 16-bit words.
Any rules associated with a multi-page module need to be handled
manually. A module file allows pages to be combined together with some
meta data that describes the combination and also contains rules for how
the pages can be placed in memory.

The Calypsi tool chain provides a module file variant with extension
``.mod2`` which is like ``.mod`` files, but the pages are stored as
16-bits words the same way as ``.rom`` files.

Dual format output
^^^^^^^^^^^^^^^^^^

If your module contains NEWT speed annotations it is desirable to
output a ``.mod2`` file. However, many tools only support ordinary
``.mod`` files and there are lots of people using standard HP-41
calculators. In such cases it makes sense to output and distribute
both formats, which can be accomplished by giving the
``--extra-output-formats=mod2`` command line option to the linker.
