ViewVC Help
View File | Revision Log | Show Annotations | Revision Graph | Root Listing
root/cebix/mon/README
(Generate patch)

Comparing mon/README (file contents):
Revision 1.2 by cebix, 1999-10-04T19:40:36Z vs.
Revision 1.12 by cebix, 2003-09-27T20:22:55Z

# Line 1 | Line 1
1  
2 <        mon, Version 2.2
3 <        A command-driven file monitor
2 >  cxmon, Version 3.1
3 >  A command-line file manipulation tool and disassembler
4  
5 <        Copyright (C) 1997-1999 Christian Bauer, Marc Hellwig
6 <        Freely distributable
5 >  Copyright (C) 1997-2003 Christian Bauer, Marc Hellwig
6 >  GNU binutils disassemblers Copyright (C) 1988, 89, 91, 93, 94, 95, 96, 97, 1998
7 >    Free Software Foundation, Inc.
8  
9  
10   License
11   -------
12  
13 < mon is available under the terms of the GNU General Public License. See the
13 > cxmon is available under the terms of the GNU General Public License. See the
14   file "COPYING" that is included in the distribution for details.
15  
16  
17   Overview
18   --------
19  
20 < "mon" is an interactive command-driven file manipulation tool that is inspired
21 < by the "Amiga Monitor" by Timo Rossi <trossi@jyu.fi>. It has commands and
22 < features similar to a machine code monitor/debugger, but it is not intended
23 < to be used for debugging. It doesn't operate on physical or virtual RAM
24 < locations of a process but rather on a fixed-size (but adjustable) buffer with
25 < adresses starting at 0. Also, there are no commands to trace code, set
26 < breakpoints etc. There are, however, built-in PowerPC, 680x0, 6502 and 8080
26 < disassemblers.
20 > cxmon is an interactive command-driven file manipulation tool that is
21 > inspired by the "Amiga Monitor" by Timo Rossi. It has commands and features
22 > similar to a machine code monitor/debugger, but it lacks any functions for
23 > running/tracing code. There are, however, built-in PowerPC, 680x0, 80x86,
24 > x86-64, 6502 and Z80 disassemblers and special support for disassembling
25 > MacOS code. By default, cxmon operates on a fixed-size (but adjustable)
26 > memory buffer with adresses starting at 0.
27  
28  
29   Installation
# Line 35 | Line 35 | Please consult the file "INSTALL" for in
35   Usage
36   -----
37  
38 < mon can be started from the Shell or from the Tracker (BeOS), but command line
39 < history doesn't work when started from the Tracker). If you give no command
40 < line arguments, mon enters interactive mode. Otherwise, all arguments are
41 < interpreted and executed as mon commands. The default buffer size is 1MB.
42 < The mon command prompt looks like this:
38 > cxmon can be started from the Shell or from the Tracker (BeOS), but command
39 > line history doesn't work when started from the Tracker.
40 >
41 > Options:
42 >  -m  enables symbolic MacOS A-Trap and low memory globals display in the
43 >      680x0 disassembler
44 >  -r  makes cxmon operate in real (virtual) memory space instead of an
45 >      allocated buffer
46 >
47 > If no additional command line arguments are given, cxmon enters interactive
48 > mode. Otherwise, all remaining arguments are interpreted and executed as cxmon
49 > commands.
50 >
51 > The default buffer size is 1MB.
52 >
53 > The cxmon command prompt looks like this:
54  
55    [00000000]->
56  
# Line 49 | Line 60 | section on expressions). You can get a s
60  
61   Commands that create a longer output can be interrupted with Ctrl-C.
62  
63 < To quit mon, enter the command "x".
63 > To quit cxmon, enter the command "x".
64  
65  
66   Constants, variables and expressions
# Line 65 | Line 76 | values. A variable is referred to by its
76   combinations of digits and letters (they may also start with a digit) that
77   are not also valid hexadecimal numbers. Names are case-sensitive.
78  
79 < mon accepts expressions in all places where you have to specify a number. The
80 < following operators are available and have the same meaning and precedence as
81 < in the C programming language:
79 > cxmon accepts expressions in all places where you have to specify a number.
80 > The following operators are available and have the same meaning and
81 > precedence as in the C programming language:
82  
83    ~   complement
84    +   unary plus
# Line 107 | Line 118 | values and ASCII strings separated by co
118   The buffer
119   ----------
120  
121 < Those mon commands that operate on "memory" operate on a buffer allocated by
122 < mon whose size is adjustable with the "@" command. The default buffer size is
123 < 1MB. The buffer is an array of bytes where each byte has a 32-bit integer
124 < address. Addresses start at 0 and are taken modulo the buffer size (i.e. for
125 < the default 1MB buffer, addresses 0 and 100000 refer to the same byte).
121 > Those cxmon commands that operate on "memory" operate on a buffer allocated
122 > by cxmon whose size is adjustable with the "@" command. The default buffer
123 > size is 1MB. The buffer is an array of bytes where each byte has a 32-bit
124 > integer address. Addresses start at 0 and are taken modulo the buffer size
125 > (i.e. for the default 1MB buffer, addresses 0 and 100000 refer to the same
126 > byte).
127  
128 < The buffer is the working area of mon where you load files into, manipulate
128 > The buffer is the working area of cxmon where you load files into, manipulate
129   them, and write files back from. Arbitraty portions of the buffer may be used
130   as scratch space.
131  
# Line 121 | Line 133 | as scratch space.
133   Commands
134   --------
135  
136 < The following commands are available in mon ('[]' marks a parameter than can be
137 < left out):
136 > The following commands are available in cxmon ('[]' marks a parameter than
137 > can be left out):
138  
139  
140 <  x                        Quit mon
140 >  x                        Quit cxmon
141  
142 < quits mon and returns to the shell.
142 > quits cxmon and returns to the shell.
143  
144  
145    h                        Show help text
# Line 142 | Line 154 | displays a short list of available comma
154  
155    ver                      Show version
156  
157 < shows the version number of mon.
157 > shows the version number of cxmon.
158  
159  
160    ? expression             Calculate expression
# Line 166 | Line 178 | characters. Entering "i" without argumen
178   of "." is set to the address after the last address displayed.
179  
180  
181 +  b [start [end]]          Binary memory dump
182 +
183 + displays the buffer contents from address "start" to address "end" in a binary
184 + format. Entering "b" without arguments is equivalent to "b .". The value of
185 + "." is set to the address after the last address displayed.
186 +
187 +
188    m [start [end]]          Hex/ASCII memory dump
189  
190   displays the buffer contents from address "start" to address "end" as hex
# Line 180 | Line 199 | Entering "d" without arguments is equiva
199   set to the address after the last address displayed.
200  
201  
202 <  d65 [start [end]]          Disassemble 6502 code
202 >  d65 [start [end]]        Disassemble 6502 code
203  
204   disassembles the buffer contents from address "start" to address "end".
205   Entering "d65" without arguments is equivalent to "d65 .". The value of
206   "." is set to the address after the last address displayed.
207  
208  
209 <  d68 [start [end]]          Disassemble 680x0 code
209 >  d68 [start [end]]        Disassemble 680x0 code
210  
211   disassembles the buffer contents from address "start" to address "end".
212   Entering "d68" without arguments is equivalent to "d68 .". The value of
213   "." is set to the address after the last address displayed.
214  
215  
216 <  d80 [start [end]]          Disassemble 8080 code
216 >  d80 [start [end]]        Disassemble Z80 code
217  
218   disassembles the buffer contents from address "start" to address "end".
219   Entering "d80" without arguments is equivalent to "d80 .". The value of
220   "." is set to the address after the last address displayed.
221  
222  
223 <  d86 [start [end]]          Disassemble 80x86 code (very incomplete)
223 >  d86 [start [end]]        Disassemble 80x86 (32-bit) code
224  
225   disassembles the buffer contents from address "start" to address "end".
226   Entering "d86" without arguments is equivalent to "d86 .". The value of
227   "." is set to the address after the last address displayed.
228  
229  
230 +  d8086 [start [end]]      Disassemble 80x86 (16-bit) code
231 +
232 + disassembles the buffer contents from address "start" to address "end".
233 + Entering "d8086" without arguments is equivalent to "d8086 .". The value
234 + of "." is set to the address after the last address displayed.
235 +
236 +
237 +  d8664 [start [end]]      Disassemble x86-64 code
238 +
239 + disassembles the buffer contents from address "start" to address "end".
240 + Entering "d8086" without arguments is equivalent to "d8086 .". The value
241 + of "." is set to the address after the last address displayed.
242 +
243 +
244    : start string           Modify memory
245  
246   puts the specified byte string at the address "start" into the buffer. The
# Line 323 | Line 356 | is omitted, the variable "var" is cleare
356   clears all currently defined variables.
357  
358  
326 rmon
327 ----
328
329 When mon is started as "rmon", it enters "real mode". That is, all memory
330 related functions no longer operate on the buffer but on "real" (virtual)
331 memory. Unless you are writing Mac emulators, this is probably of not much
332 use. :-)
333
334
359   Examples
360   --------
361  
362 < Here are some simple examples for what is possible with mon.
362 > Here are some simple examples for what is possible with cxmon.
363  
364   Join "file1" and "file2" to "file3":
365  
# Line 348 | Line 372 | Remove the first 24 bytes (e.g. an unnee
372    [ 0 "file"
373    ] 18 .-18 "file"
374  
375 < Load the mon executable and search for PowerPC "nop" commands:
375 > Load the cxmon executable and search for PowerPC "nop" commands:
376  
377 <  [ 0 "mon"
377 >  [ 0 "cxmon"
378    h 0 . 60,00,00,00
379  
380 < Create a modified version of mon so that the prompt has " $" instead of "->":
380 > Create a modified version of cxmon so that the prompt has " $" instead of
381 > "->":
382  
383 <  [ 0 "mon"
383 >  [ 0 "cxmon"
384    set size=.
385    h 0 . "->"
386    : . " $"
387 <  ] 0 size "mon1"
387 >  ] 0 size "cxmon1"
388  
389   Convert a binary file which contains 16-bit numbers in little-endian format
390   to big-endian format (or vice-versa):
# Line 374 | Line 399 | Load a BeBox boot ROM image and start di
399    d 100
400  
401  
402 + Using cxmon in your own programs
403 + --------------------------------
404 +
405 + cxmon provides a simple interface for integration in other programs. It can,
406 + for example, be used as a monitor/debugger for an emulator (it is used in
407 + Basilisk II in this way).
408 +
409 + Here's how to do it (all functions are defined in the mon.h header file):
410 +
411 + 1. Link all the cxmon object files, except main.o, to your program.
412 + 2. In your program, call mon_init() before using any other cxmon functions.
413 + 3. After calling mon_init(), set the mon_read_byte and mon_write_byte
414 +    function pointers to the routines used for accessing memory.
415 + 4. You can use mon_add_command() to add new commands to cxmon by specifying
416 +    the command name, function and help text. From within your command
417 +    function, you can use mon_get_token() and mon_expression() to parse the
418 +    arguments and the mon_read/write_*() functions to access memory.
419 + 5. To enter cxmon, call the mon() function like this:
420 +
421 +      char *args[3] = {"mon", "-r", NULL};
422 +      mon(2, args);
423 +
424 + 6. If you're done with cxmon, call mon_exit().
425 +
426 +
427   History
428   -------
429  

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines