Commit c3123552 authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab
Browse files

docs: accounting: convert to ReST 



Rename the accounting documentation files to ReST, add an
index for them and adjust in order to produce a nice html
output via the Sphinx build system.

At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.

Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+samsung@kernel.org>
parent a36d0538

Documentation/accounting/cgroupstats.txt→Documentation/accounting/cgroupstats.rst

+9 −5
Original line number Diff line number Diff line 
==================

Control Groupstats

==================



Control Groupstats is inspired by the discussion at

http://lkml.org/lkml/2007/4/11/187 and implements per cgroup statistics as

suggested by Andrew Morton in http://lkml.org/lkml/2007/4/11/263.
@@ -19,7 +23,7 @@ about tasks blocked on I/O. If CONFIG_TASK_DELAY_ACCT is disabled, this 
information will not be available.



To extract cgroup statistics a utility very similar to getdelays.c

has been developed, the sample output of the utility is shown below

has been developed, the sample output of the utility is shown below::



  ~/balbir/cgroupstats # ./getdelays  -C "/sys/fs/cgroup/a"

  sleeping 1, blocked 0, running 1, stopped 0, uninterruptible 0

Documentation/accounting/delay-accounting.txt→Documentation/accounting/delay-accounting.rst

+35 −26
Original line number Diff line number Diff line 
================

Delay accounting

----------------

================



Tasks encounter delays in execution when they wait

for some kernel resource to become available e.g. a
@@ -39,7 +40,9 @@ in detail in a separate document in this directory. Taskstats returns a 
generic data structure to userspace corresponding to per-pid and per-tgid

statistics. The delay accounting functionality populates specific fields of

this structure. See



     include/linux/taskstats.h



for a description of the fields pertaining to delay accounting.

It will generally be in the form of counters returning the cumulative

delay seen for cpu, sync block I/O, swapin, memory reclaim etc.
@@ -61,13 +64,16 @@ also serves as an example of using the taskstats interface. 
Usage

-----



Compile the kernel with

Compile the kernel with::



	CONFIG_TASK_DELAY_ACCT=y

	CONFIG_TASKSTATS=y



Delay accounting is enabled by default at boot up.

To disable, add

To disable, add::



   nodelayacct



to the kernel boot options. The rest of the instructions

below assume this has not been done.
@@ -78,16 +84,18 @@ The utility also allows a given command to be 
executed and the corresponding delays to be

seen.



General format of the getdelays command

General format of the getdelays command::



	getdelays [-t tgid] [-p pid] [-c cmd...]





Get delays, since system boot, for pid 10

Get delays, since system boot, for pid 10::



	# ./getdelays -p 10

	(output similar to next case)



Get sum of delays, since system boot, for all pids with tgid 5

Get sum of delays, since system boot, for all pids with tgid 5::



	# ./getdelays -t 5
@@ -100,7 +108,8 @@ SWAP count delay total 
	RECLAIM	count	delay total

		0	0



Get delays seen in executing a given simple command

Get delays seen in executing a given simple command::



  # ./getdelays -c ls /



  bin   data1  data3  data5  dev  home  media  opt   root  srv        sys  usr

Documentation/accounting/index.rst

0 → 100644
+14 −0
Original line number Diff line number Diff line 
:orphan:



==========

Accounting

==========



.. toctree::

   :maxdepth: 1



   cgroupstats

   delay-accounting

   psi

   taskstats

   taskstats-struct

Documentation/accounting/psi.txt→Documentation/accounting/psi.rst

+22 −20
Original line number Diff line number Diff line
@@ -35,11 +35,11 @@ Pressure interface 
Pressure information for each resource is exported through the

respective file in /proc/pressure/ -- cpu, memory, and io.



The format for CPU is as such:

The format for CPU is as such::



	some avg10=0.00 avg60=0.00 avg300=0.00 total=0



and for memory and IO:

and for memory and IO::



	some avg10=0.00 avg60=0.00 avg300=0.00 total=0

	full avg10=0.00 avg60=0.00 avg300=0.00 total=0
@@ -77,7 +77,7 @@ To register a trigger user has to open psi interface file under 
/proc/pressure/ representing the resource to be monitored and write the

desired threshold and time window. The open file descriptor should be

used to wait for trigger events using select(), poll() or epoll().

The following format is used:

The following format is used::



	<some|full> <stall amount in us> <time window in us>
@@ -115,6 +115,8 @@ trigger is closed. 
Userspace monitor usage example

===============================



::



  #include <errno.h>

  #include <fcntl.h>

  #include <stdio.h>

Documentation/accounting/taskstats-struct.txt→Documentation/accounting/taskstats-struct.rst

+49 −30
Original line number Diff line number Diff line 
====================

The struct taskstats

--------------------

====================



This document contains an explanation of the struct taskstats fields.
@@ -10,16 +11,24 @@ There are three different groups of fields in the struct taskstats: 
    the common fields and basic accounting fields are collected for

    delivery at do_exit() of a task.

2) Delay accounting fields

    These fields are placed between

    These fields are placed between::



	/* Delay accounting fields start */

    and



    and::



	/* Delay accounting fields end */



    Their values are collected if CONFIG_TASK_DELAY_ACCT is set.

3) Extended accounting fields

    These fields are placed between

    These fields are placed between::



	/* Extended accounting fields start */

    and



    and::



	/* Extended accounting fields end */



    Their values are collected if CONFIG_TASK_XACCT is set.



4) Per-task and per-thread context switch count statistics
@@ -31,10 +40,12 @@ There are three different groups of fields in the struct taskstats: 
Future extension should add fields to the end of the taskstats struct, and

should not change the relative position of each field within the struct.



::



  struct taskstats {



1) Common and basic accounting fields:

1) Common and basic accounting fields::



	/* The version number of this struct. This field is always set to

	 * TAKSTATS_VERSION, which is defined in <linux/taskstats.h>.

	 * Each time the struct is changed, the value should be incremented.
@@ -83,7 +94,8 @@ struct taskstats { 
	__u64	ac_majflt;		/* Major Page Fault Count */





2) Delay accounting fields:

2) Delay accounting fields::



	/* Delay accounting fields start

	 *

	 * All values, until the comment "Delay accounting fields end" are
@@ -134,7 +146,8 @@ struct taskstats { 
	/* version 1 ends here */





3) Extended accounting fields

3) Extended accounting fields::



	/* Extended accounting fields start */



	/* Accumulated RSS usage in duration of a task, in MBytes-usecs.
@@ -164,17 +177,23 @@ struct taskstats { 


	/* Extended accounting fields end */



4) Per-task and per-thread statistics

4) Per-task and per-thread statistics::



	__u64	nvcsw;			/* Context voluntary switch counter */

	__u64	nivcsw;			/* Context involuntary switch counter */



5) Time accounting for SMT machines

5) Time accounting for SMT machines::



	__u64	ac_utimescaled;		/* utime scaled on frequency etc */

	__u64	ac_stimescaled;		/* stime scaled on frequency etc */

	__u64	cpu_scaled_run_real_total; /* scaled cpu_run_real_total */



6) Extended delay accounting fields for memory reclaim

6) Extended delay accounting fields for memory reclaim::



	/* Delay waiting for memory reclaim */

	__u64	freepages_count;

	__u64	freepages_delay_total;



::



  }