1 |
|
2 |
cxmon, Version 3.1 |
3 |
A command-line file manipulation tool and disassembler |
4 |
|
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 |
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 |
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 |
30 |
------------ |
31 |
|
32 |
Please consult the file "INSTALL" for installation instructions. |
33 |
|
34 |
|
35 |
Usage |
36 |
----- |
37 |
|
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 |
|
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 |
To quit cxmon, enter the command "x". |
64 |
|
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 |
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 |
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 |
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 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 |
|
132 |
|
133 |
Commands |
134 |
-------- |
135 |
|
136 |
The following commands are available in cxmon ('[]' marks a parameter than |
137 |
can be left out): |
138 |
|
139 |
|
140 |
x Quit cxmon |
141 |
|
142 |
quits cxmon and returns to the shell. |
143 |
|
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 |
shows the version number of cxmon. |
158 |
|
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 |
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 |
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 |
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 |
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 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 (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 |
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 |
Here are some simple examples for what is possible with cxmon. |
363 |
|
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 |
Load the cxmon executable and search for PowerPC "nop" commands: |
376 |
|
377 |
[ 0 "cxmon" |
378 |
h 0 . 60,00,00,00 |
379 |
|
380 |
Create a modified version of cxmon so that the prompt has " $" instead of |
381 |
"->": |
382 |
|
383 |
[ 0 "cxmon" |
384 |
set size=. |
385 |
h 0 . "->" |
386 |
: . " $" |
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): |
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 |
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 |
|
430 |
Please consult the file "ChangeLog" for the release history. |
431 |
|
432 |
|
433 |
Christian Bauer |
434 |
<Christian.Bauer@uni-mainz.de> |
435 |
|
436 |
Marc Hellwig |
437 |
<Marc.Hellwig@uni-mainz.de> |