ViewVC Help
View File | Revision Log | Show Annotations | Revision Graph | Root Listing
root/cebix/mon/README
Revision: 1.14
Committed: 2007-01-14T14:03:42Z (17 years, 9 months ago) by cebix
Branch: MAIN
CVS Tags: release_3-2, HEAD
Changes since 1.13: +3 -3 lines
Log Message:
prepare for 3.2

File Contents

# User Rev Content
1 cebix 1.1
2 cebix 1.14 cxmon, Version 3.2
3 cebix 1.7 A command-line file manipulation tool and disassembler
4 cebix 1.1
5 cebix 1.14 Copyright (C) 1997-2007 Christian Bauer, Marc Hellwig
6 cebix 1.5 GNU binutils disassemblers Copyright (C) 1988, 89, 91, 93, 94, 95, 96, 97, 1998
7 cebix 1.4 Free Software Foundation, Inc.
8 cebix 1.1
9    
10 cebix 1.2 License
11     -------
12    
13 cebix 1.8 cxmon is available under the terms of the GNU General Public License. See the
14 cebix 1.2 file "COPYING" that is included in the distribution for details.
15    
16    
17 cebix 1.1 Overview
18     --------
19    
20 cebix 1.8 cxmon is an interactive command-driven file manipulation tool that is
21 cebix 1.10 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 cebix 1.12 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 cebix 1.1
28    
29     Installation
30     ------------
31    
32 cebix 1.2 Please consult the file "INSTALL" for installation instructions.
33 cebix 1.1
34    
35     Usage
36     -----
37    
38 cebix 1.8 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 cebix 1.5
41     Options:
42     -m enables symbolic MacOS A-Trap and low memory globals display in the
43     680x0 disassembler
44 cebix 1.8 -r makes cxmon operate in real (virtual) memory space instead of an
45     allocated buffer
46 cebix 1.5
47 cebix 1.8 If no additional command line arguments are given, cxmon enters interactive
48     mode. Otherwise, all remaining arguments are interpreted and executed as cxmon
49 cebix 1.5 commands.
50    
51     The default buffer size is 1MB.
52    
53 cebix 1.8 The cxmon command prompt looks like this:
54 cebix 1.1
55     [00000000]->
56    
57     The number in brackets is the value of "." (the "current address", see the
58     section on expressions). You can get a short command overview by entering
59     "h".
60    
61     Commands that create a longer output can be interrupted with Ctrl-C.
62    
63 cebix 1.8 To quit cxmon, enter the command "x".
64 cebix 1.1
65    
66     Constants, variables and expressions
67     ------------------------------------
68    
69     The default number base is hexadecimal. Decimal numbers must be prefixed with
70     "_". Hexadecimal numbers may also be prefixed with "$" for clarity. Numbers
71     can also be entered as ASCII characters enclosed in single quotes (e.g. 'BAPP'
72     is the same as $42415050). All numbers are 32-bit values (one word).
73    
74     With the "set" command, variables can be defined that hold 32-bit integer
75     values. A variable is referred to by its name. Variable names may be arbitrary
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 cebix 1.8 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 cebix 1.1
83     ~ complement
84     + unary plus
85     - unary minus
86     * multiplication
87     / integer division
88     % modulo
89     + addition
90     - subtraction
91     << shift left
92     >> shift right
93     & bitwise AND
94     ^ bitwise exclusive OR
95     | bitwise inclusive OR
96    
97     Parentheses may be used to change the evaluation order of sub-expressions.
98    
99     There are two special symbols that can be used in expressions:
100    
101     . represents the "current address" (the value of "." is also displayed in
102     the command prompt). What exactly the current address is, depends on the
103     command last executed. The display commands set "." to the address after
104     the last address displayed, the "hunt" commands sets "." to the address
105     of the first found occurence of the search string, etc.
106     : is used by the "apply" ("y") command and holds the value of the byte/
107     half-word/word at the current address.
108    
109     The "modify" (":"), "fill" ("f") and "hunt" ("h") commands require you to
110     specify a byte string. Byte strings consist of an arbitrary number of byte
111     values and ASCII strings separated by commas. Examples:
112    
113     "string"
114     12,34,56,78,9a,bc,de,f0
115     "this",0a,"is a string",0a,"with","newlines",_10
116    
117    
118     The buffer
119     ----------
120    
121 cebix 1.8 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 cebix 1.1
128 cebix 1.8 The buffer is the working area of cxmon where you load files into, manipulate
129 cebix 1.1 them, and write files back from. Arbitraty portions of the buffer may be used
130     as scratch space.
131    
132    
133     Commands
134     --------
135    
136 cebix 1.8 The following commands are available in cxmon ('[]' marks a parameter than
137     can be left out):
138 cebix 1.1
139    
140 cebix 1.8 x Quit cxmon
141 cebix 1.1
142 cebix 1.8 quits cxmon and returns to the shell.
143 cebix 1.1
144    
145     h Show help text
146    
147     displays a short overview of commands.
148    
149    
150     ?? Show list of commands
151    
152     displays a short list of available commands.
153    
154    
155     ver Show version
156    
157 cebix 1.8 shows the version number of cxmon.
158 cebix 1.1
159    
160     ? expression Calculate expression
161    
162     displays the value of the given expression in hex, decimal, and ASCII
163     characters. If the value is negative, it is displayed as a signed and unsigned
164     number.
165    
166    
167     @ [size] Reallocate buffer
168    
169     changes the size of the buffer to the given number of bytes while preserving
170     the contents of the buffer. If the "size" argument is omitted, the current
171     buffer size is displayed.
172    
173    
174     i [start [end]] ASCII memory dump
175    
176     displays the buffer contents from address "start" to address "end" as ASCII
177     characters. Entering "i" without arguments is equivalent to "i .". The value
178     of "." is set to the address after the last address displayed.
179    
180    
181 cebix 1.3 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 cebix 1.1 m [start [end]] Hex/ASCII memory dump
189    
190     displays the buffer contents from address "start" to address "end" as hex
191     words and ASCII characters. Entering "m" without arguments is equivalent to
192     "m .". The value of "." is set to the address after the last address displayed.
193    
194    
195     d [start [end]] Disassemble PowerPC code
196    
197     disassembles the buffer contents from address "start" to address "end".
198     Entering "d" without arguments is equivalent to "d .". The value of "." is
199     set to the address after the last address displayed.
200    
201    
202 cebix 1.4 d65 [start [end]] Disassemble 6502 code
203 cebix 1.1
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 cebix 1.4 d68 [start [end]] Disassemble 680x0 code
210 cebix 1.1
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 cebix 1.8 d80 [start [end]] Disassemble Z80 code
217 cebix 1.1
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 cebix 1.6 d86 [start [end]] Disassemble 80x86 (32-bit) code
224 cebix 1.1
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 cebix 1.6
229    
230     d8086 [start [end]] Disassemble 80x86 (16-bit) code
231 cebix 1.12
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 cebix 1.6
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 cebix 1.1
243    
244     : start string Modify memory
245    
246     puts the specified byte string at the address "start" into the buffer. The
247     value of "." is set to the address after the last address modified.
248    
249    
250     f start end string Fill memory
251    
252     fill the buffer in the range from "start" to (and including) "end" with the
253     given byte string.
254    
255    
256     y[b|h|w] start end expr Apply expression to memory
257    
258     works like the "fill" ("f") command, but it doesn't fill with a byte string
259     but with the value of an expression that is re-evaluated for each buffer
260     location to be filled. The command comes in three flavors: "y"/"yb" works on
261     bytes (8-bit), "yh" on half-words (16-bit) and "yw" on words (32-bit). The
262     value of "." is the current address to be modified, the value of ":" holds
263     the contents of this address before modification.
264    
265     Examples:
266     yw 0 fff :<<8 shifts all words in the address range 0..fff to the left
267     by 8 bits (you can use this to convert bitmap data from
268     ARGB to RGBA format, for example)
269     y 0 1234 ~: inverts all bytes in the address range 0..1234
270     yh 2 ff 20000/. creates a table of the fractional parts of the reciprocals
271     of 1..7f
272    
273    
274     t start end dest Transfer memory
275    
276     transfers the buffer contents from "start" to (and including) "end" to "dest".
277     Source and destination may overlap.
278    
279    
280     c start end dest Compare memory
281    
282     compares the buffer contents in the range from "start" to (and including)
283     "end" with the contents at "dest". The addresses of all different bytes and
284     the total number of differences (decimal) are printed.
285    
286    
287     h start end string Search for byte string
288    
289     searches for the given byte string in the buffer starting at "start" up to
290     (and including) "end". The addresses and the total number of occurrences are
291     displayed. The value of "." is set to the address of the first occurrence.
292    
293    
294     \ "command" Execute shell command
295    
296     executes the given shell command which must be enclosed in quotes.
297    
298    
299     ls [args] List directory contents
300    
301     works as the shell command "ls".
302    
303    
304     rm [args] Remove file(s)
305    
306     works as the shell command "rm".
307    
308    
309     cp [args] Copy file(s)
310    
311     works as the shell command "cp".
312    
313    
314     mv [args] Move file(s)
315    
316     works as the shell command "mv".
317    
318    
319     cd directory Change current directory
320    
321     works as the shell command "cd". The name of the directory doesn't have to be
322     enclosed in quotes.
323    
324    
325     o ["file"] Redirect output
326    
327     When a file name is specified, all following output is redirected to this
328     file. The file name must be enclosed in quotation marks even if it contains
329     no spaces. Entering "o" without parameters closes the file and directs the
330     output into the terminal window again.
331    
332    
333     [ start "file" Load data from file
334    
335     loads the contents of the specified file into the buffer starting from address
336     "start". The file name must be enclosed in quotation marks even if it contains
337     no spaces. The value of "." is set to the address after the last address
338     affected by the load.
339    
340    
341     ] start size "file" Save data to file
342    
343     writes "size" number of bytes of the buffer from "start" to the specified file.
344     The file name must be enclosed in quotation marks even if it contains no spaces.
345    
346    
347     set [var[=value]] Set/clear/show variables
348    
349     If no arguments are given, all currently defined variables are displayed.
350     Otherwise, the value of "var" is set to the specified value. If "=value"
351     is omitted, the variable "var" is cleared.
352    
353    
354     cv Clear all variables
355    
356     clears all currently defined variables.
357    
358    
359     Examples
360     --------
361    
362 cebix 1.8 Here are some simple examples for what is possible with cxmon.
363 cebix 1.1
364     Join "file1" and "file2" to "file3":
365    
366     [ 0 "file1"
367     [ . "file2"
368     ] 0 . "file3"
369    
370     Remove the first 24 bytes (e.g. an unneeded header) of a file:
371    
372     [ 0 "file"
373     ] 18 .-18 "file"
374    
375 cebix 1.8 Load the cxmon executable and search for PowerPC "nop" commands:
376 cebix 1.1
377 cebix 1.8 [ 0 "cxmon"
378 cebix 1.1 h 0 . 60,00,00,00
379    
380 cebix 1.8 Create a modified version of cxmon so that the prompt has " $" instead of
381     "->":
382 cebix 1.1
383 cebix 1.8 [ 0 "cxmon"
384 cebix 1.1 set size=.
385     h 0 . "->"
386     : . " $"
387 cebix 1.8 ] 0 size "cxmon1"
388 cebix 1.1
389     Convert a binary file which contains 16-bit numbers in little-endian format
390     to big-endian format (or vice-versa):
391    
392     [ 0 "file"
393     yh 0 .-1 :>>8|:<<8
394     ] 0 . "file"
395    
396     Load a BeBox boot ROM image and start disassembling the system reset handler:
397    
398     [ 0 "bootnub.image"
399     d 100
400    
401    
402 cebix 1.9 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 cebix 1.1 History
428     -------
429    
430 cebix 1.2 Please consult the file "ChangeLog" for the release history.
431 cebix 1.1
432    
433     Christian Bauer
434 cebix 1.14 www.cebix.net
435 cebix 1.1
436     Marc Hellwig
437 cebix 1.2 <Marc.Hellwig@uni-mainz.de>