Documentation: PM: Adjust freezing-of-tasks.rst to the freezer changes

The core freezer logic has been modified by commit f5d39b0208
("freezer,sched: Rewrite core freezer logic"), so adjust the
documentation to reflect the new code. The main changes include:

 - Drop references to PF_FROZEN and PF_FREEZER_SKIP
 - Describe TASK_FROZEN, TASK_FREEZABLE and __TASK_FREEZABLE_UNSAFE
 - Replace system_freezing_cnt with freezer_active
 - Use a different example for the loop of a freezable kernel thread,
   since the old code is gone gone

Signed-off-by: Kevin Hao <haokexin@gmail.com>
[ rjw: Subject and changelog edits, doc text adjustments ]
Signed-off-by: Rafael J. Wysocki <rafael.j.wysocki@intel.com>

Documentation/power/freezing-of-tasks.rst

@@ -14,27 +14,28 @@ architectures).
 II. How does it work?
 =====================
 
-There are three per-task flags used for that, PF_NOFREEZE, PF_FROZEN
+There is one per-task flag (PF_NOFREEZE) and three per-task states
-and PF_FREEZER_SKIP (the last one is auxiliary).  The tasks that have
+(TASK_FROZEN, TASK_FREEZABLE and __TASK_FREEZABLE_UNSAFE) used for that.
-PF_NOFREEZE unset (all user space processes and some kernel threads) are
+The tasks that have PF_NOFREEZE unset (all user space tasks and some kernel
-regarded as 'freezable' and treated in a special way before the system enters a
+threads) are regarded as 'freezable' and treated in a special way before the
-suspend state as well as before a hibernation image is created (in what follows
+system enters a sleep state as well as before a hibernation image is created
-we only consider hibernation, but the description also applies to suspend).
+(hibernation is directly covered by what follows, but the description applies
+to system-wide suspend too).
 
 Namely, as the first step of the hibernation procedure the function
 freeze_processes() (defined in kernel/power/process.c) is called.  A system-wide
-variable system_freezing_cnt (as opposed to a per-task flag) is used to indicate
+static key freezer_active (as opposed to a per-task flag or state) is used to
-whether the system is to undergo a freezing operation. And freeze_processes()
+indicate whether the system is to undergo a freezing operation. And
-sets this variable.  After this, it executes try_to_freeze_tasks() that sends a
+freeze_processes() sets this static key.  After this, it executes
-fake signal to all user space processes, and wakes up all the kernel threads.
+try_to_freeze_tasks() that sends a fake signal to all user space processes, and
-All freezable tasks must react to that by calling try_to_freeze(), which
+wakes up all the kernel threads. All freezable tasks must react to that by
-results in a call to __refrigerator() (defined in kernel/freezer.c), which sets
+calling try_to_freeze(), which results in a call to __refrigerator() (defined
-the task's PF_FROZEN flag, changes its state to TASK_UNINTERRUPTIBLE and makes
+in kernel/freezer.c), which changes the task's state to TASK_FROZEN, and makes
-it loop until PF_FROZEN is cleared for it. Then, we say that the task is
+it loop until it is woken by an explicit TASK_FROZEN wakeup. Then, that task
-'frozen' and therefore the set of functions handling this mechanism is referred
+is regarded as 'frozen' and so the set of functions handling this mechanism is
-to as 'the freezer' (these functions are defined in kernel/power/process.c,
+referred to as 'the freezer' (these functions are defined in
-kernel/freezer.c & include/linux/freezer.h). User space processes are generally
+kernel/power/process.c, kernel/freezer.c & include/linux/freezer.h). User space
-frozen before kernel threads.
+tasks are generally frozen before kernel threads.
 
 __refrigerator() must not be called directly.  Instead, use the
 try_to_freeze() function (defined in include/linux/freezer.h), that checks
@@ -43,31 +44,40 @@ if the task is to be frozen and makes the task enter __refrigerator().
 For user space processes try_to_freeze() is called automatically from the
 signal-handling code, but the freezable kernel threads need to call it
 explicitly in suitable places or use the wait_event_freezable() or
-wait_event_freezable_timeout() macros (defined in include/linux/freezer.h)
+wait_event_freezable_timeout() macros (defined in include/linux/wait.h)
-that combine interruptible sleep with checking if the task is to be frozen and
+that put the task to sleep (TASK_INTERRUPTIBLE) or freeze it (TASK_FROZEN) if
-calling try_to_freeze().  The main loop of a freezable kernel thread may look
+freezer_active is set. The main loop of a freezable kernel thread may look
 like the following one::
 
 	set_freezable();
-	do {
-		hub_events();
-		wait_event_freezable(khubd_wait,
-				!list_empty(&hub_event_list) ||
-				kthread_should_stop());
-	} while (!kthread_should_stop() || !list_empty(&hub_event_list));
 
-(from drivers/usb/core/hub.c::hub_thread()).
+	while (true) {
+		struct task_struct *tsk = NULL;
 
-If a freezable kernel thread fails to call try_to_freeze() after the freezer has
+		wait_event_freezable(oom_reaper_wait, oom_reaper_list != NULL);
-initiated a freezing operation, the freezing of tasks will fail and the entire
+		spin_lock_irq(&oom_reaper_lock);
-hibernation operation will be cancelled.  For this reason, freezable kernel
+		if (oom_reaper_list != NULL) {
-threads must call try_to_freeze() somewhere or use one of the
+			tsk = oom_reaper_list;
+			oom_reaper_list = tsk->oom_reaper_list;
+		}
+		spin_unlock_irq(&oom_reaper_lock);
+
+		if (tsk)
+			oom_reap_task(tsk);
+	}
+
+(from mm/oom_kill.c::oom_reaper()).
+
+If a freezable kernel thread is not put to the frozen state after the freezer
+has initiated a freezing operation, the freezing of tasks will fail and the
+entire system-wide transition will be cancelled.  For this reason, freezable
+kernel threads must call try_to_freeze() somewhere or use one of the
 wait_event_freezable() and wait_event_freezable_timeout() macros.
 
 After the system memory state has been restored from a hibernation image and
 devices have been reinitialized, the function thaw_processes() is called in
-order to clear the PF_FROZEN flag for each frozen task.  Then, the tasks that
+order to wake up each frozen task.  Then, the tasks that have been frozen leave
-have been frozen leave __refrigerator() and continue running.
+__refrigerator() and continue running.
 
 
 Rationale behind the functions dealing with freezing and thawing of tasks
@@ -96,7 +106,8 @@ III. Which kernel threads are freezable?
 Kernel threads are not freezable by default.  However, a kernel thread may clear
 PF_NOFREEZE for itself by calling set_freezable() (the resetting of PF_NOFREEZE
 directly is not allowed).  From this point it is regarded as freezable
-and must call try_to_freeze() in a suitable place.
+and must call try_to_freeze() or variants of wait_event_freezable() in a
+suitable place.
 
 IV. Why do we do that?
 ======================