PM: Wrap documentation to fit in 80 columns

Wrap to 80 columns. No textual change except to correct some "it's" that should be "its".

Bjorn Helgaas committed 6 years ago

Commit 1992b661 parent af42d348 files · +81 −74Browse files

Unified · Split

8 files

Documentation/power/drivers-testing.rst +4 −3
Documentation/power/freezing-of-tasks.rst +19 −18
Documentation/power/opp.rst +17 −15
Documentation/power/pci.rst +14 −14
Documentation/power/pm_qos_interface.rst +13 −13
Documentation/power/runtime_pm.rst +2 −2
Documentation/power/suspend-and-cpuhotplug.rst +4 −3
Documentation/power/swsusp.rst +8 −6

Documentation/power/drivers-testing.rst+4−3

 d) Attempt to hibernate with the driver compiled directly into the kernel
    in the "reboot", "shutdown" and "platform" modes.
-e) Try the test modes of suspend (see: Documentation/power/basic-pm-debugging.rst,
+e) Try the test modes of suspend (see:
-   2).  [As far as the STR tests are concerned, it should not matter whether or
+   Documentation/power/basic-pm-debugging.rst, 2).  [As far as the STR tests are
-   not the driver is built as a module.]
+   concerned, it should not matter whether or not the driver is built as a
+   module.]
 f) Attempt to suspend to RAM using the s2ram tool with the driver loaded
    (see: Documentation/power/basic-pm-debugging.rst, 2).

Documentation/power/freezing-of-tasks.rst+19−18

@@ -215,30 +215,31 @@ VI. Are there any precautions to be taken to prevent freezing failures? · 214 unmodified lines
215		215
216	Yes, there are.	216	Yes, there are.
217		217
218	First of all, grabbing the 'system_transition_mutex' lock to mutually exclude a piece of code	218	First of all, grabbing the 'system_transition_mutex' lock to mutually exclude a
219	from system-wide sleep such as suspend/hibernation is not encouraged.	219	piece of code from system-wide sleep such as suspend/hibernation is not
220	If possible, that piece of code must instead hook onto the suspend/hibernation	220	encouraged. If possible, that piece of code must instead hook onto the
221	notifiers to achieve mutual exclusion. Look at the CPU-Hotplug code	221	suspend/hibernation notifiers to achieve mutual exclusion. Look at the
222	(kernel/cpu.c) for an example.	222	CPU-Hotplug code (kernel/cpu.c) for an example.
223		223
224	However, if that is not feasible, and grabbing 'system_transition_mutex' is deemed necessary,	224	However, if that is not feasible, and grabbing 'system_transition_mutex' is
225	it is strongly discouraged to directly call mutex_[un]lock(&system_transition_mutex) since	225	deemed necessary, it is strongly discouraged to directly call
226	that could lead to freezing failures, because if the suspend/hibernate code	226	mutex_[un]lock(&system_transition_mutex) since that could lead to freezing
227	successfully acquired the 'system_transition_mutex' lock, and hence that other entity failed	227	failures, because if the suspend/hibernate code successfully acquired the
228	to acquire the lock, then that task would get blocked in TASK_UNINTERRUPTIBLE	228	'system_transition_mutex' lock, and hence that other entity failed to acquire
229	state. As a consequence, the freezer would not be able to freeze that task,	229	the lock, then that task would get blocked in TASK_UNINTERRUPTIBLE state. As a
230	leading to freezing failure.	230	consequence, the freezer would not be able to freeze that task, leading to
		231	freezing failure.
231		232
232	However, the [un]lock_system_sleep() APIs are safe to use in this scenario,	233	However, the [un]lock_system_sleep() APIs are safe to use in this scenario,
233	since they ask the freezer to skip freezing this task, since it is anyway	234	since they ask the freezer to skip freezing this task, since it is anyway
234	"frozen enough" as it is blocked on 'system_transition_mutex', which will be released	235	"frozen enough" as it is blocked on 'system_transition_mutex', which will be
235	only after the entire suspend/hibernation sequence is complete.	236	released only after the entire suspend/hibernation sequence is complete. So, to
236	So, to summarize, use [un]lock_system_sleep() instead of directly using	237	summarize, use [un]lock_system_sleep() instead of directly using
237	mutex_[un]lock(&system_transition_mutex). That would prevent freezing failures.	238	mutex_[un]lock(&system_transition_mutex). That would prevent freezing failures.
238		239
239	V. Miscellaneous	240	V. Miscellaneous
240	================	241	================
241		242
242	/sys/power/pm_freeze_timeout controls how long it will cost at most to freeze	243	/sys/power/pm_freeze_timeout controls how long it will cost at most to freeze
243	all user space processes or all freezable kernel threads, in unit of millisecond.	244	all user space processes or all freezable kernel threads, in unit of
244	The default value is 20000, with range of unsigned integer.	245	millisecond. The default value is 20000, with range of unsigned integer.

Documentation/power/opp.rst+17−15

Documentation/power/pci.rst+14−14

Documentation/power/pm_qos_interface.rst+13−13

Documentation/power/runtime_pm.rst+2−2

@@ -268,8 +268,8 @@ defined in include/linux/pm.h: · 267 unmodified lines
268	`unsigned int runtime_auto;`	268	`unsigned int runtime_auto;`
269	- if set, indicates that the user space has allowed the device driver to	269	- if set, indicates that the user space has allowed the device driver to
270	power manage the device at run time via the /sys/devices/.../power/control	270	power manage the device at run time via the /sys/devices/.../power/control
271	`interface;` it may only be modified with the help of the pm_runtime_allow()	271	`interface;` it may only be modified with the help of the
272	and pm_runtime_forbid() helper functions	272	pm_runtime_allow() and pm_runtime_forbid() helper functions
273		273
274	`unsigned int no_callbacks;`	274	`unsigned int no_callbacks;`
275	- indicates that the device does not use the runtime PM callbacks (see	275	- indicates that the device does not use the runtime PM callbacks (see

Documentation/power/suspend-and-cpuhotplug.rst+4−3

 * Release system_transition_mutex lock.
-It is to be noted here that the system_transition_mutex lock is acquired at the very
+It is to be noted here that the system_transition_mutex lock is acquired at the
-beginning, when we are just starting out to suspend, and then released only
+very beginning, when we are just starting out to suspend, and then released only
 after the entire cycle is complete (i.e., suspend + resume).
 ::
 - kernel/power/process.c : freeze_processes(), thaw_processes()
 - kernel/power/suspend.c : suspend_prepare(), suspend_enter(), suspend_finish()
-- kernel/cpu.c: cpu_[up|down](), _cpu_[up|down](), [disable|enable]_nonboot_cpus()
+- kernel/cpu.c: cpu_[up|down](), _cpu_[up|down](),
+  [disable|enable]_nonboot_cpus()

Documentation/power/swsusp.rst+8−6

   echo 1 > /proc/acpi/sleep       # for standby
   echo 2 > /proc/acpi/sleep       # for suspend to ram
-  echo 3 > /proc/acpi/sleep       # for suspend to ram, but with more power conservative
+  echo 3 > /proc/acpi/sleep       # for suspend to ram, but with more power
+                                  # conservative
   echo 4 > /proc/acpi/sleep       # for suspend to disk
   echo 5 > /proc/acpi/sleep       # for shutdown unfriendly the system
 A:
   The freezing of tasks is a mechanism by which user space processes and some
-  kernel threads are controlled during hibernation or system-wide suspend (on some
+  kernel threads are controlled during hibernation or system-wide suspend (on
-  architectures).  See freezing-of-tasks.txt for details.
+  some architectures).  See freezing-of-tasks.txt for details.
 Q:
   What is the difference between "platform" and "shutdown"?
       suspend(PMSG_FREEZE): devices are frozen so that they don't interfere
       with state snapshot
-      state snapshot: copy of whole used memory is taken with interrupts disabled
+      state snapshot: copy of whole used memory is taken with interrupts
+      disabled
       resume(): devices are woken up so that we can write image to swap
 A:
   Generally, yes, you can.  However, it requires you to use the "resume=" and
-  "resume_offset=" kernel command line parameters, so the resume from a swap file
+  "resume_offset=" kernel command line parameters, so the resume from a swap
-  cannot be initiated from an initrd or initramfs image.  See
+  file cannot be initiated from an initrd or initramfs image.  See
   swsusp-and-swap-files.txt for details.
 Q:

PM: Wrap documentation to fit in 80 columns

Keyboard shortcuts

General

Issues and pull requests

Issues, pull requests and Inbox

Repository code

@@ -73,19 +73,21 @@ factors. Example usage: Thermal management or other exceptional situations where · 72 unmodified lines
73	SoC framework might choose to disable a higher frequency OPP to safely continue	73	SoC framework might choose to disable a higher frequency OPP to safely continue
74	operations until that OPP could be re-enabled if possible.	74	operations until that OPP could be re-enabled if possible.
75		75
76	OPP library facilitates this concept in it's implementation. The following	76	OPP library facilitates this concept in its implementation. The following
77	operational functions operate only on available opps:	77	operational functions operate only on available opps:
78	opp_find_freq_{ceil, floor}, dev_pm_opp_get_voltage, dev_pm_opp_get_freq, dev_pm_opp_get_opp_count	78	opp_find_freq_{ceil, floor}, dev_pm_opp_get_voltage, dev_pm_opp_get_freq,
		79	dev_pm_opp_get_opp_count
79		80
80	dev_pm_opp_find_freq_exact is meant to be used to find the opp pointer which can then	81	dev_pm_opp_find_freq_exact is meant to be used to find the opp pointer
81	be used for dev_pm_opp_enable/disable functions to make an opp available as required.	82	which can then be used for dev_pm_opp_enable/disable functions to make an
		83	opp available as required.
82		84
83	WARNING: Users of OPP library should refresh their availability count using	85	WARNING: Users of OPP library should refresh their availability count using
84	get_opp_count if dev_pm_opp_enable/disable functions are invoked for a device, the	86	get_opp_count if dev_pm_opp_enable/disable functions are invoked for a
85	exact mechanism to trigger these or the notification mechanism to other	87	device, the exact mechanism to trigger these or the notification mechanism
86	dependent subsystems such as cpufreq are left to the discretion of the SoC	88	to other dependent subsystems such as cpufreq are left to the discretion of
87	specific framework which uses the OPP library. Similar care needs to be taken	89	the SoC specific framework which uses the OPP library. Similar care needs
88	care to refresh the cpufreq table in cases of these operations.	90	to be taken care to refresh the cpufreq table in cases of these operations.
89		91
90	2. Initial OPP List Registration	92	2. Initial OPP List Registration
91	================================	93	================================
@@ -99,11 +101,11 @@ OPPs dynamically using the dev_pm_opp_enable / disable functions. · 7 unmodified lines
99	dev_pm_opp_add	101	dev_pm_opp_add
100	Add a new OPP for a specific domain represented by the device pointer.	102	Add a new OPP for a specific domain represented by the device pointer.
101	The OPP is defined using the frequency and voltage. Once added, the OPP	103	The OPP is defined using the frequency and voltage. Once added, the OPP
102	is assumed to be available and control of it's availability can be done	104	is assumed to be available and control of its availability can be done
103	with the dev_pm_opp_enable/disable functions. OPP library internally stores	105	with the dev_pm_opp_enable/disable functions. OPP library
104	and manages this information in the opp struct. This function may be	106	internally stores and manages this information in the opp struct.
105	used by SoC framework to define a optimal list as per the demands of	107	This function may be used by SoC framework to define a optimal list
106	SoC usage environment.	108	as per the demands of SoC usage environment.
107		109
108	WARNING:	110	WARNING:
109	Do not use this function in interrupt context.	111	Do not use this function in interrupt context.
@@ -354,7 +356,7 @@ struct dev_pm_opp · 244 unmodified lines
354		356
355	struct device	357	struct device
356	This is used to identify a domain to the OPP layer. The	358	This is used to identify a domain to the OPP layer. The
357	nature of the device and it's implementation is left to the user of	359	nature of the device and its implementation is left to the user of
358	OPP library such as the SoC framework.	360	OPP library such as the SoC framework.
359		361
360	Overall, in a simplistic view, the data structure operations is represented as	362	Overall, in a simplistic view, the data structure operations is represented as

@@ -426,12 +426,12 @@ pm->runtime_idle() callback. · 425 unmodified lines
426	2.4. System-Wide Power Transitions	426	2.4. System-Wide Power Transitions
427	----------------------------------	427	----------------------------------
428	There are a few different types of system-wide power transitions, described in	428	There are a few different types of system-wide power transitions, described in
429	Documentation/driver-api/pm/devices.rst. Each of them requires devices to be handled	429	Documentation/driver-api/pm/devices.rst. Each of them requires devices to be
430	in a specific way and the PM core executes subsystem-level power management	430	handled in a specific way and the PM core executes subsystem-level power
431	callbacks for this purpose. They are executed in phases such that each phase	431	management callbacks for this purpose. They are executed in phases such that
432	involves executing the same subsystem-level callback for every device belonging	432	each phase involves executing the same subsystem-level callback for every device
433	to the given subsystem before the next phase begins. These phases always run	433	belonging to the given subsystem before the next phase begins. These phases
434	after tasks have been frozen.	434	always run after tasks have been frozen.
435		435
436	2.4.1. System Suspend	436	2.4.1. System Suspend
437	^^^^^^^^^^^^^^^^^^^^^	437	^^^^^^^^^^^^^^^^^^^^^
@@ -636,12 +636,12 @@ System restore requires a hibernation image to be loaded into memory and the · 198 unmodified lines
636	pre-hibernation memory contents to be restored before the pre-hibernation system	636	pre-hibernation memory contents to be restored before the pre-hibernation system
637	activity can be resumed.	637	activity can be resumed.
638		638
639	As described in Documentation/driver-api/pm/devices.rst, the hibernation image is loaded	639	As described in Documentation/driver-api/pm/devices.rst, the hibernation image
640	into memory by a fresh instance of the kernel, called the boot kernel, which in	640	is loaded into memory by a fresh instance of the kernel, called the boot kernel,
641	turn is loaded and run by a boot loader in the usual way. After the boot kernel	641	which in turn is loaded and run by a boot loader in the usual way. After the
642	has loaded the image, it needs to replace its own code and data with the code	642	boot kernel has loaded the image, it needs to replace its own code and data with
643	and data of the "hibernated" kernel stored within the image, called the image	643	the code and data of the "hibernated" kernel stored within the image, called the
644	kernel. For this purpose all devices are frozen just like before creating	644	image kernel. For this purpose all devices are frozen just like before creating
645	the image during hibernation, in the	645	the image during hibernation, in the
646		646
647	prepare, freeze, freeze_noirq	647	prepare, freeze, freeze_noirq
@@ -691,8 +691,8 @@ controlling the runtime power management of their devices. · 43 unmodified lines
691		691
692	At the time of this writing there are two ways to define power management	692	At the time of this writing there are two ways to define power management
693	callbacks for a PCI device driver, the recommended one, based on using a	693	callbacks for a PCI device driver, the recommended one, based on using a
694	dev_pm_ops structure described in Documentation/driver-api/pm/devices.rst, and the	694	dev_pm_ops structure described in Documentation/driver-api/pm/devices.rst, and
695	"legacy" one, in which the .suspend(), .suspend_late(), .resume_early(), and	695	the "legacy" one, in which the .suspend(), .suspend_late(), .resume_early(), and
696	.resume() callbacks from struct pci_driver are used. The legacy approach,	696	.resume() callbacks from struct pci_driver are used. The legacy approach,
697	however, doesn't allow one to define runtime power management callbacks and is	697	however, doesn't allow one to define runtime power management callbacks and is
698	not really suitable for any new drivers. Therefore it is not covered by this	698	not really suitable for any new drivers. Therefore it is not covered by this

@@ -8,8 +8,8 @@ one of the parameters. · 7 unmodified lines
8		8
9	Two different PM QoS frameworks are available:	9	Two different PM QoS frameworks are available:
10	1. PM QoS classes for cpu_dma_latency	10	1. PM QoS classes for cpu_dma_latency
11	2. the per-device PM QoS framework provides the API to manage the per-device latency	11	2. The per-device PM QoS framework provides the API to manage the
12	constraints and PM QoS flags.	12	per-device latency constraints and PM QoS flags.
13		13
14	Each parameters have defined units:	14	Each parameters have defined units:
15		15
@@ -47,14 +47,14 @@ void pm_qos_add_request(handle, param_class, target_value): · 31 unmodified lines
47	pm_qos API functions.	47	pm_qos API functions.
48		48
49	void pm_qos_update_request(handle, new_target_value):	49	void pm_qos_update_request(handle, new_target_value):
50	Will update the list element pointed to by the handle with the new target value	50	Will update the list element pointed to by the handle with the new target
51	and recompute the new aggregated target, calling the notification tree if the	51	value and recompute the new aggregated target, calling the notification tree
52	target is changed.	52	if the target is changed.
53		53
54	void pm_qos_remove_request(handle):	54	void pm_qos_remove_request(handle):
55	Will remove the element. After removal it will update the aggregate target and	55	Will remove the element. After removal it will update the aggregate target
56	call the notification tree if the target was changed as a result of removing	56	and call the notification tree if the target was changed as a result of
57	the request.	57	removing the request.
58		58
59	int pm_qos_request(param_class):	59	int pm_qos_request(param_class):
60	Returns the aggregated value for a given PM QoS class.	60	Returns the aggregated value for a given PM QoS class.
@@ -167,9 +167,9 @@ int dev_pm_qos_expose_flags(device, value) · 106 unmodified lines
167	change the value of the PM_QOS_FLAG_NO_POWER_OFF flag.	167	change the value of the PM_QOS_FLAG_NO_POWER_OFF flag.
168		168
169	void dev_pm_qos_hide_flags(device)	169	void dev_pm_qos_hide_flags(device)
170	Drop the request added by dev_pm_qos_expose_flags() from the device's PM QoS list	170	Drop the request added by dev_pm_qos_expose_flags() from the device's PM QoS
171	of flags and remove sysfs attribute pm_qos_no_power_off from the device's power	171	list of flags and remove sysfs attribute pm_qos_no_power_off from the device's
172	directory.	172	power directory.
173		173
174	Notification mechanisms:	174	Notification mechanisms:
175		175
@@ -179,8 +179,8 @@ int dev_pm_qos_add_notifier(device, notifier, type): · 3 unmodified lines
179	Adds a notification callback function for the device for a particular request	179	Adds a notification callback function for the device for a particular request
180	type.	180	type.
181		181
182	The callback is called when the aggregated value of the device constraints list	182	The callback is called when the aggregated value of the device constraints
183	is changed.	183	list is changed.
184		184
185	int dev_pm_qos_remove_notifier(device, notifier, type):	185	int dev_pm_qos_remove_notifier(device, notifier, type):
186	Removes the notification callback function for the device.	186	Removes the notification callback function for the device.