== rwmem - A small tool to read/write memory ==

Copyright (C) 2015 Tomi Valkeinen

== Intro ==

rwmem is a small tool to read and write arbitrary locations in a file.
Normally, this file is /dev/mem, so the tool reads/writes memory, but the file
can be any file that can be memory mapped (e.g. a normal file, /dev/fb0, etc.).

rwmem supports accessing 32/64 bit addresses, and accessing 8/16/32/64 bit
memory locations.

rwmem also supports bitfields (i.e. accessing only a subset of the memory
location), and operations on address ranges.

rwmem has support for using symbolic names for addresses and bitfields.

== Usage ==

usage: rwmem [options] <address>[:field][=value] [<address>[:field][=value]...]

	address		address to access:
			<address>	single address
			<start..end>	range with end address
			<start+len>	range with length

	field		bitfield (inclusive, start from 0):
			<bit>		single bit
			<high>:<low>	bitfield from high to low

	value		value to be written

	-h		show this help
	-s <size>	size of the memory access: 8/16/32/64 (default: 32)
	-w <mode>	write mode: w, rw or rwr (default)
	-p <mode>	print mode: q, r or rf (default)
	-b <address>	base address
	-R		raw output mode
	--file <file>	file to open (default: /dev/mem)
	--conf <file>	config file (default: ~/.rwmem/rwmemrc)
	--regs <file>	register set file

== Examples ==

Show what's in memory location 0x12345678

	$ rwmem 0x12345678

Show what's in memory location 0x12345678's bit 7 (i.e. 8th bit)

	$ rwmem 0x12345678:7

Show what's in memory location 0x12345678's bits 7-4 (i.e. bits 4, 5, 6, 7)

	$ rwmem 0x12345678:7:4

Write 0xbaadf00d to memory location 0x12345678

	$ rwmem 0x12345678=0xbaadf00d

Modify memory location 0x12345678's bits 7-4 to 0xf

	$ rwmem 0x12345678 0xbaadf00d:7:4=0xf

Show the byte at location 0x10 in file edid.raw

	$ rwmem --file edid.bin -s 8 0x10

Show SYSCONFIG register in DISPC

	$ rwmem -b dispc SYSCONFIG

Modify MIDLEMODE field in DISPC's SYSCONFIG register to 0x1

	$ rwmem -b dispc SYSCONFIG:MIDLEMODE=0x1

Read binary dump of DISPC to dispc.bin file

	$ rwmem -b dispc -R 0x0..0x1000 > dispc.bin

Show SYSCONFIG register, as defined in dispc.regs, in file dispc.bin

	$ rwmem --file dispc.bin --regs dispc.regs SYSCONFIG

Set /dev/fb0 to red

	$ rwmem -p q --file /dev/fb0 0x0..$((800*4*480))=0xff0000

== Write mode ==

The write mode parameter affects how rwmem handles writing.

Write mode 'w' means write-only. In this mode rwmem never reads from the
address. This means that if you modify only certain bits with the bitfield
operator, the rest of the bits will be set to 0.

Write mode 'rw' means read-write. In this mode rwmem reads from the address,
modifies the value, and writes it back.

Write mode 'rwr' means read-write-read. This is the same as 'rw' except rwmem
reads from the address again after writing for the purpose of showing the new
value. This is the default mode.

== Print mode ==

The print mode parameter affects what rwmem will output.

'q'  - quiet
'r'  - print only register value, not individual fields
'rf' - print register and fields (when available).

== Raw output mode ==

In raw output mode rwmem will copy the values it reads to stdout without any
formatting. This can be used to get binary dumps of memory areas.

== Register set files ==

Register set files are used to define symbolic addresses and fields, so that
you can use register and names instead of numerical addresses or bit numbers.

As an example, the following entry in a register file:

TIMING_H1,0x64,32
HBP,31,20
HFP,19,8
HSW,7,0

defines a 32bit register TIMING_H1, which is found at offset 0x64. It contains
three fields, HBP, HFP and HSW, and their bit locations.

Thus, instead of using address '0x64:19:8' you can use 'TIMING_H1:HFP'.

You can specify the register set file to use with --regs option. You would normally
combine that with option -b to specify the base address of the IP block. For
example:

$ rwmem --regs dispc.regs -b 0x58001000 TIMING_H1:HFP

However, to simplify things, you can define symbolic base addresses in
rwmem.cfg file. Adding the following line to rwmem.cfg:

dispc  0x58001000       dispc.regs

means that base 'dispc' means base address of 0x58001000 and register set file
dispc.regs. Thus, you can write the previous example as:

$ rwmem -b dispc TIMING_H1:HFP

== Register set file format ==

<regname>,<offset>,<size>
<fieldname>,<high>,<low>
... more fields ...
empty line

== rwmem.cfg file format ==

<base-name>	<address>	<regfile>