From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124]) by inbox.dpdk.org (Postfix) with ESMTP id F21ACA0032; Wed, 14 Sep 2022 11:26:43 +0200 (CEST) Received: from [217.70.189.124] (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id CC92C42B76; Wed, 14 Sep 2022 11:26:29 +0200 (CEST) Received: from mga05.intel.com (mga05.intel.com [192.55.52.43]) by mails.dpdk.org (Postfix) with ESMTP id 2C9074280D for ; Wed, 14 Sep 2022 11:26:26 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=intel.com; i=@intel.com; q=dns/txt; s=Intel; t=1663147587; x=1694683587; h=from:to:cc:subject:date:message-id:in-reply-to: references:mime-version:content-transfer-encoding; bh=CCYH84CxqxOBWravHGKI5REiL4NY4Mbar5gZrJDNNjQ=; b=hlXvgc1Cr64FJlytD4eScxSKHLzCOItU5BBRuwO6k74AnR7R3rHBkxVV CLW3INNOExw/GSuOIaoCPtD+5giVScw9QvhdftAKM1ono2i8YD7qVn2s5 RrtPE3wJPucR/Hw/Yie5Eabimyh89qKm7CfFN3XfVUIRwXc0w3q55iVKi Fn7+IcAxSsyJc+LQb7UXYjcvH2sOJHuUeMOxpxYM/JsHbPKLg/kbPe3qX g9GyVLrQIFHX9L3O9EgLh8lN7JAU7QtfbcPQCq+G5z4pANUhkb7/Hg5ij evSH0NdovlFpII7QjYN2rRnZPCL693Szt39iJOafjWLlvhrvDyVJbczK0 A==; X-IronPort-AV: E=McAfee;i="6500,9779,10469"; a="384675043" X-IronPort-AV: E=Sophos;i="5.93,315,1654585200"; d="scan'208";a="384675043" Received: from orsmga007.jf.intel.com ([10.7.209.58]) by fmsmga105.fm.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 14 Sep 2022 02:26:26 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.93,315,1654585200"; d="scan'208";a="612446540" Received: from silpixa00401122.ir.intel.com ([10.237.213.42]) by orsmga007.jf.intel.com with ESMTP; 14 Sep 2022 02:26:25 -0700 From: Kevin Laatz To: dev@dpdk.org Cc: anatoly.burakov@intel.com, Kevin Laatz Subject: [PATCH v7 4/4] doc: add howto guide for lcore poll busyness Date: Wed, 14 Sep 2022 10:29:29 +0100 Message-Id: <20220914092929.1159773-5-kevin.laatz@intel.com> X-Mailer: git-send-email 2.31.1 In-Reply-To: <20220914092929.1159773-1-kevin.laatz@intel.com> References: <24c49429394294cfbf0d9c506b205029bac77c8b.1657890378.git.anatoly.burakov@intel.com> <20220914092929.1159773-1-kevin.laatz@intel.com> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org Add a new section to the howto guides for using the new lcore poll busyness telemetry endpoints and describe general usage. Signed-off-by: Kevin Laatz --- v6: * Add mention of perf autotest in note mentioning perf impact. v4: * Include note on perf impact when the feature is enabled * Add doc to toctree * Updates to incorporate changes made earlier in the patchset v3: * Update naming to poll busyness --- doc/guides/howto/index.rst | 1 + doc/guides/howto/lcore_poll_busyness.rst | 93 ++++++++++++++++++++++++ 2 files changed, 94 insertions(+) create mode 100644 doc/guides/howto/lcore_poll_busyness.rst diff --git a/doc/guides/howto/index.rst b/doc/guides/howto/index.rst index bf6337d021..0a9060c1d3 100644 --- a/doc/guides/howto/index.rst +++ b/doc/guides/howto/index.rst @@ -21,3 +21,4 @@ HowTo Guides debug_troubleshoot openwrt avx512 + lcore_poll_busyness diff --git a/doc/guides/howto/lcore_poll_busyness.rst b/doc/guides/howto/lcore_poll_busyness.rst new file mode 100644 index 0000000000..be5ea2a85d --- /dev/null +++ b/doc/guides/howto/lcore_poll_busyness.rst @@ -0,0 +1,93 @@ +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2022 Intel Corporation. + +Lcore Poll Busyness Telemetry +============================= + +The lcore poll busyness telemetry provides a built-in, generic method of gathering +lcore utilization metrics for running applications. These metrics are exposed +via a new telemetry endpoint. + +Since most DPDK APIs polling based, the poll busyness is calculated based on +APIs receiving 'work' (packets, completions, events, etc). Empty polls are +considered as idle, while non-empty polls are considered busy. Using the amount +of cycles spent processing empty polls, the busyness can be calculated and recorded. + +Application Specified Busyness +------------------------------ + +Improved accuracy of the reported busyness may need more contextual awareness +from the application. For example, an application may make a number of calls to +rx_burst before processing packets. If the last burst was an "empty poll", then +the processing time of the packets would be falsely considered as "idle", since +the last burst was empty. The application should track if any of the polls +contained "work" to do and should mark the 'bulk' as "busy" cycles before +proceeding to the processesing. This type of awareness is only available within +the application. + +Applications can be modified to incorporate the extra contextual awareness in +order to improve the reported busyness by marking areas of code as "busy" or +"idle" appropriately. This can be done by inserting the timestamping macro:: + + RTE_LCORE_POLL_BUSYNESS_TIMESTAMP(0) /* to mark section as idle */ + RTE_LCORE_POLL_BUSYNESS_TIMESTAMP(32) /* where 32 is nb_pkts to mark section as busy (non-zero is busy) */ + +All cycles since the last state change (idle to busy, or vice versa) will be +counted towards the current state's counter. + +Consuming the Telemetry +----------------------- + +The telemetry gathered for lcore poll busyness can be read from the `telemetry.py` +script via the new `/eal/lcore/poll_busyness` endpoint:: + + $ ./usertools/dpdk-telemetry.py + --> /eal/lcore/poll_busyness + {"/eal/lcore/poll_busyness": {"12": -1, "13": 85, "14": 84}} + +* Cores not collecting poll busyness will report "-1". E.g. control cores or inactive cores. +* All enabled cores will report their poll busyness in the range 0-100. + +Enabling and Disabling Lcore Poll Busyness Telemetry +---------------------------------------------------- + +By default, the lcore poll busyness telemetry is disabled at compile time. In +order to allow DPDK to gather this metric, the ``enable_lcore_poll_busyness`` +meson option must be set to ``true``. + +.. note:: + Enabling lcore poll busyness telemetry may impact performance due to the + additional timestamping, potentially per poll depending on the application. + This can be measured with the `lcore_poll_busyness_perf_autotest`. + +At compile time +^^^^^^^^^^^^^^^ + +Support can be enabled/disabled at compile time via the meson option. +It is disabled by default.:: + + $ meson configure -Denable_lcore_poll_busyness=true #enable + + $ meson configure -Denable_lcore_poll_busyness=false #disable + +At run time +^^^^^^^^^^^ + +Support can also be enabled/disabled during runtime (if the meson option is +enabled at compile time). Disabling at runtime comes at the cost of an additional +branch, however no additional function calls are performed. + +To enable/disable support at runtime, a call can be made to the appropriately +telemetry endpoint. + +Disable:: + + $ ./usertools/dpdk-telemetry.py + --> /eal/lcore/poll_busyness_disable + {"/eal/lcore/poll_busyness_disable": {"poll_busyness_enabled": 0}} + +Enable:: + + $ ./usertools/dpdk-telemetry.py + --> /eal/lcore/poll_busyness_enable + {"/eal/lcore/poll_busyness_enable": {"poll_busyness_enabled": 1}} -- 2.31.1