Contents ======== Introduction The Command Line Numerical values String values Syntax definitions Current syntax problems Obtaining Help Memory Commands Introduction Memory Editor and Disassembler Hex dump mode Disassembly mode Summary Memory Copy Memory Swap Memory Compare Memory Fill Memory Search Memory CRC Disk Commands Introduction Disk Editor Control Panel Control Panel Keys Sector ID editor Disk Formatter Loading and Saving Sectors Load Sector IDs Display Sector IDs Verify Disk Fill Disk Fast Backup Permanent *ENABLE Display Disk Gaps Display Disk Format File Commands Introduction Loading and Running commands in DFS workspace 'Safe' File Removal File CRCs Updating File Start and Execution Addresses Concatenating Files Multiple File Copy Disassembly Closing IO Channels DES Encryption Comparing Files ROM Commands Introduction List ROM bank information Switching ROMs on and off Loading and Saving ROMs Obtaining detailed ROM information Master Compatible Sideways RAM commands Building a *ROM filing system ROM image Sending commands to other ROMs General Commands Introduction Printer Buffer List System Vectors *KEY manipulations Numeric base conversions BREAK commands 'Bad Program' recovery Command Line 'Echo' Command Summary ------------------------------------------------------------------------------- Introduction ============ ------------------------------------------------------------------------------- The Command Line ================ Numerical values ---------------- Numerics can be specified in decimal, hexadecimal, or binary. To specify a base prefix the number by either '#' (decimal), '&' (hexadecimal) or '%' (binary). Alternatively, no prefix assumes hexadecimal. In addition to this, there are a set of predefined constant available. These are: @ROM &8000 @PAGE Current value of BASIC PAGE (eg &1900) @TOP Current value of BASIC TOP (eg &1902) @LOMEM Current value of BASIC LOMEM @HIMEM Current value of BASIC HIMEM @OSHWM Current value of OSHWM A numerical value may be derived as an increment to a previous numerical value by using the '+' prefix. For instance, the numbers '1 2 3 4 5' can be generated by: "1 +1 +1 +1 +1" Undefined behaviour will result when using the '+' prefix after a nonnumerical value. String values ------------- These are normally specified by double quoting a string. The string is parsed using the OS routine GSREAD. To modify the value of an ascii character, use of the prefixes '|' to subtract &40 and '|!' to add &80. As an example the string "|!|@" represents the hexadecimal value &80. To include double quotes in a string, you should use two double quotes in a row (ie close quote - open quote). Some commands will take only a string as an argument. In these cases it is possible to neglect the surrounding quotes for your string. However these will naturally still be required if you wish to include a space in your string to prevent the string appearing to be two arguments. The 'close quote - open quote' paradigm still works here even if it does appear to be no longer quite correct. An exception to the above rule is of course the string starting with a double quote. The parser will assume that you are quoting your string, so you should bear this in mind. So the string consisting of only a single double quote will be """". Syntax definitions ------------------ The syntax for any can be obtained by using '*HELP '. Our symbols used are as follows: Required argument 'word' (word) Optional 'word' (word1)(word2) Optional 'word1' or 'word2' <(word1)(word2)> Combination of above - required 'word1' or 'word2'. ... 1 or more of previous argument Real examples of the syntax can be found with such things as: <(byte)("string")> ... A required list of either byte or "string" Some commands require a terminator character for a list. An example of this is MFILL which fills a block of memory with specified data supplied in the form of the example list above. An optional argument of a ROM bank can be supplied. However being optional we need a method to distinguish whether the number is part of the list or not. To do this we use a ';' separator instead of the normal space character. So for example, the syntax for MFILL is: MFILL <(to)(+len)> <(byte)("string")> ... (; ) To fill the first 1k of sideways RAM bank 4 with the string "aardwolf" the command could be: *MFILL @ROM +400 "aardwolf"; 4 The ';' operator can also be used to place comments after commands. For example: *MEM @ROM A ; Fire up memory editor at location &8000, ROM bank A Be careful with commands that do actually use semi-colons in their syntax, if a comment is required after the command then all the semi-colons will have to used, otherwise the comment may be seen as an argument. For example: *MFILL 2000 +100 "A" ; This command line is wrong This will cause a "Not a number error" as the parser has seen a semi-colon and expects a numeric value for the optional ROM bank. To prevent this the following should be used: *MFILL 2000 +100 "A" ;; This comment is ok The parser finds no ROM bank argument, only a separator, so ignores everything else. If you want comments after your command lines then just make sure there is one more semi-colon in the command line than the parser expects. Current syntax problems ----------------------- Strings containing a separator (' ', '+', or ';') need to be quoted, regardless of whether or not they are a string only argument. Solutions are to either fix rdstr so that it only treats space as a separator (messy and tricky); to accept the fact that we need to quote such things; or to introduce an escaping mechanism (eg backslash) to transform metacharacters into normal characters. Obtaining Help ============== The ROM conforms to usual *HELP methods. *HELP by itself will present you with a list of topics available. Typing *HELP will give you a list of all the commands within that topic and their relevant syntaxes. To obtain the syntax for a specific command use *HELP . Alternatively, if you attempt to use a command with an invalid syntax you will be told the correct syntax. ------------------------------------------------------------------------------- Memory Commands =============== Introduction ------------ Commands -------- MEM Scrolling memory editor MDIS Scrolling memory disassembler MCOPY Copies memory MSWAP Swaps two regions of memory MCMP Compares two regions MFILL Fills memory with specified data MSEARCH Searches through memory for specified data MCRC Calculates a Cylic Redundancy Check on a region (U) Memory Editor and Disassembler ------------------------------ Syntax: *MEM (
()) *MDIS (
()) The default for address and ROM bank are PAGE and whichever ROM bank HackROM is in respectively. The editor consists of two distinct modes; the hex dump and disassembly modes. Disassembly. Hex dump mode ------------- The screen layout consists of three main columns; on the left is the memory address; in the middle is a block of hex numbers representing the contents of that memory address; on the right is the same contents displayed in ASCII form. Using the Copy key you can move your cursor from the hex to ASCII representation of the memory. The arrow keys control movement. Left and Right moves the screen cursor left and right to the next displayed byte (scrolling the screen up or down to the next line when required). Up and Down scrolls the screen in the corresponding direction and hence changes the edited address by 8 bytes. Up and Down together with Control or Shift changes the edited address by &80 or &100 bytes respectively. For Left and Right the Shift key zooms to the far left or far right of the current screen line. With control the Left and Right keys change ROM bank up or down by one. The current bank number and ROM name (if a ROM is installed in that bank) is displayed at the top of the screen. ROM banks will cycle modulo 16 (so Control Left would change bank 0 to bank F and Control Right would change bank F to bank 0). When in ASCII edit mode, any key, or key combination (such as Control @ to represent ASCII value 0) will insert the corresponding ASCII value in that byte and increment the edited address by one. For hex edit mode things are a little more complicated. We can only edit one nibble at a time by pressing '0' to '9' or 'A' to 'F'. The existing byte at that memory location will be rotated left 4 bits (the low nibble becomes the high nibble) and our value ORed into the location (the typed nibble becomes the low nibble). This way to type in a complete 2 digit (nibble) hex number you type the digits in left to right order. Note: when typing in a 2 digit hex number '67' to a location containing 'AB' the contents of that location will change twice; once to 'B6' and again to '67'. So when editing memory mapped IO this behaviour should be taken into account. One possible solution is this case is to switch to the ASCII edit mode and type in the ASCII character 'g' which would only change once. This however is not practical for values greater than &80. In a future revision of the ROM it is hoped that a Meta key will be used to add &80 to the value of the key pressed. The hex dump mode continually refreshes the screen and so may be used to examine the contents of rapidly changing memory. An example use of this would be to examine data arriving at the 1Mhz bus. Disassembly mode ---------------- The layout here contains the address on the left hand side, the contents of this memory in both hex and ASCII, and the opcode and operands this data represents. The opcodes understood are all those used by the 6502, the 65C02 or the Rockwell 65C02. (*FIXME: check this chip name*) It is not possible to perform edit operations in this mode. To perform these you should switch to the hex dump mode using the Copy key. Movement is by similar controls to the hex dump mode with the exception that Shift Left and Shift Right no longer work, for obvious reasons. When using the Down arrow key the screen scrolls by one opcode. The opposite, the Up arrow key, currently scrolls up by one byte. It is perhaps preferable to scroll up by either 1, 2 or 3 bytes depending on whether there is a valid opcode at 1, 2 or 3 bytes back in memory. Comments are welcome. The disassembly screen does not continually refresh the screen. To force a refresh press an unrecognised key such as the spacebar. Summary ------- Hex dump keys: Tab switch to disassembly mode Copy toggle editing position from hex to ASCII and back again. Left arrow Move cursor left (one byte lower in memory) Right arrow Move cursor right (one byte higher in memory) Up arrow Scroll up (move eight bytes lower in memory) Down arrow Scroll down (move eight bytes higher in memory) Cntrl+L/R arrow Change ROM bank down (L) or up (R) one Cntrl+U/D arrow Move up or down memory by &80 bytes Shift+L/R arrow Jump to left or right of current line on screen Shift+U/D arrow Move up or down memory by &100 bytes Escape Quit Anything else Edit the data below the cursor. This will either change a nibble or change a byte depending on editing position Disassembly keys: Tab switch to hex dump mode Up arrow Scroll up 1 line (currently 1, 2 or 3 bytes lower in memory) Down arrow Scroll down 1 line (1 opcode bytes worth higher in memory) Cntrl+L/R arrow Change ROM bank down (L) or up (R) one Cntrl+U/D arrow Move up or down memory by &80 bytes Shift+U/D arrow Move up or down memory by &100 bytes Escape Quit Anything else Refresh screen Memory Copy ----------- Syntax: *MCOPY <(to)(+len)> ( ()) Memory Swap ----------- Syntax: *MSWAP <(to)(+len)> ( ()) Memory Compare -------------- Syntax: *MCMP <(to)(+len)> ( ()) Memory Fill ----------- Syntax: *MFILL <(to)(+len)> <(byte)("string")> ... (; ) Memory Search ------------- Syntax: *MSEARCH <(to)(+len)> <(byte)("string")> ... (; ) Memory Cyclic Redundancy Check (UNIMPLEMENTED) ---------------------------------------------- Syntax: *MCRC <(to)(+len)> Description: Computes a CRC for a given memory range. This value is useful as a memory checksum system and is used in the *ROM filing system. ------------------------------------------------------------------------------- DISK COMMANDS ============= Introduction ------------ The disk commands are written around the 8271 Floppy Disk Controller and The Watford Disk Filing System for which there is some support, notably the 62 file format. If using any other 8271 based DFS then the commands will work equally well. It is assumed that knowledge of disk layout, the concepts of tracks and sectors, physical and logical is known. The disk commands will understand ANY format on a disk if it is legal. The workspace required for the disk commands involves three buffers, the first is used for loads sector id's, &0A00 to &0A7F, the second is used as a sorting workspace for those id's, &0A80 to &0AFF, and the third is used for loading sectors and occupies from &6000 onwards, depending on the size of the sectors being loaded. Commands -------- DEDIT Interactive disk edtior IDEDIT Interactive sector id editor (U) FORMAT Disk formatter SECTLOAD Sector loader SECTSAVE Sector saver LOADIDS Sector id's loader PIDS Sector id's printer VERIFY Disk verify DFILL Disk filler (U) FBACKUP Fast backup, will copy *ANYTHING* (U) PENABLE Permanent *ENABLE (U) GAPS Print gaps between files on the disk (U) DMAP Print a format map of the disk (U) The disk commands are based around an extensive library of routines designed under the 'I want that sector, give it to me, and if you can't tell me what you know' philosophy. Given a sector and track the sector-loader will attempt to load that sector no matter what format it has, whether it is deleted data, whether or not the logical track matches the physical track. If it fails to do so it will have attempted to load the sector id's and will return a DFS error code, failing to load the sector id's it will only return an error code. Playing/testing this commands can be a dangerous business, especially with commands that can write to the disk, namely DEDIT, FORMAT, DFILL and SECTSAVE. Get a blank disk, make sure there isn't precious disk in another drive and test the commands then, only when you are confident that they work use them on valuable disks. It is a psychological problem of confidence that was learnt the hard way by myself (SY). Disk Editor ----------- Syntax: *DEDIT The disk editor is an interactive front end to the sector-loader and -saver functions described above. It allows MEM style editing of the data on loaded sectors, quick-key moving around the disk and on-disk file editing. Control Panel ------------- The top three lines of the screen are the control panel and consists of parameters used to point to a sector on the disk. DRIVE 0 PHYS TRACK 00 LOGI SECT 00 PHYS SECT 00 FILE $. LOGI TRACK SECTORS x P Control Panel Keys: Tab Move to next field Return Load sector Escape Quit DEDIT Cntrl-P Put DEDIT in physical sector mode Cntrl-L Put DEDIT in logical sector mode Left arrow Move cursor in field left Right Arrow Move cursor in field right To move the block cursor around the fields use the TAB key. Each field can be set to point to a sector on a disk. Pressing one of the keys which are accepted in the current field will move the cursor on by one place until it reaches the end of the field, in the drive field there is only one character to change so this is not applicable. The left/right cursor keys can be used to move within the fields. and can be used to change the behaviour of the sector-loader by making it load physical sectors or logical sectors respectively. (I will not go into the implications of physical/logical sectors as it is beyond the scope of this manual). There is also a 'FILE' field where a filename can be placed and given that the disk is a valid 10x256 byte format disk with a proper catalogue (Watford 62 file supported). Pressing whilst in the control panel will load the sector which is being described by the current field. Being in any of the DRIVE, PHYS TRACK, LOGI SECT, PHYS SECT then it will load the physical/logical sector (depending on the physical/logical mode indicator) described by those fields. Pressing in the FILE field will attempt to load the first sector of the file on the drive specified by the DRIVE field. Having pressed DEDIT will attempt to load the sector described by the Control Panel. If there is an error, the error description will displayed on the bottom line of the screen, the cursor will be returned to the DRIVE field and the status-line message will be removed after the first key press. On the load being a success the bytes stored in the sector will be displayed in a MEM style manner on the centre panel of the screen, the LOGI TRACK field will display the logical track number for the physical track from which the sector has been loaded. The size of the sector and the number of sectors on that track will be displayed in the SECTORS field. A standard DFS format disk will give SECTORS 0Ax0100 for 10 sectors of 256 bytes. There are various control keys available during the editing session, some for moving around the screen and others for moving around the disk. These are: Up arrow Move up a line in the editing area Down arrow Move down a line in the editing area Left arrow Move cursor left Right arrow Move cursor right Shift+L/R arrow Move to far left/right of editing area Shift+U/D arrow Move to top/bottom of editing area Tab Toggle between hex-byte and ascii-char editing Copy Write the edited sector to the disk Cntrl+R/L arrow Move down/up a track on the disk Cntrl+U/D arrow Move up/down a sector on the disk Escape Quit to control panel Cntrl Escape Quit DEDIT The only editing keys which work in hex-byte mode are 0..9, A..F, but in ascii-char edit mode all keys can be used to edit. Sector ID editor (UNIMPLEMENTED) -------------------------------- Syntax: *IDEDIT Disk Formatter -------------- Syntax: *FORMAT Loading and Saving Sectors -------------------------- Syntax: *SECTLOAD <(to trk)(+trks)> ( ( ())) *SECTSAVE <(P)(L)> () Load Sector IDs --------------- Syntax: *LOADIDS <(P)(L)> () Display Sector IDs ------------------ Syntax: *PIDS () Verify Disk ----------- Syntax: *VERIFY () Fill Disk (UNIMPLEMENTED) ------------------------- Syntax: *DFILL <(to trk)(+trks)> () Fast Backup (UNIMPLEMENTED) --------------------------- Syntax: *FBACKUP <(byte)("string")> ... (; ) Permanent *ENABLE (UNIMPLEMENTED) --------------------------------- Syntax: *PENABLE Display Disk Gaps (UNIMPLEMENTED) --------------------------------- Syntax: *GAPS <(on)(off)> Display Disk Format (UNIMPLEMENTED) ----------------------------------- Syntax: *DMAP <(to trk)(+trks)> (E) ------------------------------------------------------------------------------- File Commands ============= Introduction ------------ Commands -------- DLOAD Down/Up load file (can load files over DFS memory) DRUN Down/Up load and run file (can run files over DFS memory) FDELETE Blank and then delete file (U) FCRC Calculate CRC on file (U) TOUCH Adjust start and exection address of file CONCAT Concatenate two or more files (U) FCOPY Copy two or more files from one drive to another (U) FDIS Disassemble file (U) SPOOLDIS Spool memory disassembly to file (U) CLOSE Close IO channel DES DES (en|de)crypt file (U) FCMP Compare two files (U) Loading and Running commands in DFS workspace --------------------------------------------- Syntax: *DLOAD *DRUN 'Safe' File Removal (UNIMPLEMENTED) ----------------------------------- Syntax: *FDELETE File CRCs (UNIMPLEMENTED) ------------------------- Syntax: *FCRC Updating File Start and Execution Addresses ------------------------------------------- Syntax: *TOUCH Concatenating Files (UNIMPLEMENTED) ----------------------------------- Syntax: *CONCAT ... Multiple File Copy (UNIMPLEMENTED) ---------------------------------- Syntax: *FCOPY ( ...) Disassembly (UNIMPLEMENTED) --------------------------- Syntax: *FDIS () *SPOOLDIS <(to)(+len)> Closing IO Channels ------------------- Syntax: *CLOSE () Description: "*CLOSE 0" will close all channels. DES Encryption (UNIMPLEMENTED) ------------------------------ Syntax: *DES <(E)(D)> <(ECB)(CBC)> () Comparing Files (UNIMPLEMENTED) ------------------------------- Syntax: *FCMP ------------------------------------------------------------------------------- ROM Commands ============ Introduction ------------ Commands -------- RLIST List ROM bank information RON Switch on ROMs ROFF Switch off ROMs RLOAD Load ROM RSAVE Save ROM RINFO Display information on specified ROMs SRLOAD Load data into sideways RAM (U) SRSAVE Save sideways RAM data (U) SRREAD Copy data from main memory to sideways RAM (U) SRWRITE Copy data from sideways RAM to main memory (U) RFSMAKE Build ROM suitable for *ROM filing system (U) SEND Send a command to a specified ROM List ROM bank information ------------------------- Syntax: *RLIST Switching ROMs on and off ------------------------- Syntax: *RON ... *ROFF ... Loading and Saving ROMs ----------------------- Syntax: *RLOAD *RSAVE Obtaining detailed ROM information ---------------------------------- Syntax: *RINFO ( ...) Master Compatible Sideways RAM commands (UNIMPLEMENTED) ------------------------------------------------------- Syntax: *SRLOAD (Q) *SRSAVE <(src )(+len)> (Q) *SRREAD <(dest end)(+len)> *SRWRITE <(src end)(+len)> Building a *ROM filing system ROM image (UNIMPLEMENTED) ------------------------------------------------------- *RFSMAKE ... Sending commands to other ROMs ------------------------------ Syntax: *SEND ------------------------------------------------------------------------------- General Commands ================ Introduction ------------ Commands -------- PBUFF Sideways RAM printer buffer LVECTORS List system vectors KEYLIST List *KEY definitions KEYSAVE Save *KEY definitions KEYLOAD Load *KEY definitions BASE Perform base conversions (U) BREAK Simulate (U) HBREAK As HBREAK except clear memory (U) RECOVER Attempt to recover Bad Programs ECHO Echos back your arguments (to learn CLI) Printer Buffer -------------- Syntax: *PBUFF ( ...) List System Vectors ------------------- Syntax: *LVECTORS *KEY manipulations ------------------ Syntax: *KEYLIST ( ...) *KEYSAVE *KEYLOAD Numeric base conversions (UNIMPLEMENTED) ---------------------------------------- Syntax: *BASE BREAK commands (UNIMPLEMENTED) ------------------------------ Syntax: *BREAK *HBREAK 'Bad Program' recovery ---------------------- Syntax: *RECOVER Command Line 'Echo' ------------------- Syntax: *ECHO (byte) ...; (string) ...; ((byte)("string")) ... Description: This command is very useful for learning how the command line interface works. We suggest you use this command to familierise yourself with the different base entry notations, the '+' operator, and the GSREAD system style of specifying strings containing special characters. ------------------------------------------------------------------------------- Summary ======= A prefix of '*' represents currently unimplemented commands. Memory commands --------------- MEM ( ()) MDIS ( ()) MCOPY <(to)(+len)> ( ()) MSWAP <(to)(+len)> ( ()) MCMP <(to)(+len)> ( ()) MFILL <(to)(+len)> <(byte)("string")> ... (; ) MSEARCH <(to)(+len)> <(byte)("string")> ... (; ) * MCRC <(to)(+len)> Disc commands ------------- DEDIT FORMAT SECTLOAD <(to trk)(+trks)> ( ( ())) SECTSAVE <(P)(L)> () LOADIDS <(P)(L)> () PIDS () VERIFY () * DMAP <(to trk)(+trks)> (E) * DFILL <(to trk)(+trks)> () * FBACKUP <(byte)("string")> ... (; ) * PENABLE * GAPS <(on)(off)> File commands ------------- DLOAD DRUN * FDELETE * FCRC TOUCH * CONCAT ... * FCOPY ( ...) * FDIS () * SPOOLDIS <(to)(+len)> CLOSE () * DES <(E)(D)> <(ECB)(CBC)> () * FCMP ROM commands ------------ RLIST RON ... ROFF ... RLOAD RSAVE RINFO ( ...) * SRLOAD (Q) * SRSAVE <(src )(+len)> (Q) * SRREAD <(dest end)(+len)> * SRWRITE <(src end)(+len)> * RFSMAKE ... SEND General commands ---------------- PBUFF ( ...) LVECTORS KEYLIST ( ...) KEYSAVE KEYLOAD * BASE * BREAK * HBREAK RECOVER ECHO (byte) ...; (string) ...; ((byte)("string")) ...