Magic48ges presents: ÛÛÛÛÛ ÛÛÛÛÛ Û Û ÛÛÛ Û Û Û Û Û ÛÛ Û Û Û Û Û Û Û Û Û Û Û ÛÛÛÛ ÛÛÛÛ Û Û Û ÛÛÛ Û Û Û Û ÛÛÛÛÛ Û Û Û Û Û Û Û Û Û Û Û Û ÛÛÛÛ Û ÛÛÛ A SYSTEM-RPL DEVELOPMENT TOOLKIT FOR THE HP48 Version 2.02 (c) 1993 by Detlef Mueller & Raymond Hellstern, Magic48ges CONTENTS ÍÍÍÍÍÍÍÍ 1. Introduction 1.1 Copyrights & Acknowledgements 1.2 The RPL48 Toolkit 1.3 Requirements & Installation Instructions 1.4 Abbreviations 2. <-RPL-> Library 2.1 Overview 2.2 The System-RPL Compiler/Decompiler 2.3 The Saturn Assembler/Disassembler 2.3.1 The Assembler Parameter Field Parser 2.4 The Reference Table 2.5 Command Reference 2.6 Hooks 2.7 Things to Notice 3. <-LIB-> Library 3.1 Overview 3.2 Control Variables 3.3 Command Reference 3.4 Things to Notice Appendix A - Quick Reference Guides A.1 <-RPL-> A.1.1 Commands A.1.2 Flag Usage A.1.3 Error Messages A.2 <-LIB-> A.2.1 Commands A.2.2 Flag Usage A.2.3 Error Messages Appendix B - A ->COD Example Appendix C - Ordering Information 1. Introduction ÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ 1.1 Copyrights & Acknowledgements ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ All files of the RPL48 toolkit are copyrighted (c) by Detlef Mueller and Raymond Hellstern - Magic48ges, 1991-1993 - unless otherwise noted. The RPL48 package is distributed in the hope that it will be useful, but RPL48 is provided 'as is,' and is subject to change without notice. D. Mueller and R. Hellstern make no warranty of any kind with regard to the software or documentation, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. D. Mueller and R.Hellstern shall not be liable for any error or for incidental or consequential damages in connection with the furnishing, performance, or use of this software and documentation. This version of RPL48 is a GiftWare release. You may use it as long as you like without registration, but only for developing non-commercial software. Permission to copy the whole, unmodified RPL48 package is granted provided that the copies are not made or distributed for resale (excepting nominal copying fees). If you want to get your own, brand new version, and for further information, please refer to Appendix C. It should be impossible to crash your '48 by using RPL48, but be warned: no software is bug free ! We would like to thank the following people for their support: Wlodek Mier-Jedrzejowicz for presenting RPL48 to the world. Rick Grevelle for the HACKIT library, the ->DIR command of <-LIB->, the base of the sys-stack, many suggestions, exiting talks and for sending us an HP48GX. Mika Heiskanen for beta testing, lots of suggestions, MKROM, DEBUG, and for a great performance enhancement of the D->LIB and L->DIR commands. Douglas R. Cannon for beta testing, lots of suggestions, and for reviewing this document. Joseph K. Horn for beta testing and suggestions, the `HP 48 Resource Allocation Guideline; Library ID's`, SORTLS and for maintaining the '48 GDs. Carlos Ferraro for beta testing and his friendship. Simone Rapisarda for beta testing and many suggestions. Fatri Mohamed, Romain Desplats, Georg Hoppen for suggestions and beta testing. James H. Cloos, Steve VanDevender, Chris Maksymiak for suggestions. Jeoff Krontz, for suggestions, beta testing, getting another GX for Raymond, exiting talks, and.. Chris Spell ..for maintaining the '48 archive at seq.uncwil.edu and for moderating comp.sources.hp48. Dennis York for the kindly permission to publish the BNF parser generator example. W.C.Wickes & HP Corvallis for the '48 and the RPL tools. 1.2 The RPL48 Toolkit ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ The RPL48 Toolkit provides more than 50 powerful commands to aid system RPL and assembler programming and library development on a HP48. It consists of three parts: * library 1234, <-RPL->:5.00 - contains a sys-RPL compiler/decompiler and Saturn assembler/disassembler. * library 1221, <-LIB->:2.0 - contains a library creator/splitter and many commands for handling libraries and un-/supported objects. * a reference table which contains address/name pairs of ROM entry points. The main commands of RPL48 are modeled after the MesS-DOS programs RPLCOMP. EXE, SASM.EXE and USRLIB.EXE which are provided by HP in the self extracting archive TOOLS.EXE (available on several ftp sites and GD#4). This document describes the interface to RPL48; it is not a sys-RPL or Saturn assembler manual. Please refer to RPLMAN.DOC, RPLCOMP.DOC, USRLIB.DOC and SASM.DOC (all contained in TOOLS.EXE) for learning and/or reference purposes. We assume that you are familar with the fundamentals of sys-RPL, Saturn assembly and libraries. 1.3 Requirements & Installation Instructions ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ RPL48 should work on ROM versions A-M HP48 - it's tested on rev A, E, L, M machines by the authors, and it's reported to run also on rev D and J. The <-RPL-> library is compiled to a fixed address; it MUST be stored in an independent (FREEd) port (ie. it only works on a SX or GX), on a SX this can be either port 1 or 2, on a GX this must be port 1 ! Because the whole RPL48 kit requires ~60kb of memory (including a reference table made from the latest entries released by HP) it is recommended to store it into a 128k RAM card. The <-LIB-> library was developed using the standard methods, it can be stored and used in port 0 on any HP48; on a GX it's limited to the ports 0 and 1, and must not be installed in the ports 2-33. For a complete installation of RPL48 it is neccessary that you have plugged in a 128k RAM card (which must have ~60kb free space) in either port 1 or 2 of your SX, port 1 of your GX; the card must be set to R/W. Proceed as follows: a) remove all files of an earlier version b) merge the port c) set up RPL.TAB on your computer by renaming one of the two shipped reference tables or by creating an own one (see section '2.4 The Reference Table') d) download RPL.TAB, LIB.LIB and RPL.LIB e) recall RPL.TAB to the stack, purge RPL.TAB and store it as a backup object named RPL.TAB (case sensitive !) into port 0 (:0:RPL.TAB STO) f) recall the two libraries, purge the variables containing the original copies and store the libraries into port 0 (two times 0 STO) g) free the port, make sure that :0:1234 is the 1st entry of the list in level 2 for the FREE command ! (you can use 0 PVARS DROP to generate the base list) h) warmstart the '48 (power cycle it, or press [ON]-[C]) As mentioned, <-RPL-> is compiled to an absolute address. Its config code takes care of the address the library is stored at. On an SX, if neccessary, the base addresses of the ports are swapped and an additional warmstart is initiated automatically while executing the first warmstart after installation. If the config code recognizes that it is impossible to change to the correct address (ie. the library is stored in port 0, not the 1st object of port 1 or 2 on a SX, or not the 1st object of port 1 on a GX), the autoattach to the home directory is supressed and no (c)-message and no beeps are generated. If the library did not attach itself, make sure it becomes the 1st object of the desired port and execute a warmstart again. If you have installed an HP41 emulator card, <-RPL-> does not install because the emulator uses a similar sheme to install itself to the same address (it is also an absolute library) -- just remove the card. The <-RPL-> and the <-LIB-> libraries are not self-modifing - you can write protect the card containing the libraries. 1.4 Abbreviations ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ LID - library id; a number in the range 0..2047, part of any library, It is used by the HP firmware to identify libraries while resolving commands, messages etc. | - used in stack diagrams for 'or' Abbreviations denoting objects: ob object of any type xlib named or unnamed library command :x:y tagged object - tag x, ob y prg program (secondary) bak backup dir directory alg algebraic lib library libdta library data meta(t) meta object, obn .. ob1 %n, all ob's are of the same type t All other abbreviations are defined in RPLMAN.DOC (like %, # etc.). 2. <-RPL-> Library ÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ 2.1 Overview ÄÄÄÄÄÄÄÄÄÄÄÄ <-RPL-> contains 17 commands, including a sys-RPL compiler (->RPL), a sys-RPL decompiler (RPL->), a Saturn assembler (->COD), a Saturn disassembler (COD->) a RPL.TAB browser (EC) and a medium font sys-stack environment (4/5/7). 2.2 The System-RPL Compiler/Decompiler ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ The compiler is a simple token based one pass LR compiler and implements a grammatical subset of RPLCOMP.EXE. It accepts string objects containing a token sequence, seperated by whitespace (NL,CR,Space,TAB etc.), as input. The output of the decompiler can be used as input for the compiler or (with minor modifications) as input for RPLCOMP.EXE. While ->RPL is compiling a string, it recognizes certain words and generates appropriate code for them. All other words are assumed to be the labels of objects in the runstream and are emitted simply as 5-nibble constants - the reference table (see below) and the assembler symbol table are searched to resolve the appropriate 5-nibble addresses. If an entry can't be found in one of the tables and its 1st chararcter is a 'x', then ->RPL will try to resolve the word without the leading 'x' as a built-in word (e.g. for 'xDROP' the address #1FBD8 would be generated). If the currently processed token isn't resolvable by ->RPL as an object, entry, or built-in word, it is passed to the user-RPL compiler, palparse. If the result is an ID or prg, an error will be generated. If the token is parsed to a %, it will be converted to a # (eg. "12345" ->RPL --> <3039h> (negative values are mapped to 0 and fractional parts are ignored)); any other valid object is simply added to the runstream (eg. [[1,2][3,4]] (F(.)) inserts a 2*2 array of %). The following words are recognized by ->RPL or generated by RPL->: LAM (1) DOLAM object whose name is specified by . ID (1) DOIDNT object whose name is specified by . 0-IDs aren't supported by ->RPL. TAG DOTAG object whose tag is specified by and whose object is given by . $ "string" (1) DOCSTR object with the contents contained between the quotes. CHR (1) DOCHAR object with the specified character. # (3) # (3) DOBINT object whose body is the number specified in hex. % DOREAL object with the specified floating-point number. %% DOEREL object with the specified floating-point number. The number is parsed with % resolution. C% DOCMP object with the specified floating-point numbers. C%% DOECMP object with the specified floating-point numbers. The numbers are parsed with % resolution. PTR
(2,5) Inserts the specified address as a runstream pointer-obj. ROMPTR DOROMP obj whose body will contain the two 3-digit hex numbers. HXS GROB CODE (2) ARRY (2) LNKARRY (2) LIBRARY (2) BACKUP (2) LIBDAT (2) EXT1 (2,4) EXT2 (2) EXT3 (2) EXT4 (2) Specified object whose body is made from the specified hex-string. Zero-length obj's aren't supported by ->RPL. ACPTR (2,4) DOACPTR object, whose data and access routine addresses are built from the two specified hex numbers. NIBB (2) Adds the binary form of the specified hex string to the runstream, eg. NIBB 7 84E2000 creates a 0-ID. CODE ENDCODE CODE object, the assembler is called to assemble the body. ASSEMBLE RPL The assembler is called to assemble the inline code. INCLUDE The accessable path is searched for a variable with the name . Its contents must be a compilable string and may contain further INCLUDE statements. The resulting code is inserted at the position of the INCLUDE statement. INCLOB (2) The accessable path is searched for a variable with the name . Its recalled contents are inserted at the position of the INCLOB statement. The following words create runstream pointer obj's: UNIT DOEXT - Unit start SYMBOL 02AB8 - Symbolic start :: DOCOL - Program start { DOLIST - List start } SEMI - List terminator ; SEMI - Program, UNIT or SYMBOL terminator Text surrounded by ' (' and ') ' is ignored by ->RPL. Before you start compiling your own objects, play with the decompiler to get some examples of the syntax definitions, eg. try { + } 1 GET RPL-> to decompile 'x+'. ->RPL will automatically add SEMIs at the end of a compiled object to close any open composite object, ie. compiling ":: 1" will create :: ONE ; Note (1) Character substitution is supported via '\xxx' in strings, IDs, LAMs and CHRs using the internal routine which does the tranlsation for TRANSIO, code 3 (see the '48 manual for a complete description). You must use '\034' to insert doublequotes (") into strings. RPL-> generates (") within strings, not \034. Note (2) These statements are not supported by RPLCOMP.EXE. Note (3) ->RPL accepts BINTS in one of the following form: # xxx - allways compiled to BINT objects #xxx - searches the ROM for a BINT with the appropriate value, if found a pointer to it is generated instead of a BINT object xxx - real numbers are COERCED and then handled like #xxx Note (4) ACPTR and EXT1 obj's do have the same prologue addresses but are defined differently, the former is a GX only obj, the latter an SX only obj. ->RPL won't allow you to compile a EXT1 obj on a GX and vice versa. RPL-> can only handle ACPTR ! Note (5) If you want to recompile a source generated by RPL->, you must manually replace all PTR 12345 statements by ASSEMBLE CON(5) #12345 RPL 2.3 The Saturn Assembler/Disassembler ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ The assembler defines a subset of SASM.EXE written by Nathan Zelle. You can use it 'stand-alone' or in conjunction with the RPL compiler ->RPL. It's a 2-pass assembler. The input string should be plain ASCII (with blanks and/or TAB's) generated on a PC or the '48 itself. It is 'free format' which means that no column counting is required, except that labels MUST begin in the first coloumn of a line. If a line consists only of a comment, an '*' MUST be in column 1. Empty lines are ignored. The general line structure is: "