[ViewVC] Annotation of: cebix/mon/README


        mon, Version 2.2
        A command-driven file monitor

        Copyright (C) 1997-1999 Christian Bauer, Marc Hellwig
        Freely distributable


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, 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 (very incomplete)

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