Re: add file I/O support when debugging an embedded target via jtag

[Eli Zaretskii <eliz at gnu dot org>]

> Date: Tue, 12 Aug 2008 17:33:20 +0100
> From: Bart Veer <bartv@ecoscentric.com>
> 
> +When set, if the target halts at a well-defined location GDB\n\
                                                           ^
Need a comma here.

> +will treat that as a request for file I/O. The request will be\n\
                                            ^^
Please use two spaces after a period that ends a sentence.

> +@node Hardware Debug Support
> +@section Extra support for hardware debuggers
> +
> +@cindex hwdebug

This isn't a useful index entry for the Concept Index.  The entries in
that index are supposed to be phrases, not command names.  The latter
are introduced by @kindex.  How about

  @cindex hardware debuggers support
  @kindex hwdebug

> +When @value{GDBN} interacts with a server or stub running on the
> +remote target the target-side application can perform a number of
                ^
Missing comma.

> +host-side file I/O operations,  @xref{File-I/O Remote Protocol

@xref should not be in the middle of a sentence, because it produces
"See" with a capital S.  Please either use "see @ref" or replace the
preceding comma with a period.

> +or BDM.  If so then target-side code may be unable to generate the
                 ^
Missing comma.

> +remote protocol messages directly.  Instead it can send the request by
                                              ^
Missing comma

>                                       Instead it can send the request by
> +triggering a breakpoint or processor exception at a well-known
> +location @code{_gdb_hwdebug_break}.

Sorry, I'm not sure I understand this sentence.  Are you saying that
_gdb_hwdebug_break is a name of a location?  If so, please say
something like

  by triggering a breakpoint or processor exception at a well-known
  location named @code{_gdb_hwdebug_break}.

> +default, allowing the application to run stand-alone as well as inside
> +a debug session.  It can be enabled by a @kbd{set hwdebug} command, or
> +disabled by @kbd{set hwdebug off}.            ^^^^^^^^^^^

Shouldn't this be "set hwdebug on"?

> +Exact usage depends on the application being debugged.  Amongst other
> +things @kbd{set hwdebug} clears a flag @code{_gdb_hwdebug_disabled} on
         ^
Missing comma.

> +the target.  If the application is loaded into RAM then there are no
                                                     ^
Missing comma.

> +problems.  However if it is programmed into flash and restarted from
                     ^
Missing comma.

> +the reset vector inside the debug session then typically the
                                            ^
Missing comma.

> +target-side initialization code will reset the disabled flag to its
> +default state, undoing the effect of @kbd{set hwdebug}.  Instead it
                                                                   ^
Missing comma.

> +will be necessary to set a hardware breakpoint at a suitably early
> +point in the application startup and invoke @kbd{set hwdebug} when
> +that breakpoint is hit.
> +
> +The target-side API for accessing the h/w debug file I/O functionality
                                         ^^^
Please don't use shorthand in the manual.  Please use full words.

> +depends on the embedded OS or run-time being used.  If the
> +functionality has not yet been ported then a reference implementation
                                        ^
Missing comma.

Otherwise, the doco part is okay with me, assuming that the code is
approved.

Thanks!