[ViewVC] Annotation of: cebix/mon/README


  mon, Version 3.0
  A command-line file manipulation tool and disassembler

  Copyright (C) 1997-2000 Christian Bauer, Marc Hellwig
  GNU binutils disassemblers Copyright (C) 1988, 89, 91, 93, 94, 95, 96, 97, 1998
    Free Software Foundation, Inc.


License
-------

mon 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 <trossi@jyu.fi>. 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, 6502 and 8080 disassemblers. By default, mon operates
on a fixed-size (but adjustable) memory buffer with adresses starting at 0.


Installation
------------

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).

Options:
  -m  enables symbolic MacOS A-Trap and low memory globals display in the
      680x0 disassembler
  -r  makes mon operate in real (virtual) memory space instead of an allocated
      buffer

If no additional command line arguments are given, mon enters interactive
mode. Otherwise, all remaining arguments are interpreted and executed as mon
commands.

The default buffer size is 1MB.

The mon command prompt looks like this:

  [00000000]->

The number in brackets is the value of "." (the "current address", see the
section on expressions). You can get a short command overview by entering
"h".

Commands that create a longer output can be interrupted with Ctrl-C.

To quit mon, enter the command "x".


Constants, variables and expressions
------------------------------------

The default number base is hexadecimal. Decimal numbers must be prefixed with
"_". Hexadecimal numbers may also be prefixed with "$" for clarity. Numbers
can also be entered as ASCII characters enclosed in single quotes (e.g. 'BAPP'
is the same as $42415050). All numbers are 32-bit values (one word).

With the "set" command, variables can be defined that hold 32-bit integer
values. A variable is referred to by its name. Variable names may be arbitrary
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:

  ~   complement
  +   unary plus
  -   unary minus
  *   multiplication
  /   integer division
  %   modulo
  +   addition
  -   subtraction
  <<  shift left
  >>  shift right
  &   bitwise AND
  ^   bitwise exclusive OR
  |   bitwise inclusive OR

Parentheses may be used to change the evaluation order of sub-expressions.

There are two special symbols that can be used in expressions:

  .   represents the "current address" (the value of "." is also displayed in
      the command prompt). What exactly the current address is, depends on the
      command last executed. The display commands set "." to the address after
      the last address displayed, the "hunt" commands sets "." to the address
      of the first found occurence of the search string, etc.
  :   is used by the "apply" ("y") command and holds the value of the byte/
      half-word/word at the current address.

The "modify" (":"), "fill" ("f") and "hunt" ("h") commands require you to
specify a byte string. Byte strings consist of an arbitrary number of byte
values and ASCII strings separated by commas. Examples:

  "string"
  12,34,56,78,9a,bc,de,f0
  "this",0a,"is a string",0a,"with","newlines",_10


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).

The buffer is the working area of mon where you load files into, manipulate
them, and write files back from. Arbitraty portions of the buffer may be used
as scratch space.


Commands
--------

The following commands are available in mon ('[]' marks a parameter than can be
left out):


  x                        Quit mon

quits mon and returns to the shell.


  h                        Show help text

displays a short overview of commands.


  ??                       Show list of commands

displays a short list of available commands.


  ver                      Show version

shows the version number of mon.


  ? expression             Calculate expression

displays the value of the given expression in hex, decimal, and ASCII
characters. If the value is negative, it is displayed as a signed and unsigned
number.


  @ [size]                 Reallocate buffer

changes the size of the buffer to the given number of bytes while preserving
the contents of the buffer. If the "size" argument is omitted, the current
buffer size is displayed.


  i [start [end]]          ASCII memory dump

displays the buffer contents from address "start" to address "end" as ASCII
characters. Entering "i" without arguments is equivalent to "i .". The value
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
words and ASCII characters. Entering "m" without arguments is equivalent to
"m .". The value of "." is set to the address after the last address displayed.


  d [start [end]]          Disassemble PowerPC code

disassembles the buffer contents from address "start" to address "end".
Entering "d" without arguments is equivalent to "d .". The value of "." is
set to the address after the last address displayed.


  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

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

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 (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.


  : start string           Modify memory

puts the specified byte string at the address "start" into the buffer. The
value of "." is set to the address after the last address modified.


  f start end string       Fill memory

fill the buffer in the range from "start" to (and including) "end" with the
given byte string.


  y[b|h|w] start end expr  Apply expression to memory

works like the "fill" ("f") command, but it doesn't fill with a byte string
but with the value of an expression that is re-evaluated for each buffer
location to be filled. The command comes in three flavors: "y"/"yb" works on
bytes (8-bit), "yh" on half-words (16-bit) and "yw" on words (32-bit). The
value of "." is the current address to be modified,  the value of ":" holds
the contents of this address before modification.

Examples:
  yw 0 fff :<<8    shifts all words in the address range 0..fff to the left
                   by 8 bits (you can use this to convert bitmap data from
                   ARGB to RGBA format, for example)
  y 0 1234 ~:      inverts all bytes in the address range 0..1234
  yh 2 ff 20000/.  creates a table of the fractional parts of the reciprocals
                   of 1..7f


  t start end dest         Transfer memory

transfers the buffer contents from "start" to (and including) "end" to "dest".
Source and destination may overlap.


  c start end dest         Compare memory

compares the buffer contents in the range from "start" to (and including)
"end" with the contents at "dest". The addresses of all different bytes and
the total number of differences (decimal) are printed.


  h start end string       Search for byte string

searches for the given byte string in the buffer starting at "start" up to
(and including) "end". The addresses and the total number of occurrences are
displayed. The value of "." is set to the address of the first occurrence. 


  \ "command"              Execute shell command

executes the given shell command which must be enclosed in quotes.


  ls [args]                List directory contents

works as the shell command "ls".


  rm [args]                Remove file(s)

works as the shell command "rm".


  cp [args]                Copy file(s)

works as the shell command "cp".


  mv [args]                Move file(s)

works as the shell command "mv".


  cd directory             Change current directory

works as the shell command "cd". The name of the directory doesn't have to be
enclosed in quotes.


  o ["file"]               Redirect output

When a file name is specified, all following output is redirected to this
file. The file name must be enclosed in quotation marks even if it contains
no spaces. Entering "o" without parameters closes the file and directs the
output into the terminal window again.


  [ start "file"           Load data from file

loads the contents of the specified file into the buffer starting from address
"start". The file name must be enclosed in quotation marks even if it contains
no spaces. The value of "." is set to the address after the last address
affected by the load.


  ] start size "file"      Save data to file

writes "size" number of bytes of the buffer from "start" to the specified file.
The file name must be enclosed in quotation marks even if it contains no spaces.


  set [var[=value]]        Set/clear/show variables

If no arguments are given, all currently defined variables are displayed.
Otherwise, the value of "var" is set to the specified value. If "=value"
is omitted, the variable "var" is cleared.


  cv                       Clear all variables

clears all currently defined variables.


Examples
--------

Here are some simple examples for what is possible with mon.

Join "file1" and "file2" to "file3":

  [ 0 "file1"
  [ . "file2"
  ] 0 . "file3"

Remove the first 24 bytes (e.g. an unneeded header) of a file:

  [ 0 "file"
  ] 18 .-18 "file"

Load the mon executable and search for PowerPC "nop" commands:

  [ 0 "mon"
  h 0 . 60,00,00,00

Create a modified version of mon so that the prompt has " $" instead of "->":

  [ 0 "mon"
  set size=.
  h 0 . "->"
  : . " $"
  ] 0 size "mon1"

Convert a binary file which contains 16-bit numbers in little-endian format
to big-endian format (or vice-versa):

  [ 0 "file"
  yh 0 .-1 :>>8|:<<8  
  ] 0 . "file"

Load a BeBox boot ROM image and start disassembling the system reset handler:

  [ 0 "bootnub.image"
  d 100


History
-------

Please consult the file "ChangeLog" for the release history.


Christian Bauer
<Christian.Bauer@uni-mainz.de>

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