From patchwork Fri Apr 12 20:20:37 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Honnappa Nagarahalli X-Patchwork-Id: 162141 Delivered-To: patch@linaro.org Received: by 2002:a02:c6d8:0:0:0:0:0 with SMTP id r24csp1926jan; Fri, 12 Apr 2019 13:21:07 -0700 (PDT) X-Google-Smtp-Source: APXvYqzfKRDQjv1GQ04GKOjO8MboQ4VLi9duyZqLs5GnMsgg1z/z42uD+ov/69Wlww2fpizdPT1y X-Received: by 2002:a17:906:b742:: with SMTP id fx2mr32370781ejb.6.1555100467446; Fri, 12 Apr 2019 13:21:07 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1555100467; cv=none; d=google.com; s=arc-20160816; b=po5gBb2T/ig6kYn2gvyGpzCyK4/gO+xLW+Wf4Y26psqpdwSTt2Rb17y9GjyR0k6cEy YGaF1J2a07Fr8xDlNEvsNv3JeLPEWxMW0d/Q3EOwL+U8K6D5Nx6JNQCmDIo5t1RdpbER hcLzCYbV91Vcr9MRNOAMob1Y4/OeHq1TYhFIStp/r5hPwBAlum/lANwoIpTpEDppll0r g1MYRHzyHLaYnxoxCwwNa0Hz2LAC6lmUUC43k9S6v9cwifNGWqP57HfVOSb75+YQ4iuZ PtwOFfedQg1zkItrKM8eJbI/3S6hixtxWccOlFz5EmvWfEP8MMZA2bUv2kv6AKfOEN+T beGQ== 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=HzOQN3vLQRlfOv7UdNrx304Wwxj+7JkifRIlEI2J3UA=; b=0Um+19BO6t9WwfCBzZmLznuz7Fk2y+AEerXwEeagk79GhDR6Jh2PanlEIR+KeVtfTc +fE1FWqgmAbtZIdsd37ZCzQ19lEEcbDMXMEGNib9Ctc0BtNnBvilNTL4cHGGeHSwaDLW NDkjrfhvMA600gfOLViFH3zKdeFn/Y/eFCcF11ADpKUEEhEzWGFDErBjLFuH9SDutZi7 bh3OkRL02tXUM46JjWX7Qtf95LR9laiN7RdhVEzDi0BHO/58Sk52+Ee2e4QAG431vhHD bLKdWP9N9yDVewwEIGiBUXx1BlGG7ICSiSAeOu4O4BLb51pANLwgABA2gvmrsEleHEVW KVTw== 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 cb18si5057332ejb.17.2019.04.12.13.21.06; Fri, 12 Apr 2019 13:21:07 -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 3061E1B2AC; Fri, 12 Apr 2019 22:20:56 +0200 (CEST) Received: from foss.arm.com (usa-sjc-mx-foss1.foss.arm.com [217.140.101.70]) by dpdk.org (Postfix) with ESMTP id AB5E01B293 for ; Fri, 12 Apr 2019 22:20:53 +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 9840815AD; Fri, 12 Apr 2019 13:20:52 -0700 (PDT) Received: from qc2400f-1.austin.arm.com (qc2400f-1.austin.arm.com [10.118.13.209]) by usa-sjc-imap-foss1.foss.arm.com (Postfix) with ESMTPSA id 14EAF3F557; Fri, 12 Apr 2019 13:20:52 -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: Fri, 12 Apr 2019 15:20:37 -0500 Message-Id: <20190412202039.46902-2-honnappa.nagarahalli@arm.com> X-Mailer: git-send-email 2.17.1 In-Reply-To: <20190412202039.46902-1-honnappa.nagarahalli@arm.com> References: <20181122033055.3431-1-honnappa.nagarahalli@arm.com> <20190412202039.46902-1-honnappa.nagarahalli@arm.com> Subject: [dpdk-dev] [PATCH v5 1/3] 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 --- MAINTAINERS | 5 + config/common_base | 6 + lib/Makefile | 2 + lib/librte_rcu/Makefile | 23 + lib/librte_rcu/meson.build | 5 + lib/librte_rcu/rte_rcu_qsbr.c | 237 +++++++++++ lib/librte_rcu/rte_rcu_qsbr.h | 645 +++++++++++++++++++++++++++++ lib/librte_rcu/rte_rcu_version.map | 11 + lib/meson.build | 2 +- mk/rte.app.mk | 1 + 10 files changed, 936 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 9774344dd..6e9766eed 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -1267,6 +1267,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 8da08105b..ad70c79e1 100644 --- a/config/common_base +++ b/config/common_base @@ -829,6 +829,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..c009ae4b7 --- /dev/null +++ b/lib/librte_rcu/meson.build @@ -0,0 +1,5 @@ +# SPDX-License-Identifier: BSD-3-Clause +# Copyright(c) 2018 Arm Limited + +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..4aeb5f37f --- /dev/null +++ b/lib/librte_rcu/rte_rcu_qsbr.c @@ -0,0 +1,237 @@ +/* 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 "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, 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, 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, rcu_log_type, + "%s(): Invalid input parameter\n", __func__); + rte_errno = EINVAL; + + return 1; + } + + 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, rcu_log_type, + "%s(): Invalid input parameter\n", __func__); + rte_errno = EINVAL; + + return 1; + } + + 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; +} + +/* 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; + + if (v == NULL || f == NULL) { + rte_log(RTE_LOG_ERR, 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 = %lu\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 ID mask = 0x"); + for (i = 0; i < v->num_elems; i++) + fprintf(f, "%lx", __atomic_load_n( + RTE_QSBR_THRID_ARRAY_ELM(v, i), + __ATOMIC_ACQUIRE)); + fprintf(f, "\n"); + + fprintf(f, " Token = %lu\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); + while (bmap) { + t = __builtin_ctzl(bmap); + fprintf(f, "thread ID = %d, count = %lu\n", t, + __atomic_load_n( + &v->qsbr_cnt[i].cnt, + __ATOMIC_RELAXED)); + bmap &= ~(1UL << t); + } + } + + return 0; +} + +int rcu_log_type; + +RTE_INIT(rte_rcu_register) +{ + rcu_log_type = rte_log_register("lib.rcu"); + if (rcu_log_type >= 0) + rte_log_set_level(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..304534a2d --- /dev/null +++ b/lib/librte_rcu/rte_rcu_qsbr.h @@ -0,0 +1,645 @@ +/* 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 +#define RTE_LIBRTE_RCU_DEBUG +extern int rcu_log_type; + +#if RTE_LOG_DP_LEVEL >= RTE_LOG_DEBUG +#define RCU_DP_LOG(level, fmt, args...) \ + rte_log(RTE_LOG_ ## level, rcu_log_type, \ + "%s(): " fmt "\n", __func__, ## args) +#else +#define RCU_DP_LOG(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); + + /* 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); + + /* 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(struct rte_rcu_qsbr *v __rte_unused, + unsigned int thread_id __rte_unused) +{ +#if defined(RTE_LIBRTE_RCU_DEBUG) + RTE_ASSERT(v != NULL && thread_id < v->max_threads); + + /* 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(struct rte_rcu_qsbr *v __rte_unused, + unsigned int thread_id __rte_unused) +{ +#if defined(RTE_LIBRTE_RCU_DEBUG) + RTE_ASSERT(v != NULL && thread_id < v->max_threads); + + /* Decrement the lock counter */ + __atomic_fetch_sub(&v->qsbr_cnt[thread_id].lock_cnt, + 1, __ATOMIC_RELEASE); + + if (v->qsbr_cnt[thread_id].lock_cnt) + rte_log(RTE_LOG_WARNING, rcu_log_type, + "%s(): Lock counter %u. Nested locks?\n", + __func__, 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); + +#if defined(RTE_LIBRTE_RCU_DEBUG) + /* Validate that the lock counter is 0 */ + if (v->qsbr_cnt[thread_id].lock_cnt) + rte_log(RTE_LOG_ERR, rcu_log_type, + "%s(): Lock counter %u, should be 0\n", + __func__, v->qsbr_cnt[thread_id].lock_cnt); +#endif + + /* 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); + + RCU_DP_LOG(DEBUG, "%s: update: token = %lu, 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 +__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); + RCU_DP_LOG(DEBUG, + "%s: check: token = %lu, wait = %d, Bit Map = 0x%lx, Thread ID = %d", + __func__, t, wait, bmap, id + j); + c = __atomic_load_n( + &v->qsbr_cnt[id + j].cnt, + __ATOMIC_ACQUIRE); + RCU_DP_LOG(DEBUG, + "%s: status: token = %lu, wait = %d, Thread QS cnt = %lu, 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 +__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++) { + RCU_DP_LOG(DEBUG, + "%s: check: token = %lu, wait = %d, Thread ID = %d", + __func__, t, wait, i); + while (1) { + c = __atomic_load_n(&cnt->cnt, __ATOMIC_ACQUIRE); + RCU_DP_LOG(DEBUG, + "%s: status: token = %lu, wait = %d, Thread QS cnt = %lu, 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 __rcu_qsbr_check_all(v, t, wait); + else + return __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. + */ +static __rte_always_inline 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); +} + +/** + * @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..ad8cb517c --- /dev/null +++ b/lib/librte_rcu/rte_rcu_version.map @@ -0,0 +1,11 @@ +EXPERIMENTAL { + global: + + rte_rcu_qsbr_get_memsize; + rte_rcu_qsbr_init; + rte_rcu_qsbr_thread_register; + rte_rcu_qsbr_thread_unregister; + rte_rcu_qsbr_dump; + + local: *; +}; diff --git a/lib/meson.build b/lib/meson.build index 595314d7d..67be10659 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', + 'reorder', 'sched', 'security', 'stack', 'vhost', 'rcu', #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 7d994bece..e93cc366d 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 Fri Apr 12 20:20:38 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Honnappa Nagarahalli X-Patchwork-Id: 162142 Delivered-To: patch@linaro.org Received: by 2002:a02:c6d8:0:0:0:0:0 with SMTP id r24csp2091jan; Fri, 12 Apr 2019 13:21:19 -0700 (PDT) X-Google-Smtp-Source: APXvYqwMyQjOHPh0aGi0S2sCvcLxNvAR4IviwJxmo7/dfst30f696wNLyujfdwQfR1W6WitqnScF X-Received: by 2002:a05:6402:709:: with SMTP id w9mr37881630edx.14.1555100479578; Fri, 12 Apr 2019 13:21:19 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1555100479; cv=none; d=google.com; s=arc-20160816; b=uqpB/gWBsx0opfUatKwZUrEpF1bR36ChDAup1jE8IFgy1BonFYakjwoo/tWODXOSc3 Pfk5fq3OQBm50mdmdunmQGgvl+xGFTGlaN29Ay28BeltiQizKgeCj/dNzkoDtdlEaNAs WZeqWRMb71QSi4w89dYzKdRHAPfeh85eQYJJIx3ttvITQk68XwQoU1YW9rrteFnadNwg f3ZBHCoVj5DmalaCDA1njLqo9+valW7wRN/nbLBR9Lnd0A8tkVPq1D/Zyg7Crt7CvWR/ ONTimf+SpovAVuOgKttueLV+ypXzBNBa7xmbkZBWHvmrsxWXLt27gE7a+5WWO9IcVAPR /1NQ== 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=rdJw+sCaKjiIU2Q4o5gY1pk2w78oH/SrBcwWfepVYPc=; b=RyflIYL0d4qZt261J7EQ61Gx3nef0vXlMY3m79RFAKSMjYeCPcq8ZCdoFM/NMjFqJR TD14nMJLKu0xBXlbJU1ggl4wq/hphIqwFYRS7FehMUQyXQOQDcWIbJzASAh/D/u+6QTD zbFtdpScIMSfizz3QhtUw/HDbs+L8SHHVaiK5RT4MCZ0U3LQxOb4DceJcV2KOSvp0zQ9 fkoghUMXA/GwNtpsQroKxyisYCtLQsNy704kw2vNgyKJ535LBi/kYU/UwSFz2Hk2EMwX upo0iozM+whJ5pL8D8Wh30wVqyd+9LVBWksBSVSDLm/NUGnnGAEp10hX4QyTuGFqiQhK mGGg== 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 m20si4008191ejs.352.2019.04.12.13.21.19; Fri, 12 Apr 2019 13:21:19 -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 905FB1B3AA; Fri, 12 Apr 2019 22:21:04 +0200 (CEST) Received: from foss.arm.com (usa-sjc-mx-foss1.foss.arm.com [217.140.101.70]) by dpdk.org (Postfix) with ESMTP id DD47C1B2B3 for ; Fri, 12 Apr 2019 22:20:57 +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 2D12015AB; Fri, 12 Apr 2019 13:20:57 -0700 (PDT) Received: from qc2400f-1.austin.arm.com (qc2400f-1.austin.arm.com [10.118.13.209]) by usa-sjc-imap-foss1.foss.arm.com (Postfix) with ESMTPSA id 9F2BF3F557; Fri, 12 Apr 2019 13:20:56 -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: Fri, 12 Apr 2019 15:20:38 -0500 Message-Id: <20190412202039.46902-3-honnappa.nagarahalli@arm.com> X-Mailer: git-send-email 2.17.1 In-Reply-To: <20190412202039.46902-1-honnappa.nagarahalli@arm.com> References: <20181122033055.3431-1-honnappa.nagarahalli@arm.com> <20190412202039.46902-1-honnappa.nagarahalli@arm.com> Subject: [dpdk-dev] [PATCH v5 2/3] 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 | 703 +++++++++++++++++++++++ 5 files changed, 1736 insertions(+) create mode 100644 app/test/test_rcu_qsbr.c create mode 100644 app/test/test_rcu_qsbr_perf.c -- 2.17.1 diff --git a/app/test/Makefile b/app/test/Makefile index b28bed2d4..10f551ecb 100644 --- a/app/test/Makefile +++ b/app/test/Makefile @@ -217,6 +217,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 db2527489..5f259e838 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 867cc5863..1a2ee18a5 100644 --- a/app/test/meson.build +++ b/app/test/meson.build @@ -110,6 +110,8 @@ test_sources = files('commands.c', 'test_timer_perf.c', 'test_timer_racecond.c', 'test_ticketlock.c', + 'test_rcu_qsbr.c', + 'test_rcu_qsbr_perf.c', 'test_version.c', 'virtual_pmd.c' ) @@ -137,6 +139,7 @@ test_deps = ['acl', 'ring', 'stack', 'timer' + 'rcu' ] # All test cases in fast_parallel_test_names list are parallel @@ -175,6 +178,7 @@ fast_parallel_test_names = [ 'ring_autotest', 'ring_pmd_autotest', 'rwlock_autotest', + 'rcu_qsbr_autotest', 'sched_autotest', 'spinlock_autotest', 'stack_autotest', @@ -242,6 +246,7 @@ perf_test_names = [ 'red_perf', 'distributor_perf_autotest', 'ring_pmd_perf_autotest', + 'rcu_qsbr_perf_autotest', 'pmd_perf_autotest', 'stack_perf_autotest', 'stack_nb_perf_autotest', diff --git a/app/test/test_rcu_qsbr.c b/app/test/test_rcu_qsbr.c new file mode 100644 index 000000000..b16872de5 --- /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) + +#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) +{ + uint32_t sz; + + sz = rte_rcu_qsbr_get_memsize(TEST_RCU_MAX_LCORE); + + t[0] = (struct rte_rcu_qsbr *)rte_zmalloc("rcu0", sz, + RTE_CACHE_LINE_SIZE); + t[1] = (struct rte_rcu_qsbr *)rte_zmalloc("rcu1", sz, + RTE_CACHE_LINE_SIZE); + t[2] = (struct rte_rcu_qsbr *)rte_zmalloc("rcu2", sz, + RTE_CACHE_LINE_SIZE); + t[3] = (struct rte_rcu_qsbr *)rte_zmalloc("rcu3", sz, + RTE_CACHE_LINE_SIZE); + + return 0; +} + +static int +free_rcu(void) +{ + int i; + + for (i = 0; i < 4; 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 != (RTE_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 != (RTE_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 != (RTE_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 != (RTE_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 != (RTE_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; + + /* 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 (num_cores < 4) { + printf("Test failed! Need 4 or more cores\n"); + goto test_fail; + } + + 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..bb3b8e9b6 --- /dev/null +++ b/app/test/test_rcu_qsbr_perf.c @@ -0,0 +1,703 @@ +/* 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_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 = %ld\n", rte_atomic64_read(&updates)); + printf("Cycles per %d updates: %lu\n", RCU_SCALE_DOWN, + rte_atomic64_read(&update_cycles) / + (rte_atomic64_read(&updates) / RCU_SCALE_DOWN)); + printf("Total RCU checks = %ld\n", rte_atomic64_read(&checks)); + printf("Cycles per %d checks: %lu\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 = %ld\n", rte_atomic64_read(&updates)); + printf("Cycles per %d updates: %lu\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 = %ld\n", rte_atomic64_read(&checks)); + printf("Cycles per %d checks: %lu\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): %lu\n", + rte_atomic64_read(&update_cycles) / + rte_atomic64_read(&updates)); + + printf("Cycles per 1 check(start, check): %lu\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): %lu\n", + rte_atomic64_read(&update_cycles) / + rte_atomic64_read(&updates)); + + printf("Cycles per 1 check(start, check): %lu\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 Fri Apr 12 20:20:39 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Honnappa Nagarahalli X-Patchwork-Id: 162143 Delivered-To: patch@linaro.org Received: by 2002:a02:c6d8:0:0:0:0:0 with SMTP id r24csp2296jan; Fri, 12 Apr 2019 13:21:33 -0700 (PDT) X-Google-Smtp-Source: APXvYqzP4XdvO96PWFB2LPaKJCYvEwU7x2nUPevKbbUVWfPyVonCVJGfEi8cO2Lyf3/A1oSPfSw6 X-Received: by 2002:a17:906:a889:: with SMTP id ha9mr31452386ejb.171.1555100493594; Fri, 12 Apr 2019 13:21:33 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1555100493; cv=none; d=google.com; s=arc-20160816; b=yIXTe6meWD93MTdbPqdRGLlzge6fwaWQnBMdmN4n3SZ7P5h6FifF2BAgt0ziwf38Um 7V7RdRK8zYCY3JYoKK2i/D4+FrgflxgZ7f80Rc9mIK/nC/Tr4JQbPvs7zLSuD1Kp/YvJ rT+NTXVtB9J93ln+ejn4aEwJbMN0qUXtHAM71MttWyml+0utyr+0eDPeE2gWhIfdGKr0 ogmkXN4+XRHwm6pJDDe6mnONG8r9hs/G6BfInioevChuWerzB000VQkSvCEanVlyhDZk qjH7eVeg44EhMnkCZ5qcycbfz3LixNaz5WtVDTrxgNF0lYXwGLJWtTDYgFfFTyhyNbPo HqOg== 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=qkqjby/twxU9zr/dFQc39SiyGVBL1J2qVExjyVuZp91jtEbeoo+MwdgxAlXyEUcK9w uOrmWufVd9majcqqOlKRLs+9akdFXM/knsPN2dVdJ4BE2RwiKbxllmJ658yDQdyHS9D7 MISO/lIbB/YILi3KSmCU15ZvkkQnlSuXVzX9MKusCYdBqWu5W+XkK776oBxF3RdzTqYE vH0tM5s22EFoB7dIRUTjKI7S/+oMDxUtz69K7RABxClfn6JC82aS8Jdi+3MWchETzexI jEKoeYsUKd1YFRGvFJtQazFGmRH5CVKUhyQGKS+iKdUTV/TcGb4j/wgV3ns43CULyr6D 4V2Q== 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 w24si4269039edu.236.2019.04.12.13.21.33; Fri, 12 Apr 2019 13:21:33 -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 E92121B3C0; Fri, 12 Apr 2019 22:21:09 +0200 (CEST) Received: from foss.arm.com (usa-sjc-mx-foss1.foss.arm.com [217.140.101.70]) by dpdk.org (Postfix) with ESMTP id 24B021B2B3 for ; Fri, 12 Apr 2019 22:20:59 +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 8F9A015AD; Fri, 12 Apr 2019 13:20:58 -0700 (PDT) Received: from qc2400f-1.austin.arm.com (qc2400f-1.austin.arm.com [10.118.13.209]) by usa-sjc-imap-foss1.foss.arm.com (Postfix) with ESMTPSA id 14FB13F557; Fri, 12 Apr 2019 13:20:58 -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: Fri, 12 Apr 2019 15:20:39 -0500 Message-Id: <20190412202039.46902-4-honnappa.nagarahalli@arm.com> X-Mailer: git-send-email 2.17.1 In-Reply-To: <20190412202039.46902-1-honnappa.nagarahalli@arm.com> References: <20181122033055.3431-1-honnappa.nagarahalli@arm.com> <20190412202039.46902-1-honnappa.nagarahalli@arm.com> Subject: [dpdk-dev] [PATCH v5 3/3] 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 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.