From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from eggs.gnu.org (eggs.gnu.org [IPv6:2001:470:142:3::10]) by sourceware.org (Postfix) with ESMTPS id B2C3C3858D20 for ; Sat, 13 Jan 2024 07:21:54 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org B2C3C3858D20 Authentication-Results: sourceware.org; dmarc=pass (p=none dis=none) header.from=gnu.org Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=gnu.org ARC-Filter: OpenARC Filter v1.0.0 sourceware.org B2C3C3858D20 Authentication-Results: server2.sourceware.org; arc=none smtp.remote-ip=2001:470:142:3::10 ARC-Seal: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1705130516; cv=none; b=ctbQ/flYhX50WHc5fu9It5o+UUwbiJK6t+d6yX/N7L3SuR1P/21CqvxjZb6JVOcTkWbKygLNqTvGHai7W3CwHWsz1XnBN4mJ3l8+w9Ncfe0JreXnVYjY94mEDT+DEl4r5M4F2rkuizYYRjrFBoPLRpPZItG2ZMvNxrYWkWkBzp8= ARC-Message-Signature: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1705130516; c=relaxed/simple; bh=PI5v20Po3vaaVjwsvSP+Yb9DAWEM7fI6DOJ19wG+jbQ=; h=DKIM-Signature:Date:Message-Id:From:To:Subject; b=sflKKl1lj/TVIqrZyUB3oUDLK5WHFnayJdEP8ZAJ0+JbyBQYxMArmzg/YEuFU/uR+SUKO2OLOukjP+jbCxRkiaoVpDMSab/3XpW340PnelaqVfa/SYpGV3jC6Dyh1fz7mMNMktZ8COY6WfMZ3nDvSE25wy7d9xaPKYR+dd1wWD4= ARC-Authentication-Results: i=1; server2.sourceware.org Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1rOYL4-0005Ni-3y; Sat, 13 Jan 2024 02:21:54 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=References:Subject:In-Reply-To:To:From:Date: mime-version; bh=eRn1+ooQIunSxNbWcooMWkUlkFK81HEXEBoEIkhDS6E=; b=fFzA3X8yitAY u+DGxtbp1KHe72gfJ5fs0kiMU4LIB2Er1qZ+OmpbRVKstKIKGf+XYzM0k/FxoVghSz2cAHXVIdtYo ZmGNW13kkc2XvO5A24PefQZv+Ma9aktgKqOyVfakPYANmeAjpFnpUcnHNYAxv3BzRYXVi/ac/L9LN MtqfFBxBqXyOWOHuHRs15OpKKYDgLipRxfogJmk5yt7VNzND7bB/OXImQiADS8YuusDKz32oTKrid DMuS3fdNLWvRy4QmKXrIoS3rk2G3V43bA+htLTSk6o7LYf/5SwUGxUvjd/eDW1FLICYJVodsCqJ4a 9Np+ewMXS84toAghqy8aOg==; Date: Sat, 13 Jan 2024 09:21:31 +0200 Message-Id: <83r0ilhf5w.fsf@gnu.org> From: Eli Zaretskii To: Matheus Branco Borella Cc: gdb-patches@sourceware.org, aburgess@redhat.com In-Reply-To: <20240113013756.109371-1-dark.ryu.550@gmail.com> (message from Matheus Branco Borella on Fri, 12 Jan 2024 22:37:57 -0300) Subject: Re: [PATCH v3] Add support for creating new types from the Python API References: <20230808210010.95088-3-dark.ryu.550@gmail.com> <20240113013756.109371-1-dark.ryu.550@gmail.com> X-Spam-Status: No, score=-7.0 required=5.0 tests=BAYES_00,DKIMWL_WL_HIGH,DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,GIT_PATCH_0,SPF_HELO_PASS,SPF_PASS,TXREP,T_SCC_BODY_TEXT_LINE autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org List-Id: > From: Matheus Branco Borella > Cc: aburgess@redhat.com, > Matheus Branco Borella > Date: Fri, 12 Jan 2024 22:37:57 -0300 > > gdb/Makefile.in | 2 + > gdb/NEWS | 16 + > gdb/doc/python.texi | 237 ++++++++++ > gdb/python/py-float-format.c | 307 +++++++++++++ > gdb/python/py-objfile.c | 17 + > gdb/python/py-type-init.c | 520 ++++++++++++++++++++++ > gdb/python/python-internal.h | 34 ++ > gdb/python/python.c | 50 +++ > gdb/testsuite/gdb.python/py-type-init.c | 21 + > gdb/testsuite/gdb.python/py-type-init.exp | 132 ++++++ > 10 files changed, 1336 insertions(+) > create mode 100644 gdb/python/py-float-format.c > create mode 100644 gdb/python/py-type-init.c > create mode 100644 gdb/testsuite/gdb.python/py-type-init.c > create mode 100644 gdb/testsuite/gdb.python/py-type-init.exp Thanks. > diff --git a/gdb/NEWS b/gdb/NEWS > index 11cd6c0663e..e21cca24422 100644 > --- a/gdb/NEWS > +++ b/gdb/NEWS > @@ -87,6 +87,22 @@ show remote thread-options-packet > ** New function gdb.interrupt(), that interrupts GDB as if the user > typed control-c. > > + ** Functions that allow creation of instances of gdb.Type, and a new > + class gdb.FloatFormat that may be used to create floating point > + types. The functions that allow new type creation are: ^^ Our convention is to leave two spaces between sentences. > +@node Creating Types In Python > +@subsubsection Creating Types In Python > +@cindex creating types in Python > +@cindex Python, working with types > + > +@value{GDBN} makes available functionality to create new types from > +inside Python. This is awkward English. Suggest to reword: @value{GDBN} allows creation of new types from Python extensions. > +The following type creation functions are available in the @code{gdb} > +module: The following functions available in the @code{gdb} module create new types: > +@findex gdb.init_type > +@defun gdb.init_type (owner, type_code, bit_size, name) > +This function creates a new @code{gdb.Type} instance corresponding to a > +type owned by the given @code{owner}, with the given type code, > +@code{name} and size. The arguments should have the @var markup, not @code. So: This function creates a new @code{gdb.Type} instance corresponding to a type owned by the given @var{owner}, with the given @var{type_code}, @var{name} and @var{bit_size}. Likewise in the rest of this section: formal parameters should be referenced with @var{..}, not @code{..}. > +@code{owner} must be a reference to either a @code{gdb.Objfile} or a > +@code{gdb.Architecture} object. These correspond to objfile and ^^ Two spaces between sentences, here and elsewhere. > +@code{type_code} is one of the @code{TYPE_CODE_} constants defined in > +@xref{Types In Python}. ^^^^^ This should be @ref, not @xref. @xref is only used at the beginning of a sentence. > +@findex gdb.init_integer_type > +@defun gdb.init_integer_type (owner, bit_size, unsigned, name) > +This function creates a new @code{gdb.Type} instance corresponding to an > +integer type owned by the given @code{owner}, with the given > +@code{name}, size and signedness. > + > +@code{owner} must be a reference to either a @code{gdb.Objfile} or a > +@code{gdb.Architecture} object. These correspond to objfile and > +architecture-owned types, respectively. > + > +@code{bit_size} is the size of instances of the newly created type, in > +bits. Currently, accepted values are limited to multiples of 8. > + > +@code{unsigned} is a boolean indicating whether the type corresponds to > +a signed or unsigned value. > + > +This function returns an instance of @code{gdb.Type}, and will throw an > +exception in case of an error. > +@end defun There's no need to repeat the same text over and over again, for each function. It should be enough to describe these arguments once, and say that all of the functions accept these arguments. The only thing you should say about each function is what data type it creates, all the rest is similar or identical for all of these functions, and should be only described once. If some functions accept arguments that are unique to them, then describe those unique arguments as part of the function's description. Otherwise, just refer to the general description, which should be at the beginning of the section. > +@findex gdb.init_pointer_type > +@defun gdb.init_pointer_type (owner, target, bit_size, name) > +This function creates a new @code{gdb.Type} instance corresponding to a > +pointer type that points to @code{target} and is owned by the given > +@code{owner}, with the given @code{name} and size. > + > +@code{owner} must be a reference to either a @code{gdb.Objfile} or a > +@code{gdb.Architecture} object. These correspond to objfile and > +architecture-owned types, respectively. > + > +@code{target} is a @code{gdb.Type} object, corresponding to the type > +that will be pointed to by the newly created pointer type. > + > +@code{bit_size} is the size of instances of the newly created type, in > +bits. Currently, accepted values are limited to multiples of 8. Does this mean one can create pointer types of arbitrary length, regardless of the target architecture? Aren't pointers limited to what the underlying system supports? > +@findex gdb.init_boolean_type > +@defun gdb.init_fixed_point_type (owner, bit_size, unsigned, name) Typo in the first line? Reviewed-By: Eli Zaretskii