7. 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.
The module tool is a command line tool named modtool. Running it from the command line with the ``–help`` option will give a sign-on message and display accepted options:
Calypsi module tool for Hewlett-Packard Nut version 5.16
Usage: modtool [--version] [-e|--export-files FILE] [-c|--verify-checksums]
([--extract-module-descriptor] |
[--no-extract-module-descriptor]) ([--extract-module-export] |
[--no-extract-module-export]) ([--extract-rom-pages] |
[--no-extract-rom-pages]) ([--summary] | [--no-summary])
[--no-secondaries] [-l] [--list-file LIST-FILE]
[--memories-expression EXPRESSION] [--program-root SYMBOL]
[--root-symbol SYMBOL] [--program-start SYMBOL]
[--copy-initialize SECTION] [--no-copy-initialize SECTION]
[--no-automatic-placement-rules] [--raw-multiple-memories]
[--no-merge-raw-memories] [--force-output] [--no-auto-libraries]
[--cstartup VALUE] [--no-tree-shaking] [--output-format FORMAT]
FILE...
use 'modtool --help' for detailed help
Available options:
--version Display version number
-e,--export-files FILE Base name of export files (defaults to base name of
input file)
-c,--verify-checksums Verify the checksum in each ROM page
--extract-module-descriptor
Extract module header meta data
--no-extract-module-descriptor
Do not extract module header meta data
--extract-module-export Extract a module exports file
--no-extract-module-export
Do not extract a module exports file
--extract-rom-pages Extract individual ROM pages to files
--no-extract-rom-pages Do not extract individual ROM pages to files
--summary Show FAT summary
--no-summary Do not show FAT summary
--no-secondaries Do not look for secondary FATs
-l Generate a list file, defaults to 'modtool.lst'
--list-file LIST-FILE Generate list file, using given name
--memories-expression EXPRESSION
Expression that extracts the list of memory
descriptions from the .scm file, defaults to
'memories'
--program-root SYMBOL Program root point, defaults to
'__program_root_section'
--root-symbol SYMBOL Add a root symbol
--program-start SYMBOL Program start symbol, defaults to '__program_start'
--copy-initialize SECTION
Override default and initialize this section by
copying
--no-copy-initialize SECTION
Override default and do not initialize this section
by copying
--no-automatic-placement-rules
Do not add rules to a .scm linker rules file
--raw-multiple-memories Allow multiple memories for raw style output format
--no-merge-raw-memories Never attempt to merge raw memories
--force-output Ignore (some) errors and attempt to generate output
--no-auto-libraries Do not automatically add runtime libraries
--cstartup VALUE Define the C startup to be used, synonym to '--rtattr
cstartup=VALUE'
--no-tree-shaking Do not perform tree shaking and keep unused section
fragment in output
--output-format FORMAT Format, one of 'MOD1' or 'MOD2', defaults to 'MOD1'
(in addition to the ELF/DWARF output)
-h,--help Show this help text
7.1. 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:
What |
Description |
|---|---|
module descriptor |
Module meta data as an XML file.
This file is input to the linker as the
module header.
Uses |
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 |
ROM pages |
These are the actual page images.
Uses |
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
7.2. 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.
7.3. 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.
$ modtool advantage.mod
The resulting file advantage.moddesc looks as follows: 2
<?xml version="1.0" encoding="UTF-8"?>
<ModFile FileFormat="MOD1" Title="Advantage Pac" Version="B"
PartNumber="00041-15055" Author="Hewlett-Packard"
Copyright="Hewlett-Packard"
License="Hewlett-Packard Company makes no warranty as to the
accuracy or completeness of the foregoing information
and hereby disclaims any responsibility therefore."
Comments="" Category="2" Hardware="0" MemoryModules="0" XMemoryModules="0">
<Page Name="AdvL1-1B" Identity="ADV1" Page="Lower" PageGroup="1"
Bank="1" BankGroup="1" RAM="0" WriteProtect="0" FAT="1"/>
<Page Name="AdvU1-1B" Identity="ADV2" Page="Upper" PageGroup="1"
Bank="1" BankGroup="1" RAM="0" WriteProtect="0" FAT="1"/>
<Page Name="AdvU2-1B" Identity="ADV3" Page="Upper" PageGroup="1"
Bank="2" BankGroup="1" RAM="0" WriteProtect="0" FAT="0"/>
</ModFile>
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.
7.4. 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.
7.5. 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).
7.6. 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. 1
Footnotes