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, 3 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

# Content
1
2 cxmon, Version 3.2
3 A command-line file manipulation tool and disassembler
4
5 Copyright (C) 1997-2007 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 www.cebix.net
435
436 Marc Hellwig
437 <Marc.Hellwig@uni-mainz.de>