doc: Add documentation on how to use the 'perf' utility.

Signed-off-by: Rolf Neugebauer <rolf.neugebauer@docker.com>

docs/kernel-perf.md

@@ -0,0 +1,44 @@
+# Using the perf utility with LinuxKit
+
+The `perf` utility is a standard Linux tool to access performance
+counters, trace events and access various other kernel internals for
+performance analysis.
+
+The `perf` utility needs to matched be with the kernel. For recent
+kernel build, LinuxKit provides a `linuxkit/kernel-perf` package with
+a matching tag for each kernel under `linuxkit/kernel`.
+
+There are a number of ways to use `linuxkit/kernel-perf` package:
+
+1. Add it to the `init` section. This adds `/usr/bin/perf` to the
+  systems' root filesystem. From there it can be
+  - bind mounted into your container
+  - accessed via `/proc/1/root/usr/bin/perf` from with in the `getty`
+    or `ssh` container.
+2. Add it to you package. If you have a custom package already, you
+   can add `linuxkit/kernel-perf` as another stage in your package and
+   then copy `/usr/bin/perf` into the final stage.
+
+The first method is preferable since you need to match with the kernel
+package tag and that is typically defined in the YAML file. I
+typically don't add the bind mount since this requires further
+modification and simply create a symlink in the `ssh` or `getty` container:
+
+```
+ln -s /proc/1/root/usr/bin/perf /usr/bin/perf
+```
+
+If you want to use `perf` you may also want to remove the `sysctl`
+container, or alternatively, disable the kernel pointer restriction it
+enables by default:
+
+```
+echo 0 > /proc/sys/kernel/kptr_restrict
+```
+
+Now, `perf` is ready to use. The LinuxKit `perf` package only contains
+the `perf` binary, but excludes the detailed help messages or
+additional scripts. If there is demand, we can add them to the
+LinuxKit package.
+
+