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 773FE3856DE8 for ; Tue, 11 Jul 2023 21:59:10 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org 773FE3856DE8 Authentication-Results: sourceware.org; dmarc=pass (p=none dis=none) header.from=oracle.com Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=oracle.com Received: from pps.filterd (m0333521.ppops.net [127.0.0.1]) by mx0b-00069f02.pphosted.com (8.17.1.19/8.17.1.19) with ESMTP id 36BICxLd019628; Tue, 11 Jul 2023 21:59:09 GMT DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=oracle.com; h=from : to : cc : subject : date : message-id : in-reply-to : references : content-transfer-encoding : content-type : mime-version; s=corp-2023-03-30; bh=uc57RZlKzZ2eAlk12X1J9r2HQg7/gkIH4N+Arc61wJQ=; b=1wzgujfRAACJ3kvHQmFypgcHcq0rpT7B2tothG10bX37PXwBPcR9EzpHWCEdl0BDilmX yBQehjhlgxqtthTRWxK6NfmrG6CwwWMu+1/DMKlbIolwAMW+KWShC4DK4MbpnqJCkUtl SzOafrw7GBllZcw9m6Pj2feG5DruIqclP9b8zXqerf75EYIbiRiPvOSFrWgfgo9c9OHp VWI2SjUy4t2WBnY5tSeZkbFPoDL9oEbXkQ47mTPaNbA8KPSxiYGF7WeP9bY8mmcJ9P8T +E4VQIpZKn8Vb5CW+Gtmio6qhPYemR1qJBm6CRmmdPGZUdnTYu++4/CyfXRhgMjdh9x4 aw== Received: from phxpaimrmta01.imrmtpd1.prodappphxaev1.oraclevcn.com (phxpaimrmta01.appoci.oracle.com [138.1.114.2]) by mx0b-00069f02.pphosted.com (PPS) with ESMTPS id 3rrgn7ut7r-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Tue, 11 Jul 2023 21:59:08 +0000 Received: from pps.filterd (phxpaimrmta01.imrmtpd1.prodappphxaev1.oraclevcn.com [127.0.0.1]) by phxpaimrmta01.imrmtpd1.prodappphxaev1.oraclevcn.com (8.17.1.19/8.17.1.19) with ESMTP id 36BK1xpq026912; Tue, 11 Jul 2023 21:59:07 GMT Received: from nam02-dm3-obe.outbound.protection.outlook.com (mail-dm3nam02lp2042.outbound.protection.outlook.com [104.47.56.42]) by phxpaimrmta01.imrmtpd1.prodappphxaev1.oraclevcn.com (PPS) with ESMTPS id 3rpx85hjmv-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Tue, 11 Jul 2023 21:59:07 +0000 ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=Th3570PXD8fJoKKsKA2OY6+rOCPmMMPeyxpmbpNHG9QONgiGZcnhrn2OACnuMlMA9VpcA2hCFXuq7qiV6j6kC8G4IR91pK7yXfu2QFSMVeRjiZ59Opcqxg4FBvo4z+Ow75baJjVDKf3hMVZXVD/gzmYDsamuZBczYlZSGATm7Uuo2CaunMgn7rQYPlah3XGdPaqOLJ1vDAFZ+xuPif/yCnaZoFP/iwvL6CoAuw2IcrNs1+9IuAHNMa/UCLxLziQUjB5xlOC4MEJZCTP0xPF5BpNu69IB4R4ahNZr2t6Q4gw4mAaH8rRbE0CVQVsCBMVbJBcHXHovmq2sEX3BcFR4fw== 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=uc57RZlKzZ2eAlk12X1J9r2HQg7/gkIH4N+Arc61wJQ=; b=Z5sZq51TawYe482aCnBRFH0LauJqneCs6NRUetfgd31G4blye0L4vpUEzZ66gkZgXlLbylm6k3o6Znry/xH4cpn/3rV8bptooVSZ5mTlr5RB7ojgvqkci5bOKOVynZdxs0/7B2V+9Pg5O/HWpPJIILFjdKKYqeVvhJryeyruRKAhPUML2HCXnttzWqjnKCkvZc8HM/Z8UxQEv9+BDJseq7wvZJcORYC0Hiqbr701s+L6/IXgxE2lio/KqYfbkhnjid2+/JYzht3SnL6zheOaR1zwcosYM71h1kpIrHDUqapWlJftf2LLLyNM7Z+83KA6H8XJp48WZvWAiFht7ji79A== 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 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=oracle.onmicrosoft.com; s=selector2-oracle-onmicrosoft-com; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=uc57RZlKzZ2eAlk12X1J9r2HQg7/gkIH4N+Arc61wJQ=; b=hZshlIxJSYcO8Yo5MHj/pcHRboEuFf24GAGOvyO4eCgy8f251toaxLwMl1axsSLgMfR/2CbFW9+jGlc1UseKS9qj/blE9jSqckNZ5+hUK3+CreU5j0cNyocTwzwS08BPRo+GmkSJ0jNnJOY1Xxh8e9VwcQ5pC6cteDdueNjdZ5Y= Received: from MN2PR10MB3213.namprd10.prod.outlook.com (2603:10b6:208:131::33) by CO6PR10MB5650.namprd10.prod.outlook.com (2603:10b6:303:14f::20) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.6565.30; Tue, 11 Jul 2023 21:59:05 +0000 Received: from MN2PR10MB3213.namprd10.prod.outlook.com ([fe80::1797:59c3:a40e:f8ab]) by MN2PR10MB3213.namprd10.prod.outlook.com ([fe80::1797:59c3:a40e:f8ab%4]) with mapi id 15.20.6565.028; Tue, 11 Jul 2023 21:59:05 +0000 From: David Faust To: gcc-patches@gcc.gnu.org Cc: jose.marchesi@oracle.com, yhs@meta.com Subject: [PATCH 9/9] doc: document btf_decl_tag attribute Date: Tue, 11 Jul 2023 14:57:16 -0700 Message-Id: <20230711215716.12980-10-david.faust@oracle.com> X-Mailer: git-send-email 2.39.1 In-Reply-To: <20230711215716.12980-1-david.faust@oracle.com> References: <20230711215716.12980-1-david.faust@oracle.com> Content-Transfer-Encoding: 8bit Content-Type: text/plain X-ClientProxiedBy: SN4PR0501CA0110.namprd05.prod.outlook.com (2603:10b6:803:42::27) To MN2PR10MB3213.namprd10.prod.outlook.com (2603:10b6:208:131::33) MIME-Version: 1.0 X-MS-PublicTrafficType: Email X-MS-TrafficTypeDiagnostic: MN2PR10MB3213:EE_|CO6PR10MB5650:EE_ X-MS-Office365-Filtering-Correlation-Id: 397b1e1a-9304-4c35-9ea2-08db825a0b78 X-MS-Exchange-SenderADCheck: 1 X-MS-Exchange-AntiSpam-Relay: 0 X-Microsoft-Antispam: BCL:0; X-Microsoft-Antispam-Message-Info: DQaPYEI5PvZx+eSOEn7JKqMSXOkaA88ZjMAVNsaT0FRkvOZua+M59iyT3oiUFPyMEsTTFa+HVHQW5k5MiQtXQA9XbruwDhyGUa7ZY0X63aAwgKTDDgtayqgk1UsQLhMPBBDMMAozFXiPFSOvQM10hRnTEbDiNCrgSokY4TQyBUKc4/53Lst8KSgWufVRuK4DQZxnY3TeI/L8FiA7RM/XRavn40yG2vZIAFhEA6+DfweHwARwjeudJoWCDwkX4Tu+0c4FBqeWzwvRceXizVY6pey4jAaRuSWrRFHbCeAFXFy+G80h3sCT0itbma9LM0hcpN8cXKaFQnUfZjNVY6G7TnChgKXtY5x5AUgHb4NKTTdJhssaIKySBytyRlDwImIAUYuChi8dYIR9V4x/totXebgMQ+6ui7agYAahiMivWVOmNmDxsX/632FyDU33GrcbBiFlr9VZib5Jx/13VVJgT4a8CryDiDJYmJDS+z93vuXw2d3dk9UZBqzxN+HJ9FLIsEtkwh45WQcsm08/zDBh9ybnf6IuZix+YuGIncc6ogQJL+4qX7WPQ78j6jvKhLj3 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:(13230028)(39860400002)(346002)(136003)(376002)(396003)(366004)(451199021)(86362001)(38100700002)(36756003)(6486002)(6666004)(6506007)(26005)(186003)(1076003)(6512007)(2616005)(5660300002)(2906002)(316002)(66556008)(66946007)(66476007)(8676002)(44832011)(8936002)(83380400001)(4326008)(478600001)(6916009)(41300700001);DIR:OUT;SFP:1101; X-MS-Exchange-AntiSpam-MessageData-ChunkCount: 1 X-MS-Exchange-AntiSpam-MessageData-0: =?us-ascii?Q?hc45cv3ruPEK+uQ5JMJVmqUdvTmV71hhdi4uDhclXx9oFIV6lE+W1jZ7PHRC?= =?us-ascii?Q?NHPLa7hDMqjYrRiLFHqe+3gTc8PLTrjU2KYHcpVrBDu8hD9fMHxlzk7lUDPJ?= =?us-ascii?Q?tAIi+jGa4FhPta+W+qoYBYQAshbWkwX9x1bH7nBzxBTxHYS/zXOhgUIcjh3y?= =?us-ascii?Q?LqrKISjZbYahIZc3Efm9k2+vGFxT10PUd4fAbdP4Lqb0gKC6eYDPCLovDLeK?= =?us-ascii?Q?Z2XYukzBfnAuY9553npouaQlGbC4U+sb2nwZqLzEidcOEkjDI5bpMqDtlXcp?= =?us-ascii?Q?Zd+WaNIFYu8NMR+QHek45IwzKaZafxtDknK2qZLp98dICTxEPgrnZXxWbGem?= =?us-ascii?Q?P3DDMEuweYBDxFvOlcva3gJZMvFn9+7+bZ0g0UYrXg77/IjX8xaH9vpU2Sme?= =?us-ascii?Q?K445FC6qG+Iv/+OAXOWcSQAogtdKA3+vAX7J0hUXf7BFvQsoXJxt1ZhyW0+p?= =?us-ascii?Q?ipcnOlAtXG2Cxdmwk0B4v8edtSyIQZM9iE/pimWTjNK3VTNXRDMHKNyzpNyq?= =?us-ascii?Q?Zi1Q5KEVXGS5DX+IudVIqeaeBIX+mHvANjyet5vKk+WPE+yIct4upIud2UHW?= =?us-ascii?Q?+19tV5KMw7Q3gDBknd21b12KwPjLDKzT5+IacV0/Sg94MVNFdWLBtFbSjoZL?= =?us-ascii?Q?P5sfHLIqw1AhqdNETT63alQ8zSkNKEsurG4EtXp1R/O/2ec0/yzih4fdfnCo?= =?us-ascii?Q?0cFyTOZ5DrlwFn3liD3OXUZhJDdhJPSay4TYq8vzbTeMNS7OhHfBW9fuzXU9?= =?us-ascii?Q?3azho7X3gt2wX63RNP2rPrRlFkrfoH3aNqhIMBIuqW/07Yi8uA3pnDFkx9vK?= =?us-ascii?Q?IQs0MxSJfH9iMQAdE4Q7nN1A9GujwfHCXY9FjSsV4dQBRKGln6MfHx73zm7s?= =?us-ascii?Q?vVYY6mGMT3O6OoGzpZeKoEo+TX4fe3WZreZIyKiAjNnqskEmGS4d5z2ud4JP?= =?us-ascii?Q?3jsRko5lDxwF2qZSpdYJFMboZyKtCqQrxGA0jKAkd8c/TYzzP8nDa0/k78ka?= =?us-ascii?Q?FTOK+W3z9CElBHnBFUnVn+uLfqzu4fFns9S+DqNYx/GL68sW3h7OMAPRQAwy?= =?us-ascii?Q?ujsrX+42g2mujN1G16bsNR53AuFo4uQvZKYE5QZWuw6tciTfD1UwLWy5BUqA?= =?us-ascii?Q?cHoMWXjOmxQlP270/Xbhis1tLQdJOUFapXL7vJO4ZOa+GWQ32GozwhRFO4gB?= =?us-ascii?Q?VeiHyS3GRq9ZCPTV52g2A5v+5pBtZKnLFsBSrCRt5pJap8aq907gpJHyR/uU?= =?us-ascii?Q?P/KooCM/sigVPmE/pLJm5NgZ558yufy6RLtg3F+40NmB3hbpagEGBDtJixZV?= =?us-ascii?Q?Zr2Lb5HZcFv19cnyVnMYN2O4FqHOg65MQxOA1mYhiic5SJ4X/J+LiQxYwLpV?= =?us-ascii?Q?m9iaNEtHjJ60RF7H2iQEM57cLvbMKnGC5zvzL5z2D0PusQYGq+UVKHRMxcJ3?= =?us-ascii?Q?E3T3fSVc3KyOb8dvxzLtL3xEyv5Cz1hji1LN1+trzH+QJbiEaq0t2boGW0BZ?= =?us-ascii?Q?NLCPq8mma1mQ0bgDWJT8XVZA4TjLBWabQdtm9KvY8hVoUbtEJ+9wqMXCuRap?= =?us-ascii?Q?X2Uibf9uCYp2L6lgZcSdCsVpVzEuJawwNC776jgV?= X-MS-Exchange-AntiSpam-ExternalHop-MessageData-ChunkCount: 1 X-MS-Exchange-AntiSpam-ExternalHop-MessageData-0: DmlmeY2RgupNGyDhwBFUbrv+pjKlJfVO3uhGVddjHzaVMootP5aX9Mexz5gzXEd45Wty5M8h0DLL8ZFbZSiglFAwntAOq0uhS4pK22SjpSgmaCE4TZBJya07FGYsI7XvraK4jg15ZXWdsVM1vevss51FrlmgKSIr9jogfIaadOBh9wj0nSoDDfuGIA9J9W4Q3CHHouowZRvlh0IR068W37ShfLLBSCKRqIQeabq9yCIkRrZ+D8tZ327J91XQoV0p1e50fG+EpM2b0sICxtORjgo7y8SXmScxLJsPWrBYvuG3fFZpsqeI2InxQCWgYu9TrnUZoLlEN2KFLYgt2rmQQMGd44YjQvNeAj3Eepd7zAV0b7xSI6S7TXMeEmkOwfCl2l8MKdl0tgAaBx892woaHHV9kC1pMI5dyrSGjsJzqjv4A2dTssUsruMVrCQWvHYesV1z/zgOhPuULxHKNwN6WqaVGPpxuDuqaHMQ49XkzFkjyfVLdEPizC0ceT2DtQ1UEgc65alNGy5Uy1a/PdJUyqv0pvUmRH5HJJ3aZPv7BwGQ8hv4HKMeO0d6vSNnt881TyehrMbXHRlUnXs4xH52Ny/BPemW6uSLKLoY3csF3lAKD3oe95RtNRHvRhSr3wsdEsLyXDsqsghUT0GKVvyJ06CRwgWqj2c6XIqNZhv7BpQELjx/rjjnswQZcJUxu4uElAz/Rkz9P0bD1nHE3CKEFSGYWxCOYiyaZHaJkLOr+3IDKv84waPVaAg8/tK2fOapKJuY+WslblGCnEbZtRtQmQ== X-OriginatorOrg: oracle.com X-MS-Exchange-CrossTenant-Network-Message-Id: 397b1e1a-9304-4c35-9ea2-08db825a0b78 X-MS-Exchange-CrossTenant-AuthSource: MN2PR10MB3213.namprd10.prod.outlook.com X-MS-Exchange-CrossTenant-AuthAs: Internal X-MS-Exchange-CrossTenant-OriginalArrivalTime: 11 Jul 2023 21:59:05.6627 (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: 7R/lRlfsQlawu/WfniNnOwm03KvDuCu9dzGGcJnQ6ewydHxNxP+Gol9AXm3UFa/UMO3S5zi2/JuEmQfP6Edn6g== X-MS-Exchange-Transport-CrossTenantHeadersStamped: CO6PR10MB5650 X-Proofpoint-Virus-Version: vendor=baseguard engine=ICAP:2.0.254,Aquarius:18.0.957,Hydra:6.0.591,FMLib:17.11.176.26 definitions=2023-07-11_12,2023-07-11_01,2023-05-22_02 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 adultscore=0 mlxscore=0 bulkscore=0 suspectscore=0 spamscore=0 phishscore=0 mlxlogscore=971 malwarescore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.12.0-2305260000 definitions=main-2307110200 X-Proofpoint-ORIG-GUID: dQTaSWjlfgnQckxSHVBrE0YlyBIMxGw_ X-Proofpoint-GUID: dQTaSWjlfgnQckxSHVBrE0YlyBIMxGw_ X-Spam-Status: No, score=-13.4 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_H5,RCVD_IN_MSPIKE_WL,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 List-Id: Add documentation for the btf_decl_tag attribute. gcc/ * doc/extend.texi (Common Function Attributes): Document btf_decl_tag. (Common Variable Attributes): Likewise. --- gcc/doc/extend.texi | 47 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi index d88fd75e06e..57923621c46 100644 --- a/gcc/doc/extend.texi +++ b/gcc/doc/extend.texi @@ -2856,6 +2856,29 @@ declares that @code{my_alloc1} returns 16-byte aligned pointers and that @code{my_alloc2} returns a pointer whose value modulo 32 is equal to 8. +@cindex @code{btf_decl_tag} function attribute +@item btf_type_tag (@var{argument}) +The @code{btf_decl_tag} attribute may be used to associate (to ``tag'') +function declarations with arbitrary strings. Debugging information will +be emitted to associate the @var{argument} string with the attributed function. +In DWARF, a @code{DW_TAG_GNU_annotation} DIE will be emitted in the DWARF +information as a child of the DIE for the function and holding the +@var{argument} string. In BTF, a @code{BTF_KIND_DECL_TAG} record is emitted +in the .BTF ELF section. + +For example + +@smallexample +extern int bar (char, int) __attribute__((btf_decl_tag("for_user"))) +@end smallexample + +associates the string ``for_user'' to the function ``bar''. This +string will be recorded in the BTF and/or DWARF information associated +with the function. + +The @code{btf_decl_tag} attribute can also be used on variables +(@pxref{Common Variable Attributes}) and field declarations. + @cindex @code{cold} function attribute @item cold The @code{cold} attribute on functions is used to inform the compiler that @@ -7570,6 +7593,30 @@ This warning can be disabled by @option{-Wno-if-not-aligned}. The @code{warn_if_not_aligned} attribute can also be used for types (@pxref{Common Type Attributes}.) +@cindex @code{btf_decl_tag} variable attribute +@item btf_decl_tag (@var{argument}) +The @code{btf_decl_tag} attribute may be used to associate (to ``tag'') +variable declarations with arbitrary strings. Debugging information will +be emitted to associate the @var{argument} string with the attributed variable. +In DWARF, a @code{DW_TAG_GNU_annotation} DIE will be emitted in the DWARF +information as a child of the DIE for the variable and holding the +@var{argument} string. In BTF, a @code{BTF_KIND_DECL_TAG} record is emitted +in the .BTF ELF section. + +For example + +@smallexample +int * foo __attribute__((btf_decl_tag("user"))); +@end smallexample + +@noindent +associates the string ``user'' to the variable ``foo''. This string +will be recorded in the BTF and/or DWARF information associated with +the variable. + +The @code{btf_decl_tag} attribute can also be used on functions +(@pxref{Common Function Attributes}) and field declarations. + @cindex @code{strict_flex_array} variable attribute @item strict_flex_array (@var{level}) The @code{strict_flex_array} attribute should be attached to the trailing -- 2.40.1