restore: Write comments about stages

Describe what the tasks do during restore and what the
expectations at the sync points are.
Signed-off-by: Pavel Emelyanov <xemul@virtuozzo.com>
Signed-off-by: Andrei Vagin <avagin@virtuozzo.com>

criu/include/restorer.h

@@ -200,17 +200,47 @@ static inline unsigned long restorer_stack(struct restore_mem_zone *mz)
 }
 
 enum {
+	/*
+	 * Restore stages. The stage is started by criu process, then
+	 * confirmed by all tasks involved in it. Then criu does some
+	 * actions and starts the next stage.
+	 *
+	 * The first stated stage is CR_STATE_ROOT_TASK which is started
+	 * right before calling fork_with_pid() for the root_item.
+	 */
 	CR_STATE_FAIL		= -1,
-	CR_STATE_ROOT_TASK	= 0, /* is used for executing "setup-namespace" scripts */
 	/*
-	 * Need to wait a mount namespace which
-	 * will be used to clean up remap files.
+	 * Root task is created and does some pre-checks.
+	 * After the stage ACT_SETUP_NS scripts are performed.
+	 */
+	CR_STATE_ROOT_TASK	= 0,
+	/*
+	 * The prepare_namespace() is called.
+	 * After the stage criu opens root task's mntns and
+	 * calls ACT_POST_SETUP_NS scripts.
 	 */
 	CR_STATE_PREPARE_NAMESPACES,
+	/*
+	 * All tasks fork and call open_transport_socket().
+	 * Stage is needed to make sure they all have the socket.
+	 */
 	CR_STATE_FORKING,
+	/*
+	 * Main restore stage. By the end of it all tasks are
+	 * almost ready and what's left is:
+	 *   pick up zombies and helpers
+	 *   restore sigchild handlers used to detect restore errors
+	 *   restore credentials
+	 */
 	CR_STATE_RESTORE,
+	/*
+	 * Tasks restore sigchild handlers.
+	 * Stage is needed to synchronize the change in error
+	 * propagation via sigchild.
+	 */
 	CR_STATE_RESTORE_SIGCHLD,
 	/*
+	 * Final stage.
 	 * For security reason processes can be resumed only when all
 	 * credentials are restored. Otherwise someone can attach to a
 	 * process, which are not restored credentials yet and execute