From patchwork Wed Apr 17 04:13:57 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Honnappa Nagarahalli X-Patchwork-Id: 162390 Delivered-To: patch@linaro.org Received: by 2002:a02:c6d8:0:0:0:0:0 with SMTP id r24csp5025159jan; Tue, 16 Apr 2019 21:14:27 -0700 (PDT) X-Google-Smtp-Source: APXvYqwHMl5Sx5E7lPXnTM+nMbRICmDi051/Y03Y30ejy31ysKHCpCupUMzBzaJ+ho9Hdrs14r3f X-Received: by 2002:a50:8719:: with SMTP id i25mr4834137edb.172.1555474467466; Tue, 16 Apr 2019 21:14:27 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1555474467; cv=none; d=google.com; s=arc-20160816; b=TN2w2aP3m2L2L+BS3nbBrKQaH0s/XckAFD+gUGql/H0MELED9aChO3p+dxFqpvoiD4 88Hwpd+PdGkVIPbqFZo5pV2KVsY/3/AE5h9rrN6iGa33WYABgoNVOleKcqYYGG550svm E+f2L64vmEA9qTaRG6IxvWXqdPkz8j0bJh9oEYlWn2HChCC9enROekGLD0Vkrxn496ss TbMsmCCT0XBayc1E1FAu8CNdFfm4r4ORM9ITCmiI0nmHJRsWGzXgkQWif/E1wGP+ag8G WGSTcSh7iViRp5Icd77rAn6EWdaH9v4EErgFxgiLvE5JJAR7RbTDlztkSiXDjHw6nj7w jddg== 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=/UnZz7wGZ9IlZvUEInc/x0PDgyXsVgoPHP37xBzG8zE=; b=qAXwJks1fgMrXRik+1OnDtHUbojlu0v9LJeKssAh3OCGMCGR5QNvcXV+jCAjFE1euL vNs7BecE7B3KRKn8BHmrLpalDleMH/Tnv2pxFiWBCBg+GHcxw4Pa9yyvaZmyg7TW5NzX X2zzLxlSP7qbZZd4xVHpR6Bft1SmtKa3yvY8MIqkMXxZSR6K09B1nwIBBeE1hMGDbin9 8q83f29vLS1zixQKufuBeAuYIm6IY11vfLUCd06vxpzM7fzK2vZ+gZYA7P4lpXKnAN4o 8kTHHx5YaoQuMxMYHmbl6MDLh82kf/4iU0Wr5VAIxCoVwgwZTkc+arjWgJc3xgqR/A1d T9wQ== 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 d4si3427640edc.127.2019.04.16.21.14.27; Tue, 16 Apr 2019 21:14:27 -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 B22DA1B59F; Wed, 17 Apr 2019 06:14:18 +0200 (CEST) Received: from foss.arm.com (foss.arm.com [217.140.101.70]) by dpdk.org (Postfix) with ESMTP id 9658D1B59A for ; Wed, 17 Apr 2019 06:14:16 +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 CD88115A2; Tue, 16 Apr 2019 21:14:15 -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 499BC3F68F; Tue, 16 Apr 2019 21:14:15 -0700 (PDT) From: Honnappa Nagarahalli To: konstantin.ananyev@intel.com, stephen@networkplumber.org, paulmck@linux.ibm.com, marko.kovacevic@intel.com, dev@dpdk.org Cc: honnappa.nagarahalli@arm.com, gavin.hu@arm.com, dharmik.thakkar@arm.com, malvika.gupta@arm.com Date: Tue, 16 Apr 2019 23:13:57 -0500 Message-Id: <20190417041359.45335-2-honnappa.nagarahalli@arm.com> X-Mailer: git-send-email 2.17.1 In-Reply-To: <20190417041359.45335-1-honnappa.nagarahalli@arm.com> References: <20181122033055.3431-1-honnappa.nagarahalli@arm.com> <20190417041359.45335-1-honnappa.nagarahalli@arm.com> Subject: [dpdk-dev] [PATCH v6 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 | 7 + lib/librte_rcu/rte_rcu_qsbr.c | 257 ++++++++++++ lib/librte_rcu/rte_rcu_qsbr.h | 629 +++++++++++++++++++++++++++++ lib/librte_rcu/rte_rcu_version.map | 12 + lib/meson.build | 2 +- mk/rte.app.mk | 1 + 10 files changed, 943 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 a08583471..ae54f37db 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -1274,6 +1274,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 7fb0dedb6..f50d26c30 100644 --- a/config/common_base +++ b/config/common_base @@ -834,6 +834,12 @@ CONFIG_RTE_LIBRTE_LATENCY_STATS=y # CONFIG_RTE_LIBRTE_TELEMETRY=n +# +# Compile librte_rcu +# +CONFIG_RTE_LIBRTE_RCU=y +CONFIG_RTE_LIBRTE_RCU_DEBUG=n + # # Compile librte_lpm # diff --git a/lib/Makefile b/lib/Makefile index 26021d0c0..791e0d991 100644 --- a/lib/Makefile +++ b/lib/Makefile @@ -111,6 +111,8 @@ DIRS-$(CONFIG_RTE_LIBRTE_IPSEC) += librte_ipsec DEPDIRS-librte_ipsec := librte_eal librte_mbuf librte_cryptodev librte_security DIRS-$(CONFIG_RTE_LIBRTE_TELEMETRY) += librte_telemetry DEPDIRS-librte_telemetry := librte_eal librte_metrics librte_ethdev +DIRS-$(CONFIG_RTE_LIBRTE_RCU) += librte_rcu +DEPDIRS-librte_rcu := librte_eal ifeq ($(CONFIG_RTE_EXEC_ENV_LINUX),y) DIRS-$(CONFIG_RTE_LIBRTE_KNI) += librte_kni diff --git a/lib/librte_rcu/Makefile b/lib/librte_rcu/Makefile new file mode 100644 index 000000000..6aa677bd1 --- /dev/null +++ b/lib/librte_rcu/Makefile @@ -0,0 +1,23 @@ +# SPDX-License-Identifier: BSD-3-Clause +# Copyright(c) 2018 Arm Limited + +include $(RTE_SDK)/mk/rte.vars.mk + +# library name +LIB = librte_rcu.a + +CFLAGS += -DALLOW_EXPERIMENTAL_API +CFLAGS += $(WERROR_FLAGS) -I$(SRCDIR) -O3 +LDLIBS += -lrte_eal + +EXPORT_MAP := rte_rcu_version.map + +LIBABIVER := 1 + +# all source are stored in SRCS-y +SRCS-$(CONFIG_RTE_LIBRTE_RCU) := rte_rcu_qsbr.c + +# install includes +SYMLINK-$(CONFIG_RTE_LIBRTE_RCU)-include := rte_rcu_qsbr.h + +include $(RTE_SDK)/mk/rte.lib.mk diff --git a/lib/librte_rcu/meson.build b/lib/librte_rcu/meson.build new file mode 100644 index 000000000..0c2d5a2e0 --- /dev/null +++ b/lib/librte_rcu/meson.build @@ -0,0 +1,7 @@ +# SPDX-License-Identifier: BSD-3-Clause +# Copyright(c) 2018 Arm Limited + +allow_experimental_apis = true + +sources = files('rte_rcu_qsbr.c') +headers = files('rte_rcu_qsbr.h') diff --git a/lib/librte_rcu/rte_rcu_qsbr.c b/lib/librte_rcu/rte_rcu_qsbr.c new file mode 100644 index 000000000..466592a42 --- /dev/null +++ b/lib/librte_rcu/rte_rcu_qsbr.c @@ -0,0 +1,257 @@ +/* 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; +} + +/* Wait till the reader threads have entered quiescent state. */ +void __rte_experimental +rte_rcu_qsbr_synchronize(struct rte_rcu_qsbr *v, unsigned int thread_id) +{ + uint64_t t; + + RTE_ASSERT(v != NULL); + + t = rte_rcu_qsbr_start(v); + + /* If the current thread has readside critical section, + * update its quiescent state status. + */ + if (thread_id != RTE_QSBR_THRID_INVALID) + rte_rcu_qsbr_quiescent(v, thread_id); + + /* Wait for other readers to enter quiescent state */ + rte_rcu_qsbr_check(v, t, true); +} + +/* Dump the details of a single quiescent state variable to a file. */ +int __rte_experimental +rte_rcu_qsbr_dump(FILE *f, struct rte_rcu_qsbr *v) +{ + uint64_t bmap; + uint32_t i, t; + + 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..73fa3354e --- /dev/null +++ b/lib/librte_rcu/rte_rcu_qsbr.h @@ -0,0 +1,629 @@ +/* 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 + +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. + */ +void __rte_experimental +rte_rcu_qsbr_synchronize(struct rte_rcu_qsbr *v, unsigned int thread_id); + +/** + * @warning + * @b EXPERIMENTAL: this API may change without prior notice + * + * Dump the details of a single QS variables to a file. + * + * It is NOT multi-thread safe. + * + * @param f + * A pointer to a file for output + * @param v + * QS variable + * @return + * On success - 0 + * On error - 1 with error code set in rte_errno. + * Possible rte_errno codes are: + * - EINVAL - NULL parameters are passed + */ +int __rte_experimental +rte_rcu_qsbr_dump(FILE *f, struct rte_rcu_qsbr *v); + +#ifdef __cplusplus +} +#endif + +#endif /* _RTE_RCU_QSBR_H_ */ diff --git a/lib/librte_rcu/rte_rcu_version.map b/lib/librte_rcu/rte_rcu_version.map new file mode 100644 index 000000000..5ea8524db --- /dev/null +++ b/lib/librte_rcu/rte_rcu_version.map @@ -0,0 +1,12 @@ +EXPERIMENTAL { + global: + + rte_rcu_qsbr_get_memsize; + rte_rcu_qsbr_init; + rte_rcu_qsbr_thread_register; + rte_rcu_qsbr_thread_unregister; + rte_rcu_qsbr_synchronize; + 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 abea16d48..ebe6d48a7 100644 --- a/mk/rte.app.mk +++ b/mk/rte.app.mk @@ -97,6 +97,7 @@ _LDLIBS-$(CONFIG_RTE_LIBRTE_EAL) += -lrte_eal _LDLIBS-$(CONFIG_RTE_LIBRTE_CMDLINE) += -lrte_cmdline _LDLIBS-$(CONFIG_RTE_LIBRTE_REORDER) += -lrte_reorder _LDLIBS-$(CONFIG_RTE_LIBRTE_SCHED) += -lrte_sched +_LDLIBS-$(CONFIG_RTE_LIBRTE_RCU) += -lrte_rcu ifeq ($(CONFIG_RTE_EXEC_ENV_LINUX),y) _LDLIBS-$(CONFIG_RTE_LIBRTE_KNI) += -lrte_kni From patchwork Wed Apr 17 04:13:58 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Honnappa Nagarahalli X-Patchwork-Id: 162391 Delivered-To: patch@linaro.org Received: by 2002:a02:c6d8:0:0:0:0:0 with SMTP id r24csp5025273jan; Tue, 16 Apr 2019 21:14:36 -0700 (PDT) X-Google-Smtp-Source: APXvYqzgsCvM2JGzS/wzRsc/JYZQCaAO/n8x6LStWzlmiplZ368Dru7gI9NkFy9i8HndAjNKryXl X-Received: by 2002:a50:9744:: with SMTP id d4mr6965779edb.125.1555474476802; Tue, 16 Apr 2019 21:14:36 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1555474476; cv=none; d=google.com; s=arc-20160816; b=1GLGpEPxQC3GmryZGHiqPhZlS9B/1bFcrRv5JwATCqNDgY/E53/g2DRlBJsjItxGjp G2HP8sTkedEJfaQtZKKg1HzDXGDn0X3brMZbODnbQeRhLJC/6u3MG9NEGCLrVODkG/E4 f+DvpW3YRIq6l90ZqmCfI3zzuZ35CV5NJgz8qWzGX5m9BUlgP9gxUNYPPjAxgBtE1dfQ mxU2ZcYRnLxL6rMhAqco79jJ5s7BBytEVzr4em7SamR5oXv9VGq3xSTSB4o5n5kU8Z/m U2OONxEaQ95zqg2Lg3qkCKfMnu9AgGWIiAONC5Onrztp0Eu/6puj4027Bj82nxpKsTPF xtFA== 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=dMzUozWNkKpBYaC6jw8/m1TGYhRX9qqAODokLzPsdN4=; b=UAYh1z2rrmCAEcpEnnhgVuOzaBAPwThc7QkrzUDasrFs0N/qIiwOAkBPnh0JtVZNrq U1VIWSCw34s0DlCTIJztDGraF+WKF5vk2zTgnGksD9YIzRy5b5am7UbVbxsCWDWySiRx KL1XHd9Ee6EFrhmVEAlLivxMTcexs8H9CxuWFItTHhcLYDqbvlLRrr+EHtGZgFJLt9zJ aHEyEvgMGrKeW2cUK3+7u6hfXj0ejimeV48o7+7nAk9r0SKpBGumjYRqeJ+dM5mkhEWG unNr2L0g4GU+74Nwcc5V+ySB7bsNENL+nYrz8b87OB1W/JrRkHjlHoxa/7eJRBO34Z60 cCpw== 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 y33si2973417ede.60.2019.04.16.21.14.36; Tue, 16 Apr 2019 21:14:36 -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 C28711B5A5; Wed, 17 Apr 2019 06:14:20 +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 A24CF1B59C for ; Wed, 17 Apr 2019 06:14:17 +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 18107374; Tue, 16 Apr 2019 21:14:17 -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 859D93F68F; Tue, 16 Apr 2019 21:14:16 -0700 (PDT) From: Honnappa Nagarahalli To: konstantin.ananyev@intel.com, stephen@networkplumber.org, paulmck@linux.ibm.com, marko.kovacevic@intel.com, dev@dpdk.org Cc: honnappa.nagarahalli@arm.com, gavin.hu@arm.com, dharmik.thakkar@arm.com, malvika.gupta@arm.com Date: Tue, 16 Apr 2019 23:13:58 -0500 Message-Id: <20190417041359.45335-3-honnappa.nagarahalli@arm.com> X-Mailer: git-send-email 2.17.1 In-Reply-To: <20190417041359.45335-1-honnappa.nagarahalli@arm.com> References: <20181122033055.3431-1-honnappa.nagarahalli@arm.com> <20190417041359.45335-1-honnappa.nagarahalli@arm.com> Subject: [dpdk-dev] [PATCH v6 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 | 7 +- app/test/test_rcu_qsbr.c | 1014 +++++++++++++++++++++++++++++++++ app/test/test_rcu_qsbr_perf.c | 703 +++++++++++++++++++++++ 5 files changed, 1737 insertions(+), 1 deletion(-) 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 72c56e528..fba66045f 100644 --- a/app/test/autotest_data.py +++ b/app/test/autotest_data.py @@ -700,6 +700,18 @@ "Func": default_autotest, "Report": None, }, + { + "Name": "RCU QSBR autotest", + "Command": "rcu_qsbr_autotest", + "Func": default_autotest, + "Report": None, + }, + { + "Name": "RCU QSBR performance autotest", + "Command": "rcu_qsbr_perf_autotest", + "Func": default_autotest, + "Report": None, + }, # # Please always make sure that ring_perf is the last test! # diff --git a/app/test/meson.build b/app/test/meson.build index 867cc5863..e3e566bce 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' ) @@ -136,7 +138,8 @@ test_deps = ['acl', 'reorder', 'ring', 'stack', - 'timer' + '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 Wed Apr 17 04:13:59 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Honnappa Nagarahalli X-Patchwork-Id: 162392 Delivered-To: patch@linaro.org Received: by 2002:a02:c6d8:0:0:0:0:0 with SMTP id r24csp5025410jan; Tue, 16 Apr 2019 21:14:47 -0700 (PDT) X-Google-Smtp-Source: APXvYqzU/o20CmGbI9d5CUL/O063w2ibtOSx3ddHyh2v2UvaADY4L91LAAhPz41PPt+36t+X8ihF X-Received: by 2002:aa7:da13:: with SMTP id r19mr14081433eds.204.1555474487072; Tue, 16 Apr 2019 21:14:47 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1555474487; cv=none; d=google.com; s=arc-20160816; b=weNDNxWLaHdkTKuXS3MimDR+TJBcVOZmvERHEwmWM1wTW+Q6ZuUuSWuXeet4uv1WK4 YhmzuQZPlMLCRk79NgP5pc4l2uWSaEudukUCC8KnGOfkOizdfmzomzuGjujjd8bTBfxv C4QIWpiyz3V9FbE6jABuRjII2wQGplM/8k7bH8qmVc4qEuyDFiaF3mpa7syByHv3k4Mj jpETA2B6KTeJPELxhL3vTBLTdiEuKUkgjU+9hX/R8EadUv+8eWDR1SpslkYYdmBJQ3Uw 5SPVJaF88Ju3JDHpP+SF9esHAuTgto07VSDh9OgF1mS9FA1JS3swCcZAU1PjZZbVkx9A 9yBw== 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=b6z/Y5QJhL90J4c94IjETG8Q4Zy+7/HrHYxLLcMqrg2fyrzScL1bG83mujLoxMQ3vf /+70mnKfox/TXDHS5GYDT4r8wa5mPjgQUYrbZ+Uk4VugYXNvuyZ0gXj8hZM4xZw7oZNK pLtr8vi7ZMYCNcRfaoCtUk2G628R0VlbWinDmnHI1IRT7JZApoB7fBK9kls/cONAQwr6 Y7w1pYNcUdI2cFVV2zk8cE6FZx16OdUcFiYv97H8+vS9aAq7xhPrC1S04kKR3sXX6yR9 9yUSecGBTAXhkE59RNIBoROHsDsMdLVldMHZrbaJVvpZdPZyM6VjyWxetmDDv5y11wEh uTrw== 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 e8si1267771edi.417.2019.04.16.21.14.46; Tue, 16 Apr 2019 21:14:47 -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 52CE61B5AB; Wed, 17 Apr 2019 06:14:23 +0200 (CEST) Received: from foss.arm.com (foss.arm.com [217.140.101.70]) by dpdk.org (Postfix) with ESMTP id BE0181B5A0 for ; Wed, 17 Apr 2019 06:14:18 +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 386F515A2; Tue, 16 Apr 2019 21:14:18 -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 B8FAB3F68F; Tue, 16 Apr 2019 21:14:17 -0700 (PDT) From: Honnappa Nagarahalli To: konstantin.ananyev@intel.com, stephen@networkplumber.org, paulmck@linux.ibm.com, marko.kovacevic@intel.com, dev@dpdk.org Cc: honnappa.nagarahalli@arm.com, gavin.hu@arm.com, dharmik.thakkar@arm.com, malvika.gupta@arm.com Date: Tue, 16 Apr 2019 23:13:59 -0500 Message-Id: <20190417041359.45335-4-honnappa.nagarahalli@arm.com> X-Mailer: git-send-email 2.17.1 In-Reply-To: <20190417041359.45335-1-honnappa.nagarahalli@arm.com> References: <20181122033055.3431-1-honnappa.nagarahalli@arm.com> <20190417041359.45335-1-honnappa.nagarahalli@arm.com> Subject: [dpdk-dev] [PATCH v6 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.