[PATCH 3/7] Clarify doc about memory read/write and non-8-bits bytes

[Simon Marchi <simon dot marchi at ericsson dot com>]

This patch modifies the manual to clarify the MI, RSP and Python APIs in
regard to reading/writing memory on architectures with non-8-bits bytes.

Care is taken to use the word byte when referring to one piece of the
smallest addressable size on the current architecture and the word octet
when referring to an 8-bits data piece. I try to avoid "word", because
it can be ambiguous.

For MI, -data-{read,write}-memory are not modified, since they are
deprecated.

gdb/doc/ChangeLog:

	* gdb.texinfo (GDB/MI Data Manipulation): Clarify usage of
	bytes and octets for -data-{read,write}-memory-bytes.
	(Packets): Same for the m, M and X packets.
	* python.texi (Inferiors In Python): Same for read_memory and
	write_memory.
---
 gdb/doc/gdb.texinfo | 41 ++++++++++++++++++++++-------------------
 gdb/doc/python.texi |  5 +++--
 2 files changed, 25 insertions(+), 21 deletions(-)

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index d794893..e4dc24b 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -29935,18 +29935,19 @@ where:
 
 @table @samp
 @item @var{address}
-An expression specifying the address of the first memory word to be
+An expression specifying the address of the first memory byte to be
 read.  Complex expressions containing embedded white space should be
 quoted using the C convention.
 
 @item @var{count}
-The number of bytes to read.  This should be an integer literal.
+The number of target memory bytes to read.  This should be an integer
+literal.
 
 @item @var{byte-offset}
-The offsets in bytes relative to @var{address} at which to start
-reading.  This should be an integer literal.  This option is provided
-so that a frontend is not required to first evaluate address and then
-perform address arithmetics itself.
+The offset in target memory bytes relative to @var{address} at which to
+start reading.  This should be an integer literal.  This option is
+provided so that a frontend is not required to first evaluate address
+and then perform address arithmetics itself.
 
 @end table
 
@@ -29979,8 +29980,9 @@ The start address of the memory block, as hexadecimal literal.
 The end address of the memory block, as hexadecimal literal.
 
 @item offset
-The offset of the memory block, as hexadecimal literal, relative to
-the start address passed to @code{-data-read-memory-bytes}.
+The offset of the memory block in target memory bytes, as hexadecimal
+literal, relative to the start address passed to
+@code{-data-read-memory-bytes}.
 
 @item contents
 The contents of the memory block, in hex.
@@ -30020,17 +30022,18 @@ where:
 
 @table @samp
 @item @var{address}
-An expression specifying the address of the first memory word to be
+An expression specifying the address of the first memory byte to be
 written.  Complex expressions containing embedded white space should be
 quoted using the C convention.
 
 @item @var{contents}
-The hex-encoded bytes to write.
+The hex-encoded bytes to write.  It is an error if @var{contents} does
+not represent an integral number of target memory bytes.
 
 @item @var{count}
-Optional argument indicating the number of bytes to be written.  If @var{count} 
-is greater than @var{contents}' length, @value{GDBN} will repeatedly 
-write @var{contents} until it fills @var{count} bytes.
+Optional argument indicating the number of target bytes to be written.
+If @var{count} is greater than @var{contents}' length, @value{GDBN} will
+repeatedly write @var{contents} until it fills @var{count} bytes.
 
 @end table
 
@@ -34665,7 +34668,7 @@ probes the target state as if a new connection was opened
 
 @item m @var{addr},@var{length}
 @cindex @samp{m} packet
-Read @var{length} bytes of memory starting at address @var{addr}.
+Read @var{length} octets of memory starting at address @var{addr}.
 Note that @var{addr} may not be aligned to any particular boundary.
 
 The stub need not use any particular size or alignment when gathering
@@ -34680,8 +34683,8 @@ suitable for accessing memory-mapped I/O devices.
 Reply:
 @table @samp
 @item @var{XX@dots{}}
-Memory contents; each byte is transmitted as a two-digit hexadecimal
-number.  The reply may contain fewer bytes than requested if the
+Memory contents; each octet is transmitted as a two-digit hexadecimal
+number.  The reply may contain fewer octets than requested if the
 server was able to read only part of the region of memory.
 @item E @var{NN}
 @var{NN} is errno
@@ -34689,8 +34692,8 @@ server was able to read only part of the region of memory.
 
 @item M @var{addr},@var{length}:@var{XX@dots{}}
 @cindex @samp{M} packet
-Write @var{length} bytes of memory starting at address @var{addr}.
-The data is given by @var{XX@dots{}}; each byte is transmitted as a two-digit
+Write @var{length} octets of memory starting at address @var{addr}.
+The data is given by @var{XX@dots{}}; each octet is transmitted as a two-digit
 hexadecimal number.
 
 Reply:
@@ -35005,7 +35008,7 @@ for success (@pxref{Stop Reply Packets})
 @anchor{X packet}
 @cindex @samp{X} packet
 Write data to memory, where the data is transmitted in binary.
-Memory is specified by its address @var{addr} and number of bytes @var{length};
+Memory is specified by its address @var{addr} and number of octets @var{length};
 @samp{@var{XX}@dots{}} is binary data (@pxref{Binary Data}).
 
 Reply:
diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi
index 098d718..b31bce0 100644
--- a/gdb/doc/python.texi
+++ b/gdb/doc/python.texi
@@ -2718,7 +2718,7 @@ return an empty tuple.
 
 @findex Inferior.read_memory
 @defun Inferior.read_memory (address, length)
-Read @var{length} bytes of memory from the inferior, starting at
+Read @var{length} target bytes of memory from the inferior, starting at
 @var{address}.  Returns a buffer object, which behaves much like an array
 or a string.  It can be modified and given to the
 @code{Inferior.write_memory} function.  In @code{Python} 3, the return
@@ -2731,7 +2731,8 @@ Write the contents of @var{buffer} to the inferior, starting at
 @var{address}.  The @var{buffer} parameter must be a Python object
 which supports the buffer protocol, i.e., a string, an array or the
 object returned from @code{Inferior.read_memory}.  If given, @var{length}
-determines the number of bytes from @var{buffer} to be written.
+determines the number of target memory bytes from @var{buffer} to be
+written.
 @end defun
 
 @findex gdb.search_memory
-- 
2.1.4