JAZZ V6.5 System RPL and Machine Language Development Library (c) 1995 by Mika Heiskanen & Jan Brittenson CONTENTS ======== 1. Introduction 1.1 Copyrights & Ackowledgements 1.2 The Jazz Library 1.3 Installing & Deleting the Library 1.4 Uncovered Jazz mode 1.5 Entry Tables 1.6 Universal Font Library 2 The System RPL/Machine Language Assembler 2.1 Errors 2.2 System RPL Assembly 2.2.1 Lambda Variable Generation 2.3 Machine Language Assembly 2.3.1 Macros 2.3.2 Conditional Assembly 2.3.3 Expressions 2.3.4 Label Generation 2.3.5 Debugging 2.4 Library Assembly 2.5 Differences to HP Tools 3 The System RPL/Machine Language Disassembler 4 The System RPL Debugger 5 The Machine Language Debugger 6 The System RPL Stack 7 The Entries Catalog 8 The System RPL/Machine Language Editor 8.1 The Viewer 9 Entries Table Utilities 1. Introduction =============== 1.1 Copyrights & Acknowledgements --------------------------------- All files of the Jazz library are copyrighted (c) by Mika Heiskanen unless otherwise noted. The Jazz library is distributed in the public domain in the hope that it will be useful, but is provided 'as is' and is subject to change without notice. No warranty of any kind is made with regard to the software or documentation. The author shall not be liable for for any error for incidental or consequential damages in connection with the software and the documentation. So there. Permission to copy the whole, unmodified Jazz package is granted provided that the copies are not made or distributed for resale (excepting nominal copying fees). Extra credits & acknowledgements: Jan Brittenson DB program is originally from Jan's MLDL library and is still copyrighted by him. The mnemonics have been changed to the ones used by HP + some more or less significant changes have been made. Jens Kerle Bug fixing Dan Kirkland Rewrite of ED/EC keywait subroutines Sorting the default tables sensibly Will Laughlin Backward search & EC key in ED Christophe Meynard Alphabetic sort & search in EC Fill key in ED Register editing in DB Screen reformatting in DB Mario Mikocevic Basis for the machine language instruction disassembler. GNU Tools. Detlef Mueller Inspiration through RPL48 package. & Raymond Hellstern Rick Grevelle Medium font Davor Jadricevic Original small font. Al Arduengo Improved small font. Cary McCallister For answering. Beta testing & suggestions: Seth Arnold Bill Levenson Douglas Cannon Tom van Migem Carlos Ferraro Mario Mikocevic Rick Grevelle Detlef Mueller Joe Horn Richard Steventon Boris Ivanovich Kurt Vercauteren Jens Kerle Vladimir Vukicevic Dan Kirkland Christ van Willegen Jeoff Krontz Stefan Wolfrum Will Laughlin +countless others 1.2 The Jazz Library -------------------- The Jazz library provides commands for assembling, disassembling and debugging both system rpl and machine language. This document describes only the provided commands, not the languages themselves. For information on the languages please refer to the tools package published by HP, especially the files RPLMAN.DOC, RPLCOMP.DOC and SASM.DOC. Familiarity in the fundamentals is assumed from now on. Following files available from hpcvbbs.external.hp.com are recommended: dist/ms-dos/tools.exe HP Tools dist/hp48g/programming/entries/ent_srt.zip Sorted Entries dist/hp48s/programming/entries/entries.zip Address sorted entries dist/unix/sadhp105.zip Unix Disassembler GNU Tools are available from fly.cc.fer.hr: pub/hp48/gtools 1.3 Installing & Deleting the Library --------------------------------------- To install the Jazz library you need atleast: - GX with sufficient RAM or existing RAM card in slot 1 - S/G with sufficient expanded RAM - SX with existing RAM card in slot 1 or 2 The Jazz commands will not work from a covered port, thus GX banks 2-33 are not allowed storage locations for Jazz. To install the library to port 0: (similar for port 1) a) Remove possible older version with :0:992 PURGE b) Download the library to your HP48 c) Recall the library to the stack and purge the variable created by the download procedure. d) 0 STO e) Execute OFF-ON keys or do ON-C 1.4 Uncovered Jazz mode ----------------------- Since version 4.9 Jazz includes the JAZZ command, whose purpose is to enable using Jazz for those who only have a single >128K card, and thus have to keep it in GX card slot 2. JAZZ command expects to find Jazz in port 2, and if so it will change the environment variables maintained by the HP48 so that it will think there is only a single port which is visible. In other words, the HP48 will think port 2 is the only existing one and but will not realize that it is in fact working like port 1 (uncovered). For the JAZZ command to work the user should store both Jazz and the entry tables described in the next section in port 2 of a multi-bank card, and then execute JAZZ to start the uncovered mode. In the uncovered mode: - All the higher ports are inaccessible - Port 2 behaves as if it was uncovered Sadly the HP48 is good enough to notice the tampering at the OFF-ON port checks, and will thus generate a warmstart. This means the user should be careful not to let ED/EC/SSTK/SDB commands timeout while waiting for a key. This JAZZ command is only the first attempt at solving the problem though, the next future consideration is: UNJAZZ command which restores the environment back to normal Until then the only way to exit the uncovered mode is ON-C, or OFF-ON as described above. And if possible, I might make the process automatic by including the JAZZ/UNJAZZ calls in all the commands available in Jazz library. This could create some unforseeable problems, but I am hopeful this will work out fine. 1.5 Entry Tables ---------------- Jazz enables using two different entries tables: RPL.TAB - Entries sorted by their name DIS.TAB - Accessory to RPL.TAB providing address sort The purpose of the tables is the same as that of entries.o for HP and GNU Tools, it provides names for programs and regular objects in ROM. Without the tables you would have to use addresses for all ROM objects instead of names, of use equates for the names in each source code. In any case, programming without proper entry names is extremely tenuos, and thus although Jazz does not need the tables to operate, using them is highly recommended. The tables provided in this package were built from HP's latest supported entries table, with some minor modifications which I thought necessary. The tables are stored inside a library for easy storage and access, but the library can be splitted into backup objects should someone want to keep only the name table (RPL.TAB). Once again though, DIS.TAB provides an address sort to the entries and thus provides a crucial speed increase in disassembling commands, so keeping both the tables is recommended. The tables can be stored in any port. However storing them to a covered port would mean that whenever the tables are accessed, they must be copied into user RAM. This means that effective available free memory is decreased, and of course some speed loss due to the actual copying. However I personally do keep the tables in a covered port, so it isn't that bad. If someone has been using entry tables provided in Jazz packages before version 4.2, it is recommended that the user takes the tables in this package instead, as the tables have changed and the sorting has been improved. The table was built from hpentr.a file, which is provided with the package. gentab2.c is a modified version of Detlef Mueller's gentab.c. The modified version will build library source code given an entries table as input. gentab2 also takes preferred entries in disassembly into account by ordering the names for a given address based on their order in the original input. Syntax: gentab2 < SupRomEntr.a > table.a 1.6 Universal Font Library -------------------------- Jazz requires the universal font library containing the small and medium fonts to be installed in order to work properly. For convenience this is provided in the package. To install it simply upload 'ufl3.lib' and proceed with the usual library installation procedure. Note however that Jazz requires UFL to be installed in the same port as Jazz itself - typically in port 1 of course. 2 The System RPL/Machine Language Assembler ============================================ As opposed to the tools provided by HP Jazz provides only one command to assemble source code. The assembler assumes the source code to be RPL unless a switch is made via special tokens. Command: ASS Stack: ( $ --> ob ) Description: Assemble source string Keys: ON key aborts assembly User flags: 1 - Report mode on (slows down assembly considerebly!) 7 - Disables entry tables In principle the ASS command is equivalent to the following programs put together RPLCOMP - RPL precompiler MAKEROM - Library builder SASM - Saturn assembler What the assembler does is in fact simply to change the internal mode whenever some specific tokens are encountered. However there are some obvious changes, typically some missing mnemonics, but there are also new ones to ease programming. 2.1 Errors ----------- As opposed to the PC assembler's, ASS will stop at the first error it finds. To make the error message as informative as possible, the internal error handling code is never executed, the behaviour is only emulated as far as necessary. The resulting error display is shown in small font as follows: Top of display +----------------------------+ |ErrorMsg line/position| |Token/Source line | To avoid unexpected behaviour the emulated error code expects a standard error trap (SysErrorTrap) to exist in the RPL stream, if this is not the case then by default it must assume that the error trap may be crucial to the program which called the assembler. Thus the regular error code is re-entered to provide proper entry into the error trap. For those programs which find it necessary to keep the full error messages from the assembler, an errortrap starting with ":: NOP" also cause the full messages to be shown. This should be useful for example in the internal SOL replacements, and for example SSTK uses the feature. 2.2 System RPL Assembly ------------------------ System RPL assembly is the default mode for ASS, and works more or less as described in RPLMAN.DOC and RPLCOMP.DOC. Comments in RPL mode are any lines starting with "*", and anything surrounded by parenthesis. Note that RPLCOMP also requires there to be whitespace after the leading "(" character. The object generating tokens are as follows: ; --> end of composite object, eg SEMI { --> start of list, eg DOLIST } --> end of list, eg SEMI :: --> start of program, eg DOCOL SYMBOL --> start of symbolic, eg DOSYMB UNIT --> start of unit, eg DOEXT # hhhhh --> system binary #hhhhh --> system binary [1] ddddd --> system binary [1] PTR hhhhh --> pointer ACPTR hhhhh hhhhh --> access pointer, G/GX only ROMPTR hhh hhh --> rom pointer object ddd.dd --> real number % ddd --> real number [2] %% ddd --> long real number [2] C% ddd ddd --> complex number [2] C%% ddd ddd --> long complex number [2] HXS --> hex number [3] GROB --> grob [3] LIBDAT --> library data [3] BAK --> backup object [3] LIB --> library object [3] EXT1 --> external type 1, S/SX only [3] EXT2 --> external type 2 [3] EXT3 --> external type 3 [3] EXT4 --> external type 4 [3] ARRY --> array [3] LNKARRY --> linked array [3] CODE --> code object [3] NIBB --> misc nibbles $ "" --> string [4] "" --> string [4] ID --> identifier object [4] LAM --> lambda identifier object [4] TAG <..> --> tagged object [4] CHR --> character object [4] [1] Instead of outputting an object, the system binary is searched from stable ROM areas, and if found then the pointer to that object is output instead. (RPLCOMP does not do this) [2] The value may also be -Inf, Inf or NaN, which mean infinite values or an undefined value. Note that these values are actually meaningful only in machine language, not in system RPL. (RPLCOMP does not do this) [3] The length field may also be zero, in which case a null object is output. [4] Special character substitutions are performed in the string parts. Other supported tokens are: xROMWORD --> pointer or ROMPTR depending on the library number the command belongs to ( For example "xDUP" compiles to a pointer but "xASS" to a rom pointer) INCLOB --> Include object stored to a variable INCLUDE --> Include source code DEFINE --> Define substitute for token Substitution will not be done inside multipart tokens, for example "ID " is not allowed CODE --> Starts machine language assembly ASSEMBLE --> Starts machine language assembly 2.2.1 Lambda Variable Generation -------------------------------- To ease the use of NULLLAM lambda variables Jazz implements localized lambda bindings as follows: {{ label1 label2 .. labelN }} compiles to ' NULLLAM <#N> NDUPN DOBIND (or 1LAMBIND if there is only 1 label) After the binding the labels can be used as follows label1 --> 1GETLAM =label1 --> 1PUTLAM !label1 --> 1PUTLAM label1! --> 1PUTLAM The maximum number of variables in the declaration is 22. The equates are in effect until the next lambda variable binding. For example the following program assembles to :: :: {{ A B }} ' NULLLAM TWO NDUPN DOBIND B A! --> 2GETLAM 1PUTLAM ABND ABND ; ; 2.3 Machine Language Assembly ------------------------------ The assembler mode switches to machine language when an ASSEMBLE token is encountered, or the special CODE-ENDCODE pair is found. In the first case the RPL token switches back to system RPL mode. The supported mnemonics are basically those described in SASM.DOC. The behaviour of the following mnemonics has changed: TITLE text Text shown on line 1, line 2 cleared STITLE text Text shown on line 2 MESSAGE text Text shown on line 1, line 2 cleared D0=D0+ expr \ D0=D0- expr Allow values between 1 - 256, and D1=D1+ expr generate multiple opcodes if needed. D1=D1- expr / The following mnemonics are recognized, but are simply ignored: EJECT, REL, LIST, LISTM, LISTALL, UNLIST The following mnemonics have not been implemented: EXITM ABS expr Not Implemented RDSYMB file .. CHARMAP file .. Dn=HEX hh.h .. GOSHORT label .. JUMP label .. INC(n) label .. LINK label .. SLINK label .. NIBBIN bb..b .. (GNU Tools Opcodes) NIBGRB bb..b .. HEX(n) hh.h .. HEXM(n) hh.h .. ASC(n) \ASCII\ .. ASCM(n) \ASCII\ .. The following new mnemonics have been implemented: LCSTR \ASCII\ Reversed LCASC LASTR \ASCII\ Reversed LAASC CSTRING \ASCII\ NIBASC with 0-byte terminator ABASE expr Sets allocation counter to address specified by . label ALLOC expr Allocates nibbles for label at the allocation counter, then increases allocation counter by Dn=Dn+r f.ex D0=D0+A ==> CD0EX C=C+A CD0EX Dn=Dn-r f.ex D0=D0-C ==> AD0EX A=A-C AD0EX Dn=Dn+P f.ex D0=D0+P ==> CD0EX C+P+1 CD0EX Dn=Dn-P f.ex D0=D0-P ==> CD0EX C=-C C+P+1 C=-C CD0EX r=Dn f.ex A=D0 ==> AD0EX D0=A f.ex B=D0 ==> CD0EX B=C CD0EX INCLOB Include object stored to a variable. Note that in Dn=Dn-P the carry is set unless the result is zero. INCLOB will behave differently from code than from rpl. Depending on the type of the object being included it is either included entirely or the leading nibbles (prolog + possible data fields) are skipped for following object types: Prolog Skip Prolog Skip Prolog Skip ------ ---- ------ ---- ------ ---- DOCODE 10 DOEXT0 10 DOGROB 20 DOCSTR 10 DOEXT2 10 DOARRY 5 DOHSTR 10 DOEXT3 10 DOEXT4 10 2.3.1 Macros ------------- The assembler does not implement macros as described in SASM.DOC, in particular no argument substitution exists for now. The following is used to define macros: