JAZZ V4.0 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 2. Jazz Commands 2.1 The System RPL/Machine Language Assembler 2.2 The System RPL/Machine Language Disassembler 2.3 The System RPL Debugger 2.4 The Machine Language Debugger 2.5 The System RPL Stack 2.6 The Entries Catalog 2.7 The System RPL/Machine Language Editor 2.7.1 The Viewer 2.7.2 The Small Font 2.7.3 The Medium Font 2.8 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 minor changes has been made. Mario Mikocevic The small 4x6 font + the basis for the machine language instruction disassembler. Will Laughlin Backward search in ED Rick Grevelle The medium 6x8 font. Detlef Mueller Inspiration through RPL48 package. & Raymond Hellstern Dan Kirkland Sorting the default tables sensibly Jens Kerle Bug fixing 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 +anyone else who I may have forgotten 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 srcm1.zems.fer.hr (IP 161.53.64.254) pub/hp48/tools2.0.4.zip 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 The Jazz commands will not work from a covered port. Thus the 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 [Note: Also copy HPTABS.LIB to your HP48 for speedy assembly & disassembly. Then skip the following paragraphs & continue at "Jazz Commands". -jkh-] Jazz enables using two different entries tables: RPL.TAB - Entries sorted by their name DIS.TAB - Accessory to RPL.TAB providing address sort Neither table is absolutely necessary but atleast RPL.TAB is recommended, DIS.TAB also if any disassembling is to be done. For speed you can store RPL.TAB to romptr 993 0 and DIS.TAB to romptr 993 1. The tables can be stored in covered ports, but it will slow down all commands using the tables by the time it takes to fetch the tables, and the memory available to the commands is lessened by the memory taken by the tables. A default entries table is provided along with the table. It is built from the latest published SupRomEntr.a, with some sorting & deletions done by Dan Kirkland to produce the most sensible names in disassembly. Also Dan added the necessary user-rpl commands to avoid problems regarding the double hashed command names. 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 For users convenience the latest table is distributed along with the package under the name hpentr.a. [See STUFF.DOC on this disk. -jkh-] 2. Jazz Commands ================ 2.1 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 considerably!) Errors: Special error trap simulation is used to enable using the small font for error messages and thus get more information of the reason for the error. For the small font to be used the current program (possibly the kernel) must use SysErrorTrap to trap errors. If the trap found is different error handling is left to the found error trap and extra information of the reasons for the error will be lost, only the actual error number is provided for the trap. For programmers conveniece also error traps that start with ":: NOP" cause showing the full error message. When possible ASS will also output the error position to the stack so that you can immediately edit the error line/token. Display when the error is trapped: Top of display +----------------------------+ |ErrorMsg line/position| |Token/Source line | Comments in RPL mode are: "*" at the start of the line marks the entire line to be a comment. "(anything)" surrounded by whitespace is considered a comment. RPL Assembly Mode Tokens ------------------------ ; --> SEMI { --> DOLIST } --> SEMI :: --> DOCOL SYMBOL --> DOSYMB UNIT --> DOEXT # hhhhh --> system binary #hhhhh --> system binary (from ROM if possible) ddddd --> system binary PTR hhhhh --> pointer ACPTR hhhhh hhhhh --> access pointer, G/GX only ROMPTR hhh hhh --> rom pointer object ddd.dd --> real number % ddd --> real number (*) %% ddd --> long real number (*) C% ddd ddd --> complex number (*) C%% ddd ddd --> long complex number (*) (*) ddd can also be -Inf, Inf or NaN HXS --> hex number GROB --> grob LIBDAT --> library data BAK --> backup object LIB --> library object EXT1 --> external type 1, S/SX only EXT2 --> external type 2 EXT3 --> external type 3 EXT4 --> external type 4 ARRY --> array LNKARRY --> linked array CODE --> code object NIBB --> misc nibbles If is zero then the resulting object will consist of the prolog indicated by the first token and "00005" lenght field. (NIBB indicates no prolog so len must be non-zero) $ "" --> string "" --> string ID --> identifier object LAM --> lambda identifier object TAG <..> --> tagged object CHR --> character object 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 ML Assembly Mode Mnemonics -------------------------- Opcodes recognized in machine language assembly are all the normal opcodes indicated by SASM.DOC plus the next new ones as implemented in GNU Tools: 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 MAKEROM ------- ASS can be used to assemble MAKEROM source code with the following tokens: xROMID #hhh Defines hex library number. xROMID dec Defines decimal library number xTITLE Defines title to be rest of the line. If title is missing then nulltitle is used. xCONFIG <label> Defines the location of the configuration object via a label. If label is missing then no config is taken to exist. xMESSAGE <label> Defines the location of the message table via a label. If label is missing then no message table is taken to exist. EXTERNAL <label> Defines label to be external. Order of introduction determines the command number of the commands in the library so that visible commands will be first, then nullnames. xNAME <label> Specifies location of a visible command. Name: "xlabel" Hash: "label" sNAME <label> <hash> Specifies location of a visible command. Name: "label" Hash: "hash" hNAME <label> Specifies location of a 'visible' command. Name: "label" Hash: null NULLNAME <label> Specifies location of a hidden command. Name: "label" Hash: none tNAME <label> <hash> Specifies secondary hash for command. xROMID and xTITLE must be used at the start of the source code, to be specific before any actual code has been output. Also xROMID must come before any other MAKEROM token. xCONFIG and xMESSAGE declarations can be anywhere (or absent), but a suitable location is after the xROMID and xTITLE declarations. EXTERNAL declaration is needed if the corresponding command is used before its location is specified by its NAME declaration. Suitable location is after the header declarations, and it is probably best to declare all commands. xNAME, sNAME, hNAME and NULLNAME specify command location, thus they should be right in front of the object they define as a command. All but NULLNAME also define the romid/cmd header field properly and thus require a propfield, typically the value 8 to mark a regular command and 000 to mark a regular function, for other values please refer to entries.srt or other documents. Above also define a symbol '~label' having a 6 nibble value, low 3 nibbles containing the romid and high 3 nibbles the command number. The internal menu display routines stop showing library menus if a command with no hash is found. Thus any command declared after a hNAME will not be shown in the library menu, but will of course have typable/disassemblable command names as usual if so specified by NAME tokens. tNAME can be used anywhere after the declaration of the romp the secondary hash is assigned to, a suitable location is right after the corresponding NAME location declaration. Note that tNAME can be used to declare names for NULLNAMEs, thus providing easy access to low level subroutines if needed. One command can have several secondary names. Note that INCLOB does not do any ID --> ROMP conversion work on the included object like the common DIR --> LIB library builders do. Example: Jazz MAKEROM source would start like this: xROMID 992 xTITLE Jazz v4.0 Fin'95 10.06.95 mheiskan@gamma.hut.fi xCONFIG JazzCfg xMESSAGE JazzMsg EXTERNAL xFNT1 ( Fonts always come first in Jazz ) EXTERNAL xFNT2 EXTERNAL xASS ( User ASS command ) EXTERNAL Assemble ( Main assembler code object ) [..] EXTERNAL UnShowSel! ( Low level subroutines of SSTK ) EXTERNAL >SelPict! LABEL JazzCfg ( Configuration object ) :: 992 TOSRRP ; LABEL JazzMsg ( Message table ) ARRY hhhhh hhh..h NIBB 1 8 ( Easier than ASSEMBLE CON(1) 8 RPL ) xNAME ASS ( Note: the EXTERNAL declarations ) :: CK1 ... ; ( declared fonts to come before ASS ) [..] ( when assigning command numbers ) Missing Tokens and Mnemonics ---------------------------- The following ones for various reasons do not behave as documented in SASM.DOC or GNU Tools: Not implemented: IF, ELSE, ENDIF + any other conditional assembly mnemonic MACRO \ ENDM Macros not implemented EXITM / CLRFLAG expr \ Flags not implemented SETFLAG expt / 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\ .. Modified Tokens and Mnemonics ----------------------------- Behaviour 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 / Ignored: EJECT, REL, LIST, LISTM, LISTALL, UNLIST Expressions in machine language ------------------------------- Factors: #hh.h hex integer %bb.b binary integer dd.d decimal integer =symbol global symbol (RPL.TAB checked too) :symbol local symbol symbol local symbol * PC counter + - ++ -- Local labels Operators: Priority: ^ 9 * 8 / 8 % 8 (modulo) + 7 - 7 & 5 (and) ! 4 (or) Note in particular that ascii factors are not implemented. As in sasm all symbols must be surrounded with parentheses when operators are used. Label generation in machine language ------------------------------------ Symbols +, ++, - and -- are location dependant symbols and refer to the next/previous defined value of the corresponding symbol. Example: GOSUB + ---+ CSTRING 'Foobar' | + C=RSTK <--+ D0=C - A=DAT0 B <-------+ DAT1=A B | ?A=0 B | GOYES + ---+ | End of string, done D0=D0+ 2 | | D1=D1+ 2 | | GONC - ---|----+ + ... <--+ Note: Symbol ++ does not refer to the 2nd + coming up, but the next ++ label coming up, and similarly for --. INCLOB Special Features ----------------------- 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 Warnings -------- A=A+CON fs,expr and similar instructions allow single nibble fields (WP,P,S,XS) while SASM errors. These instructions behave badly due to a hardware bug but are supported by ASS for those who know how to safely use the commands. Symbol/label handling is quite secure but allows more than SASM. For example external values have no significance, thus for example (=GETPTR)-(=SAVPTR) is valid in Jazz. Relative values are followed and are significant for most opcodes. For example 'D0=D0+ label' will error. Note especially that (label1)-(label2) is absolute. = EQU and ALLOC require their expression fields to be resolvable on the first pass. 2.2 The System RPL/Machine Language Disassembler ------------------------------------------------ Several disassembler commands are provided for different purposes. Using DIS.TAB speeds up the commands considerably. Command: DIS Stack: ( ob --> $ ) Description: Disassemble object. If stk1 is a pointer to a ROM address only the pointer will be disassembled. Command: DISXY Stack: ( hxs_address hxs_end_address --> $ ) Description: Disassemble memory area. Guesses start mode, switches mode during operation if necessary. Command: DOB Stack: ( ob | #address | hxs_address | "entry" --> $ ) Description: Disassemble memory area. Guess start mode and end address. Command: DISN Stack: ( hxs_address %N --> $ ) Disassemble memory area as machine language only. Common features for the disassembler commands: ON key aborts disassembly. User flags: 2 - disable guess mode 4 - disable machine language disassembly for DIS 5 - disable tabulator, use spaces instead 6 - force generated labels on their own rows In guess mode the disassembler will try to guess data structures embedded in machine language. Currently only the following types are recognized: GOSUB + REL(5) + Optional leading size indicator BSS expr Data is all zeros + C=RSTK GOSUB + REL(5) + Optional leading size indicator NIBASC \ASCII\ \ Possibly alternating and spanning CSTRING \ASCII\ / multiple lines. + C=RSTK GOSUB + REL(5) + Optional leading size indicator NIBHEX hh.h Miscellanoues data + C=RSTK The sufficient condition for an ascii guess to be successful is that the data area should consist mostly (75%) of common ascii characters. The ascii lines are splitted to CSTRINGs or by newline characters or so that the maximum lenght will be 40 chars. Warnings: - DOB, DISXY and DISN disassemble areas of memory instead of well defined objects. Using these commands to disassemble memory in the temporary object area is dangerous since a possible garbage collection during run-time can move the memory being disassembled. Use only DIS to disassemble objects in tempob!!! - Composite history is tracked up to 64 levels. If that is exceeded a ";" may be output when "}" is due. - As opposed to the assembler the disassembler cannot handle hidden hash tables, thus some named ROMPTRs will be disassembled to "ROMPTR xxx yyy". - Label values are guessed for Dn=(2) and Dn=(4) instructions if - Dn=(2) is likely to refer to the IO page - Dn=(4) is likely to refer to a RAM variable This works well for disassembling ROM but doesn't does badly when disassembling a program that uses even-page method in its data allocation. Benefits are clearly greater though. 2.3 The System RPL Debugger =========================== Command: SDB Stack: ( seco | id | lam | romp --> ? ) Description: Start debugging program indicated by stack level 1. If the srpl debugger is already running then SDB command will only show the SDB menu: ->SST - Single step next command If right-shifted then single-steps rest of the stream as a single unit ->IN - If possible then enter the program referred to by the next command, else single step command. SNXT - Show next commands on status area Pressed for the second time shows return stack SST-> - Start continuous ->SST mode, subsequent presses toggle slow/fast mode, eg whether stack display is updated after each command or not. Any other key aborts continuous evaluation IN-> - Start continuous ->IN mode. DB - Start DB on next code object xKILL - The HP48 KILL command (xCONT can be evaluated through LS+ON keys) SKIP - Skip next command. If right-shifted then skips rest of current stream, eg executes a SEMI command. SEXEC - Execute stk1 as the 'next' command. SBRK - Set breakpoint object to STK1. If right-shifted clears breakpoint object. LOOPS - Browse loop environments. Up/Down to scroll, any other key to exit. If right-shifted dumps topmost environment to the stack. LAMS - Browse lam environments. Up/Down to scroll lams, left/right to decrease/increase environment. Any other key to exit. If right-shifted dumps topmost environment to the stack. IN? - Toggle ->IN mode to never enter into secondaries, only into IDs/LAMs/ROMPTRs when allowed. Prevents the debugger from entering into ROM subroutines during continuous debugging. Note that SDB is meant for debugging system rpl, not user rpl. Thus some user rpl commands will not be single stepped right when using SDB. One example is xHALT, for which the substitute xSHALT is provided. Note that SDB must be running before SHALT works. Warnings: Debugging system-rpl is very hairy and undoubtedly SDB cannot debug some lesser known commands correctly. If such commands are found SDB can even cause a crash and memory loss. This is unfortunately unavoidable since there really is too much code in ROM to worry about. SDB should manage to debug all normal programs though. SDB either enters commands or executes commands (by emulation if necessary). None of the interactive commands in HP48 ROM are emulated, most importantly PolOuterLoop. To emulate POLOuterLoop you need to insert SHALT commands into the display objects or whatever you want to debug, then start SDB, then use CONT to reach the point of the SHALT command. LOOPS and LAMS displays are pretty lame, I'll try to improve them later. 2.4 The Machine Language Debugger --------------------------------- Command: DB Stack: ( id --> ) ( romp --> ) ( $entry --> ) ( #address --> ) ( hxs_address --> ) ( code --> ) Description: Debug machine language Screen Keys: [A] - Screen 1 (general registers) [B] - Screen 2 (registers A-D) [C] - Screen 3 (registers R0-R4) [D] - Screen 4 (RSTK) [E] - Screen 5 (memory dump) [F] - Screen 6 (machine language disassembly) [MTH] - Screen 7 (breakpoints) [VAR] - Screen 8 (watchpoints) [ ] - Update display [EEX] - View PICT (if it exists) as long as EEX is down Arguments: [0] - Start inputting argument. [0-9A-F] add digit [DEL] abort input [BS] delete last digit [+/-] negate arg Movement keys: [NXT] - Skip instruction (or ARG instructions) [left] - PC=PC-1 (or -ARG) [right] - PC=PC+1 (or +ARG) [up] - PC=PC-16 (or -16*ARG) [down] - PC=PC+16 (or +16*ARG) [.] - Set mark to PC (or to ARG) [+/-] - Swap PC and mark [ENTER] - If ARG then set PC = ARG Debug keys: [+] - Single step (ARG) instructions [-] - Single step (ARG) instructions, debug GOSUBs as a single instruction [*] - Single step (ARG) instructions with display update. If no ARG then sets ARG to #FFFFF. [/] - Single step (ARG) instructions with display update, debug GOSUBs as a single instruction. If no ARG then sets ARG to #FFFFF. [EVAL] - Continue until end or breakpoint [SIN] - Save current registers [COS] - Save registers with the saved ones (first save is done at startup) ARG + [SIN] = clear cycle counter 1 ARG + [COS] = clear cycle counter 2 Exit keys: [DEL] - Restore registers & exit [BS] - Exit now [1/x] - Exit via reset, press second time to confirm Breakpoints: [PRG] - Set breakpoint to ARG [STO] - Set breakpoint counter to ARG Options: [CST] - Toggle option number (next key) 3 - Ascii/hex mode 4 - Shift memory dump by 1 5 - Automatic switch between PICT/ABUFF during debug 6 - Disable/enable RPL.TAB and DIS.TAB 7 - Opcode/cycles display Sample screens which can be reasonably reproduced by: "#>HXS" DB (or #59CCh DB) Screen 1 - General CPU State (key [A]) Mnemonic............................ |GOSUBL SAVPTR | Opcode.............................. | 8E4CD0 | PC, P, Carry, Hex/Dec mode, ST...... |@:059D1 P:0 CH ST:298 | A.A and C.A......................... |A:059CC C:BF4F8 | B.A, D.A, and HST................... |B:8883E D:0AF58 HST:2 | D0 and 6 bytes @D0.................. |D0:E8EF8/CCD205700074 | D1 and 6 bytes @D1.................. |D1:BF4FD/000000000000 | Top 3 levels of RSTK................ |RST:00000:00000:00000 | Screen 2 - Arithmetic registers (key [B]) Mnemonic............................ |GOSUBL SAVPTR | Opcode.............................. | 8E4CD0 | PC, P, Carry, Hex/Dec mode, ST...... |@:059D1 P:0 CH ST:298 | Register A.......................... |A:6C4475C79A7059CC | Register B.......................... |B:000000000008883E | Register C.......................... |C:36000000077BF4F8 | Register D.......................... |D:000000000000AF58 | Top 3 levels of RSTK................ |RST:00000:00000:00000 | Screen 3 - Data registers (key [C]) Mnemonic............................ |GOSUBL SAVPTR | Opcode.............................. | 8E4CD0 | PC, P, Carry, Hex/Dec mode, ST...... |@:059D1 P:0 CH ST:298 | Register R0......................... |R0:60000000000409C1 | Register R1......................... |R1:6C4475C79A7059D1 | Register R2......................... |R2:6C4475C79A7DE599 | Register R3......................... |R3:6C4475C79A700000 | Register R4......................... |R4:10000000004BFA18 | Top 3 levels of RSTK................ |RST:00000:00000:00000 | Screen 4 - Return stack (key [D]) Mnemonic............................ |GOSUBL SAVPTR | Opcode.............................. | 8E4CD0 | PC, P, Carry, Hex/Dec mode, ST...... |@:059D1 P:0 CH ST:298 | | | RSTK levels 0 and 4................. |RST0:00000 RST4:00000 | RSTK levels 1 and 5................. |RST1:00000 RST5:00000 | RSTK levels 2 and 6................. |RST2:00000 RST6:00000 | RSTK levels 3 and 7................. |RST3:00000 RST7:00000 | Screen 5 - Memory dump (key [E]) Locations 59A0-59AF................. |059A0:56113680913420CC| Locations 59B0-59BF................. |059B0:4E0156716FCC56FD| Locations 59C0-59CF................. |059C0:015B38D5E0101D95| Locations 59D0-59DF................. |059D0:08E4CD08E46C0101| Locations 59E0-59EF................. |059E0:D230574911191443| Locations 59F0-59FF................. |059F0:4E4A201101311456| Locations 5A00-5A0F................. |05A00:12280A50143174E7| Locations 5A10-5A1F................. |05A10:8E58D01311741431| current location is indicated by an inverse digit. Screen 6 - ML Instruction Stream (key [F]) PC, P, Carry, Hex/Dec mode, ST...... |@:059D1 P:0 CH ST:218 | Next 7 instructions................. | D1: GOSUBL SAVPTR | | D7: GOSUBL POP# | | DD: R1=A | | E0: C=0 A | | E2: LC(1) 5 | | E5: GOSUB MAKE$N | | E9: C=R1 | The next instruction is the one displayed in reverse. Currently, it will always appear at the top. (Here somewhat crudely illustrated with the # signs.) Screen 7 - Breakpoint Table Screen (key MTH) Breakpoint #1....................... | 1:6100 +02 | Breakpoint #2....................... | 2:6104 -02 | Breakpoint #3....................... | 3:613A 00 | Breakpoints #4-#8: not used......... | 4:0000 00 | | 5:0000 00 | | 6:0000 00 | | 7:0000 00 | | 8:0000 00 | Any breakpoints at the current location are displayed in reverse. Warning: DB uses D0 for its own purposes, thus you cannot debug code that modifies the rpl return stack nor the current stream. 2.5 The System RPL Stack ------------------------ The SSTK command starts a new kernel which is a modified version of the internal one. To exit SSTK just execute SSTK again. Modifications to the internal kernel: - Stack has 5 lines, including the interactive stack. - Flag 3 toggles the stack decompiler: Set: Use internal decompiler Clear: Use a system rpl decompiler - Multi-line mode is not supported. 2.6 The Entries Catalog ----------------------- EC command is a browser for the entry tables. Since the entries are listed in address sorted form both RPL.TAB and DIS.TAB are needed to run EC. Keys are: Up Arrow - Up one entry Down Arrow - Down one entry LS + Up Arrow - Up one page LS + Down Arrow - Down one entry RS + Up Arrow - Jump to first entry RS + Down Arrow - Jump to last entry Right Arrow - View the contents for selected entry with VV Alpha - Input find string (entry name grep) F - Input find string (entry name grep) NXT - Find next match LS + NXT - Find previous match EEX - Toggle grep mode (show only matches) ENTER - Push entry to stack as :name:address LS + ENTER - Push entry address to stack RS + ENTER - Push entry name to stack 0-9 - Find entry starting with input address Use 0-9A-F to input a more specific address. ON - Exit browser +/- - Toggle beep on/off [Note: Some users have reported warmstarts in EC; the keystroke routine seems to conflict with some ROM versions, especially R. The time and date usually get lost during these warmstarts too. So don't leave important stuff on the stack when using EC. -jkh-] 2.7 The System RPL/Machine Language Editor ------------------------------------------ ED is an editor intended for editing rpl and machine language source code. ED makes no duplicate of the edited string if it is in temporary object area, thus enabling editing very large strings. Note that this implies that no backup of the original string is kept! Note that ED is very fast but since it supports the tabulator it has to do special calculations whenever the display is scrolled. Thus scrolling the display when very long lines are present can be quite slow. As a hopefully useful feature ED will accept an optional cursor position argument on stack level one. Thus if ASS gives you the error position you will be able to jump to that position immediately. Most of the normal character keys are in their normal places, others can be fetched via the special character browser. ED also allows an alternate 4x6 font to exist in variable 'FONT.ED'. No checks are made on the correct format, but obviously the just starting ED is an easy way to see if there is a problem. [Note: the FONT.ED file on this disk is a good replacement font. Just copy it to your HOME directory. Beware: ED uses it, but VV does not. -jkh-] Special keys having different definitions are mostly in the non-alpha plane. The NS,LS,RS planes are defined as follows: +-------+-------+-------+-------+-------+-------+ |BSTART |BEND |BCOPY |BDEL | |FIND | | | | | | |REPL? | | | | | | |REPLALL| +-------+-------+-------+-------+-------+-------+ |ARG? | |MEXEC |REVERSE|UP |NEXT | |ROW? |CHR? |MSTART |TOHEX |PGUP |PREV | |POS? |CHRCAT |MEND |TOASC |TOP |STATUS | +-------+-------+-------+-------+-------+-------+ |'' |STK | |LEFT |DOWN |RIGHT | | | | | |PGDN | | | |RCLSTK1| |LSTART |BOTTOM |LEND | +-------+-------+-------+-------+-------+-------+ |GOTO |GOSUB |GOYES | | ^ |DFIND | |GOLONG |GOSUBL |GONC | |CNTRINI| | |GOVLNG |GOSBVL |GOC | |CNTR | | +-------+-------+-------+-------+-------+-------+ |EXIT | |TOGBEEP|DEL |BS | | |ASS |TOGCASE|DELLINE| | | |DOB |TOGOVER|DELRGHT| | +-------+-------+-------+-------+-------+ |alpha |7 |8 |9 |/ | | |SETMK7 |SETMK8 |SETMK9 |() | | |GOMK7 |GOMK8 |GOMK9 |# | +-------+-------+-------+-------+-------+ |lshift |4 |5 |6 |* | | |SETMK4 |SETMK5 |SETMK6 |[] | | |GOMK4 |GOMK5 |GOMK6 |ASS_RPL| +-------+-------+-------+-------+-------+ |rshift |1 |2 |3 |- | | |SETMK1 |SETMK2 |SETMK3 |<<>> | | |GOMK1 |GOMK2 |GOMK3 |"" | +-------+-------+-------+-------+-------+ |REDISP |0 |. |SPC |+ | | | |, |TAB |{} | |OFF |GOMK0 |NEWLINE|TAB |:: | +-------+-------+-------+-------+-------+ Explanations: TOGBEEP - Toggle beep on/off. Default value is taken from the system flag. TOGCASE - Toggle lower/upper case characters. TOGOVER - Toggle insert/overwrite mode. DEL - Delete character under cursor DELLINE - Delete line under cursor DELRGHT - Delete characters to right of cursor. BS - Backspace BSTART - Set block start address BEND - Set block end address BCOPY - Copy block/cut to cursor position BDEL - Delete block (copied to cut) RCLSTK1 - Pop string from stk1 into cursor position FIND - Incremental search. Search is case sensitive if find string contains lower case characters. REPL? - Find/replace with verification REPLALL - Replace all NEXT - Find next match PREV - Find previous match DFIND - Find matching delimiter for delimiter under cursor MSTART - Start defining macro key sequence MEND - End macro key sequence MEXEC - Execute macro key ARG? - Input repeat count for next key press ROW? - Input row to jump to POS? - Input position to jump to CHR? - Input character number to insert CHRCAT - Character browser, ENTER key echos chosen character to cursor position, ON key exits. SETMKn - Set mark <n> GOMKn - Jump to mark <n> GOMK0 - Go to previous cursor position TOHEX - Convert block to hex nibbles (Suitable for NIBASC -> NIBHEX) TOASC - Convert block to asc nibbles (Suitable for NIBHEX -> NIBASC) REVERSE - Reverse chars in block/word ASS - Assemble source code, if error occurs shows the error message and after a keypress jumps to the error position. DOB - Disassembles entry under cursor using DOB, spans a new editor to view the disassembly. After exit back to the original editor the disassembly will be in the clip (if memory allows) ready to be inserted into the text if so desired. Special cases: #hhhhh --> view (like plain entry) Lhhhhh --> view ROMPTR hhh hhh --> view PTR hhhhh --> view ID name --> visit contents (RCL+DIS+ED+ASS+STO) INCLOB name --> visit contents (RCL+DIS+ED+ASS+STO) INCLUDE name --> visit text contents (RCL +ED +STO) GROB hhhhh hh.h --> view grob STK - Starts a normal SOL. Recursive EDs are allowed. Exit back to ED with CONT key. All internal markers except cursor position will be lost. CNTRINI - Initialize counter variable. Number of digits used determines width of counter, possible leading "#" determines a hex counter. CNTR - Insert counter into text and increment it. At start the width is initialized to 1 hex nibble, so for example pressing [ARG?] 16 ENTER [CNTR] will produce "0123456789F" Special keys during inputline: ENTER - Input ok ON - Cancel DEL - Delete char BACKSPACE - Delete previous char LT/RT - Move left/right. During find input pressing RT at the end of input will take the next input char from the current match location, thus making it easier to complete the match. NXT - Next match during find input PREV - Previous match during find input. Special keys in alpha plane: A LS - = ::\n; (with indent checks) A RS - = $ "" A LS + = {\n} (with indent checks) A RS + = CODE\nENDCODE A ENTER = \n + indent the same way as the previous line Notes: Repetition and macro key execution can be aborted with the ON key. Repetition, macro save and macro execution are aborted automatically if an error occurs. Max lenght of a macro key sequence is 50 keys. 2.7.1 The Viewer ---------------- Command: VV Stack: ( $|grob --> $|grob ) Description: Simple string/grov viewer. Keys when viewing a string: Up/Down/Left/Right = scroll display PRG/STO/'/EVAL = scroll onedisplay page F/NXT = top/bottom - = slow scrolling + = fast scrolling (default) ON/ENTER = exit Keys when viewing a grob: Up/Down/Left/Right = move grob . = center grob ON/ENTER = exit A-F = choose scroll speed 1-6 The grob viewer uses a grob! replacement with automatic cutting. Masking grobs less than 4 bits wide is not not properly implemented yet. Viewing is done on the text grob, thus the following will create a weird effect: :: ABUFF xVV ; 2.7.2 The Small Font -------------------- The small font is fixed to ROMPTR 3E0 0 under the name FNT1. The format of the font is in assembly: CON(5) =DOEXT0 * Library Data CON(5) 256*6+5 * 256 characters, 6 nibbles each NIBHEX ...... * Char 00 NIBHEX ...... * Char 01 ... NIBHEX ...... * Char FF 2.7.3 The Medium Font --------------------- The medium font is fixed to ROMPTR 3E0 1 under the name FNT2. The format of the font is in assembly: CON(5) =DOEXT0 * Library data CON(5) 256*16+5 * 256 characters, 6 nibbles each NIBHEX ................ * Char 00 NIBHEX ................ * Char 01 ... NIBHEX ................ * Char FF [Note: there is no way to use FNT2 with ED or VV. It's just here for programmers who wish to use it in other applications. -jkh-] 2.8 Entries Table Utilities --------------------------- Command: EA Stack: ( $entry --> hxs_addr ) ( hxs_addr --> $entry ) ( ob --> hxs_addr ) Description: Converts between entry name and its address. For other argument types the address of the object is given Command: RTAB Stack: ( --> $ ) Description: Recalls RPL.TAB Command: DTAB Stack: ( --> $ ) Description: Recalls DIS.TAB Command: RTB-> Stack: ( --> $ ) Description: Converts RPL.TAB into readable form Command: ->RTB Stack: ( $ --> $' ) Description: Converts an entry list into RPL.TAB form Lines accepted are: [=]name[whitespace][EQU #]address\n ~~~ ~~~~~~~ optional optional Note that the input should be sorted, no checks for that are done. Also the last character in the input string should be a newline character. Command: ->DTB Stack: ( --> ) Description: Creates a DIS.TAB based on RPL.TAB, stores it to home directory. Adding a new entry to RPL.TAB: - Use RTB-> to get an editable string - Use ED to add the new entry definition, must add it to its correct position. - Use ->RTB to get the new RPL.TAB - Replace the old RPL.TAB with the new one - Use ->DTB to get a new DIS.TAB - Replace the old DIS.TAB with the new one Deleting entries is similar. Preferred method of editing is to edit the given hpentr.a and use gentab2 to produce the new tables. [Actually, I prefer to use the HACK library's L->DIR and D->LIB to rebuild Library 993 (the RPL.TAB and DIS.TAB library) manually. -jkh-]