ROMANTIC ROBOT present - GENIE - Multiface 128 DISASSEMBLER (c) Romantic Robot UK Ltd 1987 By C Lewis and D Gorski FOR THE ZX SPECTRUM (48K/128K/+2) Genie is a Z80 programming aid exclusively for use with Multiface 128. It loads into the 8K RAM within MF128 leaving all Spectrum memory free for other software. Genie allows you to stop/start programs and examine their operation in minute detail. Whether writing your own programs or modifying the work of others, Genie offers instant access to: * Z80 Disassembler - including undocumented op-codes. * Find - Search for text, op-codes etc. * 'Front panel' display of Z80 CPU - Registers, Program counter, Interrupt status. * View memory as numbers or ASCII characters. * Hex or decimal output to screen or printer. Although some knowledge of Z80 machine code is needed to get the best from Genie, the power to examine any program is an invaluable learning aid. The Genie cassette contains a BASIC loader and an installation program. To load Genie (in 48K or 128K mode), type LOAD "" and play the tape. To cater for different versions of MF128 hardware, you will be asked to input two numbers when Genie first loads. These specify which i/o ports your MF128 uses to page its ROM/RAM in and out. In most cases these values will be IN = 159, OUT = 31 and, as these are the default, simply press ENTER twice to skip this process. If you have a version of MF128 which caters for the Disciple disc interface, input 191 as the Page IN value, and 63 to Page OUT. MF128 must be enabled to install Genie – do this by pressing BREAK at the same time as the MF128 button, then R to quit MF128 menu. Repeat this if you need to re-install Genie for any reason. When the installation menu appears, select Printer Line Feeds On or Off as appropriate (see later) and then press I to load Genie into MF128 Shadow RAM. Pressing SYMBOL SHIFT/A will reset the Spectrum ready to load the software you wish to examine. Once installed, Genie may be summoned by pressing the MF128 button. The top third of the screen is used for displaying output; a key summary is shown here the first time Genie is accessed. The menu or various prompts are shown in this window. The Menu: RET DIS TEXT NUM Z80 FIND M1:0 An option is selected by pressing its initial letter. RET: Return to the program being examined. The program's screen will be restored and execution continued from the point that MF128 button was pressed (but see notes on altering PC register). M: Select 128K memory configuration - applies to 128K machines and only appears if 128 paging is enabled. The first digit is either 1 or 0 and indicates which of the 128's two ROMs was paged in when the button was pressed. The second number (0 to 7) shows which RAM bank was paged in. (See notes on 128 memory map). Since only one of these ROMs and 48K of RAM may be addressed by the Z80 at one time, you must select a bank before examining it. Press M and then:- ROM:0 press key 0 or 1 to select ROM RAM:7 press key 0 to 7 to select RAM Press SPACE or ENTER to move from one prompt to the next, and again to exit this prompt. DIS: Full Z80 disassemb1er using standard Zilog mnemonics. Display shows: ADDRESS OP-CODES (hex) MNEMONIC e.g. 00000 F3 DI The data byte following RST 8 (Spectrum Error RST) is decoded: RST 8 DB 1 The 128 Edit ROM uses RST 40 (28h) to access routines in the 48K Basic ROM. Two bytes fo1low the RST 40 instruction, giving the address to call in the 48K ROM. Genie decodes these bytes (RST 28 DW 0016) only if the 128 ROM is selected (ROM 0). A number of valid Z80 op-codes were omitted from the official instruction set. These cannot be guaranteed to work on every Z80 but are used nonetheless. Genie disassembles the extra op-codes, adding the suffix H or L as appropriate: DD84 ADD A,IXH or CB37 SLL A TEXT: View memory contents as ASCII characters. Bytes <32 or >143 are shown as "." NUM: View memory contents as decimal or hex numbers. Z80: View contents of Z80 registers in decimal or hex. FLAGS are shown by letter, upper case if SET (i.e. 1). The status of Maskable Interrupts (Disabled/Enabled) is shown as DI or EI to the left of the value in the (I)nterrupt register. Z80 Interrupt Mode (IM1 or IM2 only) is displayed below. R is the Refresh register. Press A to alter register contents. This works in much the same way as MF128 Tool. Select the item to alter using (shifted) left/right cursor keys or press Space to exit Alter mode. 'Mi' stands for Maskable Interrupt. Only Bits 0 and 2 have any meaning: Bit 0 : 0 = IM 1 (or IM 0) 1 = IM 2 Bit 2 : 0 = DI (Disabled) 1 = EI (Enabled) So, to set IM 1 and Disable Interrupts one would input the value 0, while 5 would set IM 2 and Enable Interrupts. 'Mb' stands for Memory Bank; the value here is only relevant to 128K Spectrums and controls selection of ROM, RAM and screen. The layout is the same as the 128K Basic System Variable BANKM at 23388. Bit 0-2: select l6K page (0 to 7) at #C000 3: 0 = screen at #4000 1 = screen at #C000 4: 0 = 128K edit ROM 1 = 48K BASIC ROM 5: 0 = paging enabled 1 = locked 48K mode 6-7: unused Don't confuse this with menu option M which only selects pages of ROM/RAM for viewing. The combination of ROM, RAM and screen held in Mb is 'live', i.e. the 128 will be put into this state when you quit Genie. 'PC' (Program Counter) is a Z80 register which, normally, can't be directly accessed. However, when menu option R is used to restart program execution, the address shown against PC will be put on top of the machine stack, causing the Z80 to resume execution at this new location. This gives a way to force the Spectrum back to BASIC from ANY program, but losing anything stored below RAMTOP. First set RAMTOP to, say, 25000 using Alter mode to Poke 23730,168 and 23731,97. Then put address 4535 (11B7 hex - NEW routine in ZX ROM) onto PC. Now, instead of returning to the program, menu option R will NEW the Spectrum, leaving memory above 25000 intact. Although Genie uses none of the Spectrum's RAM, MF128 paging inevitably places four bytes onto the Z80 machine stack. If you need to examine the stack bear in mind that the two bytes at SP and SP+1 are the value in PC, i.e. SP was actually two bytes higher when Genie was summoned. The two bytes at SP-1 and SP-2 are the value in AF. In rare cases, where stack space is very small, MF128 stack usage could cause a 'crash' on return to program from Genie. If so, try pressing the button at another stage, e.g. in PAUSE mode or at a menu. It is, of course, possible for users to crash software by haphazard alteration of RAM or Registers! FIND: Search RAM (16384 to 65535) for occurences of a specified sequence of numbers. Input up to 24 bytes in hex or decimal, one after another. Press ENTER by itself to start searching. If the string is found the address of each match is displayed (in hex and decimal). Press P to output the address to the printer, SPACE to abort or any other key to look for the next occurence. On 128K machines all 128K of RAM is searched. The bank in which a match occurs is shown after the address. An understanding of the 128's memory map will help you make full use of this option. The numbers you input can represent many things, e.g. Z80 op-codes, an address or text. To search for a string of text, input the ASCII code of each character (see Spectrum manual). For example, to find the machine code instruction LD (5C3D),SP input (in hex) ED 73 3D SC ENTER Commands available in all or some modes: H - This key can be used at any time to toggle the display between Hex and Decimal. The border colour changes to show which base is in use: blue for decimal and cyan for hex. Decimal numbers are always shown with 3 or 5 digits, hex numbers with 2 or 4 digits. A - Alter Mode lets you Poke values into any area of Spectrum RAM. Printable ASCII characters (including ZX KEYWORDS) are shown to the right, as well as a binary representation. In Z80 Mode, A lets you alter contents of Registers instead of RAM. M - Memory Select. View/alter current selection of ROM (0 or 1) and RAM (0 to 7). Press a digit key in the appropriate range to alter either item. P - Output to printer as well as screen. Input either an address for printing to start from, or ENTER to begin at the currently displayed address. The default End address is 65535. SPACE aborts printing. Printer errors or pressing BREAK will return you to the menu. C - Copies the top eight lines to the printer. S - Scroll continuously. Press any key to stop. Left/Right (shifted) cursor keys decrement/increment the memory pointer by one byte, allowing you to step back/forward a few bytes. This may restart a disassembly at an address part way through an instruction, in which case the first few mnemonics won't show the true action of the routine. If in doubt, step back and disassemble from a few bytes prior to the area of interest. You can switch between Disassemble, Text and Numeric modes using keys 0, T and N. Press SPACE to return to the menu or exit from an input prompt. Inputting Numbers: Pressing ENTER alone at a prompt for a start address gives a default value. When Genie is first summoned, the default is the value in the Program Counter (PC). Thereafter, it is the address most recently viewed. Hex digits can only be input in hex mode (cyan border). Press H to change base at an input prompt. Some Points to Note. -------------------- A few early Multiface 128s can not run Genie - if yours comes into this category, contact Romantic Robot (01-200 8870) for details of upgrading. Genie uses all of the MF128 8K Shadow RAM, so, with it installed, transferred programs will always reload with a corrupted screen as though MF128 were not connected. To summon MF128 menu instead of Genie, hold down the BREAK key as you press the MF128 button. * THIS CORRUPTS GENIE and it will need to be re-installed for subsequent use. Since Genie resides in Shadow RAM, typing NEW or RANDOMIZE USR 0 won't affect it. Neither will the ZX Reset button, unless this is pressed when Genie is actually in use. If MF128 fails to respond to the push button the BASIC command OUT Address,0 will reinstate paging - the value for Address is that used by your MF128 to Page IN its ROM. In most cases this will be 159 or 191. Never press the button during disc or Interface 1 operations. Genie can be transferred to microdrive, disc etc. The machine code is 5050 bytes long starting at address 27000. E.g. to save to microdrive alter line 20 to: 20 CLEAR VAL "26999": LOAD *"m";SGN PI;"g128.c" CODE and type: CLEAR 26999: SAVE *"m";1;"run" LINE 20 SAVE *"m";1;"g128.c" CODE 27000,5050 To avoid entering the page IN and OUT values whenever Genie is loaded, enter them once, delete Line 100 and re-save the loader and machine code. Genie took several (painful!) months to write - PLEASE don't give copies of it to your friends. Printers and interfaces. ------------------------ As well as ZX printers (or compatibles), Genie can be used with any interface that recognizes the LPRINT command, as long as it has software on ROM or that loads into the printer buffer. Printer output is sent via Stream #3. If your printer interface needs to be initialised (e.g. OPEN #3;"B" for I'face 1), this must be done BEFORE installing Genie, either before loading or by pressing B on Install menu to exit to BASIC. Select menu option "Line Feeds ON" if your interface or printer needs a CHR$ 10 after a Carriage Return (CHR$ 13). Select Line Feeds OFF for ZX printers. Other interfaces may be used by writing your own driver routine in machine code. This should load into the printer buffer (23296) and will have the character to print passed to it in Register A via RST 16. Preserve registers IY and HL'. NB Spectrum 128 and +2 - To print via the built-in RS232 port, load Genie in 128K mode. If at any time the 128 paging mechanism is disabled (by selecting 48K BASIC from the start-up menu, for Example) Genie won't be able to access the RS232 port. It is, however, possible to use the RS232 from within Genie when examining programs that only load in 48K mode: select 128K BASIC and type USR 0, which enters 48K mode without disabling the RS232 port. Disciple: Genie can print via Disciple's parallel port, even if the interface is disabled with the Inhibit button. However, you must ensure that the SYSTEM file has been loaded whenever printing takes places. If it isn't, Disciple will return the Spectrum to BASIC and Genie will need reloading. 128 Memory map: --------------- The 128 has two 16K ROMs (either of which can be mapped into the Z80 address space from 0 to 16383) and eight 16K banks of RAM, anyone of which may be mapped from 49152 to 65535 (C000h – FFFFh) In addition, RAM bank 5 is always mapped from 16384 to 32767 and bank 2 always from 32768 to 49151, so these two banks can appear in two different areas of memory at one time! FIND searches these banks in both positions; you must decide which is relevant. Key Summary: ------------ D - Disassemble. T - Text. N - Numeric. Z - View Z80 registers, interrupt mode etc. R - Return control to program being viewed. A - Alter mode (memory or registers). P - Printer output. C - Copy top 8 lines to printer. S - Scroll (any key to stop). Cursor Left/Right - step up/down one address. SPACE to abort. ------------------------------------------------------------- Chris Lewis - April 1987