From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from dpdk.org (dpdk.org [92.243.14.124]) by inbox.dpdk.org (Postfix) with ESMTP id A7446A0350; Thu, 25 Jun 2020 09:21:55 +0200 (CEST) Received: from [92.243.14.124] (localhost [127.0.0.1]) by dpdk.org (Postfix) with ESMTP id BCBA81BC25; Thu, 25 Jun 2020 09:21:42 +0200 (CEST) Received: from us-smtp-1.mimecast.com (us-smtp-delivery-1.mimecast.com [207.211.31.120]) by dpdk.org (Postfix) with ESMTP id 8A40A1BC25 for ; Thu, 25 Jun 2020 09:21:41 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1593069701; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=5MtA9+aDmXbfmNNUV5JOxUAUevkUNp9Hyi5eb7dEkEE=; b=g+8X216+qWQYq/YEWKyAYeRvKVzLC5KPC7cNNMYGneHPaZNyh96NyvNI54BbuO21NZTCip IUSx5vGkVsFm4m/RNO9BoJ/RfHz7aYXKXEqlMt56vHgr/PD0C1lugwDIIKuHqSrL64P1P7 bCFJ8qk5O+RAqzRbUr3kVvLk5lSvV+Y= Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-511-zx9TLgqFPIGFgwnqX_5-7A-1; Thu, 25 Jun 2020 03:21:39 -0400 X-MC-Unique: zx9TLgqFPIGFgwnqX_5-7A-1 Received: from smtp.corp.redhat.com (int-mx06.intmail.prod.int.phx2.redhat.com [10.5.11.16]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id AA11BEC1A7; Thu, 25 Jun 2020 07:21:36 +0000 (UTC) Received: from dmarchan.remote.csb (unknown [10.40.193.229]) by smtp.corp.redhat.com (Postfix) with ESMTP id 6E1FC5C1D4; Thu, 25 Jun 2020 07:21:32 +0000 (UTC) From: David Marchand To: dev@dpdk.org Cc: thomas@monjalon.net, honnappa.nagarahalli@arm.com, techboard@dpdk.org, stable@dpdk.org, Ray Kinsella , Neil Horman , John McNamara , Marko Kovacevic , Nicolas Chautru , Konstantin Ananyev , Fiona Trahe , Ashish Gupta , Vladimir Medvedkin , Bernard Iremonger , Gage Eads , Olivier Matz , Kevin Laatz Date: Thu, 25 Jun 2020 09:21:12 +0200 Message-Id: <20200625072112.22351-4-david.marchand@redhat.com> In-Reply-To: <20200625072112.22351-1-david.marchand@redhat.com> References: <20200522065855.31056-1-david.marchand@redhat.com> <20200625072112.22351-1-david.marchand@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.16 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 8bit Subject: [dpdk-dev] [PATCH v2 3/3] lib: remind experimental status in library headers X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org Sender: "dev" The following libraries are experimental, all of their functions can be changed or removed: - librte_bbdev - librte_bpf - librte_compressdev - librte_fib - librte_flow_classify - librte_ipsec - librte_rcu - librte_rib - librte_stack - librte_telemetry Their status is properly announced in MAINTAINERS. Remind this status in their headers in a common fashion (aligned to ABI docs). Cc: stable@dpdk.org Signed-off-by: David Marchand --- Changes since v1: - updated wording following Honnappa comment --- doc/guides/contributing/abi_policy.rst | 8 +++++--- lib/librte_bbdev/rte_bbdev.h | 3 ++- lib/librte_bpf/rte_bpf.h | 6 +++++- lib/librte_compressdev/rte_compressdev.h | 6 +++++- lib/librte_fib/rte_fib.h | 7 +++++++ lib/librte_fib/rte_fib6.h | 7 +++++++ lib/librte_flow_classify/rte_flow_classify.h | 6 ++++-- lib/librte_ipsec/rte_ipsec.h | 6 +++++- lib/librte_rcu/rte_rcu_qsbr.h | 7 ++++++- lib/librte_rib/rte_rib.h | 7 +++++++ lib/librte_rib/rte_rib6.h | 7 +++++++ lib/librte_stack/rte_stack.h | 7 +++++-- lib/librte_telemetry/rte_telemetry.h | 10 ++++++---- 13 files changed, 71 insertions(+), 16 deletions(-) diff --git a/doc/guides/contributing/abi_policy.rst b/doc/guides/contributing/abi_policy.rst index 1b2fa27865..d0affa9e60 100644 --- a/doc/guides/contributing/abi_policy.rst +++ b/doc/guides/contributing/abi_policy.rst @@ -27,7 +27,8 @@ General Guidelines #. The removal of symbols is considered an :ref:`ABI breakage `, once approved these will form part of the next ABI version. #. Libraries or APIs marked as :ref:`experimental ` may - change without constraint, as they are not considered part of an ABI version. + be changed or removed without prior notice, as they are not considered part + of an ABI version. #. Updates to the :ref:`minimum hardware requirements `, which drop support for hardware which was previously supported, should be treated as an ABI change. @@ -294,7 +295,7 @@ APIs ~~~~ APIs marked as ``experimental`` are not considered part of an ABI version and -may change without warning at any time. Since changes to APIs are most likely +may be changed or removed without prior notice. Since changes to APIs are most likely immediately after their introduction, as users begin to take advantage of those new APIs and start finding issues with them, new DPDK APIs will be automatically marked as ``experimental`` to allow for a period of stabilization before they @@ -330,4 +331,5 @@ Libraries ~~~~~~~~~ Libraries marked as ``experimental`` are entirely not considered part of an ABI -version, and may change without warning at any time. +version. +All functions in such libraries may be changed or removed without prior notice. diff --git a/lib/librte_bbdev/rte_bbdev.h b/lib/librte_bbdev/rte_bbdev.h index ecd95a823d..57291373fa 100644 --- a/lib/librte_bbdev/rte_bbdev.h +++ b/lib/librte_bbdev/rte_bbdev.h @@ -11,7 +11,8 @@ * Wireless base band device abstraction APIs. * * @warning - * @b EXPERIMENTAL: this API may change without prior notice + * @b EXPERIMENTAL: + * All functions in this file may be changed or removed without prior notice. * * This API allows an application to discover, configure and use a device to * process operations. An asynchronous API (enqueue, followed by later dequeue) diff --git a/lib/librte_bpf/rte_bpf.h b/lib/librte_bpf/rte_bpf.h index cbf1cddaca..e2d419b4ef 100644 --- a/lib/librte_bpf/rte_bpf.h +++ b/lib/librte_bpf/rte_bpf.h @@ -7,9 +7,13 @@ /** * @file rte_bpf.h - * @b EXPERIMENTAL: this API may change without prior notice * * RTE BPF support. + * + * @warning + * @b EXPERIMENTAL: + * All functions in this file may be changed or removed without prior notice. + * * librte_bpf provides a framework to load and execute eBPF bytecode * inside user-space dpdk based applications. * It supports basic set of features from eBPF spec diff --git a/lib/librte_compressdev/rte_compressdev.h b/lib/librte_compressdev/rte_compressdev.h index 8052efe675..2840c27c6c 100644 --- a/lib/librte_compressdev/rte_compressdev.h +++ b/lib/librte_compressdev/rte_compressdev.h @@ -8,7 +8,11 @@ /** * @file rte_compressdev.h * - * RTE Compression Device APIs + * RTE Compression Device APIs. + * + * @warning + * @b EXPERIMENTAL: + * All functions in this file may be changed or removed without prior notice. * * Defines comp device APIs for the provisioning of compression operations. */ diff --git a/lib/librte_fib/rte_fib.h b/lib/librte_fib/rte_fib.h index af3bbf07ee..84ee774d2d 100644 --- a/lib/librte_fib/rte_fib.h +++ b/lib/librte_fib/rte_fib.h @@ -8,6 +8,13 @@ /** * @file + * + * RTE FIB library. + * + * @warning + * @b EXPERIMENTAL: + * All functions in this file may be changed or removed without prior notice. + * * FIB (Forwarding information base) implementation * for IPv4 Longest Prefix Match */ diff --git a/lib/librte_fib/rte_fib6.h b/lib/librte_fib/rte_fib6.h index 66c71c84c9..bbfcf23a85 100644 --- a/lib/librte_fib/rte_fib6.h +++ b/lib/librte_fib/rte_fib6.h @@ -8,6 +8,13 @@ /** * @file + * + * RTE FIB6 library. + * + * @warning + * @b EXPERIMENTAL: + * All functions in this file may be changed or removed without prior notice. + * * FIB (Forwarding information base) implementation * for IPv6 Longest Prefix Match */ diff --git a/lib/librte_flow_classify/rte_flow_classify.h b/lib/librte_flow_classify/rte_flow_classify.h index 74d1ecaf50..82ea92b6a6 100644 --- a/lib/librte_flow_classify/rte_flow_classify.h +++ b/lib/librte_flow_classify/rte_flow_classify.h @@ -8,9 +8,11 @@ /** * @file * - * RTE Flow Classify Library + * RTE Flow Classify Library. * - * @b EXPERIMENTAL: this API may change without prior notice + * @warning + * @b EXPERIMENTAL: + * All functions in this file may be changed or removed without prior notice. * * This library provides flow record information with some measured properties. * diff --git a/lib/librte_ipsec/rte_ipsec.h b/lib/librte_ipsec/rte_ipsec.h index 6666cf7619..de05f4e932 100644 --- a/lib/librte_ipsec/rte_ipsec.h +++ b/lib/librte_ipsec/rte_ipsec.h @@ -7,9 +7,13 @@ /** * @file rte_ipsec.h - * @b EXPERIMENTAL: this API may change without prior notice * * RTE IPsec support. + * + * @warning + * @b EXPERIMENTAL: + * All functions in this file may be changed or removed without prior notice. + * * librte_ipsec provides a framework for data-path IPsec protocol * processing (ESP/AH). */ diff --git a/lib/librte_rcu/rte_rcu_qsbr.h b/lib/librte_rcu/rte_rcu_qsbr.h index fd4eb52b7f..a98e8f0f82 100644 --- a/lib/librte_rcu/rte_rcu_qsbr.h +++ b/lib/librte_rcu/rte_rcu_qsbr.h @@ -7,7 +7,12 @@ /** * @file - * RTE Quiescent State Based Reclamation (QSBR) + * + * RTE Quiescent State Based Reclamation (QSBR). + * + * @warning + * @b EXPERIMENTAL: + * All functions in this file may be changed or removed without prior notice. * * Quiescent State (QS) is any point in the thread execution * where the thread does not hold a reference to a data structure diff --git a/lib/librte_rib/rte_rib.h b/lib/librte_rib/rte_rib.h index 6b70de980a..da558c417e 100644 --- a/lib/librte_rib/rte_rib.h +++ b/lib/librte_rib/rte_rib.h @@ -8,6 +8,13 @@ /** * @file + * + * RTE RIB library. + * + * @warning + * @b EXPERIMENTAL: + * All functions in this file may be changed or removed without prior notice. + * * Level compressed tree implementation for IPv4 Longest Prefix Match */ diff --git a/lib/librte_rib/rte_rib6.h b/lib/librte_rib/rte_rib6.h index 871457138d..4b284c913c 100644 --- a/lib/librte_rib/rte_rib6.h +++ b/lib/librte_rib/rte_rib6.h @@ -8,6 +8,13 @@ /** * @file + * + * RTE rib6 library. + * + * @warning + * @b EXPERIMENTAL: + * All functions in this file may be changed or removed without prior notice. + * * Level compressed tree implementation for IPv6 Longest Prefix Match */ diff --git a/lib/librte_stack/rte_stack.h b/lib/librte_stack/rte_stack.h index 27ddb199e5..abf6420766 100644 --- a/lib/librte_stack/rte_stack.h +++ b/lib/librte_stack/rte_stack.h @@ -4,9 +4,12 @@ /** * @file rte_stack.h - * @b EXPERIMENTAL: this API may change without prior notice * - * RTE Stack + * RTE Stack. + * + * @warning + * @b EXPERIMENTAL: + * All functions in this file may be changed or removed without prior notice. * * librte_stack provides an API for configuration and use of a bounded stack of * pointers. Push and pop operations are MT-safe, allowing concurrent access, diff --git a/lib/librte_telemetry/rte_telemetry.h b/lib/librte_telemetry/rte_telemetry.h index eb7f2c917c..d13010b8fb 100644 --- a/lib/librte_telemetry/rte_telemetry.h +++ b/lib/librte_telemetry/rte_telemetry.h @@ -20,11 +20,13 @@ #define RTE_TEL_MAX_ARRAY_ENTRIES 512 /** - * @warning - * @b EXPERIMENTAL: all functions in this file may change without prior notice - * * @file - * RTE Telemetry + * + * RTE Telemetry. + * + * @warning + * @b EXPERIMENTAL: + * All functions in this file may be changed or removed without prior notice. * * The telemetry library provides a method to retrieve statistics from * DPDK by sending a request message over a socket. DPDK will send -- 2.23.0