From patchwork Sat Jun 27 15:08:02 2015 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: "Lespiau, Damien" X-Patchwork-Id: 6685111 Return-Path: X-Original-To: patchwork-intel-gfx@patchwork.kernel.org Delivered-To: patchwork-parsemail@patchwork1.web.kernel.org Received: from mail.kernel.org (mail.kernel.org [198.145.29.136]) by patchwork1.web.kernel.org (Postfix) with ESMTP id 121E79F401 for ; Sat, 27 Jun 2015 15:08:49 +0000 (UTC) Received: from mail.kernel.org (localhost [127.0.0.1]) by mail.kernel.org (Postfix) with ESMTP id 20F5220770 for ; Sat, 27 Jun 2015 15:08:48 +0000 (UTC) Received: from gabe.freedesktop.org (gabe.freedesktop.org [131.252.210.177]) by mail.kernel.org (Postfix) with ESMTP id 1B04420761 for ; Sat, 27 Jun 2015 15:08:47 +0000 (UTC) Received: from gabe.freedesktop.org (localhost [127.0.0.1]) by gabe.freedesktop.org (Postfix) with ESMTP id 2D04D6E72B; Sat, 27 Jun 2015 08:08:46 -0700 (PDT) X-Original-To: intel-gfx@lists.freedesktop.org Delivered-To: intel-gfx@lists.freedesktop.org Received: from mga02.intel.com (mga02.intel.com [134.134.136.20]) by gabe.freedesktop.org (Postfix) with ESMTP id 9BC616E2C6 for ; Sat, 27 Jun 2015 08:08:43 -0700 (PDT) Received: from fmsmga003.fm.intel.com ([10.253.24.29]) by orsmga101.jf.intel.com with ESMTP; 27 Jun 2015 08:08:43 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.13,689,1427785200"; d="scan'208";a="515137050" Received: from kczmudzi-mobl4.amr.corp.intel.com (HELO strange.ger.corp.intel.com) ([10.252.53.243]) by FMSMGA003.fm.intel.com with ESMTP; 27 Jun 2015 08:08:42 -0700 From: Damien Lespiau To: intel-gfx@lists.freedesktop.org Date: Sat, 27 Jun 2015 16:08:02 +0100 Message-Id: <1435417696-28115-5-git-send-email-damien.lespiau@intel.com> X-Mailer: git-send-email 2.1.0 In-Reply-To: <1435417696-28115-1-git-send-email-damien.lespiau@intel.com> References: <1435417696-28115-1-git-send-email-damien.lespiau@intel.com> Subject: [Intel-gfx] [PATCH i-g-t 04/18] stats: Add gtkdoc section for igt_stats X-BeenThere: intel-gfx@lists.freedesktop.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: Intel graphics driver community testing & development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Errors-To: intel-gfx-bounces@lists.freedesktop.org Sender: "Intel-gfx" X-Spam-Status: No, score=-5.6 required=5.0 tests=BAYES_00, RCVD_IN_DNSWL_MED, RP_MATCHES_RCVD, UNPARSEABLE_RELAY autolearn=unavailable version=3.3.1 X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on mail.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP Signed-off-by: Damien Lespiau --- .../intel-gpu-tools/intel-gpu-tools-docs.xml | 1 + lib/igt_stats.c | 74 ++++++++++++++++++++++ lib/igt_stats.h | 9 ++- 3 files changed, 83 insertions(+), 1 deletion(-) diff --git a/docs/reference/intel-gpu-tools/intel-gpu-tools-docs.xml b/docs/reference/intel-gpu-tools/intel-gpu-tools-docs.xml index a6d1f89..7e481b8 100644 --- a/docs/reference/intel-gpu-tools/intel-gpu-tools-docs.xml +++ b/docs/reference/intel-gpu-tools/intel-gpu-tools-docs.xml @@ -17,6 +17,7 @@ API Reference + diff --git a/lib/igt_stats.c b/lib/igt_stats.c index 67ee947..0bee138 100644 --- a/lib/igt_stats.c +++ b/lib/igt_stats.c @@ -28,6 +28,49 @@ #include "igt_core.h" #include "igt_stats.h" +/** + * SECTION:igt_stats + * @short_description: Tools for statistical analysis + * @title: Stats + * @include: igt_stats.h + * + * Various tools to make sense of data. + * + * #igt_stats_t is a container of data samples. igt_stats_push() is used to add + * new samples and various results (mean, variance, standard deviation, ...) + * can then be retrieved. + * + * |[ + * igt_stats_t stats; + * + * igt_stats_init(&stats, 8); + * + * igt_stats_push(&stats, 2); + * igt_stats_push(&stats, 4); + * igt_stats_push(&stats, 4); + * igt_stats_push(&stats, 4); + * igt_stats_push(&stats, 5); + * igt_stats_push(&stats, 5); + * igt_stats_push(&stats, 7); + * igt_stats_push(&stats, 9); + * + * printf("Mean: %lf\n", igt_stats_get_mean(&stats)); + * + * igt_stats_fini(&stats); + * ]| + */ + +/** + * igt_stats_init: + * @stats: An #igt_stats_t instance + * @capacity: Number of data samples @stats can contain + * + * Initializes an #igt_stats_t instance to hold @capacity samples. + * igt_stats_fini() must be called once finished with @stats. + * + * We currently assume the user knows how many data samples upfront and there's + * no need to grow the array of values. + */ void igt_stats_init(igt_stats_t *stats, unsigned int capacity) { memset(stats, 0, sizeof(*stats)); @@ -37,11 +80,24 @@ void igt_stats_init(igt_stats_t *stats, unsigned int capacity) stats->capacity = capacity; } +/** + * igt_stats_fini: + * @stats: An #igt_stats_t instance + * + * Frees resources allocated in igt_stats_init(). + */ void igt_stats_fini(igt_stats_t *stats) { free(stats->values); } +/** + * igt_stats_push: + * @stats: An #igt_stats_t instance + * @value: An integer value + * + * Adds a new value to the @stats dataset. + */ void igt_stats_push(igt_stats_t *stats, uint64_t value) { igt_assert(stats->n_values < stats->capacity); @@ -77,6 +133,12 @@ static void igt_stats_knuth_mean_variance(igt_stats_t *stats) stats->mean_variance_valid = true; } +/** + * igt_stats_get_mean: + * @stats: An #igt_stats_t instance + * + * Retrieves the mean of the @stats dataset. + */ double igt_stats_get_mean(igt_stats_t *stats) { igt_stats_knuth_mean_variance(stats); @@ -84,6 +146,12 @@ double igt_stats_get_mean(igt_stats_t *stats) return stats->mean; } +/** + * igt_stats_get_variance: + * @stats: An #igt_stats_t instance + * + * Retrieves the variance of the @stats dataset. + */ double igt_stats_get_variance(igt_stats_t *stats) { igt_stats_knuth_mean_variance(stats); @@ -91,6 +159,12 @@ double igt_stats_get_variance(igt_stats_t *stats) return stats->variance; } +/** + * igt_stats_get_std_deviation: + * @stats: An #igt_stats_t instance + * + * Retrieves the standard deviation of the @stats dataset. + */ double igt_stats_get_std_deviation(igt_stats_t *stats) { igt_stats_knuth_mean_variance(stats); diff --git a/lib/igt_stats.h b/lib/igt_stats.h index 0d4669e..c45c819 100644 --- a/lib/igt_stats.h +++ b/lib/igt_stats.h @@ -27,10 +27,17 @@ #include +/** + * igt_stats_t: + * @values: An array containing the pushed values + * @n_values: The number of pushed values + */ typedef struct { uint64_t *values; - unsigned int capacity; unsigned int n_values; + + /*< private >*/ + unsigned int capacity; unsigned int mean_variance_valid : 1; double mean, variance; } igt_stats_t;