cpuidle: Add Documentation

Documentation for cpuidle infrastructure. (resend) Signed-off-by: Venkatesh Pallipadi <venkatesh.pallipadi@intel.com> Reviewed-by: Randy Dunlap <randy.dunlap@oracle.com> Signed-off-by: Len Brown <len.brown@intel.com>

cpuidle: Add Documentation
Documentation for cpuidle infrastructure. (resend) Signed-off-by: Venkatesh Pallipadi <venkatesh.pallipadi@intel.com> Reviewed-by: Randy Dunlap <randy.dunlap@oracle.com> Signed-off-by: Len Brown <len.brown@intel.com>
Venkatesh Pallipadi · Len Brown
1 parent 4fcb2fcd4d
Showing 5 changed files with 164 additions and 0 deletions Side-by-side Diff
Documentation/00-INDEX
Documentation/cpuidle/core.txt
Documentation/cpuidle/driver.txt
Documentation/cpuidle/governor.txt
Documentation/cpuidle/sysfs.txt
@@ -109,6 +109,8 @@
 	- document describing CPU hotplug support in the Linux kernel.
 cpu-load.txt
 	- document describing how CPU load statistics are collected.
+cpuidle/
+	- info on CPU_IDLE, CPU idle state management subsystem.
 cpusets.txt
 	- documents the cpusets feature; assign CPUs and Mem to a set of tasks.
 cputopology.txt
+
+		Supporting multiple CPU idle levels in kernel
+
+				cpuidle
+
+General Information:
+
+Various CPUs today support multiple idle levels that are differentiated
+by varying exit latencies and power consumption during idle.
+cpuidle is a generic in-kernel infrastructure that separates
+idle policy (governor) from idle mechanism (driver) and provides a
+standardized infrastructure to support independent development of
+governors and drivers.
+
+cpuidle resides under drivers/cpuidle.
+
+Boot options:
+"cpuidle_sysfs_switch"
+enables current_governor interface in /sys/devices/system/cpu/cpuidle/,
+which can be used to switch governors at run time. This boot option
+is meant for developer testing only. In normal usage, kernel picks the
+best governor based on governor ratings.
+SEE ALSO: sysfs.txt in this directory.
+
+
+		Supporting multiple CPU idle levels in kernel
+
+				cpuidle drivers
+
+
+
+
+cpuidle driver hooks into the cpuidle infrastructure and handles the
+architecture/platform dependent part of CPU idle states. Driver
+provides the platform idle state detection capability and also
+has mechanisms in place to support actual entry-exit into CPU idle states.
+
+cpuidle driver initializes the cpuidle_device structure for each CPU device
+and registers with cpuidle using cpuidle_register_device.
+
+It can also support the dynamic changes (like battery <-> AC), by using
+cpuidle_pause_and_lock, cpuidle_disable_device and cpuidle_enable_device,
+cpuidle_resume_and_unlock.
+
+Interfaces:
+extern int cpuidle_register_driver(struct cpuidle_driver *drv);
+extern void cpuidle_unregister_driver(struct cpuidle_driver *drv);
+extern int cpuidle_register_device(struct cpuidle_device *dev);
+extern void cpuidle_unregister_device(struct cpuidle_device *dev);
+
+extern void cpuidle_pause_and_lock(void);
+extern void cpuidle_resume_and_unlock(void);
+extern int cpuidle_enable_device(struct cpuidle_device *dev);
+extern void cpuidle_disable_device(struct cpuidle_device *dev);
+
+
+
+		Supporting multiple CPU idle levels in kernel
+
+				cpuidle governors
+
+
+
+
+cpuidle governor is policy routine that decides what idle state to enter at
+any given time. cpuidle core uses different callbacks to the governor.
+
+* enable() to enable governor for a particular device
+* disable() to disable governor for a particular device
+* select() to select an idle state to enter
+* reflect() called after returning from the idle state, which can be used
+  by the governor for some record keeping.
+
+More than one governor can be registered at the same time and
+users can switch between drivers using /sysfs interface (when enabled).
+More than one governor part is supported for developers to easily experiment
+with different governors. By default, most optimal governor based on your
+kernel configuration and platform will be selected by cpuidle.
+
+Interfaces:
+extern int cpuidle_register_governor(struct cpuidle_governor *gov);
+extern void cpuidle_unregister_governor(struct cpuidle_governor *gov);
+struct cpuidle_governor
+
+
+		Supporting multiple CPU idle levels in kernel
+
+				cpuidle sysfs
+
+System global cpuidle related information and tunables are under
+/sys/devices/system/cpu/cpuidle
+
+The current interfaces in this directory has self-explanatory names:
+* current_driver
+* current_governor_ro
+
+With cpuidle_sysfs_switch boot option (meant for developer testing)
+following objects are visible instead.
+* current_driver
+* available_governors
+* current_governor
+In this case users can switch the governor at run time by writing
+to current_governor.
+
+
+Per logical CPU specific cpuidle information are under
+/sys/devices/system/cpu/cpuX/cpuidle
+for each online cpu X
+
+--------------------------------------------------------------------------------
+# ls -lR /sys/devices/system/cpu/cpu0/cpuidle/
+/sys/devices/system/cpu/cpu0/cpuidle/:
+total 0
+drwxr-xr-x 2 root root 0 Feb  8 10:42 state0
+drwxr-xr-x 2 root root 0 Feb  8 10:42 state1
+drwxr-xr-x 2 root root 0 Feb  8 10:42 state2
+drwxr-xr-x 2 root root 0 Feb  8 10:42 state3
+
+/sys/devices/system/cpu/cpu0/cpuidle/state0:
+total 0
+-r--r--r-- 1 root root 4096 Feb  8 10:42 desc
+-r--r--r-- 1 root root 4096 Feb  8 10:42 latency
+-r--r--r-- 1 root root 4096 Feb  8 10:42 name
+-r--r--r-- 1 root root 4096 Feb  8 10:42 power
+-r--r--r-- 1 root root 4096 Feb  8 10:42 time
+-r--r--r-- 1 root root 4096 Feb  8 10:42 usage
+
+/sys/devices/system/cpu/cpu0/cpuidle/state1:
+total 0
+-r--r--r-- 1 root root 4096 Feb  8 10:42 desc
+-r--r--r-- 1 root root 4096 Feb  8 10:42 latency
+-r--r--r-- 1 root root 4096 Feb  8 10:42 name
+-r--r--r-- 1 root root 4096 Feb  8 10:42 power
+-r--r--r-- 1 root root 4096 Feb  8 10:42 time
+-r--r--r-- 1 root root 4096 Feb  8 10:42 usage
+
+/sys/devices/system/cpu/cpu0/cpuidle/state2:
+total 0
+-r--r--r-- 1 root root 4096 Feb  8 10:42 desc
+-r--r--r-- 1 root root 4096 Feb  8 10:42 latency
+-r--r--r-- 1 root root 4096 Feb  8 10:42 name
+-r--r--r-- 1 root root 4096 Feb  8 10:42 power
+-r--r--r-- 1 root root 4096 Feb  8 10:42 time
+-r--r--r-- 1 root root 4096 Feb  8 10:42 usage
+
+/sys/devices/system/cpu/cpu0/cpuidle/state3:
+total 0
+-r--r--r-- 1 root root 4096 Feb  8 10:42 desc
+-r--r--r-- 1 root root 4096 Feb  8 10:42 latency
+-r--r--r-- 1 root root 4096 Feb  8 10:42 name
+-r--r--r-- 1 root root 4096 Feb  8 10:42 power
+-r--r--r-- 1 root root 4096 Feb  8 10:42 time
+-r--r--r-- 1 root root 4096 Feb  8 10:42 usage
+--------------------------------------------------------------------------------
+
+
+* desc : Small description about the idle state (string)
+* latency : Latency to exit out of this idle state (in microseconds)
+* name : Name of the idle state (string)
+* power : Power consumed while in this idle state (in milliwatts)
+* time : Total time spent in this idle state (in microseconds)
+* usage : Number of times this state was entered (count)
...	...	@@ -109,6 +109,8 @@
109	109	- document describing CPU hotplug support in the Linux kernel.
110	110	cpu-load.txt
111	111	- document describing how CPU load statistics are collected.
	112	+cpuidle/
	113	+ - info on CPU_IDLE, CPU idle state management subsystem.
112	114	cpusets.txt
113	115	- documents the cpusets feature; assign CPUs and Mem to a set of tasks.
114	116	cputopology.txt
	1	+
	2	+ Supporting multiple CPU idle levels in kernel
	3	+
	4	+ cpuidle
	5	+
	6	+General Information:
	7	+
	8	+Various CPUs today support multiple idle levels that are differentiated
	9	+by varying exit latencies and power consumption during idle.
	10	+cpuidle is a generic in-kernel infrastructure that separates
	11	+idle policy (governor) from idle mechanism (driver) and provides a
	12	+standardized infrastructure to support independent development of
	13	+governors and drivers.
	14	+
	15	+cpuidle resides under drivers/cpuidle.
	16	+
	17	+Boot options:
	18	+"cpuidle_sysfs_switch"
	19	+enables current_governor interface in /sys/devices/system/cpu/cpuidle/,
	20	+which can be used to switch governors at run time. This boot option
	21	+is meant for developer testing only. In normal usage, kernel picks the
	22	+best governor based on governor ratings.
	23	+SEE ALSO: sysfs.txt in this directory.
	1	+
	2	+
	3	+ Supporting multiple CPU idle levels in kernel
	4	+
	5	+ cpuidle drivers
	6	+
	7	+
	8	+
	9	+
	10	+cpuidle driver hooks into the cpuidle infrastructure and handles the
	11	+architecture/platform dependent part of CPU idle states. Driver
	12	+provides the platform idle state detection capability and also
	13	+has mechanisms in place to support actual entry-exit into CPU idle states.
	14	+
	15	+cpuidle driver initializes the cpuidle_device structure for each CPU device
	16	+and registers with cpuidle using cpuidle_register_device.
	17	+
	18	+It can also support the dynamic changes (like battery <-> AC), by using
	19	+cpuidle_pause_and_lock, cpuidle_disable_device and cpuidle_enable_device,
	20	+cpuidle_resume_and_unlock.
	21	+
	22	+Interfaces:
	23	+extern int cpuidle_register_driver(struct cpuidle_driver *drv);
	24	+extern void cpuidle_unregister_driver(struct cpuidle_driver *drv);
	25	+extern int cpuidle_register_device(struct cpuidle_device *dev);
	26	+extern void cpuidle_unregister_device(struct cpuidle_device *dev);
	27	+
	28	+extern void cpuidle_pause_and_lock(void);
	29	+extern void cpuidle_resume_and_unlock(void);
	30	+extern int cpuidle_enable_device(struct cpuidle_device *dev);
	31	+extern void cpuidle_disable_device(struct cpuidle_device *dev);
	1	+
	2	+
	3	+
	4	+ Supporting multiple CPU idle levels in kernel
	5	+
	6	+ cpuidle governors
	7	+
	8	+
	9	+
	10	+
	11	+cpuidle governor is policy routine that decides what idle state to enter at
	12	+any given time. cpuidle core uses different callbacks to the governor.
	13	+
	14	+* enable() to enable governor for a particular device
	15	+* disable() to disable governor for a particular device
	16	+* select() to select an idle state to enter
	17	+* reflect() called after returning from the idle state, which can be used
	18	+ by the governor for some record keeping.
	19	+
	20	+More than one governor can be registered at the same time and
	21	+users can switch between drivers using /sysfs interface (when enabled).
	22	+More than one governor part is supported for developers to easily experiment
	23	+with different governors. By default, most optimal governor based on your
	24	+kernel configuration and platform will be selected by cpuidle.
	25	+
	26	+Interfaces:
	27	+extern int cpuidle_register_governor(struct cpuidle_governor *gov);
	28	+extern void cpuidle_unregister_governor(struct cpuidle_governor *gov);
	29	+struct cpuidle_governor
	1	+
	2	+
	3	+ Supporting multiple CPU idle levels in kernel
	4	+
	5	+ cpuidle sysfs
	6	+
	7	+System global cpuidle related information and tunables are under
	8	+/sys/devices/system/cpu/cpuidle
	9	+
	10	+The current interfaces in this directory has self-explanatory names:
	11	+* current_driver
	12	+* current_governor_ro
	13	+
	14	+With cpuidle_sysfs_switch boot option (meant for developer testing)
	15	+following objects are visible instead.
	16	+* current_driver
	17	+* available_governors
	18	+* current_governor
	19	+In this case users can switch the governor at run time by writing
	20	+to current_governor.
	21	+
	22	+
	23	+Per logical CPU specific cpuidle information are under
	24	+/sys/devices/system/cpu/cpuX/cpuidle
	25	+for each online cpu X
	26	+
	27	+--------------------------------------------------------------------------------
	28	+# ls -lR /sys/devices/system/cpu/cpu0/cpuidle/
	29	+/sys/devices/system/cpu/cpu0/cpuidle/:
	30	+total 0
	31	+drwxr-xr-x 2 root root 0 Feb 8 10:42 state0
	32	+drwxr-xr-x 2 root root 0 Feb 8 10:42 state1
	33	+drwxr-xr-x 2 root root 0 Feb 8 10:42 state2
	34	+drwxr-xr-x 2 root root 0 Feb 8 10:42 state3
	35	+
	36	+/sys/devices/system/cpu/cpu0/cpuidle/state0:
	37	+total 0
	38	+-r--r--r-- 1 root root 4096 Feb 8 10:42 desc
	39	+-r--r--r-- 1 root root 4096 Feb 8 10:42 latency
	40	+-r--r--r-- 1 root root 4096 Feb 8 10:42 name
	41	+-r--r--r-- 1 root root 4096 Feb 8 10:42 power
	42	+-r--r--r-- 1 root root 4096 Feb 8 10:42 time
	43	+-r--r--r-- 1 root root 4096 Feb 8 10:42 usage
	44	+
	45	+/sys/devices/system/cpu/cpu0/cpuidle/state1:
	46	+total 0
	47	+-r--r--r-- 1 root root 4096 Feb 8 10:42 desc
	48	+-r--r--r-- 1 root root 4096 Feb 8 10:42 latency
	49	+-r--r--r-- 1 root root 4096 Feb 8 10:42 name
	50	+-r--r--r-- 1 root root 4096 Feb 8 10:42 power
	51	+-r--r--r-- 1 root root 4096 Feb 8 10:42 time
	52	+-r--r--r-- 1 root root 4096 Feb 8 10:42 usage
	53	+
	54	+/sys/devices/system/cpu/cpu0/cpuidle/state2:
	55	+total 0
	56	+-r--r--r-- 1 root root 4096 Feb 8 10:42 desc
	57	+-r--r--r-- 1 root root 4096 Feb 8 10:42 latency
	58	+-r--r--r-- 1 root root 4096 Feb 8 10:42 name
	59	+-r--r--r-- 1 root root 4096 Feb 8 10:42 power
	60	+-r--r--r-- 1 root root 4096 Feb 8 10:42 time
	61	+-r--r--r-- 1 root root 4096 Feb 8 10:42 usage
	62	+
	63	+/sys/devices/system/cpu/cpu0/cpuidle/state3:
	64	+total 0
	65	+-r--r--r-- 1 root root 4096 Feb 8 10:42 desc
	66	+-r--r--r-- 1 root root 4096 Feb 8 10:42 latency
	67	+-r--r--r-- 1 root root 4096 Feb 8 10:42 name
	68	+-r--r--r-- 1 root root 4096 Feb 8 10:42 power
	69	+-r--r--r-- 1 root root 4096 Feb 8 10:42 time
	70	+-r--r--r-- 1 root root 4096 Feb 8 10:42 usage
	71	+--------------------------------------------------------------------------------
	72	+
	73	+
	74	+* desc : Small description about the idle state (string)
	75	+* latency : Latency to exit out of this idle state (in microseconds)
	76	+* name : Name of the idle state (string)
	77	+* power : Power consumed while in this idle state (in milliwatts)
	78	+* time : Total time spent in this idle state (in microseconds)
	79	+* usage : Number of times this state was entered (count)