From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mx0a-00069f02.pphosted.com (mx0a-00069f02.pphosted.com [205.220.165.32]) by sourceware.org (Postfix) with ESMTPS id BB78F395250C for ; Tue, 7 Jun 2022 21:44:12 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org BB78F395250C Received: from pps.filterd (m0246617.ppops.net [127.0.0.1]) by mx0b-00069f02.pphosted.com (8.17.1.5/8.17.1.5) with ESMTP id 257IQHSn010464; Tue, 7 Jun 2022 21:44:10 GMT Received: from phxpaimrmta02.imrmtpd1.prodappphxaev1.oraclevcn.com (phxpaimrmta02.appoci.oracle.com [147.154.114.232]) by mx0b-00069f02.pphosted.com (PPS) with ESMTPS id 3gfyxsf1sb-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Tue, 07 Jun 2022 21:44:10 +0000 Received: from pps.filterd (phxpaimrmta02.imrmtpd1.prodappphxaev1.oraclevcn.com [127.0.0.1]) by phxpaimrmta02.imrmtpd1.prodappphxaev1.oraclevcn.com (8.16.1.2/8.16.1.2) with SMTP id 257LeXJv038763; Tue, 7 Jun 2022 21:44:09 GMT Received: from nam12-dm6-obe.outbound.protection.outlook.com (mail-dm6nam12lp2174.outbound.protection.outlook.com [104.47.59.174]) by phxpaimrmta02.imrmtpd1.prodappphxaev1.oraclevcn.com with ESMTP id 3gfwu2xj98-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Tue, 07 Jun 2022 21:44:09 +0000 ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=V/imccJbYJMj8L59b6BorfcVg6vQegAGwAyOU8mch7WJHrd0DAsRDLnA3/BD7o4xvlyr7ijPpKzuoNKxr//h045NmeLEZ43DFe7EDb8GJ7EYfnNmoqhEorRGxiqjbubbynxhSTOBjMjCPnZxTGgf1P/pFob1fOBSoKavTyb8QX1IRkG43+9maF1whIehu5n0bDZXUsHd8OBWZ4o6OlvjfoKFQx1Isg3gCeqVHwe/yUtBjgcFyZ7+g4RN0C3gXCFtqwcjvt1mTxjQ4M0YMBtzcMVWoxoqBGTeZdIpl5sN6CVBnxnFEr2y42uQfkBflMBlGNJcLwJ/dLivYGUCaEKyVw== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com; s=arcselector9901; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-AntiSpam-MessageData-ChunkCount:X-MS-Exchange-AntiSpam-MessageData-0:X-MS-Exchange-AntiSpam-MessageData-1; bh=/ZtnKeFHbvT68g+2ftxE8fCcWFNUb+JP4w1zcYI+KMA=; b=d7KjpD0swuLBxParqhoQxOubXHMiJZl/LN5PkVt3x8Pdc2go4IdCPHJ9crfLqHQarOlvVf1sHbiRUfogiwol/l+8dzg3XDQvQ0qxBo7zOKckqJFtVj14U3Lx8wgCw4TG18OUnVHX1igodmAqXLFCUDaWx5tLPxiK3FaCFsPTMks7jFUaaJarnGA0wQ56mRG+F59RMPO95Z/KrlsPwktKQ1iRUFcCKCB9NMLRts9oxbYzOuA0afu+q6peoWth1uMsa1cC1EKQX0/l+zM45l+QsgTCcK9FDCHXjAGhtR1uv3/VKeYL1mIwI+2GAWrbO5wREz67x3tnkBASCIGWW9iGDQ== ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=pass smtp.mailfrom=oracle.com; dmarc=pass action=none header.from=oracle.com; dkim=pass header.d=oracle.com; arc=none Received: from MN2PR10MB3213.namprd10.prod.outlook.com (2603:10b6:208:131::33) by BN0PR10MB5351.namprd10.prod.outlook.com (2603:10b6:408:127::20) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.5314.12; Tue, 7 Jun 2022 21:44:07 +0000 Received: from MN2PR10MB3213.namprd10.prod.outlook.com ([fe80::4939:15e0:57cb:87fb]) by MN2PR10MB3213.namprd10.prod.outlook.com ([fe80::4939:15e0:57cb:87fb%5]) with mapi id 15.20.5314.019; Tue, 7 Jun 2022 21:44:07 +0000 From: David Faust To: gcc-patches@gcc.gnu.org Cc: jose.marchesi@oracle.com, yhs@fb.com Subject: [PATCH 8/9] doc: document new attributes Date: Tue, 7 Jun 2022 14:43:41 -0700 Message-Id: <20220607214342.19463-9-david.faust@oracle.com> X-Mailer: git-send-email 2.35.3 In-Reply-To: <20220607214342.19463-1-david.faust@oracle.com> References: <20220607214342.19463-1-david.faust@oracle.com> Content-Transfer-Encoding: 8bit Content-Type: text/plain X-ClientProxiedBy: DM5PR11CA0003.namprd11.prod.outlook.com (2603:10b6:3:115::13) To MN2PR10MB3213.namprd10.prod.outlook.com (2603:10b6:208:131::33) MIME-Version: 1.0 X-MS-PublicTrafficType: Email X-MS-Office365-Filtering-Correlation-Id: 2d5804a9-9051-485f-f7e7-08da48ced99b X-MS-TrafficTypeDiagnostic: BN0PR10MB5351:EE_ X-Microsoft-Antispam-PRVS: X-MS-Exchange-SenderADCheck: 1 X-MS-Exchange-AntiSpam-Relay: 0 X-Microsoft-Antispam: BCL:0; X-Microsoft-Antispam-Message-Info: cCyqaq29rCSmcHp81mwMriuqR94RvYd2cYtWrguzwofnZd7uJMrwmkv27NCA3jxFuVJUdkek9FmiFNv3j5avUNKp0HJ0dVVfDeQEo1fCzcist7LeDUwbC+9VQaZLY6dkdJqMiihhZYpkkBlbpho6vIv+FUOJfU2y9XMM4lnOatwKUdPotALRV3l5boAGI8m0JFIOM5+6HCLKzxMGOHHDwlH8fLfBtys//kXtRapyM4i8cTdJ4Ours6KHVhNSXTyv/ylLSPOBW1y9JjgwENbXIEdluXTgE5SxeI4AA+kmAVOxAdPqTjFmNKRGPGqJgdoHa47LWzH0TimHsmFRL/T5ZDqpNz7sMofdpMy/4gc5wIPrk3GldHu3Pq6CCspHCGzHdWQOqjopCNCgwejbowfBbel6M9WXspof+jeKcGse/At665FqtGnTb4DAe3/9nH9oHRIr7FJo5vCeOypV01W5AZGpoTDZQBf2ICdI4Ue4lIpgcPmcIDVM9D+bPzTweZO4GKAtjBFOoPVc3YOusiPH2jbGXmld7xqkiR0SRzRu8zzJL4YBWuppxkCHTuhbANzGHMXFu+Ti8afDaKcyEOTmVttlQy22ElsZnlmok0SuZLc4ELtXktl994rrW5LFXYiIsOY/rfcS0WAGbYhfi76lJw== X-Forefront-Antispam-Report: CIP:255.255.255.255; CTRY:; LANG:en; SCL:1; SRV:; IPV:NLI; SFV:NSPM; H:MN2PR10MB3213.namprd10.prod.outlook.com; PTR:; CAT:NONE; SFS:(13230001)(366004)(508600001)(36756003)(6916009)(8936002)(1076003)(5660300002)(6512007)(2616005)(2906002)(66946007)(86362001)(38100700002)(66556008)(66476007)(316002)(6486002)(44832011)(8676002)(4326008)(6666004)(6506007)(186003)(52116002); DIR:OUT; SFP:1101; X-MS-Exchange-AntiSpam-MessageData-ChunkCount: 1 X-MS-Exchange-AntiSpam-MessageData-0: =?us-ascii?Q?mXPBQV8T87867e3dD9SVukcpai1gPL2IS5Lj6KifbPbEuF/qukbFyLkE419y?= =?us-ascii?Q?ghP0oKGUb62+dRqv6a8/Us+vFKKvt8urwfXy/DUdItRm159s/gN9x3oWcBg9?= =?us-ascii?Q?7QTjvvAx3jf7lxhm/jdX5wxyOUlL8S+0t4rs/0BX6naWV1nZdqKrTZ/XnxaR?= =?us-ascii?Q?BL3hDcJtGHLhG1FlPVzmKp4tINep9evXNipG59v86lF7ACvYn7tkih3uBJhR?= =?us-ascii?Q?XV3BPsNxsaAhCsLMVdQD190HB5kofPUrEKuSZQcx6O9GQRX/i5FzZsfAHlNY?= =?us-ascii?Q?h4OxTh2Ie4yyxC5EcMCbCgL8F64Mn4UwABtoS+u7fjjUe9JB1Gf+88x7Ra2G?= =?us-ascii?Q?BwcCPX/ZIbcRNQG4+GFNsYFr3bxXN6jWvgZTZcnrOFxyQVfVFi1I669muuFG?= =?us-ascii?Q?e2HRoVo8SOg3LlomdEixOtcwYIgdSue8LSGrGL2tRcTutaPxfFynWKupD2SE?= =?us-ascii?Q?2i3eNa3RCnUZkMC6TMycvX17xNtAcaUKT/cC0Cjr00qHB6ektXySMabTDKSz?= =?us-ascii?Q?E7vh4KXgLrVNGwI1JfJImCMjcz4P7W/PFNG1KKQ3ToA+Mu8xkb3wITYHC/1P?= =?us-ascii?Q?A+dGr6DWX4uw0OFOKqQ+2f4oDDhEXqKGmjnqq1UeJuBzkQP2JLXFSmhBxKQK?= =?us-ascii?Q?cJRKlGL/5ibts/Oc8IybnjAq+P6xOo6svoONiyVweke+oBkkA3Kkd9MMSoIp?= =?us-ascii?Q?Qmw2bOrsRRb7K5mteOViik9t8M1251CsgoHZkwkcSTeyay5KORJa3iCi7QhY?= =?us-ascii?Q?0ruP00zwwy0TUXeAVtuVRUkHhufJPoGG+j8ofAi0j8wmYHwpJNsmR6eej9cU?= =?us-ascii?Q?hPUzkytm1M+p/cxR8Xp1O7Sd8EgI8/JTNmU9Py486OFASmTqfn0qt9H4oZlb?= =?us-ascii?Q?Qa/xQ7fKGb80BbLV5x65p2L9vC/pMLo1G9gnBkBDNR/B1rnzDgQC8Yx5iXLM?= =?us-ascii?Q?dtMUAmGRZ4qTb4bZuQPM0tzPQjBnGiFU6hKR/Cie/DsAVI2Ek0XpBt9Aadcn?= =?us-ascii?Q?fkAnBbq+BA9SVT3CF2zeL/oZ69t5pRtt2oNCh0Tn+2A3QZaBVnodeUST0XTH?= =?us-ascii?Q?mmGS8S0EybYdwE9N9wwrtuYmOwwYhkDgTd2ciSDO9bsTw+8Zs4IZMwW8N9Ag?= =?us-ascii?Q?rE65JrUW3X6bPf864jUUc1nEqkkS9yMor8TVkvZBzZwTPKen4Z5TE2rwMOC2?= =?us-ascii?Q?rCI452YMCW2IZkAFZy459O25Dd/J4y0w6y+G0lMXRp3q8cvK1itdWFuMy+dv?= =?us-ascii?Q?GOYHLTR+4g50BG3ct7zkxUe7Dc1hkShShhzhgdn5pSArnYDE0ECJCaNqT/oy?= =?us-ascii?Q?QxR5v0lCRcyQKKquNvG3UjeBpKB33NljhipMwLbysBrFzHVH7Ygp3jTclFcI?= =?us-ascii?Q?LrBEZVBFELtxf9b6RdxVSa3amw80nClu6rKhd3wf/O+g8FL1dwah8Mpr5EJU?= =?us-ascii?Q?+qhiFlFo0/pJY7nWyhBIF4INJ4ZC4D3gh+tcMhuFRKhIRaln0V9hBlJ7eBBH?= =?us-ascii?Q?a5WE7w3Id1HdA/LbdpKDmXKt3p2wRN7kHZK54hJNQogMDaeFnsiMmBca4tZW?= =?us-ascii?Q?D99PdkbVVgPH/5EV8/va+AN9ySUusqSNyODps74ze+bmcytLa5/h6jetM0aP?= =?us-ascii?Q?lgtMwrwKhm4/WVqs4YCL4/TKRP/Fqzna63o3WTCxvrmeHlM34cfNtJROTFt1?= =?us-ascii?Q?lrVws5KYj9LyiIyZUdAKHtVqkGfZwDt6M8eRPO3OLXxEbod1tooHkgA6kdGK?= =?us-ascii?Q?Os2XRERkYgzfPjlwIFj1cfmerO6RsUzQ1y0wBVZbPDMAtNy3RMGl?= X-OriginatorOrg: oracle.com X-MS-Exchange-CrossTenant-Network-Message-Id: 2d5804a9-9051-485f-f7e7-08da48ced99b X-MS-Exchange-CrossTenant-AuthSource: MN2PR10MB3213.namprd10.prod.outlook.com X-MS-Exchange-CrossTenant-AuthAs: Internal X-MS-Exchange-CrossTenant-OriginalArrivalTime: 07 Jun 2022 21:44:07.9092 (UTC) X-MS-Exchange-CrossTenant-FromEntityHeader: Hosted X-MS-Exchange-CrossTenant-Id: 4e2c6054-71cb-48f1-bd6c-3a9705aca71b X-MS-Exchange-CrossTenant-MailboxType: HOSTED X-MS-Exchange-CrossTenant-UserPrincipalName: HR8xJFW3xcx2dd5uUhAMG2c2966NPallrplQS8BjKiX5Plb4mxLmQfTem9YYJUbkh/PXH6Ye0bKKiibyqdo0cQ== X-MS-Exchange-Transport-CrossTenantHeadersStamped: BN0PR10MB5351 X-Proofpoint-Virus-Version: vendor=fsecure engine=2.50.10434:6.0.517, 18.0.874 definitions=2022-06-07_10:2022-06-07, 2022-06-07 signatures=0 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 mlxlogscore=999 spamscore=0 adultscore=0 suspectscore=0 malwarescore=0 phishscore=0 bulkscore=0 mlxscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.12.0-2204290000 definitions=main-2206070089 X-Proofpoint-ORIG-GUID: j1mK2OoUrZ5MC5QfkEq1bOUMWPRarerM X-Proofpoint-GUID: j1mK2OoUrZ5MC5QfkEq1bOUMWPRarerM X-Spam-Status: No, score=-12.9 required=5.0 tests=BAYES_00, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, GIT_PATCH_0, RCVD_IN_DNSWL_LOW, RCVD_IN_MSPIKE_H2, SPF_HELO_NONE, SPF_NONE, 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 X-BeenThere: gcc-patches@gcc.gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Gcc-patches mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 07 Jun 2022 21:44:14 -0000 gcc/ * doc/extend.texi (Common Function Attributes): Document debug_annotate_decl attribute. (Common Variable Attributes): Likewise. (Common Type Attributes): Likewise. Also document debug_annotate_type attribute. --- gcc/doc/extend.texi | 106 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 106 insertions(+) diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi index a2e2a303ff1..a4c114f0e81 100644 --- a/gcc/doc/extend.texi +++ b/gcc/doc/extend.texi @@ -2931,6 +2931,30 @@ extern __attribute__ ((alloc_size (1), malloc, nothrow)) StrongAlias (allocate, alloc); @end smallexample +@item debug_annotate_decl (@var{annotation}) +@cindex @code{debug_annotate_decl} function attribute +The @code{debug_annotate_decl} attribute is used to add arbitrary +string annotations to the debugging information produced for a given +declaration. The attribute accepts a single string argument, and may be +specified multiple times for a single declaration. The behavior is +to record the string argument in debug information generated for the +declaration. Currently, DWARF and BTF debug information are supported. +There is no effect on code generation; the attribute has no effect at +all if neither DWARF nor BTF are output. + +@smallexample +int foo (int a, int b) __attribute__((debug_annotate_decl ("my_tag"))); +@end smallexample + +@noindent +results in a DW_TAG_GNU_annotation DIE associating the string ``my_tag'' +to the function ``foo'', and/or a BTF_KIND_DECL_TAG BTF record to the +same effect. + +The @code{debug_annotate_decl} attribute can also be used for +variables and types (@pxref{Common Variable Attributes}, +@pxref{Common Type Attributes}.) + @item deprecated @itemx deprecated (@var{msg}) @cindex @code{deprecated} function attribute @@ -7510,6 +7534,42 @@ but not attributes that affect a symbol's linkage or visibility such as attribute is also not copied. @xref{Common Function Attributes}. @xref{Common Type Attributes}. +@item debug_annotate_decl (@var{annotation}) +@cindex @code{debug_annotate_decl} variable attribute +The @code{debug_annotate_decl} attribute is used to add arbitrary +string annotations to the debugging information produced for a given +declaration. The attribute accepts a single string argument, and may be +specified multiple times for a single declaration. The behavior is +to record the string argument in debug information generated for the +declaration. Currently, DWARF and BTF debug information are supported. +There is no effect on code generation; the attribute has no effect at +all if neither DWARF nor BTF are output. + +@smallexample +int my_var __attribute__((debug_annotate_decl ("my_tag"))) +@end smallexample + +@noindent +results in a DW_TAG_GNU_annotation DIE associating the string ``my_tag'' +to the ``my_var'', and/or a BTF_KIND_DECL_TAG BTF record to the same +effect. + +Annotations can be specified for declarations other than variables, +such as struct fields. For example: + +@smallexample +struct foo @{ + int * x __attribute__ ((debug_annotate_decl ("my_tag"))); +@}; +@end smallexample +has similar results, producing debug info which associates the string +``my_tag'' to the struct field ``x''. + +@noindent +The @code{debug_annotate_decl} attribute can also be used for +functions and types (@pxref{Common Function Attributes}, +@pxref{Common Type Attributes}.) + @item deprecated @itemx deprecated (@var{msg}) @cindex @code{deprecated} variable attribute @@ -8593,6 +8653,52 @@ A @{ /* @r{@dots{}} */ @}; struct __attribute__ ((copy ( (struct A *)0)) B @{ /* @r{@dots{}} */ @}; @end smallexample +@item debug_annotate_decl (@var{annotation}) +@cindex @code{debug_annotate_decl} type attribute +The @code{debug_annotate_decl} attribute is used to add arbitrary +string annotations to the debugging information produced for a given +type declaration. The attribute accepts a single string argument, and +may be specified multiple times for a type declaration. The behavior +is to record the string argument in the debug information generated +for the declaration. Currently, DWARF and BTF debug information are +supported. There is no effect on code generation; the attribute has no +effect at all if neither DWARF nor BTF are output. + +@smallexample +struct t @{ +/* @r{@dots{}} */ +@} __attribute__((debug_annotate_decl ("my_tag"))); +@end smallexample + +@noindent +results in a DW_TAG_GNU_annotation DIE associating the string +``my_tag'' to the ``struct t'', and/or a BTF_KIND_DECL_TAG BTF record +to the same effect. + +The @code{debug_annotate_decl} attribute can also be used for +variables and functions (@pxref{Common Variable Attributes}, +@pxref{Common Function Attributes}.) + +@item debug_annotate_type (@var{annotation}) +@cindex @code{debug_annotate_type} type attribute +The @code{debug_annotate_type} attribute is used to add arbitrary +string annotations to the debugging information produced for a given +type. The attribute accepts a single string argument, and may be +specified multiple times for a type declaration. The behavior is to +record the string argument in the debug information generated for the +type. Currently, DWARF and BTF debug information are supported. There +is no effect on code generation; the attribute has no effect at all if +neither DWARF nor BTF are output. + +@smallexample +int * __attribute__ ((debug_annotate_type ("foo"))) x; +@end smallexample + +@noindent +results in a DW_TAG_GNU_annotation DIE associating the string ``foo'' +to the pointer type of ``x'' in the case of DWARF, and/or a +BTF_KIND_TYPE_TAG entry to the same effect in case of BTF debug info. + @item deprecated @itemx deprecated (@var{msg}) @cindex @code{deprecated} type attribute -- 2.36.1