diff mbox

[i-g-t,06/11] lib: Update docs for igt_stats

Message ID 1469623097-26044-7-git-send-email-daniel.vetter@ffwll.ch (mailing list archive)
State New, archived
Headers show

Commit Message

Daniel Vetter July 27, 2016, 12:38 p.m. UTC 
Unfortunately gtkdoc refuses to acknowledge static inlines, so need
to nuke them. It probably gets confused by that static ...

Also unamed unions confuse gtk-doc, move everything else public up.

Cc: Chris Wilson <chris@chris-wilson.co.uk>
Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>
---
 lib/igt_stats.c | 54 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 lib/igt_stats.h | 44 +++++++++++++++-----------------------------
 2 files changed, 69 insertions(+), 29 deletions(-)

Comments

Chris Wilson July 27, 2016, 2:18 p.m. UTC | #1 
On Wed, Jul 27, 2016 at 02:38:12PM +0200, Daniel Vetter wrote:
> Unfortunately gtkdoc refuses to acknowledge static inlines, so need
> to nuke them. It probably gets confused by that static ...
> 
> Also unamed unions confuse gtk-doc, move everything else public up.

Why do we bother with gtk-doc then? Have you not made kerneldoc available
to igt yet?
-Chris
Daniel Vetter July 28, 2016, 8:29 a.m. UTC | #2 
On Wed, Jul 27, 2016 at 03:18:53PM +0100, Chris Wilson wrote:
> On Wed, Jul 27, 2016 at 02:38:12PM +0200, Daniel Vetter wrote:
> > Unfortunately gtkdoc refuses to acknowledge static inlines, so need
> > to nuke them. It probably gets confused by that static ...
> > 
> > Also unamed unions confuse gtk-doc, move everything else public up.
> 
> Why do we bother with gtk-doc then? Have you not made kerneldoc available
> to igt yet?

It occured to me too ;-) I think what we'd need to undertake that step:
- More polish on the kernel side. There's talk about rewriting the C
  parser into something slightly less horrible than a state machine
  implemented in perl regexes ...
- Probably more operational experience with the new kernel doc toolchain.
  Right now we're all happy with how it works and haven't discovered the
  new real warts yet. But there are, e.g. media folks have found some fun
  with how sphinx handles (or doesn't handle) functions with the same
  name&signature.
- Someone with too much time.

But yes, I think the kernel doc toolchain is now the one that sucks less
compared to igt, pre 4.8 it was definitely igt/gtk-doc that sucked less
imo.
-Daniel
diff mbox

Patch

diff --git a/lib/igt_stats.c b/lib/igt_stats.c
index 78db6be11e7e..0fbf712c064d 100644
--- a/lib/igt_stats.c
+++ b/lib/igt_stats.c
@@ -606,3 +606,57 @@  double igt_stats_get_trimean(igt_stats_t *stats)
 	igt_stats_get_quartiles(stats, &q1, &q2, &q3);
 	return (q1 + 2*q2 + q3) / 4;
 }
+
+/**
+ * igt_mean_init:
+ * @m: tracking structure
+ *
+ * Initializes or resets @m.
+ */
+void igt_mean_init(struct igt_mean *m)
+{
+	memset(m, 0, sizeof(*m));
+	m->max = -HUGE_VAL;
+	m->min = HUGE_VAL;
+}
+
+/**
+ * igt_mean_add:
+ * @m: tracking structure
+ * @v: value
+ *
+ * Adds a new value @v to @m.
+ */
+void igt_mean_add(struct igt_mean *m, double v)
+{
+	double delta = v - m->mean;
+	m->mean += delta / ++m->count;
+	m->sq += delta * (v - m->mean);
+	if (v < m->min)
+		m->min = v;
+	if (v > m->max)
+		m->max = v;
+}
+
+/**
+ * igt_mean_get:
+ * @m: tracking structure
+ *
+ * Computes the current mean of the samples tracked in @m.
+ */
+double igt_mean_get(struct igt_mean *m)
+{
+	return m->mean;
+}
+
+/**
+ * igt_mean_get_variance:
+ * @m: tracking structure
+ *
+ * Computes the current variance of the samples tracked in @m.
+ */
+double igt_mean_get_variance(struct igt_mean *m)
+{
+	return m->sq / m->count;
+}
+
diff --git a/lib/igt_stats.h b/lib/igt_stats.h
index 32f376cc3032..5faeced4ccae 100644
--- a/lib/igt_stats.h
+++ b/lib/igt_stats.h
@@ -32,16 +32,17 @@ 
 /**
  * igt_stats_t:
  * @values_u64: An array containing pushed integer values
+ * @is_float: Whether @values_f or @values_u64 is valid
  * @values_f: An array containing pushed float values
  * @n_values: The number of pushed values
  */
 typedef struct {
+	unsigned int n_values;
+	unsigned int is_float : 1;
 	union {
 		uint64_t *values_u64;
 		double *values_f;
 	};
-	unsigned int n_values;
-	unsigned int is_float : 1;
 
 	/*< private >*/
 	unsigned int capacity;
@@ -81,37 +82,22 @@  double igt_stats_get_median(igt_stats_t *stats);
 double igt_stats_get_variance(igt_stats_t *stats);
 double igt_stats_get_std_deviation(igt_stats_t *stats);
 
+/**
+ * igt_mean:
+ *
+ * Structure to compute running statistical numbers. Needs to be initialized
+ * with igt_mean_init(). Read out data using igt_mean_get() and
+ * igt_mean_get_variance().
+ */
 struct igt_mean {
+	/*< private >*/
 	double mean, sq, min, max;
 	unsigned long count;
 };
 
-static inline void igt_mean_init(struct igt_mean *m)
-{
-	memset(m, 0, sizeof(*m));
-	m->max = -HUGE_VAL;
-	m->min = HUGE_VAL;
-}
-
-static inline void igt_mean_add(struct igt_mean *m, double v)
-{
-	double delta = v - m->mean;
-	m->mean += delta / ++m->count;
-	m->sq += delta * (v - m->mean);
-	if (v < m->min)
-		m->min = v;
-	if (v > m->max)
-		m->max = v;
-}
-
-static inline double igt_mean_get(struct igt_mean *m)
-{
-	return m->mean;
-}
-
-static inline double igt_mean_get_variance(struct igt_mean *m)
-{
-	return m->sq / m->count;
-}
+void igt_mean_init(struct igt_mean *m);
+void igt_mean_add(struct igt_mean *m, double v);
+double igt_mean_get(struct igt_mean *m);
+double igt_mean_get_variance(struct igt_mean *m);
 
 #endif /* __IGT_STATS_H__ */