[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


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

There are precompiled binaries for BeOS included in the archive. mon doesn't
need any auxiliary files.

To compile under Unix, cd to "src", edit "Makefile" and type "make".


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.


  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


Legal stuff
-----------

Copyright 1997-1999 Christian Bauer. This program is freeware. You may do
whatever you want with it for personal use. Permission is granted to
redistribute this program free of charge, provided it is distributed in the
full archive with unmodified contents and no profit  beyond the price of the
media on which it is distributed is made. Exception to the last rule: It may
be included on freeware/shareware collections on CD-ROM. There are no
warranties of any kind for this program. If you use this program, you do so
at your own risk. The authors are not responsible for any damages that might
result from using this program.


History
-------

V1.0 - Initial release
V1.3 - Now uses libreadline
       Disassembler: prints SPR names instead of numbers, fixed bugs
V1.4 - Implemented 6502 and 680x0 disassemblers
V1.5 - Non-interactive mode, real mode
V2.0 - Unified PPC and x86 release
V2.1 - Compiled for BeOS R4, opens Terminal window when started from Tracker,
       implemented 8080 disassembler, included Unix makefile
V2.2 - Switched from project files to makefiles on BeOS, fixed some minor
       bugs in the PPC disassembler, commands made modular


Christian Bauer
<cbauer@iphcip1.physik.uni-mainz.de>

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