memory region documentation

memory region documentation

[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

Re: memory region documentation

[Eli Zaretskii]

> From: jtc@redback.com (J.T. Conklin)
> Date: 14 Nov 2000 13:11:18 -0800
> 
> 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.

Thanks!

> @node Memory Region Attributes
> @chapter Memory Region Attributes

It is usually a good idea to have a @cindex entry identical to
the chapter/section names; in this case, "@cindex memory region
attributes" (note the all-lower case: it's intentional).

> Memory region attributes allow you to describe special handling required
> by regions of your target's memory.  @value{GDBN} uses attributes to

When introducing a new term, it is usually best to have it in the
@dfn{} markup, when you first use the term:

  @dfn{Memory region attributes} allow you to describe special...

> @subsection Memory Access Mode 
[...]
> @subsection Memory Access Size
[...]
> @subsection Data Cache

Here, too, I'd suggest @cindex entries.

Re: memory region documentation

[J.T. Conklin]

>>>>> "Eli" == Eli Zaretskii <eliz@delorie.com> writes:
>> I spent some time writing this.

Eli> Thanks!

No problem.  

However, this exercise has reminded me why I'm a programmer and not a
tech writer.

>> @node Memory Region Attributes
>> @chapter Memory Region Attributes

Eli> It is usually a good idea to have a @cindex entry identical to
Eli> the chapter/section names; in this case, "@cindex memory region
Eli> attributes" (note the all-lower case: it's intentional).

Done.

>> Memory region attributes allow you to describe special handling required
>> by regions of your target's memory.  @value{GDBN} uses attributes to

Eli> When introducing a new term, it is usually best to have it in the
Eli> @dfn{} markup, when you first use the term:

Done.

>> @subsection Memory Access Mode 
>> [...]
>> @subsection Memory Access Size
>> [...]
>> @subsection Data Cache

Eli> Here, too, I'd suggest @cindex entries.

This seems a bit odd to me.  These are pretty generic concepts.  If I
was browsing the index I'm not sure I'd expect that they'd be related
to memory regions.  On the other hand, if I wanted to set the memory
access width, it would take me to the right page.

Let me know what you think, I'll do whatever you feel is correct.


Can you tell me where you'd like me to put this chapter?  I assume
it's a chapter, since it doesn't seem to be a good fit into any of
the existing chapters --- especially if we start adding more varied
attributes.

Many thanks,

        --jtc

-- 
J.T. Conklin
RedBack Networks

Re: memory region documentation

[Eli Zaretskii]

> From: jtc@redback.com (J.T. Conklin)
> Date: 16 Nov 2000 11:05:29 -0800
> 
> However, this exercise has reminded me why I'm a programmer and not a
> tech writer.

Actually, what you wrote was very good; the comments I had were pretty
much minor.

> >> @subsection Memory Access Mode 
> >> [...]
> >> @subsection Memory Access Size
> >> [...]
> >> @subsection Data Cache
> 
> Eli> Here, too, I'd suggest @cindex entries.
> 
> This seems a bit odd to me.  These are pretty generic concepts.  If I
> was browsing the index I'm not sure I'd expect that they'd be related
> to memory regions.

Indices are for quickly finding something that you know or suspect
to be somewhere in the manual.  That is, you don't look in the index
to find what's in the book---that's what the TOC or the top-level menu
is for---but when you use the manual as a reference.

When that happens, it is perfectly okay to have an index entry which,
under other circumstances, would sound as a generic concept, provided
that the index entry points to the place where those concepts are
discussed in depth in the manual.

> On the other hand, if I wanted to set the memory access width, it
> would take me to the right page.

That is exactly the purpose of an index.  Imagine someone looking for
this specific piece of information, and ask yourself whether it would
be reasonable for that person to try to type "memory access mode".

I usually find the info-search command (bound to the `i' key) to be
the most efficient means of finding specific information in a manual.
When you use index-search, the situation when someone browses the
index is not the most important one.

> Can you tell me where you'd like me to put this chapter?  I assume
> it's a chapter, since it doesn't seem to be a good fit into any of
> the existing chapters --- especially if we start adding more varied
> attributes.

It looks like making this a chapter is the right thing.

As to its place, it is not very important.  You need to add an entry
to the top-level menu (in the @top node) that leads to this new node
you've written, and you need to insert the text somewhere in the
file.  It is customary to put the node between the same nodes as the
menu entry in the top-level menu (but IIRC this is not required,
strictly speaking).

It looks like between "Native Debugging" and "Support Libraries" would
be a good place.

Re: memory region documentation

[J.T. Conklin]

>>>>> "Eli" == Eli Zaretskii <eliz@delorie.com> writes:
>> However, this exercise has reminded me why I'm a programmer and not a
>> tech writer.

Eli> Actually, what you wrote was very good; the comments I had were pretty
Eli> much minor.

Thanks, but I stand by my comment --- You didn't see what went into
that draft.  I spent a lot of time writing (and re-writing) it until
it reflected what I wanted to say.

>> Can you tell me where you'd like me to put this chapter?  I assume
>> it's a chapter, since it doesn't seem to be a good fit into any of
>> the existing chapters --- especially if we start adding more varied
>> attributes.

Eli> It looks like between "Native Debugging" and "Support Libraries"
Eli> would be a good place.

Eh?  Those chapters are in the internals document, this is intended to
be user documentation.

        --jtc

-- 
J.T. Conklin
RedBack Networks

Re: memory region documentation

[Eli Zaretskii]

> From: jtc@redback.com (J.T. Conklin)
> Date: 21 Nov 2000 17:06:12 -0800
> 
> >> Can you tell me where you'd like me to put this chapter?  I assume
> >> it's a chapter, since it doesn't seem to be a good fit into any of
> >> the existing chapters --- especially if we start adding more varied
> >> attributes.
> 
> Eli> It looks like between "Native Debugging" and "Support Libraries"
> Eli> would be a good place.
> 
> Eh?  Those chapters are in the internals document, this is intended to
> be user documentation.

Ouch!  Whatever got me to think you were talking about gdbint.texinfo?
Sorry.

For gdb.texinfo, it looks like it should be a section in the
"Examining Data" chapter (node name "Data"), either as a section after
"Memory", or as a subsection of "Memory".  I'm puzzled why did you
think it didn't fit into the "Data" chapter.

Re: memory region documentation

[J.T. Conklin]

>>>>> "Eli" == Eli Zaretskii <eliz@delorie.com> writes:
Eli> For gdb.texinfo, it looks like it should be a section in the
Eli> "Examining Data" chapter (node name "Data"), either as a section
Eli> after "Memory", or as a subsection of "Memory".  I'm puzzled why
Eli> did you think it didn't fit into the "Data" chapter.

Thanks.  I've got it in a separate file now, I'll merge it into one of
those places.

The reason I didn't think it fit in the Data chapter was the not yet
implemented breakpoint attribute.  GDB needs to insert breakpoints for
step, next, continue, etc.; but it can't do it if the memory region is
protected (ie, image is running out of ROM, FLASH, etc.).  So there 
needs to be a mechanism to tell GDB to use hardware breakpoints for
those internal breakpoints.  This part of the feature isn't really
"data" related.

        --jtc 

-- 
J.T. Conklin
RedBack Networks

Re: memory region documentation

[Eli Zaretskii]

> From: jtc@redback.com (J.T. Conklin)
> Date: 30 Nov 2000 12:08:53 -0800
> 
> The reason I didn't think it fit in the Data chapter was the not yet
> implemented breakpoint attribute.  GDB needs to insert breakpoints for
> step, next, continue, etc.; but it can't do it if the memory region is
> protected (ie, image is running out of ROM, FLASH, etc.).  So there 
> needs to be a mechanism to tell GDB to use hardware breakpoints for
> those internal breakpoints.  This part of the feature isn't really
> "data" related.

That's true, but I don't think this is a reason grave enough to make
this a separate chapter.

I think the right question is: would a user reasonably expect this
feature be described under Data?  If so, we can put it there.  We can
also add a short explanation in the section about breakpoints saying
that in the case of read-only code memory, they need to use memory
regions first, with a cross-reference to the stuff you've written.