Ubstat system call - Revision history

Vdavydov at 14:06, 20 January 2011

2011-01-20T14:06:41Z

Vdavydov at 14:06, 20 January 2011

2011-01-20T14:06:31Z

Xemul: Fixed contents structure... again :\

2010-02-08T09:08:53Z

Fixed contents structure... again :\

Kir: /* The statistics format */ fiixed a typo

2010-02-05T22:22:53Z

‎The statistics format: fiixed a typo

Kir: /* Return value */ close the tag

2010-02-05T22:20:01Z

‎Return value: close the tag

Kir: use tag instead of pre where appropriate

2010-02-05T16:04:07Z

use <source> tag instead of pre where appropriate

Kir: fixed level heading for API

2010-02-05T16:01:55Z

fixed level heading for API

Kir: fixed a typo

2010-02-05T14:36:25Z

fixed a typo

Kir: do not use level1 headings

2010-02-05T14:36:10Z

do not use level1 headings

Xemul: Added the "return value" section

2010-02-05T14:20:48Z

Added the "return value" section

← Older revision		Revision as of 14:06, 20 January 2011
Line 1:		Line 1:
−	This article describes an interesting system call which was designed to pick beancounters statistics	+	This article describes an interesting system call which was designed to pick beancounters statistics.

	== Overview ==		== Overview ==

← Older revision		Revision as of 14:06, 20 January 2011
Line 1:		Line 1:
−	This article describes an interesting system call which was designed to pick beancounters statistics.	+	This article describes an interesting system call which was designed to pick beancounters statistics

	== Overview ==		== Overview ==

@@ Line 25: / Line 25: @@
 The macros and data typed used are declared in <code>include/ub/ub_stat.h</code> file.
-== Arguments description ==
+=== Arguments description ===
 '''<code>func</code>''' is like <code>cmd</code> in the <code>ioctl</code> system call. It can be one of
@@ Line 45: / Line 45: @@
 '''<code>size</code>''' is the <code>buf</code> memory size.
-== The statistics format ==
+=== The statistics format ===
 The format of data returned into the buffer depends on the function requested.

@@ Line 46: / Line 46: @@
 == The statistics format ==
-The format of data rerurned into the buffer depends on the function requested.
+The format of data returned into the buffer depends on the function requested.
 '''1. <code>UBSTAT_READ_ONE</code>''' format is

@@ Line 143: / Line 143: @@
 === Return value ===
-The system call returns -1 in case error has occurred. In case of <code>UBSTAT_UBPARMNUM</code it returns <code>UB_RESOURCES</code> and in all other cases it returns the amount of bytes written to the <code>buf</code>.
+The system call returns -1 in case error has occurred. In case of <code>UBSTAT_UBPARMNUM</code> it returns <code>UB_RESOURCES</code> and in all other cases it returns the amount of bytes written to the <code>buf</code>.
 == Demo ==

@@ Line 19: / Line 19: @@
 The system call description is
-<pre>
+<source lang="c">
 long ubstat(int func, unsigned long luid, void *notif, void *buf, int size);
-</pre>
+</source>
 The macros and data typed used are declared in <code>include/ub/ub_stat.h</code> file.
@@ Line 49: / Line 49: @@
 '''1. <code>UBSTAT_READ_ONE</code>''' format is
-<pre>
+<source lang="c">
          typedef unsigned long ubstattime_t;
@@ Line 62: / Line 62: @@
                  ubstatparm_t    param[1];
+         }
-</pre>
+</source>
 It contains the time period for which the stats are returned and the <code>maxheld</code> and <code>failcnt</code> for the resource.
 '''2. <code>UBSTAT_READ_ALL</code>''' format is
-<pre>
+<source lang="c">
          typedef unsigned long ubstattime_t;
@@ Line 80: / Line 80: @@
                  ubstatparm_t    param[UB_RESOURCES];
+         }
-</pre>
+</source>
 It contains the same info as the <code>UBSTAT_READ_ONE</code> does, but for all the resources.
 '''3. <code>UBSTAT_READ_FULL</code>''' format is
-<pre>
+<source lang="c">
          typedef unsigned long ubstattime_t;
@@ Line 104: / Line 104: @@
                  ubstatparmf_t    param[UB_RESOURCES];
+         }
-</pre>
+</source>
 It contains the extended info for all the resources.
@@ Line 113: / Line 113: @@
 '''6. UBSTAT_GETTIME''' format is
-<pre>
+<source lang="c">
          typedef unsigned long ubstattime_t;
@@ Line 121: / Line 121: @@
                  ubstattime_t    cur_time;
          };
-</pre>
+</source>
 It returns the time interval within which the stats are collected and the current time.
@@ Line 131: / Line 131: @@
 The <code>notif</code> should point to
-<pre>
+<source lang="c">
          typedef struct {
                  long            maxinterval;
                  int             signum;
          } ubnotifrq_t;
-</pre>
+</source>
 The <code>maxinterval</code> is the time after which the notification will be delivered. It should be more than 1 (second).
@@ Line 147: / Line 147: @@
 == Demo ==
 The following program demonstrates how you can (but not should) use the described API. This example is deliberately made very stupid and simple to demonstrate the main idea and will only work on x86_64.
-<pre>
+<source lang="c">
 #include <stdio.h>
 #include <unistd.h>
@@ Line 285: / Line 285: @@
 	return 0;
+}
-</pre>
+</source>
 == Implementation constraints ==

@@ Line 16: / Line 16: @@
 In a signal handler one should just perform a respective system call to get the stats and schedule the next notification (yes, they are performed in one go; see below for more details).
-=== API ===
+== API ==
 The system call description is

@@ Line 6: / Line 6: @@
 The main intention of this system call is to allow a user space process get the beancounters statistics ''periodically''. This statistics includes the fields observed in the <code>/proc/user_beancounters</code> file and one more field - the so called <code>minheld</code> value which is opposite to the <code>maxheld</code> one. As long as exporting the statistics the system call also notifies the task about the desired period has elapsed. The notification is performed by sending a signal to a process and this notification is one-shot.
--= How it works ==
+== How it works ==
 The typical usage of this call is in performing the following steps.
 # Request the amount of resources

← Older revision		Revision as of 14:20, 5 February 2010
Line 141:		Line 141:

	The <code>signum</code> is the signal that will be sent to notify.		The <code>signum</code> is the signal that will be sent to notify.
		+
		+	== Return value ==
		+	The system call returns -1 in case error has occurred. In case of <code>UBSTAT_UBPARMNUM</code it returns <code>UB_RESOURCES</code> and in all other cases it returns the amount of bytes written to the <code>buf</code>.

	= Demo =		= Demo =