memory region documentation

[jtc at redback dot com (J.T. Conklin)]

It occured to me that the memory region code can't be considered ready
until it is documented (at least by my standards, while writing this I
found that the dcache wasn't documented and it's been in practically 
forever).  

I spent some time writing this.  I'm not particularly good at writing
user documentation, and I'm not exactly sure where this goes, so I'd
appreciate any comments from Eli and any other documentation-savvy 
folks.

Many thanks,

        --jtc


@node Memory Region Attributes
@chapter Memory Region Attributes 

Memory region attributes allow you to describe special handling required
by regions of your target's memory.  @value{GDBN} uses attributes to
determine whether to allow certain types of memory accesses; whether to
use specific width accesses; and whether to cache target memory.

Defined memory regions can be individually enabled and disabled.  When a
memory region is disabled, @value{GDBN} uses the default attributes when
accessing memory in that region.  Similarly, if no memory regions have
been defined, @value{GDBN} uses the default attributes when accessing
all memory.

@table @code
@kindex mem
@item mem @var{address1} @var{address1} @var{attributes}@dots{}
Define memory region bounded by @var{address1} and @var{address2}
with attributes @var{attributes}@dots{}.

@kindex delete mem
@item delete mem @var{nums}@dots{}
Remove memory region numbers @var{nums}.

@kindex disable mem
@item disable mem @var{nums}@dots{}
Disable memory region numbers @var{nums}.
A disabled memory region is not forgotten.  
It may be enabled again later.

@kindex enable mem
@item enable mem @var{nums}@dots{}
Enable memory region numbers @var{nums}.

@kindex info mem
@item info mem
Print a table of all defined memory regions, with the following columns
for each region.

@table @emph
@item Memory Region Number
@item Enabled or Disabled.
Enabled memory regions are marked with @samp{y}.  
Disabled memory regions are marked with @samp{n}.

@item Lo Address
The address defining the inclusive lower bound of the memory region.

@item Hi Address
The address defining the exclusive upper bound of the memory region.

@item Attributes
The list of attributes set for this memory region.
@end table
@end table


@section Attributes

@subsection Memory Access Mode 
The access mode attributes set whether @value{GDBN} may make read or
write accesses to a memory region.

While these attributes prevent @value{GDBN} from performing invalid
memory accesses, they do nothing to prevent the target system, I/O DMA,
etc. from accessing memory.

@table @code
@item ro
Memory is read only.
@item wo
Memory is write only.
@item rw
Memory is read/write (default).
@end table

@subsection Memory Access Size
The acccess size attributes tells @value{GDBN} to use specific sized
accesses in the memory region.  Often memory mapped device registers
require specific sized accesses.  If no access size attribute is
specified, @value{GDBN} may use any size accesses.

@table @code
@item 8
Use 8 bit memory accesses.
@item 16
Use 16 bit memory accesses.
@item 32
Use 32 bit memory accesses.
@item 64
Use 64 bit memory accesses.
@end table

@c @subsection Hardware/Software Breakpoints
@c The hardware/software breakpoint attributes set whether @value{GDBN}
@c will use hardware or software breakpoints for the internal breakpoints
@c used by the step, next, finish, until, etc. commands.
@c
@c @table @code
@c @item hwbreak
@c Always use hardware breakpoints 
@c @item swbreak (default)
@c @end table

@subsection Data Cache
The data cache attributes set whether @value{GDBN} may can cache target
memory.  While this generally improves performance by reducing debug
protocol overhead, it can lead to incorrect results because @value{GDBN}
does not know about volatile variables or memory mapped device
registers.

@table @code
@item cache
Enable @value{GDBN} to cache target memory. 
@item nocache (default)
Disable @value{GDBN} from caching target memory.
@end table

@c @subsection Memory Write Verification
@c The memory write verification attributes set whether @value{GDBN} 
@c will re-reads data after each write to verify the write was successful.
@c
@c @table @code
@c @item verify
@c @item noverify (default)
@c @end table



-- 
J.T. Conklin
RedBack Networks