runtime: Add more steps to the lifecycle docs

runtime-config.md

@@ -12,27 +12,28 @@ Presently there are `Prestart`, `Poststart` and `Poststop`.
 Hooks allow one to run code before/after various lifecycle events of the container.
 Hooks MUST be called in the listed order.
 The state of the container is passed to the hooks over stdin, so the hooks could get the information they need to do their work.
+All hooks execute in the host environment (e.g. the same namespace, cgroups, etc. that apply to the host process).
 
 Hook paths are absolute and are executed from the host's filesystem.
 
 ### Pre-start
 
-The pre-start hooks are called after the container process is spawned, but before the user supplied command is executed.
+The pre-start hooks are called [after the container process is spawned, but before the user supplied command is executed](runtime.md#typical-lifecycle).
 They are called after the container namespaces are created on Linux, so they provide an opportunity to customize the container.
 In Linux, for e.g., the network namespace could be configured in this hook.
 
-If a hook returns a non-zero exit code, then an error including the exit code and the stderr is returned to the caller and the container is torn down.
+If a hook returns a non-zero exit code, [then an error including the exit code and the stderr is returned to the caller and the container is torn down](runtime.md#typical-lifecycle).
 
 ### Post-start
 
-The post-start hooks are called after the user process is started.
+The post-start hooks are called [after the user process is started](runtime.md#typical-lifecycle).
 For example this hook can notify user that real process is spawned.
 
 If a hook returns a non-zero exit code, then an error is logged and the remaining hooks are executed.
 
 ### Post-stop
 
-The post-stop hooks are called after the container process is stopped.
+The post-stop hooks are called [after the container process is stopped](runtime.md#typical-lifecycle).
 Cleanup or debugging could be performed in such a hook.
 If a hook returns a non-zero exit code, then an error is logged and the remaining hooks are executed.
 

runtime.md

@@ -29,24 +29,60 @@ The root directory to the bundle is provided in the state so that consumers can
 }
 ```
 
-## Lifecycle
+## Typical lifecycle
+
+A typical lifecyle progresses like this:
+
+1. There is no container
+2. A user tells the runtime to start a container and launch a process inside it
+3. The runtime [creates the container](#create)
+4. The runtime executes any [pre-start hooks](runtime-config.md#pre-start)
+5. The runtime [executes the container process](#start-process)
+6. The container process is running
+7. The runtime executes any [post-start hooks](runtime-config.md#post-start)
+8. A user tells the runtime to send a termination signal to the container process
+9. The runtime [sends a termination signal to the container process](#stop-process)
+10. The container process exits
+11. The runtime [terminates any other processes in the container](#stop-process)
+12. The runtime executes any [post-stop hooks](runtime-config.md#post-stop)
+13. The runtime [removes the container](#cleanup)
+
+With steps 7 and 8, the user is explicitly stopping the container process (via the runtime), but it's also possible that the container process could exit for other reasons.
+In that case we skip directly from 6 to [10](#stop-process), skipping any post-start hooks that hadn't been launched and terminating any in-progress post-start hook.
+
+Failure in a pre-start hook or other setup task can cause a jump straight to [12](runtime-config.md#post-stop).
 
 ### Create
 
-Creates the container: file system, namespaces, cgroups, capabilities.
+Create the container: file system, namespaces, cgroups, capabilities, etc.
+The invoked process forks, with one branch that stays in the host namespace and another that enters the container.
+The host process carries out all container setup actions, and continues running for the life of the container so it can perform teardown after the container process exits.
+The container process changes users and drops privileges in preparation for the container process start.
+At this point, the host process writes the [`state.json`](#state) file with the host-side version of the container-process's PID (the container process may be in a PID namespace).
 
 ### Start (process)
 
-Runs a process in a container.
-Can be invoked several times.
+After the pre-start hooks complete, the host process signals the container process to execute the runtime.
+The runtime execs the process defined in `config.json`'s [**`process`** attribute](config.md#process-configuration).
+On Linux hosts, some information for this execution may come from outside the `config.json` and `runtime.json` specifications.
+See the [Linux-specific notes for details](runtime-linux.md#file-descriptors).
 
 ### Stop (process)
 
-Not sure we need that from runc cli.
-Process is killed from the outside.
+Send a termination signal to the container process (can optionally send other signals to the container process, e.g. a kill signal).
+When the process exits, the host process collects it's exit status to return as its own exit status.
+If there are any remaining processes in the container's cgroup (and [we only support unified-hierarchies](runtime-config-linux.md#control-groups)), the host process kills and reaps them.
+
+### Cleanup
+
+The host process removes the [`state.json`](#state) file and the container: unmounting file systems, removing namespaces, etc.
+This is the inverse of create.
+The host process then exits with the container processes's exit status.
 
-This event needs to be captured by runc to run onstop event handlers.
+## Joining existing containers
 
-## Hooks
+Joining an existing container looks just like the usual workflow, except that the container process [joins the target container](runtime-config-linux.md#control-groups) at the beginning of step 3.
+It can then, depending on its configuration, continue to create an additional child cgroup underneath the one it joined.
 
-See [runtime configuration for hooks](./runtime-config.md)
+When exiting, the reaping logic in the [stop phase](#stop-process) is the same.
+If the container process created a child cgroup, all other processes in that child cgroup are reaped, but no other processes in the joined cgroup (which the container process did not create) are reaped.