mkMOD — prepare MOD files for V41

Abstract:
MOD files are almost the same for V41 what are plug-in modules for real HP-41C/CV/CX. mkMOD makes creating MOD files a cakewalk.

Note: before running this program read the QPL in section 6.

Contents:

  1. A Brief Description
  2. Prerequisites, Install and Run it
  3. Controls of This Program
  4. Features, Constraints, Known Bugs
  5. Updates
  6. The Fine Print

A Brief Description

MOD files expand the functions of an HP-41C/CV/CX running under V41, which emulates the pocket calculator by simulating its Nut-CPU and few selected peripherals. At first glance MOD files correspond virtually to plug-in modules of the role model, which provide a remarkable expandability to users' requirements. Taking a closer look, the difference is within those extensions which come with additional equipment like IR printer module or card reader. All complemental hardware must be simulated by the 'emulator' (for an outstanding example see NutEm/PC and its supplement), MOD files contain "only" the firmware and besides some metadata also the hint which hardware it wants to run.

mkMOD (speak 'mka-mod or make-a-mod if you like) helps to prepare MOD files. Only few users will make their own MODs, because the installation of V41 includes plenty of them, just a few more than anybody will ever use. Therefore mkMOD is only necessary when you do need to run a new ROM under V41 (as it lacks the ability to use ROM files directly), or – MOD files may also determine the emulated calculator's OS – in case you tinker around in this sector deep down below the engine bonnet.

Starting either from

mkMOD allows to modify almost all before filing the changes either as The format of ROM files to include in the new MOD may be For more details see readme.txt for MODMakeWin V1.1 (Sep 28, 2015) – a tool to prepare single-page MODs only – either on Warren Furlow's archive DVD or elsewhere.

A Note About MOD Formats

V41 may currently use the two MOD file formats MOD1 and MOD2. The later is said to be prefered by those specialist who like patching ROMs directly in the MOD file using a hex-editor, so I was told.

mkMOD reads and writes MOD1 formatted MOD files only. Modifying a ROM would just take the steps of extracting the ROM in question as ZENROM-alike listing, "patch" or edit it in a text editor (as it is human-readable no hex-editor necessary), take the changed ROM in (still opened) mkMOD and save the "mod MOD". Pronto. If few experts still prefer MOD2 format, it ain't a fault of my mkMOD.

Prerequisites, Install and Run it

To run mkMOD you need (in brackets what I used for the development): To prepare MOD files you do need the ROM or ROMs for it in one of the a. m. formats.

Install it

There is no automated installation procedure. Unzip mkMOD.ZIP to a directory named at will, one of its own or not, it's up to you. But! keep the organization of subdirectories (there are only 'HTML' and 'ROM'), otherwise you will get no access from mkMOD to help or have to modify the program. mkMOD expects ROMs in subdirectory 'ROM'.

Note: The ZIP bundles also few ROMs for first tests, included a 'nut-cxp.MOD' from J-F Garnier which is a 41CX patched to display lower case characters (what works best with emulators which transliterate display output to letters, like NutEm/PC). Another patch gives altering access to all flags.

Run it

Start mkMOD the same way like other ooREXX routines which require neither arguments nor options (for example with a double click in Windows explorer to the mkMOD program file, if its suffix corresponds to one of your choices at ooREXX installation). Important errors are reported as messages, hints of minor importance (like 'No file selected.' when cancelling file selection) are displayed on the console window. There is no functional disadvantage to run it without console.

Controls of mkMOD

If not yet obvious at first sight:
The column of buttons to the left apply to the whole,
Load... loads a template (file type MOD or ROM2MOD),
Save as... saves metadata only (file type ROM2MOD),
Convert... saves a MOD file,
Quit — could this be a hidden Easter egg?
the two buttons to the upper right apply to the current page,
Pick... let you include a ROM file, see a. m. formats,
Remove discards current page and reduces the number of pages,
Up, Down
change the sequence of pages by switching the current one (which remains the current),
Previous, Next
browse through the list of pages,
other buttons
are check boxes in 'pushlike' style,
'NumPages' (in the lower right of the 'Header' group)
define how many pages are enclosed in the ROM to build,
the spot to the lower in 'Page' group
is to display findings of the selected ROM,
the context menu (right mouse click)
i) enables to extract the ROM of the actual page transformed to one of the a. m. formats (except for MOD),
ii) offers two options to compute CRCs of the actual ROM, CRT-32 (which is well known from PKZIP, 7-Zip and more) and "YCRC" (which is used for VLC and 41CL).
If you still have pending issues to resolve you do not belong to the target audience, sorry.

Features, Constraints, Known Bugs

Are there features worth to mention?
When picking ROM files to include, the corresponding size is tested (.bin = 5.120 bytes, .rom = 8.192 bytes, .MClst = 4096 lines). In case of mismatch an advice is shown (which should be obeyed, misuse is not inhibited).
There is a "dirty flag" to indicate changes. It is the asterisk in the mkMOD dialogue window's caption. But there is no user torturing supervision if you quit w/o saving etc. It is meant as a silent hint only.
Are there significant limitations?
Yes, one at least. The ROM formats lack the direct access to ROM copies contained in LIF disk dumps. You have to extract those relevant before running mkMOD.
And another one — the values of 'Header Custom' and 'Page Custom' are not editable.
Known bugs?
All known bugs are fixed. Holler if you find a new one.
— As Christoph told me, the shown field size information would be too big by one, for some C-distinctiveness (or anomaly?) the last digit must be '00'x to work correctly. From a C programmer's irrevocable point of view it is a documentation error. To avoid futile sophistry and not to jeopardize V41 by correct but incompatible MODs I adjust all text fields internally (until the day V41 gets fixed) but show the nominal size as before.

Updates

Update 11/24/22:
– Avoid invalid characters in file dialog.
Update 10/20/22:
– Extracting ROM as ZEN listing respects page setting.
Update 10/13/22:
– Remember where to read and where to save ROM files,
– same for templates and MOD files,
– any file open shows all possible filetypes in question.
Update 7/12/22:
– Compute CRC-32 and "YCRC" to ease compare of ROMs.

The fine print

(i) Do not use this program.
(ii) Any damage you cause with this program, intentional or by chance, is a violation of clause (i). Thus all consequences are completely at your own risk.
(iii) If you manage to improve this program you have to inform me as stipulated in following THE Q PUBLIC LICENSE (QPL).
(iv) In addition applies the QPL below:

THE Q PUBLIC LICENSE version 1.0

Copyright (C) 1999 Trolltech AS, Norway.

Everyone is permitted to copy and distribute this license document. The intent of this license is to establish freedom to share and change the software regulated by this license under the open source model.

This license applies to any software containing a notice placed by the copyright holder saying that it may be distributed under the terms of the Q Public License version 1.0. Such software is herein referred to as the Software. This license covers modification and distribution of the Software, use of third-party application programs based on the Software, and development of free software which uses the Software.

Granted Rights

  1. You are granted the non-exclusive rights set forth in this license provided you agree to and comply with any and all conditions in this license. Whole or partial distribution of the Software, or software items that link with the Software, in any form signifies acceptance of this license.
  2. You may copy and distribute the Software in unmodified form provided that the entire package, including - but not restricted to - copyright, trademark notices and disclaimers, as released by the initial developer of the Software, is distributed.
  3. You may make modifications to the Software and distribute your modifications, in a form that is separate from the Software, such as patches. The following restrictions apply to modifications:
    a. Modifications must not alter or remove any copyright notices in the Software.
    b. When modifications to the Software are released under this license, a non-exclusive royalty-free right is granted to the initial developer of the Software to distribute your modification in future versions of the Software provided such versions remain available under these terms in addition to any other license(s) of the initial developer.
  4. You may distribute machine-executable forms of the Software or machine-executable forms of modified versions of the Software, provided that you meet these restrictions:
    a. You must include this license document in the distribution.
    b. You must ensure that all recipients of the machine-executable forms are also able to receive the complete machine-readable source code to the distributed Software, including all modifications, without any charge beyond the costs of data transfer, and place prominent notices in the distribution explaining this.
    c. You must ensure that all modifications included in the machine-executable forms are available under the terms of this license.
  5. You may use the original or modified versions of the Software to compile, link and run application programs legally developed by you or by others.
  6. You may develop application programs, reusable components and other software items that link with the original or modified versions of the Software. These items, when distributed, are subject to the following requirements:
    a. You must ensure that all recipients of machine-executable forms of these items are also able to receive and use the complete machine-readable source code to the items without any charge beyond the costs of data transfer.
    b. You must explicitly license all recipients of your items to use and re-distribute original and modified versions of the items in both machine-executable and source code forms. The recipients must be able to do so without any charges whatsoever, and they must be able to re-distribute to anyone they choose.
    c. If the items are not available to the general public, and the initial developer of the Software requests a copy of the items, then you must supply one.

Limitations of Liability

In no event shall the initial developers or copyright holders be liable for any damages whatsoever, including - but not restricted to - lost revenue or profits or other direct, indirect, special, incidental or consequential damages, even if they have been advised of the possibility of such damages, except to the extent invariable law, if any, provides otherwise.

No Warranty

The Software and this license document are provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.

Choice of Law

This license is governed by the Laws of England (if not yet part of Spanish East Indies)