.. index:: MCODE, VASM listings, Unicode;UTF-8
.. index:: Jacobs-DeArras;instructions
.. index:: HP;instructions
.. index:: instructions;HP, instructions;Jacobs-DeArras

=============
Nut assembler
=============

The Nut assembler accepts a source file with HP mnemonics and
generates a relocatable object file as output. This is the same
mnemonics [#SPACE]_ used in the VASM listings [#VASM]_ which makes it
easier to follow them, compared to if you adopt another mnemonic set.

There are at least two other instructions sets in use, Jacobs-DeArras
and ZENROM. The assembler can be configured to accept Jacobs-DeArras
mnemonics using the ``--jda`` option, but not ZENROM.

.. running:: "Nut assembler" asnut
.. literalinclude:: gen/AsmSignOn.text
   :language: none

.. rubric:: Footnotes
.. [#SPACE]
   HP allows space inside some mnemonics, which is quite non-standard
   in assembly languages of today. This habit is only
   partially supported here in that you can optionally do it for
   instructions with an empty argument field.
.. [#VASM] These are list files from HP covering major portions of the
           HP-41 internals and is an important source of information
           about its inner workings.



.. index:: comments

Source file format
-------------------

Source lines to the assembler follow the traditional style, with a
label field starting in the first column, followed by an instruction
and any needed operands. Comments must be preceded by a semicolon::


   [label[:]]   [instruction  [operands]]  [; comment]


The instruction can either be a mnemonic (target instruction name) or
a directive. Directives start with a dot.


.. index:: labels

A label is a symbol that describes a source location. It can be defined
by placing it in the first column of a source line, optionally
followed by a colon.

Labels can also be declared by importing them using the ``.extern``
directive.


Pre-defined words used in instructions (mnemonics and operands) are
case *insensitive*, however symbols used in operands are case
sensitive. Some examples of source lines follows:

.. code-block:: ca65

   ; Comments start with a semi-colon
   ;
   lab:          c=0   w
                 nop         ; a comment
                 GOTO  lab



.. index:: symbols;syntax

Symbol syntax
^^^^^^^^^^^^^

Symbols are case *sensitive* and can be of arbitrary length.
A symbol starts with a letter or underscore and can be followed by
letters, underscores and digits. Examples of symbols are ``_4``,
``a_symbol``, ``abc`` and ``A1``.

.. index:: symbols;quoted, quoted symbols, back quoted symbols

If you want to use other characters in a symbol, it is possible to do
so by surrounding the symbol by back quotes. Such symbols can be
```another symbol``` and ```Table: 5```.


.. index:: conditional assembly, file inclusion, include files
.. _sec-c-preprocessor:

Preprocessor
------------

The assembler uses a full featured C preprocessor to handle the input
source file. The preprocessor provides the normal features you will
find in a C preprocessor, the ability to include header files, macro
expansions, conditional compilation and use of C style comments.

Wikipedia is a good place to look for an introduction with many
examples on how to use the
`C preprocessor <http://en.wikipedia.org/wiki/C_preprocessor>`_.

When used in the assembler, the following macros are predefined:

.. index:: __CALYPSI_NUT__ (predefined symbol), predefined symbol; __CALYPSI_NUT__
.. index:: __CALYPSI_ASM__ (predefined symbol), predefined symbol; __CALYPSI_ASM__

.. table:: Predefined processor symbols
 :widths: 1 3
 :column-dividers: none single none

 +---------------------------------+----------------------------------+
 |Preprocessor symbol              |Description                       |
 +=================================+==================================+
 |``__CALYPSI_NUT__``              |An integer that is 1 when the Nut |
 |                                 |target (including NEWT variant)   |
 |                                 |is used.                          |
 +---------------------------------+----------------------------------+
 |``__CALYPSI_ASM__``              |An integer that is 1 when the     |
 |                                 |assembler is used.                |
 +---------------------------------+----------------------------------+


.. index:: section, .section; directive, directive;.section
.. index:: section; fragments

Sections
--------

The assembly source file is divided into sections using the
``.section`` directive. A section is a unit of code or data that
cannot be split up in smaller pieces.
Sections are laid out in memory by the linker according to rules
provided by a rules file.

Before reading any input, an implicit ``.section code`` is
applied. This means you will start off in a section that is named
``code``.

Using multiple sections allow more flexible placement of the code at
link time compared to using a single section.
A section name can be used multiple times and each use results in an
individual section fragment.

All sections are relocatable and must be defined in the linker rules
file.


Expressions
------------

Numeric expressions work in signed (2-complement) mode with range
checking depending on how the end result is used. If the result
exceeds the allowed range, it is reported as an error. The
:ref:`operators` table shows the existing standard operators. In
addition to these, there are  also some rather specialized relocation
and section operators, refer to :ref:`relocationOperators` and
:ref:`sectionOperators` for more details.

You can use optionally use spaces between values and operators in an
expression.

.. index:: operators
.. _operators:
.. table:: Operators
 :widths: 1 1 2
 :column-alignment: left center left
 :column-dividers: none single single none

 +-----------+------------+----------------------+
 |Operator   |Precedence  |Purpose               |
 +===========+============+======================+
 |``~``      |9           |Unary bit-wise not    |
 |           |            |                      |
 +-----------+------------+----------------------+
 |``!``      |9           |Unary logical not     |
 +-----------+------------+----------------------+
 |``-``      |9           |Unary negate          |
 +-----------+------------+----------------------+
 |``+``      |9           |Unary plus            |
 +-----------+------------+----------------------+
 |``*``      |8           |Multiply              |
 +-----------+------------+----------------------+
 |``/``      |8           |Divide                |
 +-----------+------------+----------------------+
 |``%``      |8           |Modulo                |
 +-----------+------------+----------------------+
 |``+``      |7           |Add                   |
 +-----------+------------+----------------------+
 |``-``      |7           |Subtract              |
 +-----------+------------+----------------------+
 |``<<``     |6           |Bit shift left        |
 +-----------+------------+----------------------+
 |``>>``     |6           |Bit shift right       |
 +-----------+------------+----------------------+
 |``>``      |5           |Greater than          |
 +-----------+------------+----------------------+
 |``<``      |5           |Less than             |
 +-----------+------------+----------------------+
 |``>=``     |5           |Greater than or equal |
 +-----------+------------+----------------------+
 |``<=``     |5           |Less than or equal    |
 +-----------+------------+----------------------+
 |``==``     |4           |Equal                 |
 +-----------+------------+----------------------+
 |``!=``     |4           |Not equal             |
 +-----------+------------+----------------------+
 |``&``      |3           |Bit-wise and          |
 +-----------+------------+----------------------+
 |``^``      |2           |Bit-wise exclusive or |
 +-----------+------------+----------------------+
 |``|``      |1           |Bit-wise or           |
 +-----------+------------+----------------------+


.. index:: numbers, constants

Numeric constants
^^^^^^^^^^^^^^^^^

Integer constants values can be entered in decimal, binary, octal or
hexadecimal. A sequence of digits that do not start with a zero is
considered to be a decimal integer value. Any sequence starting with
``0x`` is considered a hexadecimal integer value, a ``0b`` prefix is
considered a binary integer value and any other sequence of digits
starting with ``0`` is considered to be an octal integer value.

Character constants can also be used and they are replaced by their
corresponding ASCII value.

Some examples:

.. literalinclude:: con.s
   :language: ca65


.. index::  directives, .section directive, .fat directive
            .messl directive, .name directive, .text directive,
            .equ directive, .equlab directive,
            .public directive, .extern directive,
            .suppress directive, directive;.section,
            directive;.fat, directive;.messl, directive;.name,
            directive;.text, directive;.equ, directive;.equlab,
            directive;.public, directive;.extern, directive;.suppress


.. index:: labels;location counter, location counter

Location counter
-----------------

The assembler converts the source program into machine code that can run
on the target processor. Each instruction will end up at some location
in memory in consecutive order until the next ``.section`` directive
(or end of file is reached). The address of the current instruction
can be accessed by a single period (.), usually referred to as "dot".

The dot label which contains the current instruction location is also
called the *location counter* and it is incremented after each
instruction so that it always contains the value of the start address
of the current instruction.

The actual address value of the location counter is not known before the
program is linked, but it can still be used in expressions.
Short branches can be expressed using the location counter:

.. literalinclude:: rel-jump.s
   :language: ca65


However, it is often better to use labels or local labels instead, see below.


.. index:: labels;local, local labels

Local labels
------------

Local labels exists in two variants. They are useful for local branch
destinations in assembly source files. The first style is dollar
postfix alphanumeric labels and the other variant makes use of plus
and minus sign characters.

Dollar postfix style
^^^^^^^^^^^^^^^^^^^^

Local labels end with a single ``$``. The label name can either be an
identifier or numeric, i.e. ``loop$`` or ``3$``.
A local label is active between two non-local labels and
cannot be exported to the linker. They are meant to be used as
temporary locations for short distance branching, typically short skips
or local loops.

.. code-block:: ca65

                a=a-c x             ; adjust counter to be 0-7
                gonc  skip$
  20$:          c=c+c m             ; shift one left A.X steps
  skip$:        a=a-1 x
                gonc  20$

After a non-local label, you can no longer refer to any local label before it:

.. code-block:: ca65

  foo:          c=0   w
                gonc  20$           ; error, will no longer know about 20$ above

As an alternative, you can just use ordinary labels and perhaps add a number to make
it unique. What you do is mostly a matter of taste.

Sign style
^^^^^^^^^^

Local labels can also be created using sequences of ``+`` or ``-``
characters. The entire label name needs to use the same character and
the length is used when matching.

References to labels with minus characters goes backwards to the
closest matching label and references to labels with plus characters
goes forward to the closest matching label.

This makes it easy to see whether the destination label is before or
after an instruction. Sign style local labels are allowed to pass
over non-local labels.

.. code-block:: ca65

  +
  	      goto    +		    ; this one goes to first + below
  --
                goc     --            ; backward
  +:            goc     ++++          ; goes over foobar
  foobar:                             ; I am not in the way
                nop
  ++++:

.. note::
   Sign style local labels are only usable with branch style
   instructions. They are not allowed in more elaborate operands
   where an ordinary label is allowed,


.. index:: directive;.equ, .equ directive

Defining constants
------------------

Constants are defined using the ``.equ`` directive. As with
labels, you can use an optional colon after it:

.. code-block:: ca65

  BufNo         .equ  7
  BufSize:      .equ  2 + ContentSize

Any expression can be used as a value, however using external symbols
is subject to certain limitations imposed by relocations in the ELF
object file format. In the case of valid expressions with external
symbols, the value will be resolved by the linker.


.. index:: directive;.equlab, .equlab directive

Constants that are locations
----------------------------

Constants can also be defined with the ``.equlab`` directive. This is
similar to the ``.equ`` directive, with the difference that it defines
a label, which describes a location, rather than a plain number:

.. code-block:: ca65

  PCTOC:        .equlab  0xD7


Where this matters is in the interpretation of the debugging
information. Labels defined using ``.equlab`` are treated the same as
other location labels. The debugger will understand that a symbol
defined using ``.equlab`` can be used as a location when generating
disassembly listings, while symbols defined using ``.equ`` will not
be used for locations in the disassembly listing.


.. index:: mainframe;entry points

Mainframe entry points
----------------------

When writing MCODE programs for the HP-41, you will sooner or later
find a need to call functions defined as entry points in the
mainframe (HP-41 firmware).

In the ``include`` directory of the tools installation there is a
``mainframe.h`` file for this purpose.
To include header files, use the ``#include`` preprocessor directive,
see :ref:`sec-c-preprocessor`.
The assembler is configured to find this file in the installation, so
a simple:

.. code-block:: ca65

    #include "mainframe.h"

early in the file will make all the mainframe entry points available.


Directives
----------

All directives start with a single dot character to distinguish them from instructions.

The following table summarizes the directives known to the assembler:

.. table::
 :widths: 2 3
 :column-dividers: none single none

 +---------------------------------------------+------------------------------------+
 |Directive                                    |Purpose                             |
 +=============================================+====================================+
 |``.section`` *section-name*, *argument-list* |Generate code for given section.    |
 |                                             |The argument list is optional and   |
 |                                             |consists of words separated by      |
 |                                             |commas, see                         |
 |                                             |section kinds and modifiers below.  |
 +---------------------------------------------+------------------------------------+
 |``.fat`` *symbol*                            |Specify an entry in the function    |
 |                                             |address table.                      |
 +---------------------------------------------+------------------------------------+
 |``.fatrpn`` *symbol*                         |Specify an entry in the function    |
 |                                             |address table for an RPN program.   |
 +---------------------------------------------+------------------------------------+
 |``.name`` *string*                           |Define function header name.        |
 +---------------------------------------------+------------------------------------+
 |``.name`` *string*, *prompt-bits*            |Define function header name         |
 |                                             |with prompt bits.                   |
 +---------------------------------------------+------------------------------------+
 |``.messl`` *string*                          |Format a text for mainframe entry   |
 |                                             |``MESSL``.                          |
 +---------------------------------------------+------------------------------------+
 |``.text`` *string*                           |Text literal, lcd character         |
 |                                             |encoding.                           |
 +---------------------------------------------+------------------------------------+
 |``.equ`` *expr*                              |Define a symbol value.              |
 +---------------------------------------------+------------------------------------+
 |``.equlab`` *expr*                           |Define a symbol value that          |
 |                                             |corresponds to a memory location.   |
 +---------------------------------------------+------------------------------------+
 |``.public`` *symbol-list*                    |Export symbols to the linker.       |
 +---------------------------------------------+------------------------------------+
 |``.pubweak`` *symbol-list*                   |Export weak symbols to the linker.  |
 +---------------------------------------------+------------------------------------+
 |``.extern`` *symbol-list*                    |Import symbol from other module.    |
 +---------------------------------------------+------------------------------------+
 |``.require`` *symbol-list*                   |Require symbol from other module.   |
 +---------------------------------------------+------------------------------------+
 |``.suppress``                                |Suppress warning on the next source |
 |                                             |line.                               |
 +---------------------------------------------+------------------------------------+
 |``.rtmodel`` *symbol*, *string*              |Define a run-time model attribute.  |
 +---------------------------------------------+------------------------------------+
 |``.shadow`` *expr*                           |Define placement relative to        |
 |                                             |another section.                    |
 +---------------------------------------------+------------------------------------+
 |``.newt_timing_start``                       |Annotate following instructions     |
 |                                             |for execution at normal             |
 |                                             |speed (NEWT only).                  |
 +---------------------------------------------+------------------------------------+
 |``.newt_timing_end``                         |End annotating instructions for     |
 |                                             |execution at normal speed.          |
 |                                             |(NEWT only).                        |
 +---------------------------------------------+------------------------------------+
 |``.macro`` *parameter-list*                  |Defines a macro                     |
 +---------------------------------------------+------------------------------------+
 |``.endm``                                    |Ends a macro definition             |
 +---------------------------------------------+------------------------------------+
 |``.argdelim`` *delimiters*                   |Define delimiters for macro         |
 |                                             |arguments that contains a comma     |
 +---------------------------------------------+------------------------------------+
 |``.end``                                     |Stop processing the source file     |
 +---------------------------------------------+------------------------------------+

A *symbol-list* is a list of symbols separated by commas.


.. index:: section; directive, .section directive, directive;.section

The section directive
^^^^^^^^^^^^^^^^^^^^^

The ``.section`` directive takes the name of the section as the first
argument. It can optionally be followed by a kind and modifiers to
describe the section further.

.. code-block:: ca65

    ; A code section named "code" (Text)
            .section code

    ; A code section named "code" (Text) that are not stored
    ; in relative order to other "code" section fragments in
    ; the same compilation unit.
            .section code, reorder

    ; A data section named "storage"
            .section storage, data

    ; A constant area in ROM that are always included in output,
    ; even when put in a library (provided that something else
    ; in the compilation unit is imported).
           .section table, rodata, root


.. index:: section; kinds, section; BSS, section; Text
.. index:: section; Data, section; Read only data
.. index:: BSS section, Text section, Data section, Read only data section


Section kinds
~~~~~~~~~~~~~

There are four section kinds, Text, Data, RODdata, BSS and NoInit. If
not specified, the section is assumed to be Text.

Section kinds and modifiers are case insensitive.

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

 +---------------+-------------------------------------------------+
 |Section kind   |Description                                      |
 +===============+=================================================+
 |Text           |Executable code.                                 |
 +---------------+-------------------------------------------------+
 |Data           |An initialized data section in read/write        |
 |               |memory (RAM).                                    |
 +---------------+-------------------------------------------------+
 |ROData         |An initialized data section in read only memory  |
 |               |(ROM).                                           |
 +---------------+-------------------------------------------------+
 |BSS            |"Block Started by Symbol", intended to hold      |
 |               |variables that are not given a value yet.        |
 |               |A C compiler would normally zero fill such area  |
 |               |before calling ``main()``.                       |
 +---------------+-------------------------------------------------+
 |NoInit         |Similar to BSS, but do not zero fill it.         |
 +---------------+-------------------------------------------------+

.. index:: section; modifiers


Section modifiers
~~~~~~~~~~~~~~~~~

A section modifier can be used to describe further behavior of the
section. There are two such modifiers which can be specified either as
positive or negative.

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

 +-------------------+-------------------------------------------------+
 |Section modifier   |Description                                      |
 +===================+=================================================+
 |``noreorder``      |Obey the relative order between section          |
 |                   |fragments of the same name as encountered in a   |
 |                   |translation unit.                                |
 +-------------------+-------------------------------------------------+
 |``reorder``        |Allow section fragment to be placed in arbitrary |
 |                   |order relative to other sections with the same   |
 |                   |name.                                            |
 |                   |(This is the default).                           |
 +-------------------+-------------------------------------------------+
 |``root``           |Always include this section fragment in the      |
 |                   |program. This is the default for object files.   |
 +-------------------+-------------------------------------------------+
 |``noroot``         |Only include this section fragment in the        |
 |                   |program if someone refer to a label inside it.   |
 |                   |This is the default for library files.           |
 +-------------------+-------------------------------------------------+

.. note::
   Section fragments with the same name an ``noreorder`` modifier are
   combined by the linker into a placement group that is placed as a
   single unit. The effect of ``reorder`` (or lack of ``noreorder``)
   is that the section fragment is given its own placement group.
   This also have the effect that any following section fragments
   are combined in a new group separate from any section fragments
   before it. Thus, a section fragment with ``reorder`` not only causes
   it to be placed separately from the previous ones, it also makes a placement
   or ``noreorder`` sections before and after it separate placement groups.


.. index:: section; alignment, alignment


Section alignment
~~~~~~~~~~~~~~~~~

The ``.align`` directive specifies a given alignment in address
units. It ensures that the next location will have the specified
alignment. This is done by advancing the location and inserting
fillers if needed.

.. code-block:: ca65

    ; Ensure that "table" label is placed at an address that can be
    ; evenly divided by 4.
            .section data
            ...
            .align   4
    table:  ...


.. index:: FAT, FAT;directives, .fat directive, function address table,
           directive;.fat, .name directive, directive;.name

Function address table entry
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Each non-banked 4K ROM page has its function address table (*FAT*) and
the ``.fat`` directive is used to define an entry in this table. It
points the first execution address of an MCODE function. To make a
proper function entry, you also need to precede it by the name of the
function using the ``.name`` directive.

.. literalinclude:: fat.s
   :language: ca65

Each function table entry takes up two words in ROM. Normally a FAT
entry will point to an MCODE function within the same 4K page, but it
can actually point to another 4K page before or after. In that case
they need to be at the same relative position to each other at
run-time. [#FAT]_

Banked pages do not follow the traditional page layout and should
therefore not have any function address table.

.. rubric:: Footnotes
.. [#FAT] Recall that most 4K pages are page independent and can move
          at run-time. If you have FAT entries going to another 4K
          page, they most move together. A traditional 8K plug-in
          module moves this way, though it may or may not have FAT
          entries that go between the 4K pages.


.. index:: naming directive, .name directive, directive;.name

Naming functions
^^^^^^^^^^^^^^^^

MCODE functions can be named using the ``.name`` directive that will
take care of laying out the characters in the correct way in memory. This
means convert the ASCII characters to the corresponding LCD
characters, reverse the order and mark the end character properly.
The previous example shows how to use it.

.. index:: prompt bits, .name directive;prompt bits

You can optionally follow the name with two values that are the
prompt bits. These two values must be between ``0`` and ``3``:

.. literalinclude:: prompt-bits.s
   :language: ca65

.. index:: directive;.con, directive;.text, directive;.messl, directive;.name, LCD

ASCII and LCD characters
^^^^^^^^^^^^^^^^^^^^^^^^

Character constants are encoded in ASCII while strings are translated
to the corresponding LCD character set if needed, which are not
necessarily identical to ASCII.

This is because it is judged to be more natural to deal with
individual characters as ASCII since that is how it is in most
programming languages and the tools can not anticipate from a single
character constant how it will  be used. It may be intended for the
LCD (in which case you need to manually adjust it), but it may also be
for the Alpha register, RPN program or intended for transmissions to
other devices, such as a printer. In these case any automatic LCD
character translation would be undesirable.

On the other hand, ``.messl`` and ``.name`` directives expects LCD
characters and the ``.text`` directives is provided as a more generic
directive of similar kind. Thus, they will all translate ASCII
characters to corresponding LCD characters.

To allow for ASCII strings to be encoded more easily than using
individual characters with the ``.con`` directive, a special case with
``.con`` followed by a string is allowed:

.. literalinclude:: textcon.s
   :language: ca65


.. index:: mainframe;LCD messages, directive;.messl, .messl directive

LCD messages
^^^^^^^^^^^^

Messages to the display are often written using the ``.messl``
function in the mainframe. This function expects the string in a
special format which is easy to achieve with the ``.messl`` directive:

.. literalinclude:: messl.s
   :language: ca65


.. index:: labels;global, symbols;global, .public directive, .extern directive,
           directive;.public, directive;.extern

Global symbols
^^^^^^^^^^^^^^

Symbols are by default local to the file being assembled. Such
symbols can be exposed to the global scope and imported by other
source files.

.. index:: directive;.equ, .equ directive

For shared definitions, an alternative is to put them in an include file and
define them using the ``.equ`` directive.

Use the ``.public`` directive to export named symbols and the ``.extern`` directive
to import symbols exported from some other source file.
Both directives take a comma separated list of symbols.

.. literalinclude:: public.s
   :language: ca65

.. index:: labels;weak, symbols;weak, weak symbols

Weak symbols
^^^^^^^^^^^^

A weak symbol is created using the ``.pubweak`` directive in a similar way to
``.public``. The difference is that a weak symbol may exist in multiple copies.
Of these potentially multiple copies, one is selected by the linker. If there
is a non-weak symbol among the weak ones, it will be picked by the linker.

Weak symbols serve a couple of purposes. They can be used for library replaceable
objects where you can override a default library object using a
non-weak public symbol.
They are also useful for tools that generate assembly code where an identical
construct may be generated multiple times, though only one is needed in the end.

.. index:: symbols;required, required symbols

Required symbols
^^^^^^^^^^^^^^^^

A required symbol can be specified with the ``.require`` directive. It
works similar to the ``.extern`` directive, with the difference that
you do not need to actually use the symbol in any expression, it is
being pulled in by the linker regardless.

This is mostly of interest when building modular software using
libraries.

The typical use of this is that you have initialization code somewhere
else built up using section fragments with the no-reorder
property. The no-reorder property ensures that the code fragments
appear next to each other. A section fragment is only active if
someone actually refers to it. In this case the ``.require`` directive
can be used to refer to it without actually using it. The result is
that code which relies on certain initialization code fragment exists,
can request that such code fragment becomes active.

.. index:: run-time model directive, directive; run-time model

Run-time model
^^^^^^^^^^^^^^

It is possible to define run-time model attributes using the
``.rtmodel`` directive. Such attributes are checked at link time to
ensure object file consistency.


One example could be that you have an attribute telling how it uses
page 4. One source file that makes use of Library#4 could define an
attribute:

.. code-block:: ca65

   ; Can only be used with Library#4 in page 4
                 .rtmodel page4, "Library#4"

Another source file makes use of page 4 for a Forth system could have:

.. code-block:: ca65

   ; Can only be used with some Forth in page 4
                 .rtmodel page4, "Forth"

If you try to link these two modules together will result in an error
message describing that run-time model attribute ``page4`` has a
mismatch.

Source files that do not define the ``page`` attribute can be linked
with either. It is also possible to use the special ``*`` value which
also means it works with either. It essentially says that I know what
I am doing and it will work with whatever value is in this attribute:

.. code-block:: ca65

   ; I work with whatever you decide to put in page 4
                 .rtmodel page4, "*"

Functionally it equivalent to not having the attribute defined. The
difference is more in the eye of the reader, you have actively
considered the attribute and concluded it works with whatever
interpretation there may be.


.. note::
   A defined run-time attribute affects the entire compilation unit it
   appears in. If you need to have a more narrow scope for some
   run-time model attribute, you need to break up the source file into
   smaller pieces.


.. index:: warnings, suppressing warnings, directive;.suppress, .suppress directive

Suppressing warnings
^^^^^^^^^^^^^^^^^^^^

Due to bugs in the HP-41 microprocessor, some combinations of
instructions cause unpredictable behaviors. The assembler will try to
spot potential problem cases and report them as warnings.
There may be false warnings as the analysis made is rather shallow.
There is also a risk that some potential problems are not reported as
these unpredictable behaviors are not that well documented.

Currently the assembler will warn if any of the following instructions follow an arithmetic class two instruction:

.. literalinclude:: orand.s
   :language: ca65

Whether this is actually a problem depends on whether the previous
instruction generates a carry out of digit 13.

If you are certain that the warning is false, you can use the ``.suppress`` directive on the line before to suppress the warning:

.. literalinclude:: suppress.s
   :language: ca65

Another well known bug in the HP-41 microprocessor is related to
setting the pointer to 13 and accessing the G register. This will
cause a transfer between the G register and the byte pointed out in
the C register. Since the highest pointer value is 13, it would mean
it should wrap and use 0 for the upper 4 bits. This, however, will not
happen. This is an example of a CPU bug that is *not* flagged by the
assembler.


.. index:: banked placement, placing sections, directive;.shadow, .shadow directive

Shadowing sections
^^^^^^^^^^^^^^^^^^

The ``.shadow`` directive makes it easy to align code in different
banks to be located relative to each other in a simple, yet flexible
way.

Refer to :ref:`bankSwitching` for examples on how it can be used and a
discussion on different approaches to bank switching.


.. index:: list files;assembler

List files
----------

List files are valuable output that allows you to get an overview of
the program you are writing. Both the assembler and the linker can
emit list files.

Given the following example source file:

.. literalinclude:: decode.s
   :language: ca65

The generated list file will look as follows:

.. literalinclude:: decode.lst
   :language: ca65

The list file starts with a header that contains the name of the tool
that generated it, the command line and the time it was generated.

The body contains four columns, *a*) the line number; *b*) the location counter in the current section; *c*) the generated opcodes; and *d*) the source line.

If the opcodes cannot be resolved by the assembler, they will be represented by dots.

.. include:: macro.rst


.. index:: ELF, object file format

Object file format
------------------

The object file format used is ELF (Executable and Linkable
Format). While ELF is a flexible and extensible format, it imposes
certain limitations on what can be represented in the format.

All sections are relocatable and are given their location by the
linker (or loader). There is no support for absolute sections. As a
result, there are no directive to create a section that starts at a
fixed address in this assembler.

Expressions that need to be resolved at link time are limited in what
they can contain. They may contain a location or external symbol, and
optionally a fixed offset. This basically means that you can only have
a symbol, or a symbol with an constant added to or subtracted from
it. The following expressions are allowed:

.. code-block:: ca65

   ; Examples of accepted expressions
                 .extern  NFRPU, buffer
                 gsbp     buffer
                 golong   NFRPU + 1


The following expressions will result in errors:

.. code-block:: ca65

   ; Examples of rejected expressions
                 .extern  NFRPU, buffer, offset
                 gsbp     buffer + offset  ; error: offset not known
                 golong   NFRPU * 2        ; error: only add or subtract allowed

The assembler will simplify expressions making it possible to use
non-trivial expressions, but in the end any value used with an
external symbol must be possible to reduce down to a fixed offset.

.. index:: relocations

Relocations
-----------

A *relocation* is an entity stored in the object file format that
indicates a location in the generated code that needs to be altered
by the linker. Relocations are generated automatically by the
assembler and you do not normally need to think about them.

A relocation entry contains the location in the generated code,
expression to be relocated and which kind of relocation to perform.


.. index:: relocation operators, operators; relocation
.. _relocationOperators:

Relocation operators
^^^^^^^^^^^^^^^^^^^^

In certain contexts some additional prefix operators are
available. They can be seen as *relocation operators* as they can be
used to optionally introduce a relocation.

As they are relocations, they allow the operator to be executed at
link time when the final addresses are known. However, they have the
limitation that they must appear at the top level of the expression.

For the ``LC`` instruction which loads a nibble, you can use the
``.nib0``, ``.nib1``, ``.nib2`` and ``.nib3`` operators to specify
that you want to get a specific nibble of a relocatable expression:

.. code-block:: ca65

   ; Load the address of a location inside a module page.
                 gosub    PCTOC         ; Get my address (page)
                 pt=      5
                 lc       .nib2 table   ; set lower 12 bits to 'table'
                 lc       .nib1 table
                 lc       .nib0 table


For the ``LDI`` instruction and the ``.CON`` directive the ``.low10``
operator allows you to get the lower 10 bits of a relocatable
expression.

.. code-block:: ca65

   ; Load the lower (10 bits) part of an address
                 ldi      .low10 table

The ``.low12`` operator works in a similar way, but it allows the
address to be anywhere inside a 4K page, provided that is aligned on
an address that is a multiple of 4. It uses the available 10 bits to
store the lower 12 bits, assuming that the last two bits are 0. If you
use it to form an address, you need to scale the address:

.. code-block:: ca65

   ; Load full address of a table in my own 4K page
                 gosub    PCTOC         ; C[6:3]= my own location
                 rcr      3             ; C[3]= page
                 ldi      .low12 table
                 c=c+c    x             ; scale the page offset
                 c=c+c    x
                                        ; C[3:0]= address of table

                 ...
                 .align   4
   table:        .con     data, etc


There are also ``.low8`` and ``.high8`` operators to extract the lower
and upper half of a relocatable expression.  They work similar to
``.low10``, but extracts 8 bits at a time from different places to
cover a 16-bit address.

For the ``.CON`` directive, the ``.fatsize`` operator can be used to
get the size of the FAT. Simply use the ``.fatsize`` operator where
you put the size of the FAT of your module (at location 1) and give it
the address of the FAT end marker as argument. Here is an example:

.. code-block:: ca65

   ;;; Start of module
                 .section HEADER
                 .con  21               ; XROM number
                 .con  .fatsize fatend  ; The size of FAT
                 .fat  header

   ;;; End marker for function address table
                 .section FATEND
   fatend:       .con  0,0

The ``.fatsize`` operator does not enforce that it should be at
location 1, so feel free to use for other creative purposes. What it
does is to take the address of its argument, subtract its own location
and divide by 2.


.. note::

   Relocation operators have high precedence like other unary prefix
   operators. If you want to access an address with an offset, you
   need to surround the expression by parentheses.

   .. literalinclude:: lcnib-offset.s
      :language: ca65


.. index:: section; operators, operators; section
.. index:: operator; .sectionStart, operator; .sectionEnd, operator; .sectionSize
.. index:: .sectionStart; operator , .sectionEnd; operator , .sectionSize; operator
.. _sectionOperators:

Section operators
^^^^^^^^^^^^^^^^^

Section operators makes it possible to get hold of where a section is
placed in memory.

Section names must be known to the assembler. If you want to refer to
a section that is not used otherwise in the current assembly source
file, simply declare it.

.. code-block:: ca65

   ;;; Forward declaration
                 .section elsewhere

                 .section Code
                 ...


All these operators are resolved by the linker as placement is not
known before link time. An error is given if a section spans multiple
memories.


.. table:: Section operators
 :widths: 3 1 5
 :column-alignment: left center left
 :column-dividers: none single single none

 +-------------------------------------+------------+---------------------------+
 |Operator                             |Precedence  |Purpose                    |
 +=====================================+============+===========================+
 |``.sectionStart`` *sectionName*      |9           |The first address of the   |
 |                                     |            |given section.             |
 +-------------------------------------+------------+---------------------------+
 |``.sectionEnd`` *sectionName*        |9           |The last address of the    |
 |                                     |            |given section.             |
 +-------------------------------------+------------+---------------------------+
 |``.sectionSize`` *sectionName*       |9           |The size of the given      |
 |                                     |            |section.                   |
 +-------------------------------------+------------+---------------------------+


.. note::
   Section size corresponds to ``1 + end - start``.

.. warning::
   If you allow the linker to intermix different sections in the same allocation range, these operators will base their values on the first and last section of the given name. Different sections that are interleaved inside are silently included in the address range given by these operators.
