.. index:: module tool, module;description file, import;instructions
.. index:: import;functions, XROM;instruction, XROM;function
.. _chap-module-tool:

Module tool
===========

The module tool works with HP-41 modules files (``.mod`` extension).
It can either extract information from an existing module file or put
together a new module.

.. running:: "module tool" modtool
.. literalinclude:: gen/ModToolSignOn.text
   :language: none


Extraction mode
---------------

If a module file is given on the command line module tool runs in
extraction mode. The following files and information can be extracted:

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

 +-------------------+--------------------------------------------+
 |What               |Description                                 |
 +===================+============================================+
 |module descriptor  |Module meta data as an XML file.            |
 |                   |This file is input to the linker as the     |
 |                   |module header.                              |
 |                   |Uses ``.moddesc`` file extension.           |
 +-------------------+--------------------------------------------+
 |module export      |Module entry points as an XML file.         |
 |                   |This file can be imported by the            |
 |                   |RPN compiler to allow XROM calls to be made |
 |                   |to the imported module.                     |
 |                   |Uses ``.modexport`` file extension.         |
 +-------------------+--------------------------------------------+
 |ROM pages          |These are the actual page images.           |
 |                   |Uses ``.rom`` file extension.               |
 +-------------------+--------------------------------------------+
 |Summary            |Human readable FAT table summary on stdout. |
 |                   |No file is created.                         |
 +-------------------+--------------------------------------------+

By default all of them are done. You can pick individual ones by using
the appropriate positive option. This will result in that *only* those
specified are done.

If you specify negative options, *all but those* are done.

Some examples follow. To only see the easy readable FAT table summary
(no files created)::

$ modtool --summary file.mod


To extract everything but ``.rom`` image files::

$ modtool --no-extract-rom-pages file.mod

To get the summary and the module export (XML file)::

$ modtool --summary --extract-module-export file.mod

Creation mode
-------------

In creation mode, you give module tool a single ``.moddesc`` module
description file and as many ``.rom`` page files that are mentioned
in the description file. A single output module file is created based
on the input files.


.. _sec-extract-moddesc:

Module description file
-----------------------

This file contains the meta data of the module file. It is a required input
file when a new module file is to be created. Both the linker and the
module tool can create module files and takes a module description file
as input.

The easiest way to create a new module description file is to base it on an
existing module with similar layout as the module you want to create.
Simply locate a suitable module and run the module tool on it to
extract its module description file. Then rename and edit the description
file to fit its new purpose.

.. code-block:: none

  $ modtool advantage.mod

The resulting file ``advantage.moddesc`` looks as follows: [#formatted]_

.. literalinclude:: advantage.moddesc
   :language: xml

You can use this as a starting point. You probably want to,
*a*) rename the file; *b*) change the page names to correspond to
the memory names you have defined; *c*) change the header attributes;
and *d*) change the ``Identity`` attributes.

In other words, you will need to make several changes, but on the good
side, they are mostly trivial. If you choose the module file to start
with some care, you get the correct structure and the more tricky items
filled in.




Module exports file
-------------------

The module exports is used by the RPN compiler and the barcode generating tools.
It is useful when you write RPN programs that use plug-in modules. It makes it
possible to refer to instructions and functions in a used module by name.
The RPN compiler and barcode tool takes care of using the appropriate
XROM numbers.


Extracting ROM pages
--------------------

In extraction mode, all individual ROM pages will be extracted unless you specify
the ``--no-extract-rom-pages`` option.
A separate ROM file is created for each page. The filename is
constructed from the page name found in module meta data with an file
name extension ``.rom``.

The ``.rom`` format is very simple, each 10-bits word is encoded as two bytes,
with the upper part first (big endian).


Technical details
-----------------

To implement the extraction of entry points, the module tool loads the
pages of the module file into a simulated HP-41 memory system based on
its layout.
After that, it will look around in the fictive memory system and
decode the function address tables, extracting MCODE entries and
global RPN labels.

The HP-41 uses some special characters that cannot be represented in ASCII.
If such character is encountered, it is converted to a suitable Unicode
character.  [#ed-unicode]_

.. rubric:: Footnotes

.. [#ed-unicode]
   Hint:  If you have trouble typing these special Unicode characters
   in your text editor, open and copy the name from the module exports file.
.. [#formatted]
   The output have been formatted slightly to keep the line length
   down and to improve readability.
