--- mon/README 2000/09/25 12:44:30 1.4 +++ mon/README 2004/02/12 17:18:02 1.13 @@ -1,30 +1,29 @@ - mon, Version 3.0 - A command-driven file monitor + cxmon, Version 3.1 + A command-line file manipulation tool and disassembler - Copyright (C) 1997-2000 Christian Bauer, Marc Hellwig - GNU binutils disassemblers (C) 1988, 89, 91, 93, 94, 95, 96, 97, 1998 + Copyright (C) 1997-2004 Christian Bauer, Marc Hellwig + GNU binutils disassemblers Copyright (C) 1988, 89, 91, 93, 94, 95, 96, 97, 1998 Free Software Foundation, Inc. License ------- -mon is available under the terms of the GNU General Public License. See the +cxmon is available under the terms of the GNU General Public License. See the file "COPYING" that is included in the distribution for details. Overview -------- -"mon" is an interactive command-driven file manipulation tool that is inspired -by the "Amiga Monitor" by Timo Rossi . It has commands and -features similar to a machine code monitor/debugger, but it is not intended -to be used for debugging. It doesn't operate on physical or virtual RAM -locations of a process but rather on a fixed-size (but adjustable) buffer with -adresses starting at 0. Also, there are no commands to trace code, set -breakpoints etc. There are, however, built-in PowerPC, 680x0, 80x86, 6502 and -8080 disassemblers. +cxmon is an interactive command-driven file manipulation tool that is +inspired by the "Amiga Monitor" by Timo Rossi. It has commands and features +similar to a machine code monitor/debugger, but it lacks any functions for +running/tracing code. There are, however, built-in PowerPC, 680x0, 80x86, +x86-64, 6502 and Z80 disassemblers and special support for disassembling +MacOS code. By default, cxmon operates on a fixed-size (but adjustable) +memory buffer with adresses starting at 0. Installation @@ -36,11 +35,22 @@ Please consult the file "INSTALL" for in Usage ----- -mon can be started from the Shell or from the Tracker (BeOS), but command line -history doesn't work when started from the Tracker). If you give no command -line arguments, mon enters interactive mode. Otherwise, all arguments are -interpreted and executed as mon commands. The default buffer size is 1MB. -The mon command prompt looks like this: +cxmon can be started from the Shell or from the Tracker (BeOS), but command +line history doesn't work when started from the Tracker. + +Options: + -m enables symbolic MacOS A-Trap and low memory globals display in the + 680x0 disassembler + -r makes cxmon operate in real (virtual) memory space instead of an + allocated buffer + +If no additional command line arguments are given, cxmon enters interactive +mode. Otherwise, all remaining arguments are interpreted and executed as cxmon +commands. + +The default buffer size is 1MB. + +The cxmon command prompt looks like this: [00000000]-> @@ -50,7 +60,7 @@ section on expressions). You can get a s Commands that create a longer output can be interrupted with Ctrl-C. -To quit mon, enter the command "x". +To quit cxmon, enter the command "x". Constants, variables and expressions @@ -66,9 +76,9 @@ values. A variable is referred to by its combinations of digits and letters (they may also start with a digit) that are not also valid hexadecimal numbers. Names are case-sensitive. -mon accepts expressions in all places where you have to specify a number. The -following operators are available and have the same meaning and precedence as -in the C programming language: +cxmon accepts expressions in all places where you have to specify a number. +The following operators are available and have the same meaning and +precedence as in the C programming language: ~ complement + unary plus @@ -108,13 +118,14 @@ values and ASCII strings separated by co The buffer ---------- -Those mon commands that operate on "memory" operate on a buffer allocated by -mon whose size is adjustable with the "@" command. The default buffer size is -1MB. The buffer is an array of bytes where each byte has a 32-bit integer -address. Addresses start at 0 and are taken modulo the buffer size (i.e. for -the default 1MB buffer, addresses 0 and 100000 refer to the same byte). +Those cxmon commands that operate on "memory" operate on a buffer allocated +by cxmon whose size is adjustable with the "@" command. The default buffer +size is 1MB. The buffer is an array of bytes where each byte has a 32-bit +integer address. Addresses start at 0 and are taken modulo the buffer size +(i.e. for the default 1MB buffer, addresses 0 and 100000 refer to the same +byte). -The buffer is the working area of mon where you load files into, manipulate +The buffer is the working area of cxmon where you load files into, manipulate them, and write files back from. Arbitraty portions of the buffer may be used as scratch space. @@ -122,13 +133,13 @@ as scratch space. Commands -------- -The following commands are available in mon ('[]' marks a parameter than can be -left out): +The following commands are available in cxmon ('[]' marks a parameter than +can be left out): - x Quit mon + x Quit cxmon -quits mon and returns to the shell. +quits cxmon and returns to the shell. h Show help text @@ -143,7 +154,7 @@ displays a short list of available comma ver Show version -shows the version number of mon. +shows the version number of cxmon. ? expression Calculate expression @@ -202,20 +213,34 @@ Entering "d68" without arguments is equi "." is set to the address after the last address displayed. - d80 [start [end]] Disassemble 8080 code + d80 [start [end]] Disassemble Z80 code disassembles the buffer contents from address "start" to address "end". Entering "d80" without arguments is equivalent to "d80 .". The value of "." is set to the address after the last address displayed. - d86 [start [end]] Disassemble 80x86 code + d86 [start [end]] Disassemble 80x86 (32-bit) code disassembles the buffer contents from address "start" to address "end". Entering "d86" without arguments is equivalent to "d86 .". The value of "." is set to the address after the last address displayed. + d8086 [start [end]] Disassemble 80x86 (16-bit) code + +disassembles the buffer contents from address "start" to address "end". +Entering "d8086" without arguments is equivalent to "d8086 .". The value +of "." is set to the address after the last address displayed. + + + d8664 [start [end]] Disassemble x86-64 code + +disassembles the buffer contents from address "start" to address "end". +Entering "d8086" without arguments is equivalent to "d8086 .". The value +of "." is set to the address after the last address displayed. + + : start string Modify memory puts the specified byte string at the address "start" into the buffer. The @@ -331,19 +356,10 @@ is omitted, the variable "var" is cleare clears all currently defined variables. -rmon ----- - -When mon is started as "rmon", it enters "real mode". That is, all memory -related functions no longer operate on the buffer but on "real" (virtual) -memory. Unless you are writing Mac emulators, this is probably of not much -use. :-) - - Examples -------- -Here are some simple examples for what is possible with mon. +Here are some simple examples for what is possible with cxmon. Join "file1" and "file2" to "file3": @@ -356,18 +372,19 @@ Remove the first 24 bytes (e.g. an unnee [ 0 "file" ] 18 .-18 "file" -Load the mon executable and search for PowerPC "nop" commands: +Load the cxmon executable and search for PowerPC "nop" commands: - [ 0 "mon" + [ 0 "cxmon" h 0 . 60,00,00,00 -Create a modified version of mon so that the prompt has " $" instead of "->": +Create a modified version of cxmon so that the prompt has " $" instead of +"->": - [ 0 "mon" + [ 0 "cxmon" set size=. h 0 . "->" : . " $" - ] 0 size "mon1" + ] 0 size "cxmon1" Convert a binary file which contains 16-bit numbers in little-endian format to big-endian format (or vice-versa): @@ -382,6 +399,31 @@ Load a BeBox boot ROM image and start di d 100 +Using cxmon in your own programs +-------------------------------- + +cxmon provides a simple interface for integration in other programs. It can, +for example, be used as a monitor/debugger for an emulator (it is used in +Basilisk II in this way). + +Here's how to do it (all functions are defined in the mon.h header file): + + 1. Link all the cxmon object files, except main.o, to your program. + 2. In your program, call mon_init() before using any other cxmon functions. + 3. After calling mon_init(), set the mon_read_byte and mon_write_byte + function pointers to the routines used for accessing memory. + 4. You can use mon_add_command() to add new commands to cxmon by specifying + the command name, function and help text. From within your command + function, you can use mon_get_token() and mon_expression() to parse the + arguments and the mon_read/write_*() functions to access memory. + 5. To enter cxmon, call the mon() function like this: + + char *args[3] = {"mon", "-r", NULL}; + mon(2, args); + + 6. If you're done with cxmon, call mon_exit(). + + History -------