--- mon/README 1999/10/04 19:31:09 1.1.1.1 +++ mon/README 2007/01/14 14:03:42 1.14 @@ -1,41 +1,56 @@ - mon, Version 2.2 - A command-driven file monitor + cxmon, Version 3.2 + A command-line file manipulation tool and disassembler - Copyright (C) 1997-1999 Christian Bauer, Marc Hellwig - Freely distributable + Copyright (C) 1997-2007 Christian Bauer, Marc Hellwig + GNU binutils disassemblers Copyright (C) 1988, 89, 91, 93, 94, 95, 96, 97, 1998 + Free Software Foundation, Inc. + + +License +------- + +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, 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 ------------ -There are precompiled binaries for BeOS included in the archive. mon doesn't -need any auxiliary files. - -To compile under Unix, cd to "src", edit "Makefile" and type "make". +Please consult the file "INSTALL" for installation instructions. 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]-> @@ -45,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 @@ -61,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 @@ -103,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. @@ -117,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 @@ -138,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 @@ -162,6 +178,13 @@ characters. Entering "i" without argumen of "." is set to the address after the last address displayed. + b [start [end]] Binary memory dump + +displays the buffer contents from address "start" to address "end" in a binary +format. Entering "b" without arguments is equivalent to "b .". The value of +"." is set to the address after the last address displayed. + + m [start [end]] Hex/ASCII memory dump displays the buffer contents from address "start" to address "end" as hex @@ -176,34 +199,48 @@ Entering "d" without arguments is equiva set to the address after the last address displayed. - d65 [start [end]] Disassemble 6502 code + d65 [start [end]] Disassemble 6502 code disassembles the buffer contents from address "start" to address "end". Entering "d65" without arguments is equivalent to "d65 .". The value of "." is set to the address after the last address displayed. - d68 [start [end]] Disassemble 680x0 code + d68 [start [end]] Disassemble 680x0 code disassembles the buffer contents from address "start" to address "end". Entering "d68" without arguments is equivalent to "d68 .". The value of "." 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 (very incomplete) + 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 @@ -319,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": @@ -344,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): @@ -370,37 +399,39 @@ Load a BeBox boot ROM image and start di d 100 -Legal stuff ------------ +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); -Copyright 1997-1999 Christian Bauer. This program is freeware. You may do -whatever you want with it for personal use. Permission is granted to -redistribute this program free of charge, provided it is distributed in the -full archive with unmodified contents and no profit beyond the price of the -media on which it is distributed is made. Exception to the last rule: It may -be included on freeware/shareware collections on CD-ROM. There are no -warranties of any kind for this program. If you use this program, you do so -at your own risk. The authors are not responsible for any damages that might -result from using this program. + 6. If you're done with cxmon, call mon_exit(). History ------- -V1.0 - Initial release -V1.3 - Now uses libreadline - Disassembler: prints SPR names instead of numbers, fixed bugs -V1.4 - Implemented 6502 and 680x0 disassemblers -V1.5 - Non-interactive mode, real mode -V2.0 - Unified PPC and x86 release -V2.1 - Compiled for BeOS R4, opens Terminal window when started from Tracker, - implemented 8080 disassembler, included Unix makefile -V2.2 - Switched from project files to makefiles on BeOS, fixed some minor - bugs in the PPC disassembler, commands made modular +Please consult the file "ChangeLog" for the release history. Christian Bauer - +www.cebix.net Marc Hellwig - +