From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from simark.ca by simark.ca with LMTP id MFZjAwJYg2oYYC0AWB0awg (envelope-from ) for ; Mon, 17 Aug 2026 14:50:42 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=simark.ca; s=mail; t=1786992641; bh=c4V+zNtgdKz0BL8V6WzrRf+P/tprtG7U50rCDVkynyw=; h=Date:Subject:To:References:From:In-Reply-To:List-Id: List-Unsubscribe:List-Archive:List-Post:List-Help:List-Subscribe: From; b=UE+LeH6mATasG8451/L4xW7jU0f1W1Lk/oPX8hX/AjnE15IDEysqrhFpEZE1U8Hm+ XoN2/1nMIKds4BykgGEuEpjPtWJN0p8sO5irTG+McelT8aIZMWfKwGgRpgGMtuXX4E FVel5MDbUlZFHy4Ta3ykLk+UUO+AElVlIdj+hUIU= Received: by simark.ca (Postfix, from userid 112) id F05521E166; Mon, 17 Aug 2026 14:50:41 -0400 (EDT) X-Spam-Checker-Version: SpamAssassin 4.0.1 (2024-03-25) on simark.ca X-Spam-Level: X-Spam-Status: No, score=-5.4 required=5.0 tests=ARC_SIGNED,ARC_VALID,BAYES_00, DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,MAILING_LIST_MULTI, RCVD_IN_DNSWL_MED autolearn=ham autolearn_force=no version=4.0.1 Authentication-Results: simark.ca; dkim=pass (1024-bit key; unprotected) header.d=simark.ca header.i=@simark.ca header.a=rsa-sha256 header.s=mail header.b=EowAFDyl; dkim-atps=neutral Received: from vm01.sourceware.org (vm01.sourceware.org [IPv6:2620:52:6:3111::32]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange x25519 server-signature ECDSA (prime256v1) server-digest SHA256) (No client certificate requested) by simark.ca (Postfix) with ESMTPS id 3AC501E09B for ; Mon, 17 Aug 2026 14:50:41 -0400 (EDT) Received: from vm01.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id F30564B9DB56 for ; Mon, 17 Aug 2026 18:50:39 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org F30564B9DB56 Authentication-Results: sourceware.org; dkim=pass (1024-bit key, unprotected) header.d=simark.ca header.i=@simark.ca header.a=rsa-sha256 header.s=mail header.b=EowAFDyl Received: from simark.ca (simark.ca [158.69.221.121]) by sourceware.org (Postfix) with ESMTPS id EE9F74BA2E11 for ; Mon, 17 Aug 2026 18:50:14 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org EE9F74BA2E11 Authentication-Results: sourceware.org; dmarc=pass (p=none dis=none) header.from=simark.ca Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=simark.ca ARC-Filter: OpenARC Filter v1.0.0 sourceware.org EE9F74BA2E11 Authentication-Results: sourceware.org; arc=none smtp.remote-ip=158.69.221.121 ARC-Seal: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1786992615; cv=none; b=c9fnd6o4GOxVvPXcs85tgzSEKnkXWeD7COBMBym7s0xKyFoLgBOkdZ38+QHYS0M43Delj/7voSwFjN+l4OlxIGtmGD/JY78uY2Z460WktyOje9t26diXB8OU5QyI9iKWJnLwvN22w+GBbckg698YcwiLcGQClB5k9uu8IsDfMUY= ARC-Message-Signature: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1786992615; c=relaxed/simple; bh=c4V+zNtgdKz0BL8V6WzrRf+P/tprtG7U50rCDVkynyw=; h=DKIM-Signature:Message-ID:Date:MIME-Version:Subject:To:From; b=nTn0+/n64QWItfykGIv9WHt8LZ8tc/a6JOZiPTpfy8c9/XNqPACI5KfOTvAhKPk4ttGJfl13CpiKpawIAO471ZQjF6tA2bZB3maF42DC69U2ccZmu8FF+Vn6hsnIB+aeDWJtV8dvUHkAxAuxmG3T2q8mQAuD5A19dt2KL7PDF4o= ARC-Authentication-Results: i=1; sourceware.org; dkim=pass (1024-bit key, unprotected) header.d=simark.ca header.i=@simark.ca header.a=rsa-sha256 header.s=mail header.b=EowAFDyl DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org EE9F74BA2E11 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=simark.ca; s=mail; t=1786992613; bh=c4V+zNtgdKz0BL8V6WzrRf+P/tprtG7U50rCDVkynyw=; h=Date:Subject:To:References:From:In-Reply-To:From; b=EowAFDylmLit9Jkt8NXX5Cv1XoytLJOI1Y0uSYpg0xyO0QIAmRvtxvSDWSY5EW8P2 +3OcFLvSi/3VYQnUCQ/LxM2z7DIPIPxUGoWI6gY25fxjcWgWJp33EjZ/FLpMNxf03r /DaLDWPn7DFFV7XOClYsOB4bNkLtEsRVUn1uYH7U= Received: by simark.ca (Postfix) id 7F0EB1E09B; Mon, 17 Aug 2026 14:50:13 -0400 (EDT) Message-ID: <381a0161-9b9b-45ba-89ae-16e6a085b75d@simark.ca> Date: Mon, 17 Aug 2026 14:50:12 -0400 MIME-Version: 1.0 User-Agent: Mozilla Thunderbird Subject: Re: [PATCH v2] gdbtypes: improve documentation of composite type helpers To: Matthieu Longo , gdb-patches@sourceware.org References: <20260814104941.522777-1-matthieu.longo@arm.com> Content-Language: fr From: Simon Marchi In-Reply-To: <20260814104941.522777-1-matthieu.longo@arm.com> Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 7bit X-BeenThere: gdb-patches@sourceware.org X-Mailman-Version: 2.1.30 Precedence: list List-Id: Gdb-patches mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: gdb-patches-bounces~public-inbox=simark.ca@sourceware.org On 8/14/26 6:49 AM, Matthieu Longo wrote: > Document how arch_composite_type handles a null NAME, and clarify the > semantics of an empty field name for the append_composite_type* helpers. > > Suggested-By: Simon Marchi > --- > gdb/gdbtypes.c | 12 ++++-------- > gdb/gdbtypes.h | 30 ++++++++++++++++++++++++++---- > 2 files changed, 30 insertions(+), 12 deletions(-) > > diff --git a/gdb/gdbtypes.c b/gdb/gdbtypes.c > index 4b6c01910f4..e0c25c58d83 100644 > --- a/gdb/gdbtypes.c > +++ b/gdb/gdbtypes.c > @@ -5412,8 +5412,7 @@ append_flags_type_flag (struct type *type, int bitpos, const char *name) > name); > } > > -/* Allocate a TYPE_CODE_STRUCT or TYPE_CODE_UNION type structure (as > - specified by CODE) associated with GDBARCH. NAME is the type name. */ > +/* See gdbtypes.h. */ > > struct type * > arch_composite_type (struct gdbarch *gdbarch, const char *name, > @@ -5428,9 +5427,7 @@ arch_composite_type (struct gdbarch *gdbarch, const char *name, > return t; > } > > -/* Add new field with name NAME and type FIELD to composite type T. > - Do not set the field's position or adjust the type's length; > - the caller should do so. Return the new field. */ > +/* See gdbtypes.h. */ > > struct field * > append_composite_type_field_raw (struct type *t, const char *name, > @@ -5448,8 +5445,7 @@ append_composite_type_field_raw (struct type *t, const char *name, > return f; > } > > -/* Add new field with name NAME and type FIELD to composite type T. > - ALIGNMENT (if non-zero) specifies the minimum field alignment. */ > +/* See gdbtypes.h. */ > > void > append_composite_type_field_aligned (struct type *t, const char *name, > @@ -5489,7 +5485,7 @@ append_composite_type_field_aligned (struct type *t, const char *name, > } > } > > -/* Add new field with name NAME and type FIELD to composite type T. */ > +/* See gdbtypes.h. */ > > void > append_composite_type_field (struct type *t, const char *name, > diff --git a/gdb/gdbtypes.h b/gdb/gdbtypes.h > index dd2d24fa8e2..f7853430d64 100644 > --- a/gdb/gdbtypes.h > +++ b/gdb/gdbtypes.h > @@ -2431,20 +2431,42 @@ extern struct type *init_pointer_type (type_allocator &alloc, int bit, > extern struct type *init_fixed_point_type (type_allocator &, int, int, > const char *); > > -/* Helper functions to construct a struct or record type. An > - initially empty type is created using arch_composite_type(). > - Fields are then added using append_composite_type_field*(). A union > - type has its size set to the largest field. A struct type has each > +/* Helper functions to construct a struct or record type. An initially empty > + type is created using arch_composite_type(). Fields are then added using > + append_composite_type_field*(). > + A union type has its size set to the largest field. A struct type has each > field packed against the previous. */ I would get rid of this generic comment and move the information to the other comments. - The doc of arch_composite_type can mention that the type initially has no fields, and that fields can be added with the append_composite_type_field*() functions - The part about union and struct sizes can be moved to the doc of append_composite_type_field(). To avoid repeating things between all the three variants of append_composite_type_field*(), I would suggest using a form where the common information is documented at only one place (probably append_composite_type_field()) and the other functions refer to it This is what I propose: /* Allocate a structure or union type (as specified by CODE) associated with GDBARCH. NAME is the type name. If it is nullptr, the type is anonymous. The new type initially has no fields. Fields can be added by calling append_composite_type_field*. */ extern struct type *arch_composite_type (struct gdbarch *gdbarch, const char *name, enum type_code code); /* Add a new field named NAME with type FIELD to composite type T. If NAME is an empty string and the field's type is a structure or a union, the fields of that structure or union are visible directly in T. This function updates the size of T: - A union type has its size set to the largest field. - A structure type has each field packed against the previous. */ extern void append_composite_type_field (struct type *t, const char *name, struct type *field); /* Like append_composite_type_field, except that ALIGNMENT (if non-zero) specifies the minimum alignment of the new field. */ extern void append_composite_type_field_aligned (struct type *t, const char *name, struct type *field, int alignment); /* Like append_composite_type_field, except that this function does not set the field's position or adjust the length of T; the caller is responsible for doing so. Return the newly added field. */ struct field *append_composite_type_field_raw (struct type *t, const char *name, struct type *field); Simon