From patchwork Wed Apr 8 19:56:15 2015 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Simon Marchi X-Patchwork-Id: 6099 Received: (qmail 55741 invoked by alias); 8 Apr 2015 19:56:33 -0000 Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Unsubscribe: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org Delivered-To: mailing list gdb-patches@sourceware.org Received: (qmail 55556 invoked by uid 89); 8 Apr 2015 19:56:32 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-1.9 required=5.0 tests=AWL, BAYES_00, SPF_PASS autolearn=ham version=3.3.2 X-HELO: usevmg20.ericsson.net Received: from usevmg20.ericsson.net (HELO usevmg20.ericsson.net) (198.24.6.45) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with (AES256-SHA encrypted) ESMTPS; Wed, 08 Apr 2015 19:56:30 +0000 Received: from EUSAAHC008.ericsson.se (Unknown_Domain [147.117.188.96]) by usevmg20.ericsson.net (Symantec Mail Security) with SMTP id F2.C8.12456.66135255; Wed, 8 Apr 2015 15:47:18 +0200 (CEST) Received: from elxcz23q12-y4.mo.ca.am.ericsson.se (147.117.188.8) by smtps-am.internal.ericsson.com (147.117.188.96) with Microsoft SMTP Server (TLS) id 14.3.210.2; Wed, 8 Apr 2015 15:56:23 -0400 From: Simon Marchi To: CC: Simon Marchi Subject: [PATCH 3/7] Clarify doc about memory read/write and non-8-bits bytes Date: Wed, 8 Apr 2015 15:56:15 -0400 Message-ID: <1428522979-28709-4-git-send-email-simon.marchi@ericsson.com> In-Reply-To: <1428522979-28709-1-git-send-email-simon.marchi@ericsson.com> References: <1428522979-28709-1-git-send-email-simon.marchi@ericsson.com> MIME-Version: 1.0 X-IsSubscribed: yes 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