From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124]) by inbox.dpdk.org (Postfix) with ESMTP id 35C5643C3A; Sat, 2 Mar 2024 15:03:09 +0100 (CET) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 74BE142DE7; Sat, 2 Mar 2024 15:02:26 +0100 (CET) Received: from EUR04-DB3-obe.outbound.protection.outlook.com (mail-db3eur04on2059.outbound.protection.outlook.com [40.107.6.59]) by mails.dpdk.org (Postfix) with ESMTP id 5E01642DB6 for ; Sat, 2 Mar 2024 15:02:21 +0100 (CET) ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=lyl5gM3x8R3NRvoUZPEZC0FJntKkfcaaDJWsSoxkzGDGL9mQ7is20tLggBY/vYkN829ktZ/J1aC0sf0PaXPAiR2F4deHSS2PZtF/C0EE9xIO/8hb7TQSW6Qz3tyBcP22Bp4w32odK3p3T/WquQNMX1EcQYDvmeMTEC37cZFs82sApGf/vleFI3REbISwccGlLF8Laqw4YxePbApYBL8B4HSAzoWHg4louz2wh6aDEPUOoMinyPsd0w4Dzfc2tSc/IU72xyft7L4FF+5/DhTHMrczN+GR38rDQronmcbzwsZ0HsYu3KsJ7yozRvm96WCvoOPzI2YOZ7y+9DXxpyBUUA== 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=/X/Y07R5vgas+EGUx5s6N1Q9VFslIyXUX7RVzHEHoUs=; b=R0trabEMRWKxTi/x9fTNKLNXh4tU8ypKus5+AFMvG9AK1CWgHMLpb0ZCSDlNSbbpKVWHkViur7JgvaxayULWme0FF2zH5euLTbXeXRA7EtGQqWpgWKVTlPNI/CavieIsPIKkTnpndXypnXvaWSGQK0IZ4CoQs/o8KGmvvTadE2m/+2Sn94Yn09gv1DUmfh2MWSB2500vcywE/TsCH9N2gE8eZRalXpruSZrYlxaZn0AnhztvwqPPmcD9rH3F0Veiqy8aLMUTz0FTjFQLHDAGIuh3NdPHu2lUad/RhBHrMDonMOzSiWQNvx9TFtH11Rfc1CtpKoiCh3hhhFKkh2N+Jw== ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=pass (sender ip is 192.176.1.74) smtp.rcpttodomain=dpdk.org smtp.mailfrom=ericsson.com; dmarc=pass (p=reject sp=reject pct=100) action=none header.from=ericsson.com; dkim=none (message not signed); arc=none (0) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=ericsson.com; s=selector1; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=/X/Y07R5vgas+EGUx5s6N1Q9VFslIyXUX7RVzHEHoUs=; b=aS2uNuRm6W5ld95NBaJBRpRiD8ed+kV+PmLkqg/ySbpkEnbUeViwcQa94rnMUuBdg8832SLTK0DjjA2QfteoMXHkj76IdpfGKlfjPYQtbKsVtlx5K/6GV/kSsedOsFpw+Jb3KOo5wnq9cwAD7uI0mBYtvkYcXNWe8mJ+PfhUdiXzFrMmD90wtD+GtJaYfyQcpn1EarFmcaX475q1emKYYChYvavgE4RzDSw+CvVOFPc8i8YJkCSW2JJKR9f+Z8YOSwnJ3hAj2jhXNw39LXnolvktu8Pbyjcr8C76dRdXJuUhq1AzSYhxLBXkXdGWALxUGgZza2LuibcMX6PA0vpidA== Received: from AS4PR09CA0007.eurprd09.prod.outlook.com (2603:10a6:20b:5e0::8) by AS8PR07MB7973.eurprd07.prod.outlook.com (2603:10a6:20b:396::12) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.7339.37; Sat, 2 Mar 2024 14:02:19 +0000 Received: from AM4PEPF00027A6A.eurprd04.prod.outlook.com (2603:10a6:20b:5e0:cafe::4b) by AS4PR09CA0007.outlook.office365.com (2603:10a6:20b:5e0::8) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.7339.34 via Frontend Transport; Sat, 2 Mar 2024 14:02:19 +0000 X-MS-Exchange-Authentication-Results: spf=pass (sender IP is 192.176.1.74) smtp.mailfrom=ericsson.com; dkim=none (message not signed) header.d=none;dmarc=pass action=none header.from=ericsson.com; Received-SPF: Pass (protection.outlook.com: domain of ericsson.com designates 192.176.1.74 as permitted sender) receiver=protection.outlook.com; client-ip=192.176.1.74; helo=oa.msg.ericsson.com; pr=C Received: from oa.msg.ericsson.com (192.176.1.74) by AM4PEPF00027A6A.mail.protection.outlook.com (10.167.16.88) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.7362.11 via Frontend Transport; Sat, 2 Mar 2024 14:02:19 +0000 Received: from seliicinfr00050.seli.gic.ericsson.se (153.88.142.248) by smtp-central.internal.ericsson.com (100.87.178.62) with Microsoft SMTP Server id 15.2.1258.12; Sat, 2 Mar 2024 15:02:18 +0100 Received: from breslau.. (seliicwb00002.seli.gic.ericsson.se [10.156.25.100]) by seliicinfr00050.seli.gic.ericsson.se (Postfix) with ESMTP id 7EB831C006A; Sat, 2 Mar 2024 15:02:18 +0100 (CET) From: =?UTF-8?q?Mattias=20R=C3=B6nnblom?= To: CC: , Heng Wang , =?UTF-8?q?Mattias=20R=C3=B6nnblom?= Subject: [RFC 7/7] eal: deprecate relaxed family of bit operations Date: Sat, 2 Mar 2024 14:53:28 +0100 Message-ID: <20240302135328.531940-8-mattias.ronnblom@ericsson.com> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20240302135328.531940-1-mattias.ronnblom@ericsson.com> References: <20240302135328.531940-1-mattias.ronnblom@ericsson.com> MIME-Version: 1.0 Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: 8bit X-EOPAttributedMessage: 0 X-MS-PublicTrafficType: Email X-MS-TrafficTypeDiagnostic: AM4PEPF00027A6A:EE_|AS8PR07MB7973:EE_ X-MS-Office365-Filtering-Correlation-Id: 8ed603ba-e22f-4b90-0e44-08dc3ac15fe7 X-MS-Exchange-SenderADCheck: 1 X-MS-Exchange-AntiSpam-Relay: 0 X-Microsoft-Antispam: BCL:0; X-Microsoft-Antispam-Message-Info: 8b3KaoePWhnngOvvU/2s0wKvtkl+S3EMxiwfb1GbMsds3g0GYP66uPxwYi1YP7syRyvLZv57pvJwFwqDLgA4xBLT3pvGJsmxZKMw9TO8776tCA/oZU+ujnxKa4zbU3Ogr1DU3WmkPhu9CdFPlmcVtXgZzajBMKFBd7XJmiiuoVaWguKbTwarwzU8QyRhvlo6x/C9bjL5P0Jk/h6gaadaZcyNb7rKP5M0802cwnKYG90bWiHGzCkeVZxqf81zWt1xcvcX1h5n2w9J49pprPncrlFaQWy1tzcY1Jx7dAAKIKKlFnBpOgmigcq8ySHSU29sXZcw4bszhZ0uBuEVx8cM8EUBun7wGio27kCkpX7Fcydbl6qMlzXhrQ70kq1yqaGf4NK5kee91yheGcsJExP9pu39O2iQRzaLufjM24clXWxpdMZimZe8lwuJsxxb8ggaWb5rDyXt4ihGz1qRrowmTWDHdWGjQjhHVqCEMUCejm7EtRaI3lazqr8dabIdvKWm46z+xopuNEEHtfFGp9pSFLFKpp2Xz7IzJmNriPb4Qq9QVGzqNXMdspERAPYgMQ0IxbeFhKB4mkserShM5zFTI/aCKgm4vFne7Dl4XH658K1LRVF+OdLv++r/VJtdvGEpsXHkS+LWFeYxSvH1m7RwfVzpucnuUz8TU6sb9b+b30LC5vSiBL4RuGQj/gksFCT/IsreUBSKpXv1bysHpPO0TY0YCUnNbED4p84jZY13HKaB0tL4DnsM829R3R+LiRvV X-Forefront-Antispam-Report: CIP:192.176.1.74; CTRY:SE; LANG:en; SCL:1; SRV:; IPV:NLI; SFV:NSPM; H:oa.msg.ericsson.com; PTR:office365.se.ericsson.net; CAT:NONE; SFS:(13230031)(82310400014)(36860700004)(376005); DIR:OUT; SFP:1101; X-OriginatorOrg: ericsson.com X-MS-Exchange-CrossTenant-OriginalArrivalTime: 02 Mar 2024 14:02:19.1219 (UTC) X-MS-Exchange-CrossTenant-Network-Message-Id: 8ed603ba-e22f-4b90-0e44-08dc3ac15fe7 X-MS-Exchange-CrossTenant-Id: 92e84ceb-fbfd-47ab-be52-080c6b87953f X-MS-Exchange-CrossTenant-OriginalAttributedTenantConnectingIp: TenantId=92e84ceb-fbfd-47ab-be52-080c6b87953f; Ip=[192.176.1.74]; Helo=[oa.msg.ericsson.com] X-MS-Exchange-CrossTenant-AuthSource: AM4PEPF00027A6A.eurprd04.prod.outlook.com X-MS-Exchange-CrossTenant-AuthAs: Anonymous X-MS-Exchange-CrossTenant-FromEntityHeader: HybridOnPrem X-MS-Exchange-Transport-CrossTenantHeadersStamped: AS8PR07MB7973 X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org Informally (by means of documentation) deprecate the rte_bit_relaxed_*() family of bit-level operations. rte_bit_relaxed_*() has been replaced by three new families of bit-level query and manipulation functions. rte_bit_relaxed_*() failed to deliver the atomicity guarantees their name suggested. If deprecated, it will encourage the user to consider whether the actual, implemented behavior (e.g., non-atomic test-and-set with read/write-once semantics) or the semantics implied by their names (i.e., atomic), or something else, is what's actually needed. Bugzilla ID: 1385 Signed-off-by: Mattias Rönnblom --- lib/eal/include/rte_bitops.h | 48 ++++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) diff --git a/lib/eal/include/rte_bitops.h b/lib/eal/include/rte_bitops.h index b5a9df5930..783dd0e1ee 100644 --- a/lib/eal/include/rte_bitops.h +++ b/lib/eal/include/rte_bitops.h @@ -1179,6 +1179,10 @@ __RTE_GEN_BIT_ATOMIC_OPS(64) * The address holding the bit. * @return * The target bit. + * @note + * This function is deprecated. Use rte_bit_test32(), + * rte_bit_once_test32(), or rte_bit_atomic_test32() instead, + * depending on exactly what guarantees are required. */ static inline uint32_t rte_bit_relaxed_get32(unsigned int nr, volatile uint32_t *addr) @@ -1196,6 +1200,10 @@ rte_bit_relaxed_get32(unsigned int nr, volatile uint32_t *addr) * The target bit to set. * @param addr * The address holding the bit. + * @note + * This function is deprecated. Use rte_bit_set32(), + * rte_bit_once_set32(), or rte_bit_atomic_set32() instead, + * depending on exactly what guarantees are required. */ static inline void rte_bit_relaxed_set32(unsigned int nr, volatile uint32_t *addr) @@ -1213,6 +1221,10 @@ rte_bit_relaxed_set32(unsigned int nr, volatile uint32_t *addr) * The target bit to clear. * @param addr * The address holding the bit. + * @note + * This function is deprecated. Use rte_bit_clear32(), + * rte_bit_once_clear32(), or rte_bit_atomic_clear32() instead, + * depending on exactly what guarantees are required. */ static inline void rte_bit_relaxed_clear32(unsigned int nr, volatile uint32_t *addr) @@ -1233,6 +1245,12 @@ rte_bit_relaxed_clear32(unsigned int nr, volatile uint32_t *addr) * The address holding the bit. * @return * The original bit. + * @note + * This function is deprecated and replaced by + * rte_bit_atomic_test_and_set32(), for use cases where the + * operation needs to be atomic. For non-atomic/non-ordered use + * cases, use rte_bit_test32() + rte_bit_set32() or + * rte_bit_once_test32() + rte_bit_once_set32(). */ static inline uint32_t rte_bit_relaxed_test_and_set32(unsigned int nr, volatile uint32_t *addr) @@ -1255,6 +1273,12 @@ rte_bit_relaxed_test_and_set32(unsigned int nr, volatile uint32_t *addr) * The address holding the bit. * @return * The original bit. + * @note + * This function is deprecated and replaced by + * rte_bit_atomic_test_and_clear32(), for use cases where the + * operation needs to be atomic. For non-atomic/non-ordered use + * cases, use rte_bit_test32() + rte_bit_clear32() or + * rte_bit_once_test32() + rte_bit_once_clear32(). */ static inline uint32_t rte_bit_relaxed_test_and_clear32(unsigned int nr, volatile uint32_t *addr) @@ -1278,6 +1302,10 @@ rte_bit_relaxed_test_and_clear32(unsigned int nr, volatile uint32_t *addr) * The address holding the bit. * @return * The target bit. + * @note + * This function is deprecated. Use rte_bit_test64(), + * rte_bit_once_test64(), or rte_bit_atomic_test64() instead, + * depending on exactly what guarantees are required. */ static inline uint64_t rte_bit_relaxed_get64(unsigned int nr, volatile uint64_t *addr) @@ -1295,6 +1323,10 @@ rte_bit_relaxed_get64(unsigned int nr, volatile uint64_t *addr) * The target bit to set. * @param addr * The address holding the bit. + * @note + * This function is deprecated. Use rte_bit_set64(), + * rte_bit_once_set64(), or rte_bit_atomic_set64() instead, + * depending on exactly what guarantees are required. */ static inline void rte_bit_relaxed_set64(unsigned int nr, volatile uint64_t *addr) @@ -1312,6 +1344,10 @@ rte_bit_relaxed_set64(unsigned int nr, volatile uint64_t *addr) * The target bit to clear. * @param addr * The address holding the bit. + * @note + * This function is deprecated. Use rte_bit_clear64(), + * rte_bit_once_clear64(), or rte_bit_atomic_clear64() instead, + * depending on exactly what guarantees are required. */ static inline void rte_bit_relaxed_clear64(unsigned int nr, volatile uint64_t *addr) @@ -1332,6 +1368,12 @@ rte_bit_relaxed_clear64(unsigned int nr, volatile uint64_t *addr) * The address holding the bit. * @return * The original bit. + * @note + * This function is deprecated and replaced by + * rte_bit_atomic_test_and_set64(), for use cases where the + * operation needs to be atomic. For non-atomic/non-ordered use + * cases, use rte_bit_test64() + rte_bit_set64() or + * rte_bit_once_test64() + rte_bit_once_set64(). */ static inline uint64_t rte_bit_relaxed_test_and_set64(unsigned int nr, volatile uint64_t *addr) @@ -1354,6 +1396,12 @@ rte_bit_relaxed_test_and_set64(unsigned int nr, volatile uint64_t *addr) * The address holding the bit. * @return * The original bit. + * @note + * This function is deprecated and replaced by + * rte_bit_atomic_test_and_clear64(), for use cases where the + * operation needs to be atomic. For non-atomic/non-ordered use + * cases, use rte_bit_test64() + rte_bit_clear64() or + * rte_bit_once_test64() + rte_bit_once_clear64(). */ static inline uint64_t rte_bit_relaxed_test_and_clear64(unsigned int nr, volatile uint64_t *addr) -- 2.34.1