From patchwork Wed May 1 03:54:16 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Honnappa Nagarahalli X-Patchwork-Id: 163167 Delivered-To: patch@linaro.org Received: by 2002:a92:7e86:0:0:0:0:0 with SMTP id q6csp4068231ill; Tue, 30 Apr 2019 20:54:44 -0700 (PDT) X-Google-Smtp-Source: APXvYqxOZ+d8EGUcJG4LY5OQq5rzpzAlYdO4wYGnE2YM6oABWnvYGICkcNHf7+fFkB+8L9fERzWX X-Received: by 2002:a50:8b95:: with SMTP id m21mr43639586edm.178.1556682884748; Tue, 30 Apr 2019 20:54:44 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1556682884; cv=none; d=google.com; s=arc-20160816; b=rKHRCMzbdXzLGEIw/kVyA9bnPkWf4WYzXR/rW2noUq0XvfI2xsi+KftC5BD/Pf2Oc3 FpAB2CopMZPvylsFP7ToOfEaJ/eThSnI33sAgP0/h66p9KSZ/uB0CGFQ7tBp38vPQlqJ dXnbLV9jd13T9Z7+9ZtbwnUk0z20CUgal/p8ldYqPfIz11F0i9GHCuStKZV4le8CXp/J BPG/J0HcsmHfkYzuhbKUtp2xf07ZNxq8oMY+h/GrCXST9Zd5VEPSQYwyn9qUQW5ZHVdG gCvKB223HPaPD1jZaYWwksjf5ynl5B4T7QMkneexq5L/r4YGxhIkV/S4JNb9yok63GMW wjyw== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:list-subscribe:list-help:list-post:list-archive :list-unsubscribe:list-id:precedence:subject:references:in-reply-to :message-id:date:cc:to:from; bh=HTMCkrchSbllM/FdbpUvRRl/bCJirQDYk4xhbuqIYpU=; b=DfAOdyArTUothWgcJorZN7X1e3lljQChecWSLZrEP1Uln73DdlrKOUMjAK66KL8rO3 GinG8Lmda0nJa3VTjG+zNgIiKu+TxJPsVrnzRL4RZIW7ejfidxn2iT6jc4TO4tN8H3It UZULlSjyyVZE4fblvMqY2II/9Ow+t+908q5fEjfH44qmxTYPCP+e2IVUeMb942lP/uQj +jZWuwdI4WnezaDhLzms1IvbMn+lS1mjx8efroD0kBqdQunC9YFohHzirqvtlOoyHiXv 4qR05Tb2cSnoCTZWzRPo7J9yAWreXlK0AqExK1SM1TZAlMd375ZFrZqjQv8gASGXa1jz cw7A== ARC-Authentication-Results: i=1; mx.google.com; spf=pass (google.com: domain of dev-bounces@dpdk.org designates 92.243.14.124 as permitted sender) smtp.mailfrom=dev-bounces@dpdk.org Return-Path: Received: from dpdk.org (dpdk.org. [92.243.14.124]) by mx.google.com with ESMTP id x19si855653eds.179.2019.04.30.20.54.44; Tue, 30 Apr 2019 20:54:44 -0700 (PDT) Received-SPF: pass (google.com: domain of dev-bounces@dpdk.org designates 92.243.14.124 as permitted sender) client-ip=92.243.14.124; Authentication-Results: mx.google.com; spf=pass (google.com: domain of dev-bounces@dpdk.org designates 92.243.14.124 as permitted sender) smtp.mailfrom=dev-bounces@dpdk.org Received: from [92.243.14.124] (localhost [127.0.0.1]) by dpdk.org (Postfix) with ESMTP id 6BFF25B1E; Wed, 1 May 2019 05:54:33 +0200 (CEST) Received: from foss.arm.com (foss.arm.com [217.140.101.70]) by dpdk.org (Postfix) with ESMTP id ACB1E5911 for ; Wed, 1 May 2019 05:54:30 +0200 (CEST) Received: from usa-sjc-imap-foss1.foss.arm.com (unknown [10.72.51.249]) by usa-sjc-mx-foss1.foss.arm.com (Postfix) with ESMTP id 0AEF3EBD; Tue, 30 Apr 2019 20:54:30 -0700 (PDT) Received: from qc2400f-1.austin.arm.com (qc2400f-1.austin.arm.com [10.118.12.65]) by usa-sjc-imap-foss1.foss.arm.com (Postfix) with ESMTPSA id 7B76F3F719; Tue, 30 Apr 2019 20:54:29 -0700 (PDT) From: Honnappa Nagarahalli To: konstantin.ananyev@intel.com, stephen@networkplumber.org, paulmck@linux.ibm.com, marko.kovacevic@intel.com, dev@dpdk.org Cc: honnappa.nagarahalli@arm.com, gavin.hu@arm.com, dharmik.thakkar@arm.com, malvika.gupta@arm.com Date: Tue, 30 Apr 2019 22:54:16 -0500 Message-Id: <20190501035419.33524-2-honnappa.nagarahalli@arm.com> X-Mailer: git-send-email 2.17.1 In-Reply-To: <20190501035419.33524-1-honnappa.nagarahalli@arm.com> References: <20181122033055.3431-1-honnappa.nagarahalli@arm.com> <20190501035419.33524-1-honnappa.nagarahalli@arm.com> Subject: [dpdk-dev] [PATCH v9 1/4] rcu: add RCU library supporting QSBR mechanism 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" Add RCU library supporting quiescent state based memory reclamation method. This library helps identify the quiescent state of the reader threads so that the writers can free the memory associated with the lock less data structures. Signed-off-by: Honnappa Nagarahalli Reviewed-by: Steve Capper Reviewed-by: Gavin Hu Reviewed-by: Ola Liljedahl Acked-by: Konstantin Ananyev Acked-by: Paul E. McKenney --- MAINTAINERS | 5 + config/common_base | 6 + lib/Makefile | 2 + lib/librte_rcu/Makefile | 23 ++ lib/librte_rcu/meson.build | 7 + lib/librte_rcu/rte_rcu_qsbr.c | 277 +++++++++++++ lib/librte_rcu/rte_rcu_qsbr.h | 641 +++++++++++++++++++++++++++++ lib/librte_rcu/rte_rcu_version.map | 13 + lib/meson.build | 2 +- mk/rte.app.mk | 1 + 10 files changed, 976 insertions(+), 1 deletion(-) create mode 100644 lib/librte_rcu/Makefile create mode 100644 lib/librte_rcu/meson.build create mode 100644 lib/librte_rcu/rte_rcu_qsbr.c create mode 100644 lib/librte_rcu/rte_rcu_qsbr.h create mode 100644 lib/librte_rcu/rte_rcu_version.map -- 2.17.1 diff --git a/MAINTAINERS b/MAINTAINERS index 4493aa636..5d25b21f0 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -1281,6 +1281,11 @@ F: examples/bpf/ F: app/test/test_bpf.c F: doc/guides/prog_guide/bpf_lib.rst +RCU - EXPERIMENTAL +M: Honnappa Nagarahalli +F: lib/librte_rcu/ +F: doc/guides/prog_guide/rcu_lib.rst + Test Applications ----------------- diff --git a/config/common_base b/config/common_base index 4236c2a67..6b96e0e80 100644 --- a/config/common_base +++ b/config/common_base @@ -838,6 +838,12 @@ CONFIG_RTE_LIBRTE_LATENCY_STATS=y # CONFIG_RTE_LIBRTE_TELEMETRY=n +# +# Compile librte_rcu +# +CONFIG_RTE_LIBRTE_RCU=y +CONFIG_RTE_LIBRTE_RCU_DEBUG=n + # # Compile librte_lpm # diff --git a/lib/Makefile b/lib/Makefile index 26021d0c0..791e0d991 100644 --- a/lib/Makefile +++ b/lib/Makefile @@ -111,6 +111,8 @@ DIRS-$(CONFIG_RTE_LIBRTE_IPSEC) += librte_ipsec DEPDIRS-librte_ipsec := librte_eal librte_mbuf librte_cryptodev librte_security DIRS-$(CONFIG_RTE_LIBRTE_TELEMETRY) += librte_telemetry DEPDIRS-librte_telemetry := librte_eal librte_metrics librte_ethdev +DIRS-$(CONFIG_RTE_LIBRTE_RCU) += librte_rcu +DEPDIRS-librte_rcu := librte_eal ifeq ($(CONFIG_RTE_EXEC_ENV_LINUX),y) DIRS-$(CONFIG_RTE_LIBRTE_KNI) += librte_kni diff --git a/lib/librte_rcu/Makefile b/lib/librte_rcu/Makefile new file mode 100644 index 000000000..6aa677bd1 --- /dev/null +++ b/lib/librte_rcu/Makefile @@ -0,0 +1,23 @@ +# SPDX-License-Identifier: BSD-3-Clause +# Copyright(c) 2018 Arm Limited + +include $(RTE_SDK)/mk/rte.vars.mk + +# library name +LIB = librte_rcu.a + +CFLAGS += -DALLOW_EXPERIMENTAL_API +CFLAGS += $(WERROR_FLAGS) -I$(SRCDIR) -O3 +LDLIBS += -lrte_eal + +EXPORT_MAP := rte_rcu_version.map + +LIBABIVER := 1 + +# all source are stored in SRCS-y +SRCS-$(CONFIG_RTE_LIBRTE_RCU) := rte_rcu_qsbr.c + +# install includes +SYMLINK-$(CONFIG_RTE_LIBRTE_RCU)-include := rte_rcu_qsbr.h + +include $(RTE_SDK)/mk/rte.lib.mk diff --git a/lib/librte_rcu/meson.build b/lib/librte_rcu/meson.build new file mode 100644 index 000000000..0c2d5a2e0 --- /dev/null +++ b/lib/librte_rcu/meson.build @@ -0,0 +1,7 @@ +# SPDX-License-Identifier: BSD-3-Clause +# Copyright(c) 2018 Arm Limited + +allow_experimental_apis = true + +sources = files('rte_rcu_qsbr.c') +headers = files('rte_rcu_qsbr.h') diff --git a/lib/librte_rcu/rte_rcu_qsbr.c b/lib/librte_rcu/rte_rcu_qsbr.c new file mode 100644 index 000000000..b4ed01045 --- /dev/null +++ b/lib/librte_rcu/rte_rcu_qsbr.c @@ -0,0 +1,277 @@ +/* SPDX-License-Identifier: BSD-3-Clause + * + * Copyright (c) 2018 Arm Limited + */ + +#include +#include +#include +#include +#include + +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +#include "rte_rcu_qsbr.h" + +/* Get the memory size of QSBR variable */ +size_t __rte_experimental +rte_rcu_qsbr_get_memsize(uint32_t max_threads) +{ + size_t sz; + + if (max_threads == 0) { + rte_log(RTE_LOG_ERR, rte_rcu_log_type, + "%s(): Invalid max_threads %u\n", + __func__, max_threads); + rte_errno = EINVAL; + + return 1; + } + + sz = sizeof(struct rte_rcu_qsbr); + + /* Add the size of quiescent state counter array */ + sz += sizeof(struct rte_rcu_qsbr_cnt) * max_threads; + + /* Add the size of the registered thread ID bitmap array */ + sz += __RTE_QSBR_THRID_ARRAY_SIZE(max_threads); + + return sz; +} + +/* Initialize a quiescent state variable */ +int __rte_experimental +rte_rcu_qsbr_init(struct rte_rcu_qsbr *v, uint32_t max_threads) +{ + size_t sz; + + if (v == NULL) { + rte_log(RTE_LOG_ERR, rte_rcu_log_type, + "%s(): Invalid input parameter\n", __func__); + rte_errno = EINVAL; + + return 1; + } + + sz = rte_rcu_qsbr_get_memsize(max_threads); + if (sz == 1) + return 1; + + /* Set all the threads to offline */ + memset(v, 0, sz); + v->max_threads = max_threads; + v->num_elems = RTE_ALIGN_MUL_CEIL(max_threads, + __RTE_QSBR_THRID_ARRAY_ELM_SIZE) / + __RTE_QSBR_THRID_ARRAY_ELM_SIZE; + v->token = __RTE_QSBR_CNT_INIT; + + return 0; +} + +/* Register a reader thread to report its quiescent state + * on a QS variable. + */ +int __rte_experimental +rte_rcu_qsbr_thread_register(struct rte_rcu_qsbr *v, unsigned int thread_id) +{ + unsigned int i, id, success; + uint64_t old_bmap, new_bmap; + + if (v == NULL || thread_id >= v->max_threads) { + rte_log(RTE_LOG_ERR, rte_rcu_log_type, + "%s(): Invalid input parameter\n", __func__); + rte_errno = EINVAL; + + return 1; + } + + __RTE_RCU_IS_LOCK_CNT_ZERO(v, thread_id, ERR, "Lock counter %u\n", + v->qsbr_cnt[thread_id].lock_cnt); + + id = thread_id & __RTE_QSBR_THRID_MASK; + i = thread_id >> __RTE_QSBR_THRID_INDEX_SHIFT; + + /* Make sure that the counter for registered threads does not + * go out of sync. Hence, additional checks are required. + */ + /* Check if the thread is already registered */ + old_bmap = __atomic_load_n(__RTE_QSBR_THRID_ARRAY_ELM(v, i), + __ATOMIC_RELAXED); + if (old_bmap & 1UL << id) + return 0; + + do { + new_bmap = old_bmap | (1UL << id); + success = __atomic_compare_exchange( + __RTE_QSBR_THRID_ARRAY_ELM(v, i), + &old_bmap, &new_bmap, 0, + __ATOMIC_RELEASE, __ATOMIC_RELAXED); + + if (success) + __atomic_fetch_add(&v->num_threads, + 1, __ATOMIC_RELAXED); + else if (old_bmap & (1UL << id)) + /* Someone else registered this thread. + * Counter should not be incremented. + */ + return 0; + } while (success == 0); + + return 0; +} + +/* Remove a reader thread, from the list of threads reporting their + * quiescent state on a QS variable. + */ +int __rte_experimental +rte_rcu_qsbr_thread_unregister(struct rte_rcu_qsbr *v, unsigned int thread_id) +{ + unsigned int i, id, success; + uint64_t old_bmap, new_bmap; + + if (v == NULL || thread_id >= v->max_threads) { + rte_log(RTE_LOG_ERR, rte_rcu_log_type, + "%s(): Invalid input parameter\n", __func__); + rte_errno = EINVAL; + + return 1; + } + + __RTE_RCU_IS_LOCK_CNT_ZERO(v, thread_id, ERR, "Lock counter %u\n", + v->qsbr_cnt[thread_id].lock_cnt); + + id = thread_id & __RTE_QSBR_THRID_MASK; + i = thread_id >> __RTE_QSBR_THRID_INDEX_SHIFT; + + /* Make sure that the counter for registered threads does not + * go out of sync. Hence, additional checks are required. + */ + /* Check if the thread is already unregistered */ + old_bmap = __atomic_load_n(__RTE_QSBR_THRID_ARRAY_ELM(v, i), + __ATOMIC_RELAXED); + if (old_bmap & ~(1UL << id)) + return 0; + + do { + new_bmap = old_bmap & ~(1UL << id); + /* Make sure any loads of the shared data structure are + * completed before removal of the thread from the list of + * reporting threads. + */ + success = __atomic_compare_exchange( + __RTE_QSBR_THRID_ARRAY_ELM(v, i), + &old_bmap, &new_bmap, 0, + __ATOMIC_RELEASE, __ATOMIC_RELAXED); + + if (success) + __atomic_fetch_sub(&v->num_threads, + 1, __ATOMIC_RELAXED); + else if (old_bmap & ~(1UL << id)) + /* Someone else unregistered this thread. + * Counter should not be incremented. + */ + return 0; + } while (success == 0); + + return 0; +} + +/* Wait till the reader threads have entered quiescent state. */ +void __rte_experimental +rte_rcu_qsbr_synchronize(struct rte_rcu_qsbr *v, unsigned int thread_id) +{ + uint64_t t; + + RTE_ASSERT(v != NULL); + + t = rte_rcu_qsbr_start(v); + + /* If the current thread has readside critical section, + * update its quiescent state status. + */ + if (thread_id != RTE_QSBR_THRID_INVALID) + rte_rcu_qsbr_quiescent(v, thread_id); + + /* Wait for other readers to enter quiescent state */ + rte_rcu_qsbr_check(v, t, true); +} + +/* Dump the details of a single quiescent state variable to a file. */ +int __rte_experimental +rte_rcu_qsbr_dump(FILE *f, struct rte_rcu_qsbr *v) +{ + uint64_t bmap; + uint32_t i, t, id; + + if (v == NULL || f == NULL) { + rte_log(RTE_LOG_ERR, rte_rcu_log_type, + "%s(): Invalid input parameter\n", __func__); + rte_errno = EINVAL; + + return 1; + } + + fprintf(f, "\nQuiescent State Variable @%p\n", v); + + fprintf(f, " QS variable memory size = %zu\n", + rte_rcu_qsbr_get_memsize(v->max_threads)); + fprintf(f, " Given # max threads = %u\n", v->max_threads); + fprintf(f, " Current # threads = %u\n", v->num_threads); + + fprintf(f, " Registered thread IDs = "); + for (i = 0; i < v->num_elems; i++) { + bmap = __atomic_load_n(__RTE_QSBR_THRID_ARRAY_ELM(v, i), + __ATOMIC_ACQUIRE); + id = i << __RTE_QSBR_THRID_INDEX_SHIFT; + while (bmap) { + t = __builtin_ctzl(bmap); + fprintf(f, "%d ", id + t); + + bmap &= ~(1UL << t); + } + } + + fprintf(f, "\n"); + + fprintf(f, " Token = %"PRIu64"\n", + __atomic_load_n(&v->token, __ATOMIC_ACQUIRE)); + + fprintf(f, "Quiescent State Counts for readers:\n"); + for (i = 0; i < v->num_elems; i++) { + bmap = __atomic_load_n(__RTE_QSBR_THRID_ARRAY_ELM(v, i), + __ATOMIC_ACQUIRE); + id = i << __RTE_QSBR_THRID_INDEX_SHIFT; + while (bmap) { + t = __builtin_ctzl(bmap); + fprintf(f, "thread ID = %d, count = %"PRIu64", lock count = %u\n", + id + t, + __atomic_load_n( + &v->qsbr_cnt[id + t].cnt, + __ATOMIC_RELAXED), + __atomic_load_n( + &v->qsbr_cnt[id + t].lock_cnt, + __ATOMIC_RELAXED)); + bmap &= ~(1UL << t); + } + } + + return 0; +} + +int rte_rcu_log_type; + +RTE_INIT(rte_rcu_register) +{ + rte_rcu_log_type = rte_log_register("lib.rcu"); + if (rte_rcu_log_type >= 0) + rte_log_set_level(rte_rcu_log_type, RTE_LOG_ERR); +} diff --git a/lib/librte_rcu/rte_rcu_qsbr.h b/lib/librte_rcu/rte_rcu_qsbr.h new file mode 100644 index 000000000..9727f4922 --- /dev/null +++ b/lib/librte_rcu/rte_rcu_qsbr.h @@ -0,0 +1,641 @@ +/* SPDX-License-Identifier: BSD-3-Clause + * Copyright (c) 2018 Arm Limited + */ + +#ifndef _RTE_RCU_QSBR_H_ +#define _RTE_RCU_QSBR_H_ + +/** + * @file + * RTE Quiescent State Based Reclamation (QSBR) + * + * Quiescent State (QS) is any point in the thread execution + * where the thread does not hold a reference to a data structure + * in shared memory. While using lock-less data structures, the writer + * can safely free memory once all the reader threads have entered + * quiescent state. + * + * This library provides the ability for the readers to report quiescent + * state and for the writers to identify when all the readers have + * entered quiescent state. + */ + +#ifdef __cplusplus +extern "C" { +#endif + +#include +#include +#include +#include +#include +#include +#include +#include +#include + +extern int rte_rcu_log_type; + +#if RTE_LOG_DP_LEVEL >= RTE_LOG_DEBUG +#define __RTE_RCU_DP_LOG(level, fmt, args...) \ + rte_log(RTE_LOG_ ## level, rte_rcu_log_type, \ + "%s(): " fmt "\n", __func__, ## args) +#else +#define __RTE_RCU_DP_LOG(level, fmt, args...) +#endif + +#if defined(RTE_LIBRTE_RCU_DEBUG) +#define __RTE_RCU_IS_LOCK_CNT_ZERO(v, thread_id, level, fmt, args...) do {\ + if (v->qsbr_cnt[thread_id].lock_cnt) \ + rte_log(RTE_LOG_ ## level, rte_rcu_log_type, \ + "%s(): " fmt "\n", __func__, ## args); \ +} while (0) +#else +#define __RTE_RCU_IS_LOCK_CNT_ZERO(v, thread_id, level, fmt, args...) +#endif + +/* Registered thread IDs are stored as a bitmap of 64b element array. + * Given thread id needs to be converted to index into the array and + * the id within the array element. + */ +#define __RTE_QSBR_THRID_ARRAY_ELM_SIZE (sizeof(uint64_t) * 8) +#define __RTE_QSBR_THRID_ARRAY_SIZE(max_threads) \ + RTE_ALIGN(RTE_ALIGN_MUL_CEIL(max_threads, \ + __RTE_QSBR_THRID_ARRAY_ELM_SIZE) >> 3, RTE_CACHE_LINE_SIZE) +#define __RTE_QSBR_THRID_ARRAY_ELM(v, i) ((uint64_t *) \ + ((struct rte_rcu_qsbr_cnt *)(v + 1) + v->max_threads) + i) +#define __RTE_QSBR_THRID_INDEX_SHIFT 6 +#define __RTE_QSBR_THRID_MASK 0x3f +#define RTE_QSBR_THRID_INVALID 0xffffffff + +/* Worker thread counter */ +struct rte_rcu_qsbr_cnt { + uint64_t cnt; + /**< Quiescent state counter. Value 0 indicates the thread is offline + * 64b counter is used to avoid adding more code to address + * counter overflow. Changing this to 32b would require additional + * changes to various APIs. + */ + uint32_t lock_cnt; + /**< Lock counter. Used when CONFIG_RTE_LIBRTE_RCU_DEBUG is enabled */ +} __rte_cache_aligned; + +#define __RTE_QSBR_CNT_THR_OFFLINE 0 +#define __RTE_QSBR_CNT_INIT 1 + +/* RTE Quiescent State variable structure. + * This structure has two elements that vary in size based on the + * 'max_threads' parameter. + * 1) Quiescent state counter array + * 2) Register thread ID array + */ +struct rte_rcu_qsbr { + uint64_t token __rte_cache_aligned; + /**< Counter to allow for multiple concurrent quiescent state queries */ + + uint32_t num_elems __rte_cache_aligned; + /**< Number of elements in the thread ID array */ + uint32_t num_threads; + /**< Number of threads currently using this QS variable */ + uint32_t max_threads; + /**< Maximum number of threads using this QS variable */ + + struct rte_rcu_qsbr_cnt qsbr_cnt[0] __rte_cache_aligned; + /**< Quiescent state counter array of 'max_threads' elements */ + + /**< Registered thread IDs are stored in a bitmap array, + * after the quiescent state counter array. + */ +} __rte_cache_aligned; + +/** + * @warning + * @b EXPERIMENTAL: this API may change without prior notice + * + * Return the size of the memory occupied by a Quiescent State variable. + * + * @param max_threads + * Maximum number of threads reporting quiescent state on this variable. + * @return + * On success - size of memory in bytes required for this QS variable. + * On error - 1 with error code set in rte_errno. + * Possible rte_errno codes are: + * - EINVAL - max_threads is 0 + */ +size_t __rte_experimental +rte_rcu_qsbr_get_memsize(uint32_t max_threads); + +/** + * @warning + * @b EXPERIMENTAL: this API may change without prior notice + * + * Initialize a Quiescent State (QS) variable. + * + * @param v + * QS variable + * @param max_threads + * Maximum number of threads reporting quiescent state on this variable. + * This should be the same value as passed to rte_rcu_qsbr_get_memsize. + * @return + * On success - 0 + * On error - 1 with error code set in rte_errno. + * Possible rte_errno codes are: + * - EINVAL - max_threads is 0 or 'v' is NULL. + * + */ +int __rte_experimental +rte_rcu_qsbr_init(struct rte_rcu_qsbr *v, uint32_t max_threads); + +/** + * @warning + * @b EXPERIMENTAL: this API may change without prior notice + * + * Register a reader thread to report its quiescent state + * on a QS variable. + * + * This is implemented as a lock-free function. It is multi-thread + * safe. + * Any reader thread that wants to report its quiescent state must + * call this API. This can be called during initialization or as part + * of the packet processing loop. + * + * Note that rte_rcu_qsbr_thread_online must be called before the + * thread updates its quiescent state using rte_rcu_qsbr_quiescent. + * + * @param v + * QS variable + * @param thread_id + * Reader thread with this thread ID will report its quiescent state on + * the QS variable. thread_id is a value between 0 and (max_threads - 1). + * 'max_threads' is the parameter passed in 'rte_rcu_qsbr_init' API. + */ +int __rte_experimental +rte_rcu_qsbr_thread_register(struct rte_rcu_qsbr *v, unsigned int thread_id); + +/** + * @warning + * @b EXPERIMENTAL: this API may change without prior notice + * + * Remove a reader thread, from the list of threads reporting their + * quiescent state on a QS variable. + * + * This is implemented as a lock-free function. It is multi-thread safe. + * This API can be called from the reader threads during shutdown. + * Ongoing quiescent state queries will stop waiting for the status from this + * unregistered reader thread. + * + * @param v + * QS variable + * @param thread_id + * Reader thread with this thread ID will stop reporting its quiescent + * state on the QS variable. + */ +int __rte_experimental +rte_rcu_qsbr_thread_unregister(struct rte_rcu_qsbr *v, unsigned int thread_id); + +/** + * @warning + * @b EXPERIMENTAL: this API may change without prior notice + * + * Add a registered reader thread, to the list of threads reporting their + * quiescent state on a QS variable. + * + * This is implemented as a lock-free function. It is multi-thread + * safe. + * + * Any registered reader thread that wants to report its quiescent state must + * call this API before calling rte_rcu_qsbr_quiescent. This can be called + * during initialization or as part of the packet processing loop. + * + * The reader thread must call rte_rcu_thread_offline API, before + * calling any functions that block, to ensure that rte_rcu_qsbr_check + * API does not wait indefinitely for the reader thread to update its QS. + * + * The reader thread must call rte_rcu_thread_online API, after the blocking + * function call returns, to ensure that rte_rcu_qsbr_check API + * waits for the reader thread to update its quiescent state. + * + * @param v + * QS variable + * @param thread_id + * Reader thread with this thread ID will report its quiescent state on + * the QS variable. + */ +static __rte_always_inline void __rte_experimental +rte_rcu_qsbr_thread_online(struct rte_rcu_qsbr *v, unsigned int thread_id) +{ + uint64_t t; + + RTE_ASSERT(v != NULL && thread_id < v->max_threads); + + __RTE_RCU_IS_LOCK_CNT_ZERO(v, thread_id, ERR, "Lock counter %u\n", + v->qsbr_cnt[thread_id].lock_cnt); + + /* Copy the current value of token. + * The fence at the end of the function will ensure that + * the following will not move down after the load of any shared + * data structure. + */ + t = __atomic_load_n(&v->token, __ATOMIC_RELAXED); + + /* __atomic_store_n(cnt, __ATOMIC_RELAXED) is used to ensure + * 'cnt' (64b) is accessed atomically. + */ + __atomic_store_n(&v->qsbr_cnt[thread_id].cnt, + t, __ATOMIC_RELAXED); + + /* The subsequent load of the data structure should not + * move above the store. Hence a store-load barrier + * is required. + * If the load of the data structure moves above the store, + * writer might not see that the reader is online, even though + * the reader is referencing the shared data structure. + */ +#ifdef RTE_ARCH_X86_64 + /* rte_smp_mb() for x86 is lighter */ + rte_smp_mb(); +#else + __atomic_thread_fence(__ATOMIC_SEQ_CST); +#endif +} + +/** + * @warning + * @b EXPERIMENTAL: this API may change without prior notice + * + * Remove a registered reader thread from the list of threads reporting their + * quiescent state on a QS variable. + * + * This is implemented as a lock-free function. It is multi-thread + * safe. + * + * This can be called during initialization or as part of the packet + * processing loop. + * + * The reader thread must call rte_rcu_thread_offline API, before + * calling any functions that block, to ensure that rte_rcu_qsbr_check + * API does not wait indefinitely for the reader thread to update its QS. + * + * @param v + * QS variable + * @param thread_id + * rte_rcu_qsbr_check API will not wait for the reader thread with + * this thread ID to report its quiescent state on the QS variable. + */ +static __rte_always_inline void __rte_experimental +rte_rcu_qsbr_thread_offline(struct rte_rcu_qsbr *v, unsigned int thread_id) +{ + RTE_ASSERT(v != NULL && thread_id < v->max_threads); + + __RTE_RCU_IS_LOCK_CNT_ZERO(v, thread_id, ERR, "Lock counter %u\n", + v->qsbr_cnt[thread_id].lock_cnt); + + /* The reader can go offline only after the load of the + * data structure is completed. i.e. any load of the + * data strcture can not move after this store. + */ + + __atomic_store_n(&v->qsbr_cnt[thread_id].cnt, + __RTE_QSBR_CNT_THR_OFFLINE, __ATOMIC_RELEASE); +} + +/** + * @warning + * @b EXPERIMENTAL: this API may change without prior notice + * + * Acquire a lock for accessing a shared data structure. + * + * This is implemented as a lock-free function. It is multi-thread + * safe. + * + * This API is provided to aid debugging. This should be called before + * accessing a shared data structure. + * + * When CONFIG_RTE_LIBRTE_RCU_DEBUG is enabled a lock counter is incremented. + * Similarly rte_rcu_qsbr_unlock will decrement the counter. When the + * rte_rcu_qsbr_check API will verify that this counter is 0. + * + * When CONFIG_RTE_LIBRTE_RCU_DEBUG is disabled, this API will do nothing. + * + * @param v + * QS variable + * @param thread_id + * Reader thread id + */ +static __rte_always_inline void __rte_experimental +rte_rcu_qsbr_lock(__rte_unused struct rte_rcu_qsbr *v, + __rte_unused unsigned int thread_id) +{ + RTE_ASSERT(v != NULL && thread_id < v->max_threads); + +#if defined(RTE_LIBRTE_RCU_DEBUG) + /* Increment the lock counter */ + __atomic_fetch_add(&v->qsbr_cnt[thread_id].lock_cnt, + 1, __ATOMIC_ACQUIRE); +#endif +} + +/** + * @warning + * @b EXPERIMENTAL: this API may change without prior notice + * + * Release a lock after accessing a shared data structure. + * + * This is implemented as a lock-free function. It is multi-thread + * safe. + * + * This API is provided to aid debugging. This should be called after + * accessing a shared data structure. + * + * When CONFIG_RTE_LIBRTE_RCU_DEBUG is enabled, rte_rcu_qsbr_unlock will + * decrement a lock counter. rte_rcu_qsbr_check API will verify that this + * counter is 0. + * + * When CONFIG_RTE_LIBRTE_RCU_DEBUG is disabled, this API will do nothing. + * + * @param v + * QS variable + * @param thread_id + * Reader thread id + */ +static __rte_always_inline void __rte_experimental +rte_rcu_qsbr_unlock(__rte_unused struct rte_rcu_qsbr *v, + __rte_unused unsigned int thread_id) +{ + RTE_ASSERT(v != NULL && thread_id < v->max_threads); + +#if defined(RTE_LIBRTE_RCU_DEBUG) + /* Decrement the lock counter */ + __atomic_fetch_sub(&v->qsbr_cnt[thread_id].lock_cnt, + 1, __ATOMIC_RELEASE); + + __RTE_RCU_IS_LOCK_CNT_ZERO(v, thread_id, WARNING, + "Lock counter %u. Nested locks?\n", + v->qsbr_cnt[thread_id].lock_cnt); +#endif +} + +/** + * @warning + * @b EXPERIMENTAL: this API may change without prior notice + * + * Ask the reader threads to report the quiescent state + * status. + * + * This is implemented as a lock-free function. It is multi-thread + * safe and can be called from worker threads. + * + * @param v + * QS variable + * @return + * - This is the token for this call of the API. This should be + * passed to rte_rcu_qsbr_check API. + */ +static __rte_always_inline uint64_t __rte_experimental +rte_rcu_qsbr_start(struct rte_rcu_qsbr *v) +{ + uint64_t t; + + RTE_ASSERT(v != NULL); + + /* Release the changes to the shared data structure. + * This store release will ensure that changes to any data + * structure are visible to the workers before the token + * update is visible. + */ + t = __atomic_add_fetch(&v->token, 1, __ATOMIC_RELEASE); + + return t; +} + +/** + * @warning + * @b EXPERIMENTAL: this API may change without prior notice + * + * Update quiescent state for a reader thread. + * + * This is implemented as a lock-free function. It is multi-thread safe. + * All the reader threads registered to report their quiescent state + * on the QS variable must call this API. + * + * @param v + * QS variable + * @param thread_id + * Update the quiescent state for the reader with this thread ID. + */ +static __rte_always_inline void __rte_experimental +rte_rcu_qsbr_quiescent(struct rte_rcu_qsbr *v, unsigned int thread_id) +{ + uint64_t t; + + RTE_ASSERT(v != NULL && thread_id < v->max_threads); + + __RTE_RCU_IS_LOCK_CNT_ZERO(v, thread_id, ERR, "Lock counter %u\n", + v->qsbr_cnt[thread_id].lock_cnt); + + /* Acquire the changes to the shared data structure released + * by rte_rcu_qsbr_start. + * Later loads of the shared data structure should not move + * above this load. Hence, use load-acquire. + */ + t = __atomic_load_n(&v->token, __ATOMIC_ACQUIRE); + + /* Inform the writer that updates are visible to this reader. + * Prior loads of the shared data structure should not move + * beyond this store. Hence use store-release. + */ + __atomic_store_n(&v->qsbr_cnt[thread_id].cnt, + t, __ATOMIC_RELEASE); + + __RTE_RCU_DP_LOG(DEBUG, "%s: update: token = %"PRIu64", Thread ID = %d", + __func__, t, thread_id); +} + +/* Check the quiescent state counter for registered threads only, assuming + * that not all threads have registered. + */ +static __rte_always_inline int +__rte_rcu_qsbr_check_selective(struct rte_rcu_qsbr *v, uint64_t t, bool wait) +{ + uint32_t i, j, id; + uint64_t bmap; + uint64_t c; + uint64_t *reg_thread_id; + + for (i = 0, reg_thread_id = __RTE_QSBR_THRID_ARRAY_ELM(v, 0); + i < v->num_elems; + i++, reg_thread_id++) { + /* Load the current registered thread bit map before + * loading the reader thread quiescent state counters. + */ + bmap = __atomic_load_n(reg_thread_id, __ATOMIC_ACQUIRE); + id = i << __RTE_QSBR_THRID_INDEX_SHIFT; + + while (bmap) { + j = __builtin_ctzl(bmap); + __RTE_RCU_DP_LOG(DEBUG, + "%s: check: token = %"PRIu64", wait = %d, Bit Map = 0x%"PRIx64", Thread ID = %d", + __func__, t, wait, bmap, id + j); + c = __atomic_load_n( + &v->qsbr_cnt[id + j].cnt, + __ATOMIC_ACQUIRE); + __RTE_RCU_DP_LOG(DEBUG, + "%s: status: token = %"PRIu64", wait = %d, Thread QS cnt = %"PRIu64", Thread ID = %d", + __func__, t, wait, c, id+j); + /* Counter is not checked for wrap-around condition + * as it is a 64b counter. + */ + if (unlikely(c != + __RTE_QSBR_CNT_THR_OFFLINE && c < t)) { + /* This thread is not in quiescent state */ + if (!wait) + return 0; + + rte_pause(); + /* This thread might have unregistered. + * Re-read the bitmap. + */ + bmap = __atomic_load_n(reg_thread_id, + __ATOMIC_ACQUIRE); + + continue; + } + + bmap &= ~(1UL << j); + } + } + + return 1; +} + +/* Check the quiescent state counter for all threads, assuming that + * all the threads have registered. + */ +static __rte_always_inline int +__rte_rcu_qsbr_check_all(struct rte_rcu_qsbr *v, uint64_t t, bool wait) +{ + uint32_t i; + struct rte_rcu_qsbr_cnt *cnt; + uint64_t c; + + for (i = 0, cnt = v->qsbr_cnt; i < v->max_threads; i++, cnt++) { + __RTE_RCU_DP_LOG(DEBUG, + "%s: check: token = %"PRIu64", wait = %d, Thread ID = %d", + __func__, t, wait, i); + while (1) { + c = __atomic_load_n(&cnt->cnt, __ATOMIC_ACQUIRE); + __RTE_RCU_DP_LOG(DEBUG, + "%s: status: token = %"PRIu64", wait = %d, Thread QS cnt = %"PRIu64", Thread ID = %d", + __func__, t, wait, c, i); + /* Counter is not checked for wrap-around condition + * as it is a 64b counter. + */ + if (likely(c == __RTE_QSBR_CNT_THR_OFFLINE || c >= t)) + break; + + /* This thread is not in quiescent state */ + if (!wait) + return 0; + + rte_pause(); + } + } + + return 1; +} + +/** + * @warning + * @b EXPERIMENTAL: this API may change without prior notice + * + * Checks if all the reader threads have entered the quiescent state + * referenced by token. + * + * This is implemented as a lock-free function. It is multi-thread + * safe and can be called from the worker threads as well. + * + * If this API is called with 'wait' set to true, the following + * factors must be considered: + * + * 1) If the calling thread is also reporting the status on the + * same QS variable, it must update the quiescent state status, before + * calling this API. + * + * 2) In addition, while calling from multiple threads, only + * one of those threads can be reporting the quiescent state status + * on a given QS variable. + * + * @param v + * QS variable + * @param t + * Token returned by rte_rcu_qsbr_start API + * @param wait + * If true, block till all the reader threads have completed entering + * the quiescent state referenced by token 't'. + * @return + * - 0 if all reader threads have NOT passed through specified number + * of quiescent states. + * - 1 if all reader threads have passed through specified number + * of quiescent states. + */ +static __rte_always_inline int __rte_experimental +rte_rcu_qsbr_check(struct rte_rcu_qsbr *v, uint64_t t, bool wait) +{ + RTE_ASSERT(v != NULL); + + if (likely(v->num_threads == v->max_threads)) + return __rte_rcu_qsbr_check_all(v, t, wait); + else + return __rte_rcu_qsbr_check_selective(v, t, wait); +} + +/** + * @warning + * @b EXPERIMENTAL: this API may change without prior notice + * + * Wait till the reader threads have entered quiescent state. + * + * This is implemented as a lock-free function. It is multi-thread safe. + * This API can be thought of as a wrapper around rte_rcu_qsbr_start and + * rte_rcu_qsbr_check APIs. + * + * If this API is called from multiple threads, only one of + * those threads can be reporting the quiescent state status on a + * given QS variable. + * + * @param v + * QS variable + * @param thread_id + * Thread ID of the caller if it is registered to report quiescent state + * on this QS variable (i.e. the calling thread is also part of the + * readside critical section). If not, pass RTE_QSBR_THRID_INVALID. + */ +void __rte_experimental +rte_rcu_qsbr_synchronize(struct rte_rcu_qsbr *v, unsigned int thread_id); + +/** + * @warning + * @b EXPERIMENTAL: this API may change without prior notice + * + * Dump the details of a single QS variables to a file. + * + * It is NOT multi-thread safe. + * + * @param f + * A pointer to a file for output + * @param v + * QS variable + * @return + * On success - 0 + * On error - 1 with error code set in rte_errno. + * Possible rte_errno codes are: + * - EINVAL - NULL parameters are passed + */ +int __rte_experimental +rte_rcu_qsbr_dump(FILE *f, struct rte_rcu_qsbr *v); + +#ifdef __cplusplus +} +#endif + +#endif /* _RTE_RCU_QSBR_H_ */ diff --git a/lib/librte_rcu/rte_rcu_version.map b/lib/librte_rcu/rte_rcu_version.map new file mode 100644 index 000000000..f8b9ef2ab --- /dev/null +++ b/lib/librte_rcu/rte_rcu_version.map @@ -0,0 +1,13 @@ +EXPERIMENTAL { + global: + + rte_rcu_log_type; + rte_rcu_qsbr_dump; + rte_rcu_qsbr_get_memsize; + rte_rcu_qsbr_init; + rte_rcu_qsbr_synchronize; + rte_rcu_qsbr_thread_register; + rte_rcu_qsbr_thread_unregister; + + local: *; +}; diff --git a/lib/meson.build b/lib/meson.build index a379dd682..e067ce5ea 100644 --- a/lib/meson.build +++ b/lib/meson.build @@ -22,7 +22,7 @@ libraries = [ 'gro', 'gso', 'ip_frag', 'jobstats', 'kni', 'latencystats', 'lpm', 'member', 'power', 'pdump', 'rawdev', - 'reorder', 'sched', 'security', 'stack', 'vhost', + 'rcu', 'reorder', 'sched', 'security', 'stack', 'vhost', #ipsec lib depends on crypto and security 'ipsec', # add pkt framework libs which use other libs from above diff --git a/mk/rte.app.mk b/mk/rte.app.mk index f020bb10c..7c9b4b538 100644 --- a/mk/rte.app.mk +++ b/mk/rte.app.mk @@ -97,6 +97,7 @@ _LDLIBS-$(CONFIG_RTE_LIBRTE_EAL) += -lrte_eal _LDLIBS-$(CONFIG_RTE_LIBRTE_CMDLINE) += -lrte_cmdline _LDLIBS-$(CONFIG_RTE_LIBRTE_REORDER) += -lrte_reorder _LDLIBS-$(CONFIG_RTE_LIBRTE_SCHED) += -lrte_sched +_LDLIBS-$(CONFIG_RTE_LIBRTE_RCU) += -lrte_rcu ifeq ($(CONFIG_RTE_EXEC_ENV_LINUX),y) _LDLIBS-$(CONFIG_RTE_LIBRTE_KNI) += -lrte_kni From patchwork Wed May 1 03:54:17 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Honnappa Nagarahalli X-Patchwork-Id: 163168 Delivered-To: patch@linaro.org Received: by 2002:a92:7e86:0:0:0:0:0 with SMTP id q6csp4068350ill; Tue, 30 Apr 2019 20:54:57 -0700 (PDT) X-Google-Smtp-Source: APXvYqxeJJvx/oxbTVxiyDll5wCu6ZFNlN3K+1eHG1tXYIQeR4EWbfS9kZVsnyNji3fuway5NOBp X-Received: by 2002:a17:906:4cd6:: with SMTP id q22mr3182509ejt.14.1556682896981; Tue, 30 Apr 2019 20:54:56 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1556682896; cv=none; d=google.com; s=arc-20160816; b=lrFiZk9vICHz/ZNwMqT+f3sVI8Dh/ynXEols2hIDF7lldhIbv2gtezFl9xDx1gtSFY Y/Jplcw8j2P7IJRmz/dSykebNq5C8kmVxLvKv0f/EHVTZ9qVfl3Tl4Zm/pBoQ4QkHdnt ozH52wjr7Q+0tLpm6Pgn8UGzyOJcl2XaK2BFsV/NtJpVqzJRlSnQuV8M+ZhMMWVG6F7Q h+Y4VHvqJm40qzZCdzF6kLstQOl2ETFOJ3n3qJDyXaKdEGJCk1tkBziGL8oWtMiFiwgC F4lJqzUaVI8UDMnAf1iOAD3i8UykXzYK4CzN+JndQo7nXHo1XTUxqVODw9okHZMw9AKF sDDA== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:list-subscribe:list-help:list-post:list-archive :list-unsubscribe:list-id:precedence:subject:references:in-reply-to :message-id:date:cc:to:from; bh=gpaYIfXVzb83H3YvmDuu0cHSrVKhV0vRapjqgenhACE=; b=oID6xWuzdDkaZCW/UpQ/DNdbQVRK2hvx0cfYqUtOOeGMCsB6TvWg7KoIVErccD920X dxqLY1ixsjVojriiIyGUPXqiFnthCFkvRkBN+vqKRN9ecwLnP1m+Ex5p4bf8N9KTkJlt qKjqUdvdbBT5pE9n+byHHbu5FeQiiSC/30PGgtJZGLH4m67B8ohTIAZce/MjWMXd75eg h+LjC7uRprKiIgRudWJw43OiSYs2EieSh8/ir8jhEgj1yJ8Bsitirq7Xh8FmOZ8yOvR4 qZi6fGpYEM1ooiBHQnkFaSM1YJUbRfOP1VkZPxeClhSWm8jeJuAEHqfas4u+xX1QS8p5 816w== ARC-Authentication-Results: i=1; mx.google.com; spf=pass (google.com: domain of dev-bounces@dpdk.org designates 92.243.14.124 as permitted sender) smtp.mailfrom=dev-bounces@dpdk.org Return-Path: Received: from dpdk.org (dpdk.org. [92.243.14.124]) by mx.google.com with ESMTP id j28si1909761ede.264.2019.04.30.20.54.56; Tue, 30 Apr 2019 20:54:56 -0700 (PDT) Received-SPF: pass (google.com: domain of dev-bounces@dpdk.org designates 92.243.14.124 as permitted sender) client-ip=92.243.14.124; Authentication-Results: mx.google.com; spf=pass (google.com: domain of dev-bounces@dpdk.org designates 92.243.14.124 as permitted sender) smtp.mailfrom=dev-bounces@dpdk.org Received: from [92.243.14.124] (localhost [127.0.0.1]) by dpdk.org (Postfix) with ESMTP id 991D25B38; Wed, 1 May 2019 05:54:36 +0200 (CEST) Received: from foss.arm.com (foss.arm.com [217.140.101.70]) by dpdk.org (Postfix) with ESMTP id E9C545B12 for ; Wed, 1 May 2019 05:54:32 +0200 (CEST) Received: from usa-sjc-imap-foss1.foss.arm.com (unknown [10.72.51.249]) by usa-sjc-mx-foss1.foss.arm.com (Postfix) with ESMTP id 36EA515AD; Tue, 30 Apr 2019 20:54:32 -0700 (PDT) Received: from qc2400f-1.austin.arm.com (qc2400f-1.austin.arm.com [10.118.12.65]) by usa-sjc-imap-foss1.foss.arm.com (Postfix) with ESMTPSA id 9EFA13F719; Tue, 30 Apr 2019 20:54:31 -0700 (PDT) From: Honnappa Nagarahalli To: konstantin.ananyev@intel.com, stephen@networkplumber.org, paulmck@linux.ibm.com, marko.kovacevic@intel.com, dev@dpdk.org Cc: honnappa.nagarahalli@arm.com, gavin.hu@arm.com, dharmik.thakkar@arm.com, malvika.gupta@arm.com Date: Tue, 30 Apr 2019 22:54:17 -0500 Message-Id: <20190501035419.33524-3-honnappa.nagarahalli@arm.com> X-Mailer: git-send-email 2.17.1 In-Reply-To: <20190501035419.33524-1-honnappa.nagarahalli@arm.com> References: <20181122033055.3431-1-honnappa.nagarahalli@arm.com> <20190501035419.33524-1-honnappa.nagarahalli@arm.com> Subject: [dpdk-dev] [PATCH v9 2/4] test/rcu_qsbr: add API and functional tests 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" From: Dharmik Thakkar Add API positive/negative test cases, functional tests and performance tests. Signed-off-by: Malvika Gupta Signed-off-by: Dharmik Thakkar Signed-off-by: Honnappa Nagarahalli Reviewed-by: Gavin Hu Acked-by: Konstantin Ananyev --- app/test/Makefile | 2 + app/test/autotest_data.py | 12 + app/test/meson.build | 5 + app/test/test_rcu_qsbr.c | 1014 +++++++++++++++++++++++++++++++++ app/test/test_rcu_qsbr_perf.c | 704 +++++++++++++++++++++++ 5 files changed, 1737 insertions(+) create mode 100644 app/test/test_rcu_qsbr.c create mode 100644 app/test/test_rcu_qsbr_perf.c -- 2.17.1 Signed-off-by: Malvika Gupta Signed-off-by: Dharmik Thakkar Signed-off-by: Honnappa Nagarahalli Reviewed-by: Gavin Hu Acked-by: Konstantin Ananyev diff --git a/app/test/Makefile b/app/test/Makefile index 54f706792..68d6b4fbc 100644 --- a/app/test/Makefile +++ b/app/test/Makefile @@ -218,6 +218,8 @@ SRCS-$(CONFIG_RTE_LIBRTE_KVARGS) += test_kvargs.c SRCS-$(CONFIG_RTE_LIBRTE_BPF) += test_bpf.c +SRCS-$(CONFIG_RTE_LIBRTE_RCU) += test_rcu_qsbr.c test_rcu_qsbr_perf.c + SRCS-$(CONFIG_RTE_LIBRTE_IPSEC) += test_ipsec.c ifeq ($(CONFIG_RTE_LIBRTE_IPSEC),y) LDLIBS += -lrte_ipsec diff --git a/app/test/autotest_data.py b/app/test/autotest_data.py index 72c56e528..fba66045f 100644 --- a/app/test/autotest_data.py +++ b/app/test/autotest_data.py @@ -700,6 +700,18 @@ "Func": default_autotest, "Report": None, }, + { + "Name": "RCU QSBR autotest", + "Command": "rcu_qsbr_autotest", + "Func": default_autotest, + "Report": None, + }, + { + "Name": "RCU QSBR performance autotest", + "Command": "rcu_qsbr_perf_autotest", + "Func": default_autotest, + "Report": None, + }, # # Please always make sure that ring_perf is the last test! # diff --git a/app/test/meson.build b/app/test/meson.build index 80cdea5d1..4e8077cd2 100644 --- a/app/test/meson.build +++ b/app/test/meson.build @@ -85,6 +85,8 @@ test_sources = files('commands.c', 'test_power_acpi_cpufreq.c', 'test_power_kvm_vm.c', 'test_prefetch.c', + 'test_rcu_qsbr.c', + 'test_rcu_qsbr_perf.c', 'test_reciprocal_division.c', 'test_reciprocal_division_perf.c', 'test_red.c', @@ -134,6 +136,7 @@ test_deps = ['acl', 'metrics', 'pipeline', 'port', + 'rcu', 'reorder', 'ring', 'stack', @@ -172,6 +175,7 @@ fast_parallel_test_names = [ 'multiprocess_autotest', 'per_lcore_autotest', 'prefetch_autotest', + 'rcu_qsbr_autotest', 'red_autotest', 'ring_autotest', 'ring_pmd_autotest', @@ -240,6 +244,7 @@ perf_test_names = [ 'member_perf_autotest', 'efd_perf_autotest', 'lpm6_perf_autotest', + 'rcu_qsbr_perf_autotest', 'red_perf', 'distributor_perf_autotest', 'ring_pmd_perf_autotest', diff --git a/app/test/test_rcu_qsbr.c b/app/test/test_rcu_qsbr.c new file mode 100644 index 000000000..ed6934a47 --- /dev/null +++ b/app/test/test_rcu_qsbr.c @@ -0,0 +1,1014 @@ +/* SPDX-License-Identifier: BSD-3-Clause + * Copyright (c) 2018 Arm Limited + */ + +#include +#include +#include +#include +#include +#include +#include +#include +#include + +#include "test.h" + +/* Check condition and return an error if true. */ +#define TEST_RCU_QSBR_RETURN_IF_ERROR(cond, str, ...) do { \ + if (cond) { \ + printf("ERROR file %s, line %d: " str "\n", __FILE__, \ + __LINE__, ##__VA_ARGS__); \ + return -1; \ + } \ +} while (0) + +/* Make sure that this has the same value as __RTE_QSBR_CNT_INIT */ +#define TEST_RCU_QSBR_CNT_INIT 1 + +#define TEST_RCU_MAX_LCORE 128 +uint16_t enabled_core_ids[TEST_RCU_MAX_LCORE]; +uint8_t num_cores; + +static uint32_t *keys; +#define TOTAL_ENTRY (1024 * 8) +#define COUNTER_VALUE 4096 +static uint32_t *hash_data[TEST_RCU_MAX_LCORE][TOTAL_ENTRY]; +static uint8_t writer_done; + +static struct rte_rcu_qsbr *t[TEST_RCU_MAX_LCORE]; +struct rte_hash *h[TEST_RCU_MAX_LCORE]; +char hash_name[TEST_RCU_MAX_LCORE][8]; + +static inline int +get_enabled_cores_mask(void) +{ + uint16_t core_id; + uint32_t max_cores = rte_lcore_count(); + + if (max_cores > TEST_RCU_MAX_LCORE) { + printf("Number of cores exceed %d\n", TEST_RCU_MAX_LCORE); + return -1; + } + + core_id = 0; + num_cores = 0; + RTE_LCORE_FOREACH_SLAVE(core_id) { + enabled_core_ids[num_cores] = core_id; + num_cores++; + } + + return 0; +} + +static int +alloc_rcu(void) +{ + int i; + uint32_t sz; + + sz = rte_rcu_qsbr_get_memsize(TEST_RCU_MAX_LCORE); + + for (i = 0; i < TEST_RCU_MAX_LCORE; i++) + t[i] = (struct rte_rcu_qsbr *)rte_zmalloc(NULL, sz, + RTE_CACHE_LINE_SIZE); + + return 0; +} + +static int +free_rcu(void) +{ + int i; + + for (i = 0; i < TEST_RCU_MAX_LCORE; i++) + rte_free(t[i]); + + return 0; +} + +/* + * rte_rcu_qsbr_thread_register: Add a reader thread, to the list of threads + * reporting their quiescent state on a QS variable. + */ +static int +test_rcu_qsbr_get_memsize(void) +{ + uint32_t sz; + + printf("\nTest rte_rcu_qsbr_thread_register()\n"); + + sz = rte_rcu_qsbr_get_memsize(0); + TEST_RCU_QSBR_RETURN_IF_ERROR((sz != 1), "Get Memsize for 0 threads"); + + sz = rte_rcu_qsbr_get_memsize(TEST_RCU_MAX_LCORE); + /* For 128 threads, + * for machines with cache line size of 64B - 8384 + * for machines with cache line size of 128 - 16768 + */ + TEST_RCU_QSBR_RETURN_IF_ERROR((sz != 8384 && sz != 16768), + "Get Memsize"); + + return 0; +} + +/* + * rte_rcu_qsbr_init: Initialize a QSBR variable. + */ +static int +test_rcu_qsbr_init(void) +{ + int r; + + printf("\nTest rte_rcu_qsbr_init()\n"); + + r = rte_rcu_qsbr_init(NULL, TEST_RCU_MAX_LCORE); + TEST_RCU_QSBR_RETURN_IF_ERROR((r != 1), "NULL variable"); + + return 0; +} + +/* + * rte_rcu_qsbr_thread_register: Add a reader thread, to the list of threads + * reporting their quiescent state on a QS variable. + */ +static int +test_rcu_qsbr_thread_register(void) +{ + int ret; + + printf("\nTest rte_rcu_qsbr_thread_register()\n"); + + ret = rte_rcu_qsbr_thread_register(NULL, enabled_core_ids[0]); + TEST_RCU_QSBR_RETURN_IF_ERROR((ret == 0), "NULL variable check"); + + ret = rte_rcu_qsbr_thread_register(NULL, 100000); + TEST_RCU_QSBR_RETURN_IF_ERROR((ret == 0), + "NULL variable, invalid thread id"); + + rte_rcu_qsbr_init(t[0], TEST_RCU_MAX_LCORE); + + /* Register valid thread id */ + ret = rte_rcu_qsbr_thread_register(t[0], enabled_core_ids[0]); + TEST_RCU_QSBR_RETURN_IF_ERROR((ret == 1), "Valid thread id"); + + /* Re-registering should not return error */ + ret = rte_rcu_qsbr_thread_register(t[0], enabled_core_ids[0]); + TEST_RCU_QSBR_RETURN_IF_ERROR((ret == 1), + "Already registered thread id"); + + /* Register valid thread id - max allowed thread id */ + ret = rte_rcu_qsbr_thread_register(t[0], TEST_RCU_MAX_LCORE - 1); + TEST_RCU_QSBR_RETURN_IF_ERROR((ret == 1), "Max thread id"); + + ret = rte_rcu_qsbr_thread_register(t[0], 100000); + TEST_RCU_QSBR_RETURN_IF_ERROR((ret == 0), + "NULL variable, invalid thread id"); + + return 0; +} + +/* + * rte_rcu_qsbr_thread_unregister: Remove a reader thread, from the list of + * threads reporting their quiescent state on a QS variable. + */ +static int +test_rcu_qsbr_thread_unregister(void) +{ + int i, j, ret; + uint64_t token; + uint8_t num_threads[3] = {1, TEST_RCU_MAX_LCORE, 1}; + + printf("\nTest rte_rcu_qsbr_thread_unregister()\n"); + + ret = rte_rcu_qsbr_thread_unregister(NULL, enabled_core_ids[0]); + TEST_RCU_QSBR_RETURN_IF_ERROR((ret == 0), "NULL variable check"); + + ret = rte_rcu_qsbr_thread_unregister(NULL, 100000); + TEST_RCU_QSBR_RETURN_IF_ERROR((ret == 0), + "NULL variable, invalid thread id"); + + rte_rcu_qsbr_init(t[0], TEST_RCU_MAX_LCORE); + + rte_rcu_qsbr_thread_register(t[0], enabled_core_ids[0]); + + ret = rte_rcu_qsbr_thread_unregister(t[0], 100000); + TEST_RCU_QSBR_RETURN_IF_ERROR((ret == 0), + "NULL variable, invalid thread id"); + + /* Find first disabled core */ + for (i = 0; i < TEST_RCU_MAX_LCORE; i++) { + if (enabled_core_ids[i] == 0) + break; + } + /* Test with disabled lcore */ + ret = rte_rcu_qsbr_thread_unregister(t[0], i); + TEST_RCU_QSBR_RETURN_IF_ERROR((ret == 1), + "disabled thread id"); + /* Unregister already unregistered core */ + ret = rte_rcu_qsbr_thread_unregister(t[0], i); + TEST_RCU_QSBR_RETURN_IF_ERROR((ret == 1), + "Already unregistered core"); + + /* Test with enabled lcore */ + ret = rte_rcu_qsbr_thread_unregister(t[0], enabled_core_ids[0]); + TEST_RCU_QSBR_RETURN_IF_ERROR((ret == 1), + "enabled thread id"); + /* Unregister already unregistered core */ + ret = rte_rcu_qsbr_thread_unregister(t[0], enabled_core_ids[0]); + TEST_RCU_QSBR_RETURN_IF_ERROR((ret == 1), + "Already unregistered core"); + + /* + * Test with different thread_ids: + * 1 - thread_id = 0 + * 2 - All possible thread_ids, from 0 to TEST_RCU_MAX_LCORE + * 3 - thread_id = TEST_RCU_MAX_LCORE - 1 + */ + for (j = 0; j < 3; j++) { + rte_rcu_qsbr_init(t[0], TEST_RCU_MAX_LCORE); + + for (i = 0; i < num_threads[j]; i++) + rte_rcu_qsbr_thread_register(t[0], + (j == 2) ? (TEST_RCU_MAX_LCORE - 1) : i); + + token = rte_rcu_qsbr_start(t[0]); + TEST_RCU_QSBR_RETURN_IF_ERROR( + (token != (TEST_RCU_QSBR_CNT_INIT + 1)), "QSBR Start"); + /* Update quiescent state counter */ + for (i = 0; i < num_threads[j]; i++) { + /* Skip one update */ + if (i == (TEST_RCU_MAX_LCORE - 10)) + continue; + rte_rcu_qsbr_quiescent(t[0], + (j == 2) ? (TEST_RCU_MAX_LCORE - 1) : i); + } + + if (j == 1) { + /* Validate the updates */ + ret = rte_rcu_qsbr_check(t[0], token, false); + TEST_RCU_QSBR_RETURN_IF_ERROR((ret == 0), + "Non-blocking QSBR check"); + /* Update the previously skipped thread */ + rte_rcu_qsbr_quiescent(t[0], TEST_RCU_MAX_LCORE - 10); + } + + /* Validate the updates */ + ret = rte_rcu_qsbr_check(t[0], token, false); + TEST_RCU_QSBR_RETURN_IF_ERROR((ret == 0), + "Non-blocking QSBR check"); + + for (i = 0; i < num_threads[j]; i++) + rte_rcu_qsbr_thread_unregister(t[0], + (j == 2) ? (TEST_RCU_MAX_LCORE - 1) : i); + + /* Check with no thread registered */ + ret = rte_rcu_qsbr_check(t[0], token, true); + TEST_RCU_QSBR_RETURN_IF_ERROR((ret == 0), + "Blocking QSBR check"); + } + return 0; +} + +/* + * rte_rcu_qsbr_start: Ask the worker threads to report the quiescent state + * status. + */ +static int +test_rcu_qsbr_start(void) +{ + uint64_t token; + int i; + + printf("\nTest rte_rcu_qsbr_start()\n"); + + rte_rcu_qsbr_init(t[0], TEST_RCU_MAX_LCORE); + + for (i = 0; i < 3; i++) + rte_rcu_qsbr_thread_register(t[0], enabled_core_ids[i]); + + token = rte_rcu_qsbr_start(t[0]); + TEST_RCU_QSBR_RETURN_IF_ERROR( + (token != (TEST_RCU_QSBR_CNT_INIT + 1)), "QSBR Start"); + return 0; +} + +static int +test_rcu_qsbr_check_reader(void *arg) +{ + struct rte_rcu_qsbr *temp; + uint8_t read_type = (uint8_t)((uintptr_t)arg); + + temp = t[read_type]; + + /* Update quiescent state counter */ + rte_rcu_qsbr_quiescent(temp, enabled_core_ids[0]); + rte_rcu_qsbr_quiescent(temp, enabled_core_ids[1]); + rte_rcu_qsbr_thread_unregister(temp, enabled_core_ids[2]); + rte_rcu_qsbr_quiescent(temp, enabled_core_ids[3]); + return 0; +} + +/* + * rte_rcu_qsbr_check: Checks if all the worker threads have entered the queis- + * cent state 'n' number of times. 'n' is provided in rte_rcu_qsbr_start API. + */ +static int +test_rcu_qsbr_check(void) +{ + int i, ret; + uint64_t token; + + printf("\nTest rte_rcu_qsbr_check()\n"); + + rte_rcu_qsbr_init(t[0], TEST_RCU_MAX_LCORE); + + token = rte_rcu_qsbr_start(t[0]); + TEST_RCU_QSBR_RETURN_IF_ERROR( + (token != (TEST_RCU_QSBR_CNT_INIT + 1)), "QSBR Start"); + + + ret = rte_rcu_qsbr_check(t[0], 0, false); + TEST_RCU_QSBR_RETURN_IF_ERROR((ret == 0), "Token = 0"); + + ret = rte_rcu_qsbr_check(t[0], token, true); + TEST_RCU_QSBR_RETURN_IF_ERROR((ret == 0), "Blocking QSBR check"); + + for (i = 0; i < 3; i++) + rte_rcu_qsbr_thread_register(t[0], enabled_core_ids[i]); + + ret = rte_rcu_qsbr_check(t[0], token, false); + /* Threads are offline, hence this should pass */ + TEST_RCU_QSBR_RETURN_IF_ERROR((ret == 0), "Non-blocking QSBR check"); + + token = rte_rcu_qsbr_start(t[0]); + TEST_RCU_QSBR_RETURN_IF_ERROR( + (token != (TEST_RCU_QSBR_CNT_INIT + 2)), "QSBR Start"); + + ret = rte_rcu_qsbr_check(t[0], token, false); + /* Threads are offline, hence this should pass */ + TEST_RCU_QSBR_RETURN_IF_ERROR((ret == 0), "Non-blocking QSBR check"); + + for (i = 0; i < 3; i++) + rte_rcu_qsbr_thread_unregister(t[0], enabled_core_ids[i]); + + ret = rte_rcu_qsbr_check(t[0], token, true); + TEST_RCU_QSBR_RETURN_IF_ERROR((ret == 0), "Blocking QSBR check"); + + rte_rcu_qsbr_init(t[0], TEST_RCU_MAX_LCORE); + + for (i = 0; i < 4; i++) + rte_rcu_qsbr_thread_register(t[0], enabled_core_ids[i]); + + token = rte_rcu_qsbr_start(t[0]); + TEST_RCU_QSBR_RETURN_IF_ERROR( + (token != (TEST_RCU_QSBR_CNT_INIT + 1)), "QSBR Start"); + + rte_eal_remote_launch(test_rcu_qsbr_check_reader, NULL, + enabled_core_ids[0]); + + rte_eal_mp_wait_lcore(); + ret = rte_rcu_qsbr_check(t[0], token, true); + TEST_RCU_QSBR_RETURN_IF_ERROR((ret != 1), "Blocking QSBR check"); + + return 0; +} + +static int +test_rcu_qsbr_synchronize_reader(void *arg) +{ + uint32_t lcore_id = rte_lcore_id(); + (void)arg; + + /* Register and become online */ + rte_rcu_qsbr_thread_register(t[0], lcore_id); + rte_rcu_qsbr_thread_online(t[0], lcore_id); + + while (!writer_done) + rte_rcu_qsbr_quiescent(t[0], lcore_id); + + rte_rcu_qsbr_thread_offline(t[0], lcore_id); + rte_rcu_qsbr_thread_unregister(t[0], lcore_id); + + return 0; +} + +/* + * rte_rcu_qsbr_synchronize: Wait till all the reader threads have entered + * the queiscent state. + */ +static int +test_rcu_qsbr_synchronize(void) +{ + int i; + + printf("\nTest rte_rcu_qsbr_synchronize()\n"); + + rte_rcu_qsbr_init(t[0], TEST_RCU_MAX_LCORE); + + /* Test if the API returns when there are no threads reporting + * QS on the variable. + */ + rte_rcu_qsbr_synchronize(t[0], RTE_QSBR_THRID_INVALID); + + /* Test if the API returns when there are threads registered + * but not online. + */ + for (i = 0; i < TEST_RCU_MAX_LCORE; i++) + rte_rcu_qsbr_thread_register(t[0], i); + rte_rcu_qsbr_synchronize(t[0], RTE_QSBR_THRID_INVALID); + + /* Test if the API returns when the caller is also + * reporting the QS status. + */ + rte_rcu_qsbr_thread_online(t[0], 0); + rte_rcu_qsbr_synchronize(t[0], 0); + rte_rcu_qsbr_thread_offline(t[0], 0); + + /* Check the other boundary */ + rte_rcu_qsbr_thread_online(t[0], TEST_RCU_MAX_LCORE - 1); + rte_rcu_qsbr_synchronize(t[0], TEST_RCU_MAX_LCORE - 1); + rte_rcu_qsbr_thread_offline(t[0], TEST_RCU_MAX_LCORE - 1); + + /* Test if the API returns after unregisterng all the threads */ + for (i = 0; i < TEST_RCU_MAX_LCORE; i++) + rte_rcu_qsbr_thread_unregister(t[0], i); + rte_rcu_qsbr_synchronize(t[0], RTE_QSBR_THRID_INVALID); + + /* Test if the API returns with the live threads */ + writer_done = 0; + for (i = 0; i < num_cores; i++) + rte_eal_remote_launch(test_rcu_qsbr_synchronize_reader, + NULL, enabled_core_ids[i]); + rte_rcu_qsbr_synchronize(t[0], RTE_QSBR_THRID_INVALID); + rte_rcu_qsbr_synchronize(t[0], RTE_QSBR_THRID_INVALID); + rte_rcu_qsbr_synchronize(t[0], RTE_QSBR_THRID_INVALID); + rte_rcu_qsbr_synchronize(t[0], RTE_QSBR_THRID_INVALID); + rte_rcu_qsbr_synchronize(t[0], RTE_QSBR_THRID_INVALID); + + writer_done = 1; + rte_eal_mp_wait_lcore(); + + return 0; +} + +/* + * rte_rcu_qsbr_thread_online: Add a registered reader thread, to + * the list of threads reporting their quiescent state on a QS variable. + */ +static int +test_rcu_qsbr_thread_online(void) +{ + int i, ret; + uint64_t token; + + printf("Test rte_rcu_qsbr_thread_online()\n"); + + rte_rcu_qsbr_init(t[0], TEST_RCU_MAX_LCORE); + + /* Register 2 threads to validate that only the + * online thread is waited upon. + */ + rte_rcu_qsbr_thread_register(t[0], enabled_core_ids[0]); + rte_rcu_qsbr_thread_register(t[0], enabled_core_ids[1]); + + /* Use qsbr_start to verify that the thread_online API + * succeeded. + */ + token = rte_rcu_qsbr_start(t[0]); + + /* Make the thread online */ + rte_rcu_qsbr_thread_online(t[0], enabled_core_ids[0]); + + /* Check if the thread is online */ + ret = rte_rcu_qsbr_check(t[0], token, true); + TEST_RCU_QSBR_RETURN_IF_ERROR((ret == 0), "thread online"); + + /* Check if the online thread, can report QS */ + token = rte_rcu_qsbr_start(t[0]); + rte_rcu_qsbr_quiescent(t[0], enabled_core_ids[0]); + ret = rte_rcu_qsbr_check(t[0], token, true); + TEST_RCU_QSBR_RETURN_IF_ERROR((ret == 0), "thread update"); + + /* Make all the threads online */ + rte_rcu_qsbr_init(t[0], TEST_RCU_MAX_LCORE); + token = rte_rcu_qsbr_start(t[0]); + for (i = 0; i < TEST_RCU_MAX_LCORE; i++) { + rte_rcu_qsbr_thread_register(t[0], i); + rte_rcu_qsbr_thread_online(t[0], i); + } + /* Check if all the threads are online */ + ret = rte_rcu_qsbr_check(t[0], token, true); + TEST_RCU_QSBR_RETURN_IF_ERROR((ret == 0), "thread online"); + /* Check if all the online threads can report QS */ + token = rte_rcu_qsbr_start(t[0]); + for (i = 0; i < TEST_RCU_MAX_LCORE; i++) + rte_rcu_qsbr_quiescent(t[0], i); + ret = rte_rcu_qsbr_check(t[0], token, true); + TEST_RCU_QSBR_RETURN_IF_ERROR((ret == 0), "thread update"); + + return 0; +} + +/* + * rte_rcu_qsbr_thread_offline: Remove a registered reader thread, from + * the list of threads reporting their quiescent state on a QS variable. + */ +static int +test_rcu_qsbr_thread_offline(void) +{ + int i, ret; + uint64_t token; + + printf("\nTest rte_rcu_qsbr_thread_offline()\n"); + + rte_rcu_qsbr_init(t[0], TEST_RCU_MAX_LCORE); + + rte_rcu_qsbr_thread_register(t[0], enabled_core_ids[0]); + + /* Make the thread offline */ + rte_rcu_qsbr_thread_offline(t[0], enabled_core_ids[0]); + + /* Use qsbr_start to verify that the thread_offline API + * succeeded. + */ + token = rte_rcu_qsbr_start(t[0]); + /* Check if the thread is offline */ + ret = rte_rcu_qsbr_check(t[0], token, true); + TEST_RCU_QSBR_RETURN_IF_ERROR((ret == 0), "thread offline"); + + /* Bring an offline thread online and check if it can + * report QS. + */ + rte_rcu_qsbr_thread_online(t[0], enabled_core_ids[0]); + /* Check if the online thread, can report QS */ + token = rte_rcu_qsbr_start(t[0]); + rte_rcu_qsbr_quiescent(t[0], enabled_core_ids[0]); + ret = rte_rcu_qsbr_check(t[0], token, true); + TEST_RCU_QSBR_RETURN_IF_ERROR((ret == 0), "offline to online"); + + /* + * Check a sequence of online/status/offline/status/online/status + */ + rte_rcu_qsbr_init(t[0], TEST_RCU_MAX_LCORE); + token = rte_rcu_qsbr_start(t[0]); + /* Make the threads online */ + for (i = 0; i < TEST_RCU_MAX_LCORE; i++) { + rte_rcu_qsbr_thread_register(t[0], i); + rte_rcu_qsbr_thread_online(t[0], i); + } + + /* Check if all the threads are online */ + ret = rte_rcu_qsbr_check(t[0], token, true); + TEST_RCU_QSBR_RETURN_IF_ERROR((ret == 0), "thread online"); + + /* Check if all the online threads can report QS */ + token = rte_rcu_qsbr_start(t[0]); + for (i = 0; i < TEST_RCU_MAX_LCORE; i++) + rte_rcu_qsbr_quiescent(t[0], i); + ret = rte_rcu_qsbr_check(t[0], token, true); + TEST_RCU_QSBR_RETURN_IF_ERROR((ret == 0), "report QS"); + + /* Make all the threads offline */ + for (i = 0; i < TEST_RCU_MAX_LCORE; i++) + rte_rcu_qsbr_thread_offline(t[0], i); + /* Make sure these threads are not being waited on */ + token = rte_rcu_qsbr_start(t[0]); + ret = rte_rcu_qsbr_check(t[0], token, true); + TEST_RCU_QSBR_RETURN_IF_ERROR((ret == 0), "offline QS"); + + /* Make the threads online */ + for (i = 0; i < TEST_RCU_MAX_LCORE; i++) + rte_rcu_qsbr_thread_online(t[0], i); + /* Check if all the online threads can report QS */ + token = rte_rcu_qsbr_start(t[0]); + for (i = 0; i < TEST_RCU_MAX_LCORE; i++) + rte_rcu_qsbr_quiescent(t[0], i); + ret = rte_rcu_qsbr_check(t[0], token, true); + TEST_RCU_QSBR_RETURN_IF_ERROR((ret == 0), "online again"); + + return 0; +} + +/* + * rte_rcu_qsbr_dump: Dump status of a single QS variable to a file + */ +static int +test_rcu_qsbr_dump(void) +{ + int i; + + printf("\nTest rte_rcu_qsbr_dump()\n"); + + /* Negative tests */ + rte_rcu_qsbr_dump(NULL, t[0]); + rte_rcu_qsbr_dump(stdout, NULL); + rte_rcu_qsbr_dump(NULL, NULL); + + rte_rcu_qsbr_init(t[0], TEST_RCU_MAX_LCORE); + rte_rcu_qsbr_init(t[1], TEST_RCU_MAX_LCORE); + + /* QS variable with 0 core mask */ + rte_rcu_qsbr_dump(stdout, t[0]); + + rte_rcu_qsbr_thread_register(t[0], enabled_core_ids[0]); + + for (i = 1; i < 3; i++) + rte_rcu_qsbr_thread_register(t[1], enabled_core_ids[i]); + + rte_rcu_qsbr_dump(stdout, t[0]); + rte_rcu_qsbr_dump(stdout, t[1]); + printf("\n"); + return 0; +} + +static int +test_rcu_qsbr_reader(void *arg) +{ + struct rte_rcu_qsbr *temp; + struct rte_hash *hash = NULL; + int i; + uint32_t lcore_id = rte_lcore_id(); + uint8_t read_type = (uint8_t)((uintptr_t)arg); + uint32_t *pdata; + + temp = t[read_type]; + hash = h[read_type]; + + do { + rte_rcu_qsbr_thread_register(temp, lcore_id); + rte_rcu_qsbr_thread_online(temp, lcore_id); + for (i = 0; i < TOTAL_ENTRY; i++) { + rte_rcu_qsbr_lock(temp, lcore_id); + if (rte_hash_lookup_data(hash, keys+i, + (void **)&pdata) != -ENOENT) { + *pdata = 0; + while (*pdata < COUNTER_VALUE) + ++*pdata; + } + rte_rcu_qsbr_unlock(temp, lcore_id); + } + /* Update quiescent state counter */ + rte_rcu_qsbr_quiescent(temp, lcore_id); + rte_rcu_qsbr_thread_offline(temp, lcore_id); + rte_rcu_qsbr_thread_unregister(temp, lcore_id); + } while (!writer_done); + + return 0; +} + +static int +test_rcu_qsbr_writer(void *arg) +{ + uint64_t token; + int32_t pos; + struct rte_rcu_qsbr *temp; + struct rte_hash *hash = NULL; + uint8_t writer_type = (uint8_t)((uintptr_t)arg); + + temp = t[(writer_type/2) % TEST_RCU_MAX_LCORE]; + hash = h[(writer_type/2) % TEST_RCU_MAX_LCORE]; + + /* Delete element from the shared data structure */ + pos = rte_hash_del_key(hash, keys + (writer_type % TOTAL_ENTRY)); + if (pos < 0) { + printf("Delete key failed #%d\n", + keys[writer_type % TOTAL_ENTRY]); + return -1; + } + /* Start the quiescent state query process */ + token = rte_rcu_qsbr_start(temp); + /* Check the quiescent state status */ + rte_rcu_qsbr_check(temp, token, true); + if (*hash_data[(writer_type/2) % TEST_RCU_MAX_LCORE] + [writer_type % TOTAL_ENTRY] != COUNTER_VALUE && + *hash_data[(writer_type/2) % TEST_RCU_MAX_LCORE] + [writer_type % TOTAL_ENTRY] != 0) { + printf("Reader did not complete #%d = %d\t", writer_type, + *hash_data[(writer_type/2) % TEST_RCU_MAX_LCORE] + [writer_type % TOTAL_ENTRY]); + return -1; + } + + if (rte_hash_free_key_with_position(hash, pos) < 0) { + printf("Failed to free the key #%d\n", + keys[writer_type % TOTAL_ENTRY]); + return -1; + } + rte_free(hash_data[(writer_type/2) % TEST_RCU_MAX_LCORE] + [writer_type % TOTAL_ENTRY]); + hash_data[(writer_type/2) % TEST_RCU_MAX_LCORE] + [writer_type % TOTAL_ENTRY] = NULL; + + return 0; +} + +static struct rte_hash * +init_hash(int hash_id) +{ + int i; + struct rte_hash *h = NULL; + + sprintf(hash_name[hash_id], "hash%d", hash_id); + struct rte_hash_parameters hash_params = { + .entries = TOTAL_ENTRY, + .key_len = sizeof(uint32_t), + .hash_func_init_val = 0, + .socket_id = rte_socket_id(), + .hash_func = rte_hash_crc, + .extra_flag = + RTE_HASH_EXTRA_FLAGS_RW_CONCURRENCY_LF, + .name = hash_name[hash_id], + }; + + h = rte_hash_create(&hash_params); + if (h == NULL) { + printf("Hash create Failed\n"); + return NULL; + } + + for (i = 0; i < TOTAL_ENTRY; i++) { + hash_data[hash_id][i] = rte_zmalloc(NULL, sizeof(uint32_t), 0); + if (hash_data[hash_id][i] == NULL) { + printf("No memory\n"); + return NULL; + } + } + keys = rte_malloc(NULL, sizeof(uint32_t) * TOTAL_ENTRY, 0); + if (keys == NULL) { + printf("No memory\n"); + return NULL; + } + + for (i = 0; i < TOTAL_ENTRY; i++) + keys[i] = i; + + for (i = 0; i < TOTAL_ENTRY; i++) { + if (rte_hash_add_key_data(h, keys + i, + (void *)((uintptr_t)hash_data[hash_id][i])) + < 0) { + printf("Hash key add Failed #%d\n", i); + return NULL; + } + } + return h; +} + +/* + * Functional test: + * Single writer, Single QS variable, simultaneous QSBR Queries + */ +static int +test_rcu_qsbr_sw_sv_3qs(void) +{ + uint64_t token[3]; + int i; + int32_t pos[3]; + + writer_done = 0; + + printf("Test: 1 writer, 1 QSBR variable, simultaneous QSBR queries\n"); + + rte_rcu_qsbr_init(t[0], TEST_RCU_MAX_LCORE); + + /* Shared data structure created */ + h[0] = init_hash(0); + if (h[0] == NULL) { + printf("Hash init failed\n"); + goto error; + } + + /* Reader threads are launched */ + for (i = 0; i < 4; i++) + rte_eal_remote_launch(test_rcu_qsbr_reader, NULL, + enabled_core_ids[i]); + + /* Delete element from the shared data structure */ + pos[0] = rte_hash_del_key(h[0], keys + 0); + if (pos[0] < 0) { + printf("Delete key failed #%d\n", keys[0]); + goto error; + } + /* Start the quiescent state query process */ + token[0] = rte_rcu_qsbr_start(t[0]); + + /* Delete element from the shared data structure */ + pos[1] = rte_hash_del_key(h[0], keys + 3); + if (pos[1] < 0) { + printf("Delete key failed #%d\n", keys[3]); + goto error; + } + /* Start the quiescent state query process */ + token[1] = rte_rcu_qsbr_start(t[0]); + + /* Delete element from the shared data structure */ + pos[2] = rte_hash_del_key(h[0], keys + 6); + if (pos[2] < 0) { + printf("Delete key failed #%d\n", keys[6]); + goto error; + } + /* Start the quiescent state query process */ + token[2] = rte_rcu_qsbr_start(t[0]); + + /* Check the quiescent state status */ + rte_rcu_qsbr_check(t[0], token[0], true); + if (*hash_data[0][0] != COUNTER_VALUE && *hash_data[0][0] != 0) { + printf("Reader did not complete #0 = %d\n", *hash_data[0][0]); + goto error; + } + + if (rte_hash_free_key_with_position(h[0], pos[0]) < 0) { + printf("Failed to free the key #%d\n", keys[0]); + goto error; + } + rte_free(hash_data[0][0]); + hash_data[0][0] = NULL; + + /* Check the quiescent state status */ + rte_rcu_qsbr_check(t[0], token[1], true); + if (*hash_data[0][3] != COUNTER_VALUE && *hash_data[0][3] != 0) { + printf("Reader did not complete #3 = %d\n", *hash_data[0][3]); + goto error; + } + + if (rte_hash_free_key_with_position(h[0], pos[1]) < 0) { + printf("Failed to free the key #%d\n", keys[3]); + goto error; + } + rte_free(hash_data[0][3]); + hash_data[0][3] = NULL; + + /* Check the quiescent state status */ + rte_rcu_qsbr_check(t[0], token[2], true); + if (*hash_data[0][6] != COUNTER_VALUE && *hash_data[0][6] != 0) { + printf("Reader did not complete #6 = %d\n", *hash_data[0][6]); + goto error; + } + + if (rte_hash_free_key_with_position(h[0], pos[2]) < 0) { + printf("Failed to free the key #%d\n", keys[6]); + goto error; + } + rte_free(hash_data[0][6]); + hash_data[0][6] = NULL; + + writer_done = 1; + /* Wait until all readers have exited */ + rte_eal_mp_wait_lcore(); + /* Check return value from threads */ + for (i = 0; i < 4; i++) + if (lcore_config[enabled_core_ids[i]].ret < 0) + goto error; + rte_hash_free(h[0]); + rte_free(keys); + + return 0; + +error: + writer_done = 1; + /* Wait until all readers have exited */ + rte_eal_mp_wait_lcore(); + + rte_hash_free(h[0]); + rte_free(keys); + for (i = 0; i < TOTAL_ENTRY; i++) + rte_free(hash_data[0][i]); + + return -1; +} + +/* + * Multi writer, Multiple QS variable, simultaneous QSBR queries + */ +static int +test_rcu_qsbr_mw_mv_mqs(void) +{ + int i, j; + uint8_t test_cores; + + writer_done = 0; + test_cores = num_cores / 4; + test_cores = test_cores * 4; + + printf("Test: %d writers, %d QSBR variable, simultaneous QSBR queries\n" + , test_cores / 2, test_cores / 4); + + for (i = 0; i < num_cores / 4; i++) { + rte_rcu_qsbr_init(t[i], TEST_RCU_MAX_LCORE); + h[i] = init_hash(i); + if (h[i] == NULL) { + printf("Hash init failed\n"); + goto error; + } + } + + /* Reader threads are launched */ + for (i = 0; i < test_cores / 2; i++) + rte_eal_remote_launch(test_rcu_qsbr_reader, + (void *)(uintptr_t)(i / 2), + enabled_core_ids[i]); + + /* Writer threads are launched */ + for (; i < test_cores; i++) + rte_eal_remote_launch(test_rcu_qsbr_writer, + (void *)(uintptr_t)(i - (test_cores / 2)), + enabled_core_ids[i]); + /* Wait for writers to complete */ + for (i = test_cores / 2; i < test_cores; i++) + rte_eal_wait_lcore(enabled_core_ids[i]); + + writer_done = 1; + /* Wait for readers to complete */ + rte_eal_mp_wait_lcore(); + + /* Check return value from threads */ + for (i = 0; i < test_cores; i++) + if (lcore_config[enabled_core_ids[i]].ret < 0) + goto error; + + for (i = 0; i < num_cores / 4; i++) + rte_hash_free(h[i]); + + rte_free(keys); + + return 0; + +error: + writer_done = 1; + /* Wait until all readers have exited */ + rte_eal_mp_wait_lcore(); + + for (i = 0; i < num_cores / 4; i++) + rte_hash_free(h[i]); + rte_free(keys); + for (j = 0; j < TEST_RCU_MAX_LCORE; j++) + for (i = 0; i < TOTAL_ENTRY; i++) + rte_free(hash_data[j][i]); + + return -1; +} + +static int +test_rcu_qsbr_main(void) +{ + if (get_enabled_cores_mask() != 0) + return -1; + + if (num_cores < 4) { + printf("Test failed! Need 4 or more cores\n"); + goto test_fail; + } + + /* Error-checking test cases */ + if (test_rcu_qsbr_get_memsize() < 0) + goto test_fail; + + if (test_rcu_qsbr_init() < 0) + goto test_fail; + + alloc_rcu(); + + if (test_rcu_qsbr_thread_register() < 0) + goto test_fail; + + if (test_rcu_qsbr_thread_unregister() < 0) + goto test_fail; + + if (test_rcu_qsbr_start() < 0) + goto test_fail; + + if (test_rcu_qsbr_check() < 0) + goto test_fail; + + if (test_rcu_qsbr_synchronize() < 0) + goto test_fail; + + if (test_rcu_qsbr_dump() < 0) + goto test_fail; + + if (test_rcu_qsbr_thread_online() < 0) + goto test_fail; + + if (test_rcu_qsbr_thread_offline() < 0) + goto test_fail; + + printf("\nFunctional tests\n"); + + if (test_rcu_qsbr_sw_sv_3qs() < 0) + goto test_fail; + + if (test_rcu_qsbr_mw_mv_mqs() < 0) + goto test_fail; + + free_rcu(); + + printf("\n"); + return 0; + +test_fail: + free_rcu(); + + return -1; +} + +REGISTER_TEST_COMMAND(rcu_qsbr_autotest, test_rcu_qsbr_main); diff --git a/app/test/test_rcu_qsbr_perf.c b/app/test/test_rcu_qsbr_perf.c new file mode 100644 index 000000000..16a43f8db --- /dev/null +++ b/app/test/test_rcu_qsbr_perf.c @@ -0,0 +1,704 @@ +/* SPDX-License-Identifier: BSD-3-Clause + * Copyright (c) 2018 Arm Limited + */ + +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +#include "test.h" + +/* Check condition and return an error if true. */ +#define TEST_RCU_MAX_LCORE 128 +static uint16_t enabled_core_ids[TEST_RCU_MAX_LCORE]; +static uint8_t num_cores; + +static uint32_t *keys; +#define TOTAL_ENTRY (1024 * 8) +#define COUNTER_VALUE 4096 +static uint32_t *hash_data[TEST_RCU_MAX_LCORE][TOTAL_ENTRY]; +static volatile uint8_t writer_done; +static volatile uint8_t all_registered; +static volatile uint32_t thr_id; + +static struct rte_rcu_qsbr *t[TEST_RCU_MAX_LCORE]; +static struct rte_hash *h[TEST_RCU_MAX_LCORE]; +static char hash_name[TEST_RCU_MAX_LCORE][8]; +static rte_atomic64_t updates, checks; +static rte_atomic64_t update_cycles, check_cycles; + +/* Scale down results to 1000 operations to support lower + * granularity clocks. + */ +#define RCU_SCALE_DOWN 1000 + +/* Simple way to allocate thread ids in 0 to TEST_RCU_MAX_LCORE space */ +static inline uint32_t +alloc_thread_id(void) +{ + uint32_t tmp_thr_id; + + tmp_thr_id = __atomic_fetch_add(&thr_id, 1, __ATOMIC_RELAXED); + if (tmp_thr_id >= TEST_RCU_MAX_LCORE) + printf("Invalid thread id %u\n", tmp_thr_id); + + return tmp_thr_id; +} + +static inline int +get_enabled_cores_mask(void) +{ + uint16_t core_id; + uint32_t max_cores = rte_lcore_count(); + + if (max_cores > TEST_RCU_MAX_LCORE) { + printf("Number of cores exceed %d\n", TEST_RCU_MAX_LCORE); + return -1; + } + + core_id = 0; + num_cores = 0; + RTE_LCORE_FOREACH_SLAVE(core_id) { + enabled_core_ids[num_cores] = core_id; + num_cores++; + } + + return 0; +} + +static int +test_rcu_qsbr_reader_perf(void *arg) +{ + bool writer_present = (bool)arg; + uint32_t thread_id = alloc_thread_id(); + uint64_t loop_cnt = 0; + uint64_t begin, cycles; + + /* Register for report QS */ + rte_rcu_qsbr_thread_register(t[0], thread_id); + /* Make the thread online */ + rte_rcu_qsbr_thread_online(t[0], thread_id); + + begin = rte_rdtsc_precise(); + + if (writer_present) { + while (!writer_done) { + /* Update quiescent state counter */ + rte_rcu_qsbr_quiescent(t[0], thread_id); + loop_cnt++; + } + } else { + while (loop_cnt < 100000000) { + /* Update quiescent state counter */ + rte_rcu_qsbr_quiescent(t[0], thread_id); + loop_cnt++; + } + } + + cycles = rte_rdtsc_precise() - begin; + rte_atomic64_add(&update_cycles, cycles); + rte_atomic64_add(&updates, loop_cnt); + + /* Make the thread offline */ + rte_rcu_qsbr_thread_offline(t[0], thread_id); + /* Unregister before exiting to avoid writer from waiting */ + rte_rcu_qsbr_thread_unregister(t[0], thread_id); + + return 0; +} + +static int +test_rcu_qsbr_writer_perf(void *arg) +{ + bool wait = (bool)arg; + uint64_t token = 0; + uint64_t loop_cnt = 0; + uint64_t begin, cycles; + + begin = rte_rdtsc_precise(); + + do { + /* Start the quiescent state query process */ + if (wait) + token = rte_rcu_qsbr_start(t[0]); + + /* Check quiescent state status */ + rte_rcu_qsbr_check(t[0], token, wait); + loop_cnt++; + } while (loop_cnt < 20000000); + + cycles = rte_rdtsc_precise() - begin; + rte_atomic64_add(&check_cycles, cycles); + rte_atomic64_add(&checks, loop_cnt); + return 0; +} + +/* + * Perf test: Reader/writer + * Single writer, Multiple Readers, Single QS var, Non-Blocking rcu_qsbr_check + */ +static int +test_rcu_qsbr_perf(void) +{ + int i, sz; + int tmp_num_cores; + + writer_done = 0; + + rte_atomic64_clear(&updates); + rte_atomic64_clear(&update_cycles); + rte_atomic64_clear(&checks); + rte_atomic64_clear(&check_cycles); + + printf("\nPerf Test: %d Readers/1 Writer('wait' in qsbr_check == true)\n", + num_cores - 1); + + __atomic_store_n(&thr_id, 0, __ATOMIC_SEQ_CST); + + if (all_registered == 1) + tmp_num_cores = num_cores - 1; + else + tmp_num_cores = TEST_RCU_MAX_LCORE; + + sz = rte_rcu_qsbr_get_memsize(tmp_num_cores); + t[0] = (struct rte_rcu_qsbr *)rte_zmalloc("rcu0", sz, + RTE_CACHE_LINE_SIZE); + /* QS variable is initialized */ + rte_rcu_qsbr_init(t[0], tmp_num_cores); + + /* Reader threads are launched */ + for (i = 0; i < num_cores - 1; i++) + rte_eal_remote_launch(test_rcu_qsbr_reader_perf, (void *)1, + enabled_core_ids[i]); + + /* Writer thread is launched */ + rte_eal_remote_launch(test_rcu_qsbr_writer_perf, + (void *)1, enabled_core_ids[i]); + + /* Wait for the writer thread */ + rte_eal_wait_lcore(enabled_core_ids[i]); + writer_done = 1; + + /* Wait until all readers have exited */ + rte_eal_mp_wait_lcore(); + + printf("Total RCU updates = %"PRIi64"\n", rte_atomic64_read(&updates)); + printf("Cycles per %d updates: %"PRIi64"\n", RCU_SCALE_DOWN, + rte_atomic64_read(&update_cycles) / + (rte_atomic64_read(&updates) / RCU_SCALE_DOWN)); + printf("Total RCU checks = %"PRIi64"\n", rte_atomic64_read(&checks)); + printf("Cycles per %d checks: %"PRIi64"\n", RCU_SCALE_DOWN, + rte_atomic64_read(&check_cycles) / + (rte_atomic64_read(&checks) / RCU_SCALE_DOWN)); + + rte_free(t[0]); + + return 0; +} + +/* + * Perf test: Readers + * Single writer, Multiple readers, Single QS variable + */ +static int +test_rcu_qsbr_rperf(void) +{ + int i, sz; + int tmp_num_cores; + + rte_atomic64_clear(&updates); + rte_atomic64_clear(&update_cycles); + + __atomic_store_n(&thr_id, 0, __ATOMIC_SEQ_CST); + + printf("\nPerf Test: %d Readers\n", num_cores); + + if (all_registered == 1) + tmp_num_cores = num_cores; + else + tmp_num_cores = TEST_RCU_MAX_LCORE; + + sz = rte_rcu_qsbr_get_memsize(tmp_num_cores); + t[0] = (struct rte_rcu_qsbr *)rte_zmalloc("rcu0", sz, + RTE_CACHE_LINE_SIZE); + /* QS variable is initialized */ + rte_rcu_qsbr_init(t[0], tmp_num_cores); + + /* Reader threads are launched */ + for (i = 0; i < num_cores; i++) + rte_eal_remote_launch(test_rcu_qsbr_reader_perf, NULL, + enabled_core_ids[i]); + + /* Wait until all readers have exited */ + rte_eal_mp_wait_lcore(); + + printf("Total RCU updates = %"PRIi64"\n", rte_atomic64_read(&updates)); + printf("Cycles per %d updates: %"PRIi64"\n", RCU_SCALE_DOWN, + rte_atomic64_read(&update_cycles) / + (rte_atomic64_read(&updates) / RCU_SCALE_DOWN)); + + rte_free(t[0]); + + return 0; +} + +/* + * Perf test: + * Multiple writer, Single QS variable, Non-blocking rcu_qsbr_check + */ +static int +test_rcu_qsbr_wperf(void) +{ + int i, sz; + + rte_atomic64_clear(&checks); + rte_atomic64_clear(&check_cycles); + + __atomic_store_n(&thr_id, 0, __ATOMIC_SEQ_CST); + + printf("\nPerf test: %d Writers ('wait' in qsbr_check == false)\n", + num_cores); + + /* Number of readers does not matter for QS variable in this test + * case as no reader will be registered. + */ + sz = rte_rcu_qsbr_get_memsize(TEST_RCU_MAX_LCORE); + t[0] = (struct rte_rcu_qsbr *)rte_zmalloc("rcu0", sz, + RTE_CACHE_LINE_SIZE); + /* QS variable is initialized */ + rte_rcu_qsbr_init(t[0], TEST_RCU_MAX_LCORE); + + /* Writer threads are launched */ + for (i = 0; i < num_cores; i++) + rte_eal_remote_launch(test_rcu_qsbr_writer_perf, + (void *)0, enabled_core_ids[i]); + + /* Wait until all readers have exited */ + rte_eal_mp_wait_lcore(); + + printf("Total RCU checks = %"PRIi64"\n", rte_atomic64_read(&checks)); + printf("Cycles per %d checks: %"PRIi64"\n", RCU_SCALE_DOWN, + rte_atomic64_read(&check_cycles) / + (rte_atomic64_read(&checks) / RCU_SCALE_DOWN)); + + rte_free(t[0]); + + return 0; +} + +/* + * RCU test cases using rte_hash data structure. + */ +static int +test_rcu_qsbr_hash_reader(void *arg) +{ + struct rte_rcu_qsbr *temp; + struct rte_hash *hash = NULL; + int i; + uint64_t loop_cnt = 0; + uint64_t begin, cycles; + uint32_t thread_id = alloc_thread_id(); + uint8_t read_type = (uint8_t)((uintptr_t)arg); + uint32_t *pdata; + + temp = t[read_type]; + hash = h[read_type]; + + rte_rcu_qsbr_thread_register(temp, thread_id); + + begin = rte_rdtsc_precise(); + + do { + rte_rcu_qsbr_thread_online(temp, thread_id); + for (i = 0; i < TOTAL_ENTRY; i++) { + rte_rcu_qsbr_lock(temp, thread_id); + if (rte_hash_lookup_data(hash, keys+i, + (void **)&pdata) != -ENOENT) { + *pdata = 0; + while (*pdata < COUNTER_VALUE) + ++*pdata; + } + rte_rcu_qsbr_unlock(temp, thread_id); + } + /* Update quiescent state counter */ + rte_rcu_qsbr_quiescent(temp, thread_id); + rte_rcu_qsbr_thread_offline(temp, thread_id); + loop_cnt++; + } while (!writer_done); + + cycles = rte_rdtsc_precise() - begin; + rte_atomic64_add(&update_cycles, cycles); + rte_atomic64_add(&updates, loop_cnt); + + rte_rcu_qsbr_thread_unregister(temp, thread_id); + + return 0; +} + +static struct rte_hash * +init_hash(int hash_id) +{ + int i; + struct rte_hash *h = NULL; + + sprintf(hash_name[hash_id], "hash%d", hash_id); + struct rte_hash_parameters hash_params = { + .entries = TOTAL_ENTRY, + .key_len = sizeof(uint32_t), + .hash_func_init_val = 0, + .socket_id = rte_socket_id(), + .hash_func = rte_hash_crc, + .extra_flag = + RTE_HASH_EXTRA_FLAGS_RW_CONCURRENCY_LF, + .name = hash_name[hash_id], + }; + + h = rte_hash_create(&hash_params); + if (h == NULL) { + printf("Hash create Failed\n"); + return NULL; + } + + for (i = 0; i < TOTAL_ENTRY; i++) { + hash_data[hash_id][i] = rte_zmalloc(NULL, sizeof(uint32_t), 0); + if (hash_data[hash_id][i] == NULL) { + printf("No memory\n"); + return NULL; + } + } + keys = rte_malloc(NULL, sizeof(uint32_t) * TOTAL_ENTRY, 0); + if (keys == NULL) { + printf("No memory\n"); + return NULL; + } + + for (i = 0; i < TOTAL_ENTRY; i++) + keys[i] = i; + + for (i = 0; i < TOTAL_ENTRY; i++) { + if (rte_hash_add_key_data(h, keys + i, + (void *)((uintptr_t)hash_data[hash_id][i])) + < 0) { + printf("Hash key add Failed #%d\n", i); + return NULL; + } + } + return h; +} + +/* + * Functional test: + * Single writer, Single QS variable Single QSBR query, Blocking rcu_qsbr_check + */ +static int +test_rcu_qsbr_sw_sv_1qs(void) +{ + uint64_t token, begin, cycles; + int i, tmp_num_cores, sz; + int32_t pos; + + writer_done = 0; + + rte_atomic64_clear(&updates); + rte_atomic64_clear(&update_cycles); + rte_atomic64_clear(&checks); + rte_atomic64_clear(&check_cycles); + + __atomic_store_n(&thr_id, 0, __ATOMIC_SEQ_CST); + + printf("\nPerf test: 1 writer, %d readers, 1 QSBR variable, 1 QSBR Query, Blocking QSBR Check\n", num_cores); + + if (all_registered == 1) + tmp_num_cores = num_cores; + else + tmp_num_cores = TEST_RCU_MAX_LCORE; + + sz = rte_rcu_qsbr_get_memsize(tmp_num_cores); + t[0] = (struct rte_rcu_qsbr *)rte_zmalloc("rcu0", sz, + RTE_CACHE_LINE_SIZE); + /* QS variable is initialized */ + rte_rcu_qsbr_init(t[0], tmp_num_cores); + + /* Shared data structure created */ + h[0] = init_hash(0); + if (h[0] == NULL) { + printf("Hash init failed\n"); + goto error; + } + + /* Reader threads are launched */ + for (i = 0; i < num_cores; i++) + rte_eal_remote_launch(test_rcu_qsbr_hash_reader, NULL, + enabled_core_ids[i]); + + begin = rte_rdtsc_precise(); + + for (i = 0; i < TOTAL_ENTRY; i++) { + /* Delete elements from the shared data structure */ + pos = rte_hash_del_key(h[0], keys + i); + if (pos < 0) { + printf("Delete key failed #%d\n", keys[i]); + goto error; + } + /* Start the quiescent state query process */ + token = rte_rcu_qsbr_start(t[0]); + + /* Check the quiescent state status */ + rte_rcu_qsbr_check(t[0], token, true); + if (*hash_data[0][i] != COUNTER_VALUE && + *hash_data[0][i] != 0) { + printf("Reader did not complete #%d = %d\n", i, + *hash_data[0][i]); + goto error; + } + + if (rte_hash_free_key_with_position(h[0], pos) < 0) { + printf("Failed to free the key #%d\n", keys[i]); + goto error; + } + rte_free(hash_data[0][i]); + hash_data[0][i] = NULL; + } + + cycles = rte_rdtsc_precise() - begin; + rte_atomic64_add(&check_cycles, cycles); + rte_atomic64_add(&checks, i); + + writer_done = 1; + + /* Wait until all readers have exited */ + rte_eal_mp_wait_lcore(); + /* Check return value from threads */ + for (i = 0; i < num_cores; i++) + if (lcore_config[enabled_core_ids[i]].ret < 0) + goto error; + rte_hash_free(h[0]); + rte_free(keys); + + printf("Following numbers include calls to rte_hash functions\n"); + printf("Cycles per 1 update(online/update/offline): %"PRIi64"\n", + rte_atomic64_read(&update_cycles) / + rte_atomic64_read(&updates)); + + printf("Cycles per 1 check(start, check): %"PRIi64"\n\n", + rte_atomic64_read(&check_cycles) / + rte_atomic64_read(&checks)); + + rte_free(t[0]); + + return 0; + +error: + writer_done = 1; + /* Wait until all readers have exited */ + rte_eal_mp_wait_lcore(); + + rte_hash_free(h[0]); + rte_free(keys); + for (i = 0; i < TOTAL_ENTRY; i++) + rte_free(hash_data[0][i]); + + rte_free(t[0]); + + return -1; +} + +/* + * Functional test: + * Single writer, Single QS variable, Single QSBR query, + * Non-blocking rcu_qsbr_check + */ +static int +test_rcu_qsbr_sw_sv_1qs_non_blocking(void) +{ + uint64_t token, begin, cycles; + int i, ret, tmp_num_cores, sz; + int32_t pos; + + writer_done = 0; + + printf("Perf test: 1 writer, %d readers, 1 QSBR variable, 1 QSBR Query, Non-Blocking QSBR check\n", num_cores); + + __atomic_store_n(&thr_id, 0, __ATOMIC_SEQ_CST); + + if (all_registered == 1) + tmp_num_cores = num_cores; + else + tmp_num_cores = TEST_RCU_MAX_LCORE; + + sz = rte_rcu_qsbr_get_memsize(tmp_num_cores); + t[0] = (struct rte_rcu_qsbr *)rte_zmalloc("rcu0", sz, + RTE_CACHE_LINE_SIZE); + /* QS variable is initialized */ + rte_rcu_qsbr_init(t[0], tmp_num_cores); + + /* Shared data structure created */ + h[0] = init_hash(0); + if (h[0] == NULL) { + printf("Hash init failed\n"); + goto error; + } + + /* Reader threads are launched */ + for (i = 0; i < num_cores; i++) + rte_eal_remote_launch(test_rcu_qsbr_hash_reader, NULL, + enabled_core_ids[i]); + + begin = rte_rdtsc_precise(); + + for (i = 0; i < TOTAL_ENTRY; i++) { + /* Delete elements from the shared data structure */ + pos = rte_hash_del_key(h[0], keys + i); + if (pos < 0) { + printf("Delete key failed #%d\n", keys[i]); + goto error; + } + /* Start the quiescent state query process */ + token = rte_rcu_qsbr_start(t[0]); + + /* Check the quiescent state status */ + do { + ret = rte_rcu_qsbr_check(t[0], token, false); + } while (ret == 0); + if (*hash_data[0][i] != COUNTER_VALUE && + *hash_data[0][i] != 0) { + printf("Reader did not complete #%d = %d\n", i, + *hash_data[0][i]); + goto error; + } + + if (rte_hash_free_key_with_position(h[0], pos) < 0) { + printf("Failed to free the key #%d\n", keys[i]); + goto error; + } + rte_free(hash_data[0][i]); + hash_data[0][i] = NULL; + } + + cycles = rte_rdtsc_precise() - begin; + rte_atomic64_add(&check_cycles, cycles); + rte_atomic64_add(&checks, i); + + writer_done = 1; + /* Wait until all readers have exited */ + rte_eal_mp_wait_lcore(); + /* Check return value from threads */ + for (i = 0; i < num_cores; i++) + if (lcore_config[enabled_core_ids[i]].ret < 0) + goto error; + rte_hash_free(h[0]); + rte_free(keys); + + printf("Following numbers include calls to rte_hash functions\n"); + printf("Cycles per 1 update(online/update/offline): %"PRIi64"\n", + rte_atomic64_read(&update_cycles) / + rte_atomic64_read(&updates)); + + printf("Cycles per 1 check(start, check): %"PRIi64"\n\n", + rte_atomic64_read(&check_cycles) / + rte_atomic64_read(&checks)); + + rte_free(t[0]); + + return 0; + +error: + writer_done = 1; + /* Wait until all readers have exited */ + rte_eal_mp_wait_lcore(); + + rte_hash_free(h[0]); + rte_free(keys); + for (i = 0; i < TOTAL_ENTRY; i++) + rte_free(hash_data[0][i]); + + rte_free(t[0]); + + return -1; +} + +static int +test_rcu_qsbr_main(void) +{ + rte_atomic64_init(&updates); + rte_atomic64_init(&update_cycles); + rte_atomic64_init(&checks); + rte_atomic64_init(&check_cycles); + + if (get_enabled_cores_mask() != 0) + return -1; + + printf("Number of cores provided = %d\n", num_cores); + if (num_cores < 2) { + printf("Test failed! Need 2 or more cores\n"); + goto test_fail; + } + if (num_cores > TEST_RCU_MAX_LCORE) { + printf("Test failed! %d cores supported\n", TEST_RCU_MAX_LCORE); + goto test_fail; + } + + printf("Perf test with all reader threads registered\n"); + printf("--------------------------------------------\n"); + all_registered = 1; + + if (test_rcu_qsbr_perf() < 0) + goto test_fail; + + if (test_rcu_qsbr_rperf() < 0) + goto test_fail; + + if (test_rcu_qsbr_wperf() < 0) + goto test_fail; + + if (test_rcu_qsbr_sw_sv_1qs() < 0) + goto test_fail; + + if (test_rcu_qsbr_sw_sv_1qs_non_blocking() < 0) + goto test_fail; + + /* Make sure the actual number of cores provided is less than + * TEST_RCU_MAX_LCORE. This will allow for some threads not + * to be registered on the QS variable. + */ + if (num_cores >= TEST_RCU_MAX_LCORE) { + printf("Test failed! number of cores provided should be less than %d\n", + TEST_RCU_MAX_LCORE); + goto test_fail; + } + + printf("Perf test with some of reader threads registered\n"); + printf("------------------------------------------------\n"); + all_registered = 0; + + if (test_rcu_qsbr_perf() < 0) + goto test_fail; + + if (test_rcu_qsbr_rperf() < 0) + goto test_fail; + + if (test_rcu_qsbr_wperf() < 0) + goto test_fail; + + if (test_rcu_qsbr_sw_sv_1qs() < 0) + goto test_fail; + + if (test_rcu_qsbr_sw_sv_1qs_non_blocking() < 0) + goto test_fail; + + printf("\n"); + + return 0; + +test_fail: + return -1; +} + +REGISTER_TEST_COMMAND(rcu_qsbr_perf_autotest, test_rcu_qsbr_main); From patchwork Wed May 1 03:54:18 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Honnappa Nagarahalli X-Patchwork-Id: 163169 Delivered-To: patch@linaro.org Received: by 2002:a92:7e86:0:0:0:0:0 with SMTP id q6csp4068470ill; Tue, 30 Apr 2019 20:55:10 -0700 (PDT) X-Google-Smtp-Source: APXvYqw6BkfvvCp1b38amRkMkBRVcedwL1/nEdZ93GQ+RS3h94FVbgeUiF6X0bOdPdwIStuTCrem X-Received: by 2002:aa7:db50:: with SMTP id n16mr3860152edt.108.1556682910056; Tue, 30 Apr 2019 20:55:10 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1556682910; cv=none; d=google.com; s=arc-20160816; b=g3a8Npn0H98TwFGOW9inCl3DL61sVSW1TDiuSsGzaGNvVv+7hO5eRDPk1NvaSgjVt8 t70JSSoVZf1chpCnxQ01MkxK5Nti4nlYPGJeJPcPoZUpiSBf0MvSCD7pwxJtCP07dThB hNiUHAxRYcAOZLLV2aW3Haqp6Z/rM4PQYphFbEp4RdsGezCL75My3LmhGC1jOnV06SRo v9X3+PbbIw1yOmiYhbIe//13OExkJm/SfrMH9CnTGGBWVzRsMAXOd8qWIqSXrZ/45l7O mmz5BdZRiqoWj+a2peV5kBzM8DAPSxQxapNaQHu9KDoKppjM5ysFpYUs57Nxn8+8qA+0 +JQw== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:list-subscribe:list-help:list-post:list-archive :list-unsubscribe:list-id:precedence:subject:references:in-reply-to :message-id:date:cc:to:from; bh=7o5bnBqN5T6Du4CNXixCZ/8T6yWIGsyGjHrMwlpIKs4=; b=o0UAUMV9rwdrlHguKPs2C68GCMiaeu3CdI9Cwshopfhc/IIgupc+CAywUvWw2+/ARH mDWq2utsYA9bLSgVMY6DjldpVIemFqkcVmBmBug9KbRJwNKUhqM5yM5j9gdkqIMr5K1B Fwav7abqlHErjV0suMS3UoUH4ppI/oPWkHPlJ6aZ+E/eT52d8UmEdLPHJ6MIAjJ0wBFa O2iikn9woEDEMqxALkDb0BJKmkmkk9fd+6TTj5fU5NQX7xgcfGVbQnSf2/7ivkIlNi33 lXmHRdzSkY0YeJJ98YRAF4vlIuTEcTw0tlbA6t3Sp0hUWpbECO0hm+bJe68yd4X0r5Kd sgtA== ARC-Authentication-Results: i=1; mx.google.com; spf=pass (google.com: domain of dev-bounces@dpdk.org designates 92.243.14.124 as permitted sender) smtp.mailfrom=dev-bounces@dpdk.org Return-Path: Received: from dpdk.org (dpdk.org. [92.243.14.124]) by mx.google.com with ESMTP id b25si990333edn.258.2019.04.30.20.55.09; Tue, 30 Apr 2019 20:55:10 -0700 (PDT) Received-SPF: pass (google.com: domain of dev-bounces@dpdk.org designates 92.243.14.124 as permitted sender) client-ip=92.243.14.124; Authentication-Results: mx.google.com; spf=pass (google.com: domain of dev-bounces@dpdk.org designates 92.243.14.124 as permitted sender) smtp.mailfrom=dev-bounces@dpdk.org Received: from [92.243.14.124] (localhost [127.0.0.1]) by dpdk.org (Postfix) with ESMTP id A86595F19; Wed, 1 May 2019 05:54:40 +0200 (CEST) Received: from foss.arm.com (foss.arm.com [217.140.101.70]) by dpdk.org (Postfix) with ESMTP id CD3C05B12 for ; Wed, 1 May 2019 05:54:34 +0200 (CEST) Received: from usa-sjc-imap-foss1.foss.arm.com (unknown [10.72.51.249]) by usa-sjc-mx-foss1.foss.arm.com (Postfix) with ESMTP id 4456EA78; Tue, 30 Apr 2019 20:54:34 -0700 (PDT) Received: from qc2400f-1.austin.arm.com (qc2400f-1.austin.arm.com [10.118.12.65]) by usa-sjc-imap-foss1.foss.arm.com (Postfix) with ESMTPSA id BDC5F3F719; Tue, 30 Apr 2019 20:54:33 -0700 (PDT) From: Honnappa Nagarahalli To: konstantin.ananyev@intel.com, stephen@networkplumber.org, paulmck@linux.ibm.com, marko.kovacevic@intel.com, dev@dpdk.org Cc: honnappa.nagarahalli@arm.com, gavin.hu@arm.com, dharmik.thakkar@arm.com, malvika.gupta@arm.com Date: Tue, 30 Apr 2019 22:54:18 -0500 Message-Id: <20190501035419.33524-4-honnappa.nagarahalli@arm.com> X-Mailer: git-send-email 2.17.1 In-Reply-To: <20190501035419.33524-1-honnappa.nagarahalli@arm.com> References: <20181122033055.3431-1-honnappa.nagarahalli@arm.com> <20190501035419.33524-1-honnappa.nagarahalli@arm.com> Subject: [dpdk-dev] [PATCH v9 3/4] doc/rcu: add lib_rcu documentation 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" Add lib_rcu QSBR API and programmer guide documentation. Signed-off-by: Honnappa Nagarahalli Reviewed-by: Marko Kovacevic --- doc/api/doxy-api-index.md | 3 +- doc/api/doxy-api.conf.in | 1 + .../prog_guide/img/rcu_general_info.svg | 509 ++++++++++++++++++ doc/guides/prog_guide/index.rst | 1 + doc/guides/prog_guide/rcu_lib.rst | 185 +++++++ 5 files changed, 698 insertions(+), 1 deletion(-) create mode 100644 doc/guides/prog_guide/img/rcu_general_info.svg create mode 100644 doc/guides/prog_guide/rcu_lib.rst -- 2.17.1 Acked-by: John McNamara diff --git a/doc/api/doxy-api-index.md b/doc/api/doxy-api-index.md index de1e215dd..8f0e84de6 100644 --- a/doc/api/doxy-api-index.md +++ b/doc/api/doxy-api-index.md @@ -54,7 +54,8 @@ The public API headers are grouped by topics: [memzone] (@ref rte_memzone.h), [mempool] (@ref rte_mempool.h), [malloc] (@ref rte_malloc.h), - [memcpy] (@ref rte_memcpy.h) + [memcpy] (@ref rte_memcpy.h), + [rcu] (@ref rte_rcu_qsbr.h) - **timers**: [cycles] (@ref rte_cycles.h), diff --git a/doc/api/doxy-api.conf.in b/doc/api/doxy-api.conf.in index 7722fc3e9..b9896cb63 100644 --- a/doc/api/doxy-api.conf.in +++ b/doc/api/doxy-api.conf.in @@ -51,6 +51,7 @@ INPUT = @TOPDIR@/doc/api/doxy-api-index.md \ @TOPDIR@/lib/librte_port \ @TOPDIR@/lib/librte_power \ @TOPDIR@/lib/librte_rawdev \ + @TOPDIR@/lib/librte_rcu \ @TOPDIR@/lib/librte_reorder \ @TOPDIR@/lib/librte_ring \ @TOPDIR@/lib/librte_sched \ diff --git a/doc/guides/prog_guide/img/rcu_general_info.svg b/doc/guides/prog_guide/img/rcu_general_info.svg new file mode 100644 index 000000000..e7ca1dacb --- /dev/null +++ b/doc/guides/prog_guide/img/rcu_general_info.svg @@ -0,0 +1,509 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Page-1 + + + + Sheet.3 + + + + Sheet.4 + + + + Sheet.5 + D1 + + + + D1 + + Sheet.6 + + + + Sheet.7 + + + + Sheet.8 + D2 + + + + D2 + + Sheet.9 + + + + Sheet.10 + Reader Thread 1 + + + + Reader Thread 1 + + Sheet.11 + + + + Sheet.12 + + + + Sheet.13 + D1 + + + + D1 + + Sheet.14 + + + + Sheet.15 + + + + Sheet.16 + D2 + + + + D2 + + Sheet.17 + + + + Sheet.18 + T 2 + + + + T 2 + + Sheet.19 + + + + Sheet.20 + + + + Sheet.21 + D1 + + + + D1 + + Sheet.22 + + + + Sheet.23 + + + + Sheet.24 + D2 + + + + D2 + + Sheet.25 + + + + Sheet.26 + T 3 + + + + T 3 + + Sheet.28 + Time + + + + Time + + Sheet.29 + + + + Sheet.30 + + + + Sheet.31 + Remove reference to entry1 + + + + Remove reference to entry1 + + Sheet.33 + + + + Sheet.34 + Delete + + + + Delete + + Sheet.35 + + + + Sheet.36 + + + + Sheet.37 + Delete entry1 from D1 + + + + Delete entry1 from D1 + + Sheet.38 + + + + Sheet.39 + + + + Sheet.40 + + + + Sheet.41 + Free memory for entries1 and 2 after every reader has gone th... + + + + Free memory for entries1 and 2 after every reader has gone through at least 1 quiescent state + + Sheet.46 + Free + + + + Free + + Sheet.48 + + + + Sheet.49 + + + + Sheet.50 + Grace Period + + + + Grace Period + + Sheet.51 + + + + Sheet.52 + + + + Sheet.53 + + + + Sheet.54 + Delete entry2 from D1 + + + + Delete entry2 from D1 + + Sheet.56 + + + + Sheet.57 + + + + Sheet.58 + + + + Sheet.59 + Critical sections + + + + Critical sections + + Sheet.60 + + + + Sheet.61 + + + + Sheet.62 + + + + Sheet.63 + Quiescent states + + + + Quiescent states + + Sheet.64 + + + + Sheet.65 + + + + Sheet.66 + + + + Sheet.67 + + + + Sheet.68 + + + + Sheet.69 + + + + Sheet.70 + while(1) loop + + + + while(1) loop + + Sheet.71 + + + + Sheet.72 + Reader thread is not accessing any shared data structure. i.e... + + + + Reader thread is not accessing any shared data structure.i.e. non critical section or quiescent state. + + Sheet.73 + Dx + + + + Dx + + Sheet.74 + Reader thread is accessing the shared data structure Dx. i.e.... + + + + Reader thread is accessing the shared data structure Dx.i.e. critical section. + + Sheet.75 + Point in time when the reference to the entry is removed usin... + + + + Point in time when the reference to the entry is removed using an atomic operation. + + Sheet.76 + Delete + + + + Delete + + Sheet.77 + Point in time when the writer can free the deleted entry. + + + + Point in time when the writer can free the deleted entry. + + Sheet.78 + Free + + + + Free + + Sheet.79 + Time duration between Delete and Free, during which memory ca... + + + + Time duration between Delete and Free, during which memory cannot be freed. + + Sheet.80 + Grace Period + + + + Grace Period + + Sheet.83 + + + + Sheet.84 + + + + Sheet.85 + + + + Sheet.86 + + + + Sheet.87 + + + + Sheet.88 + Remove reference to entry2 + + + + Remove reference to entry2 + + diff --git a/doc/guides/prog_guide/index.rst b/doc/guides/prog_guide/index.rst index 95f5e7964..17df2c563 100644 --- a/doc/guides/prog_guide/index.rst +++ b/doc/guides/prog_guide/index.rst @@ -56,6 +56,7 @@ Programmer's Guide metrics_lib bpf_lib ipsec_lib + rcu_lib source_org dev_kit_build_system dev_kit_root_make_help diff --git a/doc/guides/prog_guide/rcu_lib.rst b/doc/guides/prog_guide/rcu_lib.rst new file mode 100644 index 000000000..55d44e15d --- /dev/null +++ b/doc/guides/prog_guide/rcu_lib.rst @@ -0,0 +1,185 @@ +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2019 Arm Limited. + +.. _RCU_Library: + +RCU Library +============ + +Lock-less data structures provide scalability and determinism. +They enable use cases where locking may not be allowed +(for ex: real-time applications). + +In the following paras, the term 'memory' refers to memory allocated +by typical APIs like malloc or anything that is representative of +memory, for ex: an index of a free element array. + +Since these data structures are lock less, the writers and readers +are accessing the data structures concurrently. Hence, while removing +an element from a data structure, the writers cannot return the memory +to the allocator, without knowing that the readers are not +referencing that element/memory anymore. Hence, it is required to +separate the operation of removing an element into 2 steps: + +Delete: in this step, the writer removes the reference to the element from +the data structure but does not return the associated memory to the +allocator. This will ensure that new readers will not get a reference to +the removed element. Removing the reference is an atomic operation. + +Free(Reclaim): in this step, the writer returns the memory to the +memory allocator, only after knowing that all the readers have stopped +referencing the deleted element. + +This library helps the writer determine when it is safe to free the +memory. + +This library makes use of thread Quiescent State (QS). + +What is Quiescent State +----------------------- +Quiescent State can be defined as 'any point in the thread execution where the +thread does not hold a reference to shared memory'. It is up to the application +to determine its quiescent state. + +Let us consider the following diagram: + +.. figure:: img/rcu_general_info.* + + +As shown, reader thread 1 accesses data structures D1 and D2. When it is +accessing D1, if the writer has to remove an element from D1, the +writer cannot free the memory associated with that element immediately. +The writer can return the memory to the allocator only after the reader +stops referencing D1. In other words, reader thread RT1 has to enter +a quiescent state. + +Similarly, since reader thread 2 is also accessing D1, writer has to +wait till thread 2 enters quiescent state as well. + +However, the writer does not need to wait for reader thread 3 to enter +quiescent state. Reader thread 3 was not accessing D1 when the delete +operation happened. So, reader thread 1 will not have a reference to the +deleted entry. + +It can be noted that, the critical sections for D2 is a quiescent state +for D1. i.e. for a given data structure Dx, any point in the thread execution +that does not reference Dx is a quiescent state. + +Since memory is not freed immediately, there might be a need for +provisioning of additional memory, depending on the application requirements. + +Factors affecting RCU mechanism +--------------------------------- + +It is important to make sure that this library keeps the overhead of +identifying the end of grace period and subsequent freeing of memory, +to a minimum. The following paras explain how grace period and critical +section affect this overhead. + +The writer has to poll the readers to identify the end of grace period. +Polling introduces memory accesses and wastes CPU cycles. The memory +is not available for reuse during grace period. Longer grace periods +exasperate these conditions. + +The length of the critical section and the number of reader threads +is proportional to the duration of the grace period. Keeping the critical +sections smaller will keep the grace period smaller. However, keeping the +critical sections smaller requires additional CPU cycles (due to additional +reporting) in the readers. + +Hence, we need the characteristics of small grace period and large critical +section. This library addresses this by allowing the writer to do +other work without having to block till the readers report their quiescent +state. + +RCU in DPDK +----------- + +For DPDK applications, the start and end of while(1) loop (where no +references to shared data structures are kept) act as perfect quiescent +states. This will combine all the shared data structure accesses into a +single, large critical section which helps keep the overhead on the +reader side to a minimum. + +DPDK supports pipeline model of packet processing and service cores. +In these use cases, a given data structure may not be used by all the +workers in the application. The writer does not have to wait for all +the workers to report their quiescent state. To provide the required +flexibility, this library has a concept of QS variable. The application +can create one QS variable per data structure to help it track the +end of grace period for each data structure. This helps keep the grace +period to a minimum. + +How to use this library +----------------------- + +The application must allocate memory and initialize a QS variable. + +Application can call ``rte_rcu_qsbr_get_memsize`` to calculate the size +of memory to allocate. This API takes maximum number of reader threads, +using this variable, as a parameter. Currently, a maximum of 1024 threads +are supported. + +Further, the application can initialize a QS variable using the API +``rte_rcu_qsbr_init``. + +Each reader thread is assumed to have a unique thread ID. Currently, the +management of the thread ID (for ex: allocation/free) is left to the +application. The thread ID should be in the range of 0 to +maximum number of threads provided while creating the QS variable. +The application could also use lcore_id as the thread ID where applicable. + +``rte_rcu_qsbr_thread_register`` API will register a reader thread +to report its quiescent state. This can be called from a reader thread. +A control plane thread can also call this on behalf of a reader thread. +The reader thread must call ``rte_rcu_qsbr_thread_online`` API to start +reporting its quiescent state. + +Some of the use cases might require the reader threads to make +blocking API calls (for ex: while using eventdev APIs). The writer thread +should not wait for such reader threads to enter quiescent state. +The reader thread must call ``rte_rcu_qsbr_thread_offline`` API, before calling +blocking APIs. It can call ``rte_rcu_qsbr_thread_online`` API once the blocking +API call returns. + +The writer thread can trigger the reader threads to report their quiescent +state by calling the API ``rte_rcu_qsbr_start``. It is possible for multiple +writer threads to query the quiescent state status simultaneously. Hence, +``rte_rcu_qsbr_start`` returns a token to each caller. + +The writer thread must call ``rte_rcu_qsbr_check`` API with the token to +get the current quiescent state status. Option to block till all the reader +threads enter the quiescent state is provided. If this API indicates that +all the reader threads have entered the quiescent state, the application +can free the deleted entry. + +The APIs ``rte_rcu_qsbr_start`` and ``rte_rcu_qsbr_check`` are lock free. +Hence, they can be called concurrently from multiple writers even while +running as worker threads. + +The separation of triggering the reporting from querying the status provides +the writer threads flexibility to do useful work instead of blocking for the +reader threads to enter the quiescent state or go offline. This reduces the +memory accesses due to continuous polling for the status. + +``rte_rcu_qsbr_synchronize`` API combines the functionality of +``rte_rcu_qsbr_start`` and blocking ``rte_rcu_qsbr_check`` into a single API. +This API triggers the reader threads to report their quiescent state and +polls till all the readers enter the quiescent state or go offline. This +API does not allow the writer to do useful work while waiting and +introduces additional memory accesses due to continuous polling. + +The reader thread must call ``rte_rcu_qsbr_thread_offline`` and +``rte_rcu_qsbr_thread_unregister`` APIs to remove itself from reporting its +quiescent state. The ``rte_rcu_qsbr_check`` API will not wait for this reader +thread to report the quiescent state status anymore. + +The reader threads should call ``rte_rcu_qsbr_quiescent`` API to indicate that +they entered a quiescent state. This API checks if a writer has triggered a +quiescent state query and update the state accordingly. + +The ``rte_rcu_qsbr_lock`` and ``rte_rcu_qsbr_unlock`` are empty functions. +However, when ``CONFIG_RTE_LIBRTE_RCU_DEBUG`` is enabled, these APIs aid +in debugging issues. One can mark the access to shared data structures on the +reader side using these APIs. The ``rte_rcu_qsbr_quiescent`` will check if +all the locks are unlocked. From patchwork Wed May 1 03:54:19 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Honnappa Nagarahalli X-Patchwork-Id: 163170 Delivered-To: patch@linaro.org Received: by 2002:a92:7e86:0:0:0:0:0 with SMTP id q6csp4068608ill; Tue, 30 Apr 2019 20:55:22 -0700 (PDT) X-Google-Smtp-Source: APXvYqx+HWeaor0QBWL2veZmqS0dSYogle9Ow2xDDAuYYlc02pDIO5ShCc2Xh3sXzzdoqwYKOlom X-Received: by 2002:a50:b6b2:: with SMTP id d47mr17997966ede.169.1556682922817; Tue, 30 Apr 2019 20:55:22 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1556682922; cv=none; d=google.com; s=arc-20160816; b=TuBTmCVUbWAvA6266LHiVGVUTlM5Iog/66xa9mACrg8YqT+HBYrGbhViz9EOdjDhlt I48B3OzOBR1SMwknnASa1uYuFOphW5sQINlNoIzdKN3NPA9GR251eYtR1Ch+DdFbOVTx /OEqbMEOojmv91ztp8rT7II0EuH92oJse5DC48T/46PQkQhMBNn7d5tpeQ5fymeA5XYL rysTiRYmjBzYAtmdEkWJC0Q6+pXfkNhI2V8F/p8itUDUOF0Vnrsq5kb8evyKzXVlBfC1 v9zZB7NqanG1G9SxL7cmjKBfKuTwgeF38TG340j0VfDAruIdNWX6F9t1DZDQgqmRlMJ4 tDEw== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:list-subscribe:list-help:list-post:list-archive :list-unsubscribe:list-id:precedence:subject:references:in-reply-to :message-id:date:cc:to:from; bh=s1nkdALCBkEIXgDK3NxEsbtDDlJsDZ6z8okDL0IgKjw=; b=T59GYx1eRDgCwxSa78O3SvBWN023so2Nmk5giHB1HT5KkaZuMwUxL1aHM93Om0Il/T JfOR6x9KNtKaPYUZx1ZN71R7B2n/LS3lx/kA3vrIY9gEdjfC5AEAdqgVcurJv7yAqgaT 0h711RzI96Hf1eS2Rn7ep6VI9/ke3fka0Vdx4rhPDgwMkvlxBFPEpbJqa6PKLNeWsXB2 POs1VCW+eO9XkyiTLozLlObnmN0zgFij9JE13IRWbDKPYZASDSFcY90xpksPu8lH4z7m 1tUshMiSQ+InkUGzdXn4ZoEmunljFOKRst/AGK3Fk2+eKuaFtzJOvPSkZmx5ZnUe6wz/ ixDA== ARC-Authentication-Results: i=1; mx.google.com; spf=pass (google.com: domain of dev-bounces@dpdk.org designates 92.243.14.124 as permitted sender) smtp.mailfrom=dev-bounces@dpdk.org Return-Path: Received: from dpdk.org (dpdk.org. [92.243.14.124]) by mx.google.com with ESMTP id s9si161638ejj.117.2019.04.30.20.55.22; Tue, 30 Apr 2019 20:55:22 -0700 (PDT) Received-SPF: pass (google.com: domain of dev-bounces@dpdk.org designates 92.243.14.124 as permitted sender) client-ip=92.243.14.124; Authentication-Results: mx.google.com; spf=pass (google.com: domain of dev-bounces@dpdk.org designates 92.243.14.124 as permitted sender) smtp.mailfrom=dev-bounces@dpdk.org Received: from [92.243.14.124] (localhost [127.0.0.1]) by dpdk.org (Postfix) with ESMTP id C73165F25; Wed, 1 May 2019 05:54:44 +0200 (CEST) Received: from foss.arm.com (foss.arm.com [217.140.101.70]) by dpdk.org (Postfix) with ESMTP id 2699C5F0F for ; Wed, 1 May 2019 05:54:37 +0200 (CEST) Received: from usa-sjc-imap-foss1.foss.arm.com (unknown [10.72.51.249]) by usa-sjc-mx-foss1.foss.arm.com (Postfix) with ESMTP id 91FF3EBD; Tue, 30 Apr 2019 20:54:36 -0700 (PDT) Received: from qc2400f-1.austin.arm.com (qc2400f-1.austin.arm.com [10.118.12.65]) by usa-sjc-imap-foss1.foss.arm.com (Postfix) with ESMTPSA id 222EC3F719; Tue, 30 Apr 2019 20:54:36 -0700 (PDT) From: Honnappa Nagarahalli To: konstantin.ananyev@intel.com, stephen@networkplumber.org, paulmck@linux.ibm.com, marko.kovacevic@intel.com, dev@dpdk.org Cc: honnappa.nagarahalli@arm.com, gavin.hu@arm.com, dharmik.thakkar@arm.com, malvika.gupta@arm.com Date: Tue, 30 Apr 2019 22:54:19 -0500 Message-Id: <20190501035419.33524-5-honnappa.nagarahalli@arm.com> X-Mailer: git-send-email 2.17.1 In-Reply-To: <20190501035419.33524-1-honnappa.nagarahalli@arm.com> References: <20181122033055.3431-1-honnappa.nagarahalli@arm.com> <20190501035419.33524-1-honnappa.nagarahalli@arm.com> Subject: [dpdk-dev] [PATCH v9 4/4] doc: added RCU to the release notes 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" Added RCU library addition to the release notes Signed-off-by: Honnappa Nagarahalli --- doc/guides/rel_notes/release_19_05.rst | 8 ++++++++ 1 file changed, 8 insertions(+) -- 2.17.1 Acked-by: John McNamara diff --git a/doc/guides/rel_notes/release_19_05.rst b/doc/guides/rel_notes/release_19_05.rst index d5ed564ab..687c01bc1 100644 --- a/doc/guides/rel_notes/release_19_05.rst +++ b/doc/guides/rel_notes/release_19_05.rst @@ -68,6 +68,13 @@ New Features Added a new lock-free stack handler, which uses the newly added stack library. +* **Added RCU library.** + + Added RCU library supporting quiescent state based memory reclamation method. + This library helps identify the quiescent state of the reader threads so + that the writers can free the memory associated with the lock free data + structures. + * **Updated KNI module and PMD.** Updated the KNI kernel module to set the max_mtu according to the given @@ -330,6 +337,7 @@ The libraries prepended with a plus sign were incremented in this version. librte_port.so.3 librte_power.so.1 librte_rawdev.so.1 + + librte_rcu.so.1 librte_reorder.so.1 librte_ring.so.2 librte_sched.so.2