From patchwork Wed Apr 15 19:47:34 2015 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Simon Marchi X-Patchwork-Id: 6240 Received: (qmail 53171 invoked by alias); 15 Apr 2015 19:47:55 -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 53094 invoked by uid 89); 15 Apr 2015 19:47:54 -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: usevmg21.ericsson.net Received: from usevmg21.ericsson.net (HELO usevmg21.ericsson.net) (198.24.6.65) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with (AES256-SHA encrypted) ESMTPS; Wed, 15 Apr 2015 19:47:52 +0000 Received: from EUSAAHC001.ericsson.se (Unknown_Domain [147.117.188.75]) by usevmg21.ericsson.net (Symantec Mail Security) with SMTP id 16.E5.17241.B5D5E255; Wed, 15 Apr 2015 14:45:15 +0200 (CEST) Received: from elxcz23q12-y4.mo.ca.am.ericsson.se (147.117.188.8) by smtps-am.internal.ericsson.com (147.117.188.75) with Microsoft SMTP Server (TLS) id 14.3.210.2; Wed, 15 Apr 2015 15:47:46 -0400 From: Simon Marchi To: CC: Simon Marchi Subject: [PATCH v2 3/7] Clarify doc about memory read/write and non-8-bits addressable memory unit sizes Date: Wed, 15 Apr 2015 15:47:34 -0400 Message-ID: <1429127258-1033-4-git-send-email-simon.marchi@ericsson.com> In-Reply-To: <1429127258-1033-1-git-send-email-simon.marchi@ericsson.com> References: <1429127258-1033-1-git-send-email-simon.marchi@ericsson.com> MIME-Version: 1.0 X-IsSubscribed: yes New in v2: * Change wording: use byte for 8-bits chunks and addressable memory unit for the unit of data associated to a single address. * Introduce definition of addressable memory unit in the Memory section. This patch modifies the manual to clarify the MI, RSP and Python APIs in regard to reading/writing memory on architectures with addressable memory unit that are not 8 bits. Care is taken to use the word "addressable memory unit" or "memory unit" when referring to one piece of the smallest addressable size on the current architecture and the word "byte" when referring to an 8-bits data piece. 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 memory units for -data-{read,write}-memory-bytes. * python.texi (Inferiors In Python): Same for read_memory and write_memory. --- gdb/doc/gdb.texinfo | 56 +++++++++++++++++++++++++++++++++++------------------ gdb/doc/python.texi | 5 +++-- 2 files changed, 40 insertions(+), 21 deletions(-) diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index 6255c14..dd5f941 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -9006,6 +9006,18 @@ If the @code{x} command has a repeat count, the address and contents saved are from the last memory unit printed; this is not the same as the last address printed if several units were printed on the last line of output. +@anchor{addressable memory unit} +@cindex addressable memory unit +Most targets have an addressable memory unit size of 8 bits. This means +that to each memory address are associated 8 bits of data. Some +targets, however, have other addressable memory unit sizes. +Within @value{GDBN} and this document, the term +@dfn{addressable memory unit} (or @dfn{memory unit} for short) is used +when explicitely referring to a chunk of data of that size. The word +@dfn{byte} is used to refer to a chunk of data of 8 bits, regardless of +the addressable memory unit size of the target. For most systems, +addressable memory unit is a synonym of byte. + @cindex remote memory comparison @cindex target memory comparison @cindex verify remote memory image @@ -29473,6 +29485,9 @@ can be used to instantiate this class for a varobj: This section describes the @sc{gdb/mi} commands that manipulate data: examine memory and registers, evaluate expressions, etc. +For details about what an addressable memory unit is, +@pxref{addressable memory unit}. + @c REMOVED FROM THE INTERFACE. @c @subheading -data-assign @c Change the value of a program variable. Plenty of side effects. @@ -29997,7 +30012,7 @@ next-page="0x000013c0",prev-page="0x00001380",memory=[ @subsubheading Synopsis @smallexample - -data-read-memory-bytes [ -o @var{byte-offset} ] + -data-read-memory-bytes [ -o @var{offset} ] @var{address} @var{count} @end smallexample @@ -30006,18 +30021,19 @@ where: @table @samp @item @var{address} -An expression specifying the address of the first memory word to be -read. Complex expressions containing embedded white space should be +An expression specifying the address of the first addressable memory unit +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 addressable memory units 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. +@item @var{offset} +The offset 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 @@ -30028,10 +30044,10 @@ Attributes}. Second, @value{GDBN} will attempt to read the remaining regions. For each one, if reading full region results in an errors, @value{GDBN} will try to read a subset of the region. -In general, every single byte in the region may be readable or not, -and the only way to read every readable byte is to try a read at +In general, every single memory unit in the region may be readable or not, +and the only way to read every readable unit is to try a read at every address, which is not practical. Therefore, @value{GDBN} will -attempt to read all accessible bytes at either beginning or the end +attempt to read all accessible memory units at either beginning or the end of the region, using a binary division scheme. This heuristic works well for reading accross a memory map boundary. Note that if a region has a readable range that is neither at the beginning or the end, @@ -30091,17 +30107,19 @@ where: @table @samp @item @var{address} -An expression specifying the address of the first memory word to be -written. Complex expressions containing embedded white space should be -quoted using the C convention. +An expression specifying the address of the first addressable memory unit +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 data to write. It is an error if @var{contents} does +not represent an integral number of addressable memory units. @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 addressable memory units to be +written. If @var{count} is greater than @var{contents}' length, +@value{GDBN} will repeatedly write @var{contents} until it fills +@var{count} memory units. @end table diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi index 098d718..c9d3f13 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} addressable memory units 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 addressable memory units from @var{buffer} to be +written. @end defun @findex gdb.search_memory