MFC r276419:

Move the explanation for examples before the example itself.  Add
numerous QEMU examples and explanations supplied by sbruno, with thanks
to Ingo Schwarze for help with the mdoc markup.  Code, text, testing,
proofreading, cinematography, stunts, and the haunting theme song
supplied by sbruno.

1 files changed, 125 insertions, 23 deletions

diff --git a/usr.sbin/binmiscctl/binmiscctl.8 b/usr.sbin/binmiscctl/binmiscctl.8
index 646a5a3..8eb5552 100644
--- a/usr.sbin/binmiscctl/binmiscctl.8
+++ b/usr.sbin/binmiscctl/binmiscctl.8
@@ -27,8 +27,8 @@
 .\"
 .\" Support for miscellaneous binary image activators
 .\"
-.Dd April 10, 2014
-.Dt BINMISCCTL 8 
+.Dd December 30, 2014
+.Dt BINMISCCTL 8
 .Os
 .Sh NAME
 .Nm binmiscctl
@@ -142,50 +142,152 @@ Enable the activator entry identified with
 .It Cm lookup Ar name
 Look up and print out the activator entry identified with
 .Ar name .
-.It Cm list 
+.It Cm list
 Take a snapshot and print all the activator entries currently configured.
 .El
 .Sh EXAMPLES
-.Bl
-# binmiscctl add llvmbc --interpreter ''/usr/bin/lli --fake-argv0=#a'' \\
-  --magic ''BC\\xc0\\xde'' --size 4 --set-enabled
-.El
-.Pp
 Add an image activator to run the LLVM interpreter (lli) on bitcode
-compiled files.
+compiled files:
+.Bd -ragged -offset indent
+# binmiscctl add llvmbc --interpreter ''/usr/bin/lli --fake-argv0=#a''
+--magic ''BC\\xc0\\xde'' --size 4 --set-enabled
+.Ed
+.Pp
 .Ar #a
-gets replaced with the old
+is replaced with the old
 .Dv argv0
 value so that 'lli' can fake its
 .Dv argv0 .
 Set its state to enabled.
 .Pp
+Set the state of the
+.Ar llvmbc
+image activator to disabled:
 .Dl # binmiscctl disable llvmbc
 .Pp
-Set the state of the 
+Set the state of the
 .Ar llvmbc
-image activator to disabled.
-.Pp
+image activator to enabled:
 .Dl # binmiscctl enable llvmbc
 .Pp
-Set the state of the 
+Delete the
 .Ar llvmbc
-image activator to enabled.
-.Pp
+image activator:
 .Dl # binmiscctl remove llvmbc
 .Pp
-Delete the
+Look up and list the record for the
 .Ar llvmbc
-image activator.
-.Pp
+image activator:
 .Dl # binmiscctl lookup llvmbc
 .Pp
-Look up and list the record for the
-.Ar llvmbc
-image activator.
+Add QEMU bsd-user program as an image activator for ARM little-endian binaries:
+.Bd -literal -offset indent
+# binmiscctl add armelf \e
+  --interpreter "/usr/local/bin/qemu-arm-static" \e
+  --magic "\ex7f\ex45\ex4c\ex46\ex01\ex01\ex01\ex00\ex00\ex00\e
+           \ex00\ex00\ex00\ex00\ex00\ex00\ex02\ex00\ex28\ex00" \e
+  --mask  "\exff\exff\exff\exff\exff\exff\exff\ex00\exff\exff\e
+           \exff\exff\exff\exff\exff\exff\exfe\exff\exff\exff" \e
+  --size 20 --set-enabled
+.Ed
+.Pp
+Add QEMU bsd-user program as an image activator for ARM big-endian binaries:
+.Bd -literal -offset indent
+# binmiscctl add armebelf \e
+  --interpreter "/usr/local/bin/qemu-arm-static" \e
+  --magic "\ex7f\ex45\ex4c\ex46\ex01\ex02\ex01\ex00\ex00\ex00\e
+           \ex00\ex00\ex00\ex00\ex00\ex00\ex00\ex02\ex00\ex28" \e
+  --mask  "\exff\exff\exff\exff\exff\exff\exff\ex00\exff\exff\e
+           \exff\exff\exff\exff\exff\exff\exff\exfe\exff\exff" \e
+  --size 20 --set-enabled
+.Ed
+.Pp
+Add QEMU bsd-user program as an image activator for MIPS32 binaries:
+.Bd -literal -offset indent
+# binmiscctl add mips32 \e
+  --interpreter "/usr/local/bin/qemu-mips-static" \e
+  --magic "\ex7f\ex45\ex4c\ex46\ex01\ex02\ex01\ex00\ex00\ex00\e
+           \ex00\ex00\ex00\ex00\ex00\ex00\ex00\ex02\ex00\ex08" \e
+  --mask  "\exff\exff\exff\exff\exff\exff\exff\ex00\exff\exff\e
+           \exff\exff\exff\exff\exff\exff\exff\exfe\exff\exff" \e
+  --size 20 --set-enabled
+.Ed
+.Pp
+Add QEMU bsd-user program as an image activator for MIPS64 binaries:
+.Bd -literal -offset indent
+# binmiscctl add mips64 \e
+  --interpreter "/usr/local/bin/qemu-mips64-static" \e
+  --magic "\ex7f\ex45\ex4c\ex46\ex02\ex02\ex01\ex00\ex00\ex00\e
+           \ex00\ex00\ex00\ex00\ex00\ex00\ex00\ex02\ex00\ex08" \e
+  --mask "\exff\exff\exff\exff\exff\exff\exff\ex00\exff\exff\e
+          \exff\exff\exff\exff\exff\exff\exff\exfe\exff\exff" \e
+  --size 20 --set-enabled
+.Ed
+.Pp
+Add QEMU bsd-user program as an image activator for PowerPC binaries:
+.Bd -literal -offset indent
+# binmiscctl add powerpc \e
+  --interpreter "/usr/local/bin/qemu-ppc-static" \e
+  --magic "\ex7f\ex45\ex4c\ex46\ex01\ex02\ex01\ex00\ex00\ex00\e
+           \ex00\ex00\ex00\ex00\ex00\ex00\ex00\ex02\ex00\ex14" \e
+  --mask  "\exff\exff\exff\exff\exff\exff\exff\ex00\exff\exff\e
+           \exff\exff\exff\exff\exff\exff\exff\exfe\exff\exff" \e
+  --size 20 --set-enabled
+.Ed
+.Pp
+Add QEMU bsd-user program as an image activator for PowerPC64 binaries:
+.Bd -literal -offset indent
+# binmiscctl add powerpc64 \e
+  --interpreter "/usr/local/bin/qemu-ppc64-static" \e
+  --magic "\ex7f\ex45\ex4c\ex46\ex01\ex02\ex01\ex00\ex00\ex00\e
+           \ex00\ex00\ex00\ex00\ex00\ex00\ex00\ex02\ex00\ex15" \e
+  --mask  "\exff\exff\exff\exff\exff\exff\exff\ex00\exff\exff\e
+           \exff\exff\exff\exff\exff\exff\exff\exfe\exff\exff" \e
+  --size 20 --set-enabled
+.Ed
+.Pp
+Add QEMU bsd-user program as an image activator for SPARC64 binaries:
+.Bd -literal -offset indent
+# binmiscctl add sparc64 \e
+  --interpreter "/usr/local/bin/qemu-sparc64-static" \e
+  --magic "\ex7f\ex45\ex4c\ex46\ex02\ex02\ex01\ex00\ex00\ex00\e
+           \ex00\ex00\ex00\ex00\ex00\ex00\ex00\ex02\ex00\ex2b" \e
+  --mask  "\exff\exff\exff\exff\exff\exff\exff\ex00\exff\exff\e
+           \exff\exff\exff\exff\exff\exff\exff\exfe\exff\exff" \e
+  --size 20 --set-enabled
+.Ed
+.Pp
+.Ss "Create and use an ARMv6 chroot on an AMD64 host"
+Use an existing source tree to build a chroot host with architecture
+overrides:
+.Bd -literal
+D=/path/to/chroot
+cd /usr/src
+mkdir -p $D
+make world TARGET=arm TARGET_ARCH=armv6 DESTDIR=$D
+make distribution TARGET=arm TARGET_ARCH=armv6 DESTDIR=$D
+.Ed
+.Pp
+With
+.Pa emulators/qemu-user-static
+from the
+.Fx
+Ports Collection, the emulator must be copied into the jail path
+specified in the binmiscctl command.
+Using the example above:
+.Bd -literal
+mkdir $D/usr/local/bin
+cp /usr/local/bin/qemu-arm-static $D/usr/local/bin
+.Ed
+.Pp
+Now the user can chroot into the environment normally, as root:
+.Bd -literal
+chroot $D
+.Ed
 .Sh SEE ALSO
 .Xr lli 1 ,
-.Xr execve 2
+.Xr execve 2 ,
+.Xr jail 8
 .Sh HISTORY
 The
 .Cm binmiscctl