[ViewVC] Annotation of: cebix/mon/README


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

cxmon is available under the terms of the GNU General Public License. See the
file "COPYING" that is included in the distribution for details.


Overview
--------

cxmon 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 Z80 disassemblers. By default, cxmon operates
on a fixed-size (but adjustable) memory buffer with adresses starting at 0.


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

Please consult the file "INSTALL" for installation instructions.


Usage
-----

cxmon 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 cxmon operate in real (virtual) memory space instead of an
      allocated buffer

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

The default buffer size is 1MB.

The cxmon 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 cxmon, 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.

cxmon 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 cxmon commands that operate on "memory" operate on a buffer allocated
by cxmon 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 cxmon 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 cxmon ('[]' marks a parameter than
can be left out):


  x                        Quit cxmon

quits cxmon 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 cxmon.


  ? 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 Z80 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 cxmon.

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 cxmon executable and search for PowerPC "nop" commands:

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

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

  [ 0 "cxmon"
  set size=.
  h 0 . "->"
  : . " $"
  ] 0 size "cxmon1"

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.8
Committed:	2000-10-15T15:07:09Z (24 years, 1 month ago) by cebix
Branch:	MAIN
Changes since 1.7:	+35 -33 lines
Log Message:	- extended to 8080 disassembler to a Z80 disassembler - program renamed to "cxmon"
#	User	Rev	Content
1	cebix	1.1
2	cebix	1.8	cxmon, 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	cebix	1.8	cxmon is available under the terms of the GNU General Public License. See the
14	cebix	1.2	file "COPYING" that is included in the distribution for details.
15
16
17	cebix	1.1	Overview
18			--------
19
20	cebix	1.8	cxmon is an interactive command-driven file manipulation tool that is
21	cebix	1.5	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	cebix	1.8	PowerPC, 680x0, 80x86, 6502 and Z80 disassemblers. By default, cxmon operates
25	cebix	1.5	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	cebix	1.8	cxmon can be started from the Shell or from the Tracker (BeOS), but command
38			line history doesn't work when started from the Tracker.
39	cebix	1.5
40			Options:
41			-m enables symbolic MacOS A-Trap and low memory globals display in the
42			680x0 disassembler
43	cebix	1.8	-r makes cxmon operate in real (virtual) memory space instead of an
44			allocated buffer
45	cebix	1.5
46	cebix	1.8	If no additional command line arguments are given, cxmon enters interactive
47			mode. Otherwise, all remaining arguments are interpreted and executed as cxmon
48	cebix	1.5	commands.
49
50			The default buffer size is 1MB.
51
52	cebix	1.8	The cxmon command prompt looks like this:
53	cebix	1.1
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	cebix	1.8	To quit cxmon, enter the command "x".
63	cebix	1.1
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	cebix	1.8	cxmon accepts expressions in all places where you have to specify a number.
79			The following operators are available and have the same meaning and
80			precedence as in the C programming language:
81	cebix	1.1
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	cebix	1.8	Those cxmon commands that operate on "memory" operate on a buffer allocated
121			by cxmon whose size is adjustable with the "@" command. The default buffer
122			size is 1MB. The buffer is an array of bytes where each byte has a 32-bit
123			integer address. Addresses start at 0 and are taken modulo the buffer size
124			(i.e. for the default 1MB buffer, addresses 0 and 100000 refer to the same
125			byte).
126	cebix	1.1
127	cebix	1.8	The buffer is the working area of cxmon where you load files into, manipulate
128	cebix	1.1	them, and write files back from. Arbitraty portions of the buffer may be used
129			as scratch space.
130
131
132			Commands
133			--------
134
135	cebix	1.8	The following commands are available in cxmon ('[]' marks a parameter than
136			can be left out):
137	cebix	1.1
138
139	cebix	1.8	x Quit cxmon
140	cebix	1.1
141	cebix	1.8	quits cxmon and returns to the shell.
142	cebix	1.1
143
144			h Show help text
145
146			displays a short overview of commands.
147
148
149			?? Show list of commands
150
151			displays a short list of available commands.
152
153
154			ver Show version
155
156	cebix	1.8	shows the version number of cxmon.
157	cebix	1.1
158
159			? expression Calculate expression
160
161			displays the value of the given expression in hex, decimal, and ASCII
162			characters. If the value is negative, it is displayed as a signed and unsigned
163			number.
164
165
166			@ [size] Reallocate buffer
167
168			changes the size of the buffer to the given number of bytes while preserving
169			the contents of the buffer. If the "size" argument is omitted, the current
170			buffer size is displayed.
171
172
173			i [start [end]] ASCII memory dump
174
175			displays the buffer contents from address "start" to address "end" as ASCII
176			characters. Entering "i" without arguments is equivalent to "i .". The value
177			of "." is set to the address after the last address displayed.
178
179
180	cebix	1.3	b [start [end]] Binary memory dump
181
182			displays the buffer contents from address "start" to address "end" in a binary
183			format. Entering "b" without arguments is equivalent to "b .". The value of
184			"." is set to the address after the last address displayed.
185
186
187	cebix	1.1	m [start [end]] Hex/ASCII memory dump
188
189			displays the buffer contents from address "start" to address "end" as hex
190			words and ASCII characters. Entering "m" without arguments is equivalent to
191			"m .". The value of "." is set to the address after the last address displayed.
192
193
194			d [start [end]] Disassemble PowerPC code
195
196			disassembles the buffer contents from address "start" to address "end".
197			Entering "d" without arguments is equivalent to "d .". The value of "." is
198			set to the address after the last address displayed.
199
200
201	cebix	1.4	d65 [start [end]] Disassemble 6502 code
202	cebix	1.1
203			disassembles the buffer contents from address "start" to address "end".
204			Entering "d65" without arguments is equivalent to "d65 .". The value of
205			"." is set to the address after the last address displayed.
206
207
208	cebix	1.4	d68 [start [end]] Disassemble 680x0 code
209	cebix	1.1
210			disassembles the buffer contents from address "start" to address "end".
211			Entering "d68" without arguments is equivalent to "d68 .". The value of
212			"." is set to the address after the last address displayed.
213
214
215	cebix	1.8	d80 [start [end]] Disassemble Z80 code
216	cebix	1.1
217			disassembles the buffer contents from address "start" to address "end".
218			Entering "d80" without arguments is equivalent to "d80 .". The value of
219			"." is set to the address after the last address displayed.
220
221
222	cebix	1.6	d86 [start [end]] Disassemble 80x86 (32-bit) code
223	cebix	1.1
224			disassembles the buffer contents from address "start" to address "end".
225			Entering "d86" without arguments is equivalent to "d86 .". The value of
226			"." is set to the address after the last address displayed.
227	cebix	1.6
228
229			d8086 [start [end]] Disassemble 80x86 (16-bit) code
230
231			disassembles the buffer contents from address "start" to address "end".
232			Entering "d8086" without arguments is equivalent to "d8086 .". The value
233			of "." is set to the address after the last address displayed.
234	cebix	1.1
235
236			: start string Modify memory
237
238			puts the specified byte string at the address "start" into the buffer. The
239			value of "." is set to the address after the last address modified.
240
241
242			f start end string Fill memory
243
244			fill the buffer in the range from "start" to (and including) "end" with the
245			given byte string.
246
247
248			y[b\|h\|w] start end expr Apply expression to memory
249
250			works like the "fill" ("f") command, but it doesn't fill with a byte string
251			but with the value of an expression that is re-evaluated for each buffer
252			location to be filled. The command comes in three flavors: "y"/"yb" works on
253			bytes (8-bit), "yh" on half-words (16-bit) and "yw" on words (32-bit). The
254			value of "." is the current address to be modified, the value of ":" holds
255			the contents of this address before modification.
256
257			Examples:
258			yw 0 fff :<<8 shifts all words in the address range 0..fff to the left
259			by 8 bits (you can use this to convert bitmap data from
260			ARGB to RGBA format, for example)
261			y 0 1234 ~: inverts all bytes in the address range 0..1234
262			yh 2 ff 20000/. creates a table of the fractional parts of the reciprocals
263			of 1..7f
264
265
266			t start end dest Transfer memory
267
268			transfers the buffer contents from "start" to (and including) "end" to "dest".
269			Source and destination may overlap.
270
271
272			c start end dest Compare memory
273
274			compares the buffer contents in the range from "start" to (and including)
275			"end" with the contents at "dest". The addresses of all different bytes and
276			the total number of differences (decimal) are printed.
277
278
279			h start end string Search for byte string
280
281			searches for the given byte string in the buffer starting at "start" up to
282			(and including) "end". The addresses and the total number of occurrences are
283			displayed. The value of "." is set to the address of the first occurrence.
284
285
286			\ "command" Execute shell command
287
288			executes the given shell command which must be enclosed in quotes.
289
290
291			ls [args] List directory contents
292
293			works as the shell command "ls".
294
295
296			rm [args] Remove file(s)
297
298			works as the shell command "rm".
299
300
301			cp [args] Copy file(s)
302
303			works as the shell command "cp".
304
305
306			mv [args] Move file(s)
307
308			works as the shell command "mv".
309
310
311			cd directory Change current directory
312
313			works as the shell command "cd". The name of the directory doesn't have to be
314			enclosed in quotes.
315
316
317			o ["file"] Redirect output
318
319			When a file name is specified, all following output is redirected to this
320			file. The file name must be enclosed in quotation marks even if it contains
321			no spaces. Entering "o" without parameters closes the file and directs the
322			output into the terminal window again.
323
324
325			[ start "file" Load data from file
326
327			loads the contents of the specified file into the buffer starting from address
328			"start". The file name must be enclosed in quotation marks even if it contains
329			no spaces. The value of "." is set to the address after the last address
330			affected by the load.
331
332
333			] start size "file" Save data to file
334
335			writes "size" number of bytes of the buffer from "start" to the specified file.
336			The file name must be enclosed in quotation marks even if it contains no spaces.
337
338
339			set [var[=value]] Set/clear/show variables
340
341			If no arguments are given, all currently defined variables are displayed.
342			Otherwise, the value of "var" is set to the specified value. If "=value"
343			is omitted, the variable "var" is cleared.
344
345
346			cv Clear all variables
347
348			clears all currently defined variables.
349
350
351			Examples
352			--------
353
354	cebix	1.8	Here are some simple examples for what is possible with cxmon.
355	cebix	1.1
356			Join "file1" and "file2" to "file3":
357
358			[ 0 "file1"
359			[ . "file2"
360			] 0 . "file3"
361
362			Remove the first 24 bytes (e.g. an unneeded header) of a file:
363
364			[ 0 "file"
365			] 18 .-18 "file"
366
367	cebix	1.8	Load the cxmon executable and search for PowerPC "nop" commands:
368	cebix	1.1
369	cebix	1.8	[ 0 "cxmon"
370	cebix	1.1	h 0 . 60,00,00,00
371
372	cebix	1.8	Create a modified version of cxmon so that the prompt has " $" instead of
373			"->":
374	cebix	1.1
375	cebix	1.8	[ 0 "cxmon"
376	cebix	1.1	set size=.
377			h 0 . "->"
378			: . " $"
379	cebix	1.8	] 0 size "cxmon1"
380	cebix	1.1
381			Convert a binary file which contains 16-bit numbers in little-endian format
382			to big-endian format (or vice-versa):
383
384			[ 0 "file"
385			yh 0 .-1 :>>8\|:<<8
386			] 0 . "file"
387
388			Load a BeBox boot ROM image and start disassembling the system reset handler:
389
390			[ 0 "bootnub.image"
391			d 100
392
393
394			History
395			-------
396
397	cebix	1.2	Please consult the file "ChangeLog" for the release history.
398	cebix	1.1
399
400			Christian Bauer
401	cebix	1.2	<Christian.Bauer@uni-mainz.de>
402	cebix	1.1
403			Marc Hellwig
404	cebix	1.2	<Marc.Hellwig@uni-mainz.de>