20. Examples¶
Now lets look at some examples on how to use the tools to build actual modules. HP-41 modules come in many variants and Calypsi will allow you to make virtually any kind of software module using RPN or MCODE, allowing multi-page layouts, with or without page banking.
20.1. Hello world¶
The first example is a very basic MCODE module that contains a simple
instruction HELLO that will display HELLO WORLD. The purpose
is to put together minimal, but complete module, following the module
layout as described in 4K page layout.
While this example is simple, it is useful for getting familiar with the tools and how to use the resulting module on your HP-41 or HP-41 emulator.
The example can be found relative to the installation directory in
example/HelloWorld. In order to build it you will need to, a)
copy the example elsewhere; b) ensure that you have GNU Make
installed; and c) have your path environment variable set up so
that GNU Make and the Calypsi can be found.
When properly set up, you should be able to build the example by just
saying make from the command line.
$ make
../../../../../../bin/asnut HelloWorld.s
../../../../../../bin/lnnut HelloWorld.o plugin4k.scm hello.moddesc -o hello.mod
Trying it out¶
The result will be a module file hello.mod that you need to plug in
to your HP-41 or load in your HP-41 emulator. If you are using a real
HP-41, you need either an MLDL, Clonix module or something similar,
and some means to download the module to it. If you are using an
emulator, it needs to support the module file format to be able to load
the module.
Once installed in the HP-41, try the command HELLO which should
display HELLO WORLD. You can also see the module in catalog 2
(using CAT 2).
20.2. RPN games module¶
In this example we will start with a games module that makes use of a couple of nice Poker and Roulette games written by Jean-Marc Baillard. The intention here is to use them as an example how to make a module (not document these programs in detail).
The example can be found in the example/games directory in the
Calypsi installation.
Originally, these programs were obtained from internet by using copy
and paste into a source file. Since they use features on the HP-41CX,
an .import directive stating this has been added at the beginning.
When importing source code, you should check which convention has been
used to represent append alpha strings, as there are many variants in
use. This is because there
is no natural way to do this in ASCII as the HP-41 uses character 127,
which is DEL in ASCII.
In the original sources for these programs, character code 126 is used
as append character. This is the tilde in ASCII, but actually Σ on the
HP-41. The RPN Compiler does not accept this and those strings need to
be changed, i.e. change "~NTH" to >"NTH".
The project¶
This example uses GNU Make which you need to have installed. The Makefile contains the following:
BIN=../../../../../../bin
RPN_SRCS = poker.rpn roulette.rpn
RPN_RAWS =
ASM_SRCS = header.s PokerSupport.s
OBJS = $(RPN_SRCS:%.rpn=%.o) $(RPN_RAWS:%.raw=%.o) $(ASM_SRCS:%.s=%.o)
MOD = games.mod
all: $(MOD)
clean:
-rm -f $(OBJS) *.lst $(MOD)
%.o: %.rpn
$(BIN)/rpncomp -l $<
%.o: %.raw
$(BIN)/rpncomp -l $<
%.o: %.s
$(BIN)/asnut $<
$(MOD): $(OBJS) Plugin4K.scm games.moddesc Makefile
$(BIN)/lnnut -l $(OBJS) Plugin4K.scm games.moddesc -o $(MOD)
As can be seen, it is fairly simple to add source files to the project by adding files to the variables at the top. There are two RPN source files, no raw RPN files and two assembly source files.
The assembly files¶
The PokerSupport.s file contains some special MCODE routines used
by the poker program to speed it up. These routines are imported into
the poker.rpn program at the top:
.import 41cx
.local CARD, MV, TRI
01 LBL "POKER+"
02 10
...
The second one is header.s which defines everything related to the
module layout:
;;; *******************************************************************
;;;
;;; Module header
;;;
;;; *******************************************************************
.section HEADER
.con 21 ; XROM number
.con .fatsize fatend
.fat header
.section FATEND
;;; End marker for function address table
fatend: .con 0,0
.section Code
;;; Make an empty name function for the module to show up in CAT 2
.name "-GAMES EX 1A" ; The name of the module
header: rtn
.section TAIL
;;; Tail of the module with empty poll points and module ID
.con 0,0,0,0,0,0,0
.text "A1XG" ; GX1A
This file can be used as a starting point for other projects simply by changing the XROM identity, the ROM header function and the module ID at the end.
The size of the FAT is automatically calculated thanks to the .fatsize relocation operator being used to point to the end marker of the FAT.
Linker rules¶
The linker rule file lists the order of the sections and ensures that
the TAIL section ends up at the proper starting position (hex
FF4):
(define memories
'((memory Page (address (#x0 . #xFFF)) (position independent)
(section (HEADER FAT FATEND #x0) Code RPN (TAIL #xFF4))
(checksum #xFFF hp41)
(fill 0))))
The TAIL section contains the poll vectors and module identity which
shall go to the end of the module page.
Trying it out¶
The result will be a module file games.mod that you need to plugin
to your HP-41 or load in you HP-41 emulator as described in the
previous example, see Trying it out.
Once installed in the HP-41, you can try the games, but you are probably best advised to go to Jean-Marc Baillard’s web site and read the instructions.
20.3. Modules on the internet¶
Here is a collection of real projects that use Calypsi.
Amateur astronomy¶
Amateur astronomy ROM contains a collection of telescope and observational utilities.
CLILUP¶
CLILUP is an update module for HP-41CL using HP-IL. It is a mixed module using both MCODE and RPN.
Data and statistical analysis¶
Data and statistical analysis ROM is a comprehensive statistical analysis of data sets on the HP-41 calculator.
EquationLibrary¶
EquationLibrary implements an equation library on top of the Formula Evaluation module. It is mostly written in RPN with some MCODE.
Geir ROM¶
Geir ROM is a collection of the most essential programs, utilities and tools as used by Geir Isene. This contains a mixture of useful RPN and MCODE programs.
Isene ROM¶
Isene ROM contains the most useful of Geir Isene’s RPN programs. Ultimate Alarm Clock, the PDA programs NOTES and REM as well as CRYPT to encrypt and decrypt ASCII files and other neat stuff. Makes use of HEPAX and XM files.
Ladybug¶
Ladybug is a banked module that makes use of various techniques to switch banks on the fly. It converts the HP-41 into an integer mode calculator, similar to the HP-16C.