[ViewVC] Annotation of: cebix/mon/README


  mon, Version 3.0
  A command-driven file monitor

  Copyright (C) 1997-2000 Christian Bauer, Marc Hellwig
  GNU binutils disassemblers (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 is not intended
to be used for debugging. It doesn't operate on physical or virtual RAM
locations of a process but rather on a fixed-size (but adjustable) buffer with
adresses starting at 0. Also, there are no commands to trace code, set
breakpoints etc. There are, however, built-in PowerPC, 680x0, 80x86, 6502 and
8080 disassemblers.


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). If you give no command
line arguments, mon enters interactive mode. Otherwise, all 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 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.


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


rmon
----

When mon is started as "rmon", it enters "real mode". That is, all memory
related functions no longer operate on the buffer but on "real" (virtual)
memory. Unless you are writing Mac emulators, this is probably of not much
use. :-)


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