Merge head

33 files changed, 883 insertions, 241 deletions

diff --git a/share/examples/FreeBSD_version/Makefile b/share/examples/FreeBSD_version/Makefile
index fcfc6b314506..834d925a6fe2 100644
--- a/share/examples/FreeBSD_version/Makefile
+++ b/share/examples/FreeBSD_version/Makefile
@@ -1,7 +1,7 @@
 # $FreeBSD$
 
 PROG=	FreeBSD_version
-NO_MAN=
+MAN=
 
 install:
 
diff --git a/share/examples/Makefile b/share/examples/Makefile
index 04f53d683a2c..a4270bf38ae8 100644
--- a/share/examples/Makefile
+++ b/share/examples/Makefile
@@ -107,8 +107,8 @@ XFILES=	BSD_daemon/FreeBSD.pfa \
 	kld/syscall/test/call.c \
 	libusb20/Makefile \
 	libusb20/README \
-	libusb20/aux.c \
-	libusb20/aux.h \
+	libusb20/util.c \
+	libusb20/util.h \
 	libusb20/bulk.c \
 	libusb20/control.c \
 	libvgl/Makefile \
@@ -241,15 +241,19 @@ etc-examples:
 
 .if ${SHARED} != "symlinks"
 SUBDIR=	smbfs
-.if ${MK_ATF} != "no"
-SUBDIR+=atf
-.endif
 .if ${MK_IPFILTER} != "no"
 SUBDIR+=ipfilter
 .endif
 .if ${MK_PF} != "no"
 SUBDIR+=pf
 .endif
+.if ${MK_DMAGENT} != "no"
+SUBDIR+=dma
+.endif
+.endif
+
+.if ${MK_TESTS} != "no"
+SUBDIR+=tests
 .endif
 
 .include <bsd.subdir.mk>
diff --git a/share/examples/atf/Makefile b/share/examples/atf/Makefile
deleted file mode 100644
index 1a8cf9685fc2..000000000000
--- a/share/examples/atf/Makefile
+++ /dev/null
@@ -1,38 +0,0 @@
-#-
-# Copyright (c) 2011 Google, Inc.
-# All rights reserved.
-#
-# Redistribution and use in source and binary forms, with or without
-# modification, are permitted provided that the following conditions
-# are met:
-# 1. Redistributions of source code must retain the above copyright
-#    notice, this list of conditions and the following disclaimer.
-# 2. Redistributions in binary form must reproduce the above copyright
-#    notice, this list of conditions and the following disclaimer in the
-#    documentation and/or other materials provided with the distribution.
-#
-# THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
-# ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
-# ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
-# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
-# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
-# OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
-# HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
-# LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
-# OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
-# SUCH DAMAGE.
-#
-# $FreeBSD$
-
-ATF=		${.CURDIR}/../../../contrib/atf
-
-.PATH:		${ATF}/atf-report
-.PATH:		${ATF}/atf-run/sample
-
-
-FILESDIR=	${SHAREDIR}/examples/atf
-FILES=		atf-run.hooks \
-		tests-results.css
-
-.include <bsd.prog.mk>
diff --git a/share/examples/atf/Makefile.depend b/share/examples/atf/Makefile.depend
deleted file mode 100644
index 57b7e10c3d71..000000000000
--- a/share/examples/atf/Makefile.depend
+++ /dev/null
@@ -1,12 +0,0 @@
-# Autogenerated - do NOT edit!
-
-DEP_RELDIR := ${_PARSEDIR:S,${SRCTOP}/,,}
-
-DIRDEPS = \
-
-
-.include <dirdeps.mk>
-
-.if ${DEP_RELDIR} == ${_DEP_RELDIR}
-# local dependencies - needed for -jN in clean tree
-.endif
diff --git a/share/examples/autofs/driver/Makefile b/share/examples/autofs/driver/Makefile
index d577668dc4e7..3e158837b59f 100644
--- a/share/examples/autofs/driver/Makefile
+++ b/share/examples/autofs/driver/Makefile
@@ -2,7 +2,7 @@
 # $FreeBSD$
 
 PROG=		autodriver
-NO_MAN=
+MAN=
 
 SRCS=		autodriver.c
 WARNS?=		4
diff --git a/share/examples/bhyve/vmrun.sh b/share/examples/bhyve/vmrun.sh
index 2e1bb38cd9df..0714b7f6cebc 100755
--- a/share/examples/bhyve/vmrun.sh
+++ b/share/examples/bhyve/vmrun.sh
@@ -34,17 +34,25 @@ FBSDRUN=/usr/sbin/bhyve
 DEFAULT_MEMSIZE=512M
 DEFAULT_CPUS=2
 DEFAULT_TAPDEV=tap0
+DEFAULT_CONSOLE=stdio
 
 DEFAULT_VIRTIO_DISK="./diskdev"
 DEFAULT_ISOFILE="./release.iso"
 
 usage() {
-	echo "Usage: vmrun.sh [-hai][-g <gdbport>][-m <memsize>][-d <disk file>][-I <location of installation iso>][-t <tapdev>] <vmname>"
+	echo "Usage: vmrun.sh [-ahi] [-c <CPUs>] [-C <console>] [-d <disk file>]"
+	echo "                [-e <name=value>] [-g <gdbport> ] [-H <directory>]"
+	echo "                [-I <location of installation iso>] [-m <memsize>]"
+	echo "                [-t <tapdev>] <vmname>"
+	echo ""
 	echo "       -h: display this help message"
-	echo "       -a: force memory mapped local apic access"
+	echo "       -a: force memory mapped local APIC access"
 	echo "       -c: number of virtual cpus (default is ${DEFAULT_CPUS})"
+	echo "       -C: console device (default is ${DEFAULT_CONSOLE})"
 	echo "       -d: virtio diskdev file (default is ${DEFAULT_VIRTIO_DISK})"
+	echo "       -e: set FreeBSD loader environment variable"
 	echo "       -g: listen for connection from kgdb at <gdbport>"
+	echo "       -H: host filesystem to export to the loader"
 	echo "       -i: force boot of the Installation CDROM image"
 	echo "       -I: Installation CDROM image location (default is ${DEFAULT_ISOFILE})"
 	echo "       -m: memory size (default is ${DEFAULT_MEMSIZE})"
@@ -68,24 +76,36 @@ fi
 force_install=0
 isofile=${DEFAULT_ISOFILE}
 memsize=${DEFAULT_MEMSIZE}
+console=${DEFAULT_CONSOLE}
 cpus=${DEFAULT_CPUS}
 virtio_diskdev=${DEFAULT_VIRTIO_DISK}
 tapdev=${DEFAULT_TAPDEV}
 apic_opt=""
 gdbport=0
+loader_opt=""
 
-while getopts haic:g:I:m:d:t: c ; do
+while getopts ac:C:d:e:g:hH:iI:m:t: c ; do
 	case $c in
-	h)
-		usage
-		;;
 	a)
 		apic_opt="-a"
 		;;
+	c)
+		cpus=${OPTARG}
+		;;
+	C)
+		console=${OPTARG}
+		;;
 	d)
 		virtio_diskdev=${OPTARG}
 		;;
-	g)	gdbport=${OPTARG}
+	e)
+		loader_opt="${loader_opt} -e ${OPTARG}"
+		;;
+	g)	
+		gdbport=${OPTARG}
+		;;
+	H)
+		host_base=`realpath ${OPTARG}`
 		;;
 	i)
 		force_install=1
@@ -93,16 +113,13 @@ while getopts haic:g:I:m:d:t: c ; do
 	I)
 		isofile=${OPTARG}
 		;;
-	c)
-		cpus=${OPTARG}
-		;;
 	m)
 		memsize=${OPTARG}
 		;;
 	t)
 		tapdev=${OPTARG}
 		;;
-	\?)
+	*)
 		usage
 		;;
 	esac
@@ -115,6 +132,9 @@ if [ $# -ne 1 ]; then
 fi
 
 vmname="$1"
+if [ -n "${host_base}" ]; then
+	loader_opt="${loader_opt} -h ${host_base}"
+fi
 
 # Create the virtio diskdev file if needed
 if [ ! -f ${virtio_diskdev} ]; then
@@ -157,24 +177,26 @@ while [ 1 ]; do
 			exit 1
 		fi
 		BOOTDISK=${isofile}
-		installer_opt="-s 3:0,virtio-blk,${BOOTDISK}"
+		installer_opt="-s 31:0,virtio-blk,${BOOTDISK}"
 	else
 		BOOTDISK=${virtio_diskdev}
 		installer_opt=""
 	fi
 
-	${LOADER} -m ${memsize} -d ${BOOTDISK} ${vmname}
+	${LOADER} -c ${console} -m ${memsize} -d ${BOOTDISK} ${loader_opt} \
+		${vmname}
 	if [ $? -ne 0 ]; then
 		break
 	fi
 
-	${FBSDRUN} -c ${cpus} -m ${memsize} ${apic_opt} -AI -H -P	\
+	${FBSDRUN} -c ${cpus} -m ${memsize} ${apic_opt} -A -H -P	\
 		-g ${gdbport}						\
 		-s 0:0,hostbridge					\
-		-s 1:0,virtio-net,${tapdev}				\
-		-s 2:0,virtio-blk,${virtio_diskdev}			\
+		-s 1:0,lpc						\
+		-s 2:0,virtio-net,${tapdev}				\
+		-s 3:0,virtio-blk,${virtio_diskdev}			\
+		-l com1,${console}					\
 		${installer_opt}					\
-		-S 31,uart,stdio					\
 		${vmname}
 	if [ $? -ne 0 ]; then
 		break
diff --git a/share/examples/dma/Makefile b/share/examples/dma/Makefile
new file mode 100644
index 000000000000..d4ce70930fe8
--- /dev/null
+++ b/share/examples/dma/Makefile
@@ -0,0 +1,10 @@
+# $FreeBSD$
+
+NO_OBJ=
+
+FILES=	mailer.conf
+
+FILESDIR=	${SHAREDIR}/examples/dma
+
+.include <bsd.prog.mk>
+
diff --git a/share/examples/dma/mailer.conf b/share/examples/dma/mailer.conf
new file mode 100644
index 000000000000..53f42c251ce6
--- /dev/null
+++ b/share/examples/dma/mailer.conf
@@ -0,0 +1,5 @@
+# $FreeBSD$
+
+sendmail  /usr/libexec/dma
+send-mail /usr/libexec/dma
+mailq     /usr/libexec/dma
diff --git a/share/examples/etc/make.conf b/share/examples/etc/make.conf
index 19be71347235..5a5293319761 100644
--- a/share/examples/etc/make.conf
+++ b/share/examples/etc/make.conf
@@ -45,8 +45,8 @@
 #				if omitted), ultrasparc3
 # Additionally the following CPU types are recognized by clang:
 #   Intel x86 architecture (for both amd64 and i386):
-#       (AMD CPUs)	bdver2, bdver1, btver2, btver1
-#       (Intel CPUs)	core-avx2, core-avx-i, corei7-avx, corei7, atom
+#       (AMD CPUs)	bdver3, bdver2, bdver1, btver2, btver1
+#       (Intel CPUs)	slm, core-avx2, core-avx-i, corei7-avx, corei7, atom
 #
 # (?= allows to buildworld for a different CPUTYPE.)
 #
@@ -60,6 +60,12 @@
 # nonstandard optimization settings
 # before submitting bug reports without patches to the developers.
 #
+# CFLAGS.arch provides a mechanism for applying CFLAGS only when building 
+# the given architecture.  This is useful primarily on a system used for 
+# cross-building, when you have a set of flags to apply to the TARGET_ARCH 
+# being cross-built but don't want those settings applied to building the 
+# cross-tools or other components that run on the build host machine.  
+#
 # CXXFLAGS controls the compiler settings used when compiling C++ code.
 # Note that CXXFLAGS is initially set to the value of CFLAGS.  If you wish
 # to add to CXXFLAGS value, "+=" must be used rather than "=".  Using "="
@@ -71,6 +77,7 @@
 #
 # CFLAGS+=	-msse3
 # CXXFLAGS+=	-msse3
+# CFLAGS.armv6+= -mfloat-abi=softfp
 #
 # MAKE_SHELL controls the shell used internally by make(1) to process the
 # command scripts in makefiles.  Three shells are supported, sh, ksh, and
@@ -131,7 +138,7 @@
 # If you do not want unformatted manual pages to be compressed
 # when they are installed:
 #
-#NO_MANCOMPRESS=
+#WITHOUT_MANCOMPRESS=t
 #
 #
 # Default format for system documentation, depends on your printer.
diff --git a/share/examples/find_interface/Makefile b/share/examples/find_interface/Makefile
index ac6de9cf7f05..425d5d3fa106 100644
--- a/share/examples/find_interface/Makefile
+++ b/share/examples/find_interface/Makefile
@@ -1,6 +1,6 @@
 # $FreeBSD$
 
 PROG=	find_interface
-NO_MAN=
+MAN=
 
 .include <bsd.prog.mk>
diff --git a/share/examples/kld/cdev/test/Makefile b/share/examples/kld/cdev/test/Makefile
index ad0c0fcd08d0..eebf54d7cb6a 100644
--- a/share/examples/kld/cdev/test/Makefile
+++ b/share/examples/kld/cdev/test/Makefile
@@ -67,7 +67,7 @@
 # $FreeBSD$
 #
 PROG=	testcdev
-NO_MAN=
+MAN=
 WARNS?=	5
 
 MODSTAT= /sbin/kldstat
diff --git a/share/examples/kld/random_adaptor/random_adaptor_example.c b/share/examples/kld/random_adaptor/random_adaptor_example.c
index c0ab10a83fc5..da588a87fe5d 100644
--- a/share/examples/kld/random_adaptor/random_adaptor_example.c
+++ b/share/examples/kld/random_adaptor/random_adaptor_example.c
@@ -30,32 +30,29 @@ __FBSDID("$FreeBSD$");
 
 #include <sys/param.h>
 #include <sys/kernel.h>
+#include <sys/lock.h>
 #include <sys/module.h>
-#include <sys/selinfo.h>
+#include <sys/random.h>
 #include <sys/systm.h>
 
+#include <dev/random/live_entropy_sources.h>
 #include <dev/random/random_adaptors.h>
 #include <dev/random/randomdev.h>
 
-#define RNG_NAME "example"
-
 static int random_example_read(void *, int);
 
 struct random_adaptor random_example = {
 	.ident = "Example RNG",
-	.init = (random_init_func_t *)random_null_func,
-	.deinit = (random_deinit_func_t *)random_null_func,
+	.source = RANDOM_PURE_BOGUS,	/* Make sure this is in
+					 * sys/random.h and is unique */
 	.read = random_example_read,
-	.write = (random_write_func_t *)random_null_func,
-	.reseed = (random_reseed_func_t *)random_null_func,
-	.seeded = 1,
 };
 
 /*
  * Used under the license provided @ http://xkcd.com/221/
  * http://creativecommons.org/licenses/by-nc/2.5/
  */
-static u_char
+static uint8_t
 getRandomNumber(void)
 {
 	return 4;   /* chosen by fair dice roll, guaranteed to be random */
@@ -64,14 +61,13 @@ getRandomNumber(void)
 static int
 random_example_read(void *buf, int c)
 {
-	u_char *b;
+	uint8_t *b;
 	int count;
 
 	b = buf;
 
-	for (count = 0; count < c; count++) {
+	for (count = 0; count < c; count++)
 		b[count] = getRandomNumber();
-	}
 
 	printf("returning %d bytes of pure randomness\n", c);
 	return (c);
@@ -80,15 +76,26 @@ random_example_read(void *buf, int c)
 static int
 random_example_modevent(module_t mod, int type, void *unused)
 {
+	int error = 0;
 
 	switch (type) {
 	case MOD_LOAD:
-		random_adaptor_register(RNG_NAME, &random_example);
-		EVENTHANDLER_INVOKE(random_adaptor_attach, &random_example);
-		return (0);
+		live_entropy_source_register(&random_example);
+		break;
+
+	case MOD_UNLOAD:
+		live_entropy_source_deregister(&random_example);
+		break;
+
+	case MOD_SHUTDOWN:
+		break;
+
+	default:
+		error = EOPNOTSUPP;
+		break;
 	}
 
-	return (EINVAL);
+	return (error);
 }
 
-RANDOM_ADAPTOR_MODULE(random_example, random_example_modevent, 1);
+LIVE_ENTROPY_SRC_MODULE(live_entropy_source_example, random_example_modevent, 1);
diff --git a/share/examples/kld/syscall/test/Makefile b/share/examples/kld/syscall/test/Makefile
index 09d535bf686c..6cc6907d1f4c 100644
--- a/share/examples/kld/syscall/test/Makefile
+++ b/share/examples/kld/syscall/test/Makefile
@@ -2,7 +2,7 @@
 # $FreeBSD$
 
 PROG=	call
-NO_MAN=
+MAN=
 WARNS?=	5
 
 .include <bsd.prog.mk>
diff --git a/share/examples/libusb20/Makefile b/share/examples/libusb20/Makefile
index 6f870a192949..f0da6bf527a4 100644
--- a/share/examples/libusb20/Makefile
+++ b/share/examples/libusb20/Makefile
@@ -1,13 +1,14 @@
 # $FreeBSD$
 TARGETS=	bulk control
+CFLAGS+=	-Wall
 
 all: $(TARGETS)
 
-bulk: bulk.o aux.o
-	$(CC) $(CFLAGS) -o bulk bulk.o aux.o -lusb
+bulk: bulk.o util.o
+	$(CC) $(CFLAGS) -o bulk bulk.o util.o -lusb
 
-control: control.o aux.o
-	$(CC) $(CFLAGS) -o control control.o aux.o -lusb
+control: control.o util.o
+	$(CC) $(CFLAGS) -o control control.o util.o -lusb
 
 clean:
 	rm -f $(TARGETS) *.o *~
diff --git a/share/examples/libusb20/aux.c b/share/examples/libusb20/aux.c
deleted file mode 100644
index 434972aa736c..000000000000
--- a/share/examples/libusb20/aux.c
+++ /dev/null
@@ -1,120 +0,0 @@
-/* ----------------------------------------------------------------------------
- * "THE BEER-WARE LICENSE" (Revision 42) (by Poul-Henning Kamp):
- * <joerg@FreeBSD.ORG> wrote this file.  As long as you retain this notice you
- * can do whatever you want with this stuff. If we meet some day, and you think
- * this stuff is worth it, you can buy me a beer in return.        Joerg Wunsch
- * ----------------------------------------------------------------------------
- *
- * $FreeBSD$
- */
-
-/*
- * Helper functions common to all examples
- */
-
-#include <stdio.h>
-#include <stdint.h>
-#include <stdlib.h>
-
-#include <libusb20.h>
-#include <libusb20_desc.h>
-
-#include "aux.h"
-
-/*
- * Return a textual description for error "r".
- */
-const char *
-usb_error(enum libusb20_error r)
-{
-  const char *msg = "UNKNOWN";
-
-  switch (r)
-    {
-    case LIBUSB20_SUCCESS:
-      msg = "success";
-      break;
-
-    case LIBUSB20_ERROR_IO:
-      msg = "IO error";
-      break;
-
-    case LIBUSB20_ERROR_INVALID_PARAM:
-      msg = "Invalid parameter";
-      break;
-
-    case LIBUSB20_ERROR_ACCESS:
-      msg = "Access denied";
-      break;
-
-    case LIBUSB20_ERROR_NO_DEVICE:
-      msg = "No such device";
-      break;
-
-    case LIBUSB20_ERROR_NOT_FOUND:
-      msg = "Entity not found";
-      break;
-
-    case LIBUSB20_ERROR_BUSY:
-      msg = "Resource busy";
-      break;
-
-    case LIBUSB20_ERROR_TIMEOUT:
-      msg = "Operation timed out";
-      break;
-
-    case LIBUSB20_ERROR_OVERFLOW:
-      msg = "Overflow";
-      break;
-
-    case LIBUSB20_ERROR_PIPE:
-      msg = "Pipe error";
-      break;
-
-    case LIBUSB20_ERROR_INTERRUPTED:
-      msg = "System call interrupted";
-      break;
-
-    case LIBUSB20_ERROR_NO_MEM:
-      msg = "Insufficient memory";
-      break;
-
-    case LIBUSB20_ERROR_NOT_SUPPORTED:
-      msg = "Operation not supported";
-      break;
-
-    case LIBUSB20_ERROR_OTHER:
-      msg = "Other error";
-      break;
-    }
-
-  return msg;
-}
-
-/*
- * Print "len" bytes from "buf" in hex, followed by an ASCII
- * representation (somewhat resembling the output of hd(1)).
- */
-void
-print_formatted(uint8_t *buf, uint32_t len)
-{
-  int i, j;
-
-  for (j = 0; j < len; j += 16)
-    {
-      printf("%02x: ", j);
-
-      for (i = 0; i < 16 && i + j < len; i++)
-	printf("%02x ", buf[i + j]);
-      printf("  ");
-      for (i = 0; i < 16 && i + j < len; i++)
-	{
-	  uint8_t c = buf[i + j];
-	  if(c >= ' ' && c <= '~')
-	    printf("%c", (char)c);
-	  else
-	    putchar('.');
-	}
-      putchar('\n');
-    }
-}
diff --git a/share/examples/libusb20/bulk.c b/share/examples/libusb20/bulk.c
index 7b6b02c005b1..08ba029c0817 100644
--- a/share/examples/libusb20/bulk.c
+++ b/share/examples/libusb20/bulk.c
@@ -41,7 +41,7 @@
 #include <libusb20.h>
 #include <libusb20_desc.h>
 
-#include "aux.h"
+#include "util.h"
 
 /*
  * If you want to see the details of the internal datastructures
@@ -74,7 +74,7 @@ doit(struct libusb20_device *dev)
    */
   if ((rv = libusb20_dev_open(dev, 2)) != 0)
     {
-      fprintf(stderr, "libusb20_dev_open: %s\n", usb_error(rv));
+      fprintf(stderr, "libusb20_dev_open: %s\n", libusb20_strerror(rv));
       return;
     }
 
@@ -84,7 +84,7 @@ doit(struct libusb20_device *dev)
    */
   if ((rv = libusb20_dev_set_config_index(dev, 0)) != 0)
     {
-      fprintf(stderr, "libusb20_dev_set_config_index: %s\n", usb_error(rv));
+      fprintf(stderr, "libusb20_dev_set_config_index: %s\n", libusb20_strerror(rv));
       return;
     }
 
@@ -97,7 +97,7 @@ doit(struct libusb20_device *dev)
 
   if (xfr_in == NULL || xfr_out == NULL)
     {
-      fprintf(stderr, "libusb20_tr_get_pointer: %s\n", usb_error(rv));
+      fprintf(stderr, "libusb20_tr_get_pointer: %s\n", libusb20_strerror(rv));
       return;
     }
 
@@ -107,12 +107,12 @@ doit(struct libusb20_device *dev)
    */
   if ((rv = libusb20_tr_open(xfr_out, 0, 1, out_ep)) != 0)
     {
-      fprintf(stderr, "libusb20_tr_open: %s\n", usb_error(rv));
+      fprintf(stderr, "libusb20_tr_open: %s\n", libusb20_strerror(rv));
       return;
     }
   if ((rv = libusb20_tr_open(xfr_in, 0, 1, in_ep)) != 0)
     {
-      fprintf(stderr, "libusb20_tr_open: %s\n", usb_error(rv));
+      fprintf(stderr, "libusb20_tr_open: %s\n", libusb20_strerror(rv));
       return;
     }
 
@@ -124,7 +124,7 @@ doit(struct libusb20_device *dev)
       if ((rv = libusb20_tr_bulk_intr_sync(xfr_out, out_buf, out_len, &rlen, TIMEOUT))
 	  != 0)
 	{
-	  fprintf(stderr, "libusb20_tr_bulk_intr_sync (OUT): %s\n", usb_error(rv));
+	  fprintf(stderr, "libusb20_tr_bulk_intr_sync (OUT): %s\n", libusb20_strerror(rv));
 	}
       printf("sent %d bytes\n", rlen);
     }
@@ -132,7 +132,7 @@ doit(struct libusb20_device *dev)
   if ((rv = libusb20_tr_bulk_intr_sync(xfr_in, in_buf, BUFLEN, &rlen, TIMEOUT))
       != 0)
     {
-      fprintf(stderr, "libusb20_tr_bulk_intr_sync: %s\n", usb_error(rv));
+      fprintf(stderr, "libusb20_tr_bulk_intr_sync: %s\n", libusb20_strerror(rv));
     }
       printf("received %d bytes\n", rlen);
       if (rlen > 0)
diff --git a/share/examples/libusb20/control.c b/share/examples/libusb20/control.c
index 0a9d152068a0..724ef5979ede 100644
--- a/share/examples/libusb20/control.c
+++ b/share/examples/libusb20/control.c
@@ -11,8 +11,6 @@
 /*
  * Simple demo program to illustrate the handling of FreeBSD's
  * libusb20.
- *
- * XXX
  */
 
 /*
@@ -38,12 +36,15 @@
 #include <stdlib.h>
 #include <sysexits.h>
 #include <unistd.h>
+#include <string.h>
 
 #include <libusb20.h>
 #include <libusb20_desc.h>
 
 #include <sys/queue.h>
 
+#include "util.h"
+
 /*
  * If you want to see the details of the internal datastructures
  * in the debugger, unifdef the following.
@@ -86,7 +87,7 @@ doit(struct libusb20_device *dev)
    */
   if ((rv = libusb20_dev_open(dev, 1)) != 0)
     {
-      fprintf(stderr, "libusb20_dev_open: %s\n", usb_error(rv));
+      fprintf(stderr, "libusb20_dev_open: %s\n", libusb20_strerror(rv));
       return;
     }
 
@@ -96,7 +97,7 @@ doit(struct libusb20_device *dev)
    */
   if ((rv = libusb20_dev_set_config_index(dev, 0)) != 0)
     {
-      fprintf(stderr, "libusb20_dev_set_config_index: %s\n", usb_error(rv));
+      fprintf(stderr, "libusb20_dev_set_config_index: %s\n", libusb20_strerror(rv));
       return;
     }
 
@@ -126,7 +127,7 @@ doit(struct libusb20_device *dev)
 					  0 /* flags */)) != 0)
 	{
 	  fprintf(stderr,
-		  "libusb20_dev_request_sync: %s\n", usb_error(rv));
+		  "libusb20_dev_request_sync: %s\n", libusb20_strerror(rv));
 	}
       printf("sent %d bytes\n", actlen);
       if ((setup.bmRequestType & 0x80) != 0)
@@ -146,7 +147,7 @@ doit(struct libusb20_device *dev)
 
       if (xfr_intr == NULL)
 	{
-	  fprintf(stderr, "libusb20_tr_get_pointer: %s\n", usb_error(rv));
+	  fprintf(stderr, "libusb20_tr_get_pointer: %s\n", libusb20_strerror(rv));
 	  return;
 	}
 
@@ -155,7 +156,7 @@ doit(struct libusb20_device *dev)
        */
       if ((rv = libusb20_tr_open(xfr_intr, 0, 1, intr_ep)) != 0)
 	{
-	  fprintf(stderr, "libusb20_tr_open: %s\n", usb_error(rv));
+	  fprintf(stderr, "libusb20_tr_open: %s\n", libusb20_strerror(rv));
 	  return;
 	}
 
@@ -165,7 +166,7 @@ doit(struct libusb20_device *dev)
       if ((rv = libusb20_tr_bulk_intr_sync(xfr_intr, in_buf, BUFLEN, &rlen, TIMEOUT))
 	  != 0)
 	{
-	  fprintf(stderr, "libusb20_tr_bulk_intr_sync: %s\n", usb_error(rv));
+	  fprintf(stderr, "libusb20_tr_bulk_intr_sync: %s\n", libusb20_strerror(rv));
 	}
       printf("received %d bytes\n", rlen);
       if (rlen > 0)
diff --git a/share/examples/libusb20/util.c b/share/examples/libusb20/util.c
new file mode 100644
index 000000000000..4a24ee0cf8c9
--- /dev/null
+++ b/share/examples/libusb20/util.c
@@ -0,0 +1,50 @@
+/* ----------------------------------------------------------------------------
+ * "THE BEER-WARE LICENSE" (Revision 42) (by Poul-Henning Kamp):
+ * <joerg@FreeBSD.ORG> wrote this file.  As long as you retain this notice you
+ * can do whatever you want with this stuff. If we meet some day, and you think
+ * this stuff is worth it, you can buy me a beer in return.        Joerg Wunsch
+ * ----------------------------------------------------------------------------
+ *
+ * $FreeBSD$
+ */
+
+/*
+ * Helper functions common to all examples
+ */
+
+#include <stdio.h>
+#include <stdint.h>
+#include <stdlib.h>
+
+#include <libusb20.h>
+#include <libusb20_desc.h>
+
+#include "util.h"
+
+/*
+ * Print "len" bytes from "buf" in hex, followed by an ASCII
+ * representation (somewhat resembling the output of hd(1)).
+ */
+void
+print_formatted(uint8_t *buf, uint32_t len)
+{
+  int i, j;
+
+  for (j = 0; j < len; j += 16)
+    {
+      printf("%02x: ", j);
+
+      for (i = 0; i < 16 && i + j < len; i++)
+	printf("%02x ", buf[i + j]);
+      printf("  ");
+      for (i = 0; i < 16 && i + j < len; i++)
+	{
+	  uint8_t c = buf[i + j];
+	  if(c >= ' ' && c <= '~')
+	    printf("%c", (char)c);
+	  else
+	    putchar('.');
+	}
+      putchar('\n');
+    }
+}
diff --git a/share/examples/libusb20/aux.h b/share/examples/libusb20/util.h
index d43ea4e571fb..5fd2a6e09c2d 100644
--- a/share/examples/libusb20/aux.h
+++ b/share/examples/libusb20/util.h
@@ -11,5 +11,4 @@
 #include <stdint.h>
 #include <libusb20.h>
 
-const char *usb_error(enum libusb20_error r);
 void print_formatted(uint8_t *buf, uint32_t len);
diff --git a/share/examples/libvgl/Makefile b/share/examples/libvgl/Makefile
index 6b4e916851da..f78584ed3888 100644
--- a/share/examples/libvgl/Makefile
+++ b/share/examples/libvgl/Makefile
@@ -1,7 +1,7 @@
 # $FreeBSD$
 
 PROG=	demo
-NO_MAN=
+MAN=
 DPADD=	${LIBVGL}
 LDADD=	-lvgl
 
diff --git a/share/examples/perfmon/Makefile b/share/examples/perfmon/Makefile
index de59b9effcf0..51ecf4dd74db 100644
--- a/share/examples/perfmon/Makefile
+++ b/share/examples/perfmon/Makefile
@@ -1,7 +1,7 @@
 # $FreeBSD$
 
 PROG=	perfmon
-NO_MAN=
+MAN=
 
 install:
 
diff --git a/share/examples/ppi/Makefile b/share/examples/ppi/Makefile
index 9b0d0d59c3d3..09a98cdc8963 100644
--- a/share/examples/ppi/Makefile
+++ b/share/examples/ppi/Makefile
@@ -3,6 +3,6 @@
 # $FreeBSD$
 
 PROG=	ppilcd
-NO_MAN=
+MAN=
 
 .include <bsd.prog.mk>
diff --git a/share/examples/tests/Makefile b/share/examples/tests/Makefile
new file mode 100644
index 000000000000..387b8068b1f7
--- /dev/null
+++ b/share/examples/tests/Makefile
@@ -0,0 +1,12 @@
+# $FreeBSD$
+
+.include <bsd.own.mk>
+
+TESTSDIR=	${TESTSBASE}/share/examples
+
+SUBDIR=		tests
+
+KYUAFILE=	yes
+.PATH:		${.CURDIR:H:H:H}/tests
+
+.include <bsd.test.mk>
diff --git a/share/examples/tests/README b/share/examples/tests/README
new file mode 100644
index 000000000000..0465cbe79889
--- /dev/null
+++ b/share/examples/tests/README
@@ -0,0 +1,37 @@
+$FreeBSD$
+
+This directory contains sample test programs along the Makefile and
+Kyuafile logic to get them build and installed.
+
+The goal of these test programs is to illustrate, via simple and
+heaviliy-commented code, how to construct test programs using all the
+supported interfaces in the system.
+
+If you use any files in here as templates for your own code, please
+remove all comments while doing so and then write your own if necessary.
+
+The subdirectories here contain:
+
+* tests/: Regular directory containing the tests code.  Note that the
+  apparently-redundant tests/tests/ path component here is expected for
+  consistency reasons and required to get the right layout under
+  /usr/tests/.
+
+* tests/atf/: Tests that use the ATF libraries, including atf-c, atf-c++
+  and atf-sh.  See kyua-atf-interface(1) for details.
+
+* tests/plain/: Tests that do not use any testing framework.  See
+  kyua-plain-interface(1) for details.
+
+To inspect the available sample test cases from an installed system:
+
+    $ kyua list -k /usr/tests/share/examples/tests/Kyuafile
+
+To run the full suite of sample test cases:
+
+    $ kyua test -k /usr/tests/share/examples/tests/Kyuafile
+
+And to debug a specific failing test case, if any:
+
+    $ kyua debug -k /usr/tests/share/examples/tests/Kyuafile \
+      atf/cp_test:simple
diff --git a/share/examples/tests/tests/Makefile b/share/examples/tests/tests/Makefile
new file mode 100644
index 000000000000..9f7b5a4729c4
--- /dev/null
+++ b/share/examples/tests/tests/Makefile
@@ -0,0 +1,27 @@
+# $FreeBSD$
+
+.include <bsd.own.mk>
+
+# Directory into which the Kyuafile provided by this directory will be
+# installed.
+#
+# This is always a subdirectory of ${TESTSBASE}/.  The remainder of the
+# path has to match the relative path within the source tree in which
+# these files are found modulo the tests/ component at the end.
+#
+# For example: if this Makefile were in src/bin/cp/tests/, its TESTSDIR
+# would point at ${TESTSBASE}/bin/cp/.
+TESTSDIR=	${TESTSBASE}/share/examples/tests
+
+# List of subdirectories into which we want to recurse during the build
+# of the system.  We use TESTS_SUBDIRS instead of SUBDIR because we want
+# the auto-generated Kyuafile to recurse into these directories.
+TESTS_SUBDIRS=	atf plain
+
+# We leave KYUAFILE unset so that bsd.test.mk auto-generates a Kyuafile
+# for us based on the contents of the TESTS_SUBDIRS line above.  The
+# generated file will tell the tests run-time engine to recurse into the
+# directories listed above.
+#KYUAFILE=	auto
+
+.include <bsd.test.mk>
diff --git a/share/examples/tests/tests/atf/Kyuafile b/share/examples/tests/tests/atf/Kyuafile
new file mode 100644
index 000000000000..8c60947d1082
--- /dev/null
+++ b/share/examples/tests/tests/atf/Kyuafile
@@ -0,0 +1,46 @@
+-- $FreeBSD$
+--
+-- Copyright 2013 Google Inc.
+-- All rights reserved.
+--
+-- Redistribution and use in source and binary forms, with or without
+-- modification, are permitted provided that the following conditions are
+-- met:
+--
+-- * Redistributions of source code must retain the above copyright
+--   notice, this list of conditions and the following disclaimer.
+-- * Redistributions in binary form must reproduce the above copyright
+--   notice, this list of conditions and the following disclaimer in the
+--   documentation and/or other materials provided with the distribution.
+-- * Neither the name of Google Inc. nor the names of its contributors
+--   may be used to endorse or promote products derived from this software
+--   without specific prior written permission.
+--
+-- THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+-- "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+-- LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+-- A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+-- OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+-- SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+-- LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+-- DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+-- THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+-- (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+-- OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+syntax(2)
+
+-- All tests provided by the FreeBSD base system should set the test_suite
+-- property to FreeBSD.  This creates a namespace in the configuration file
+-- in which specific run-time properties can be passed to the tests below.
+test_suite('FreeBSD')
+
+-- Register the various test programs into the test suite defined in this
+-- directory.
+--
+-- Note that, while Kyua supports overriding the test case metadata
+-- properties (e.g. their timeout) along the test program definition, you
+-- should not do so for ATF test programs.  The ATF test cases themselves
+-- encode the right values.
+atf_test_program{name='cp_test'}
+atf_test_program{name='printf_test'}
diff --git a/share/examples/tests/tests/atf/Makefile b/share/examples/tests/tests/atf/Makefile
new file mode 100644
index 000000000000..c7bd46fef7b1
--- /dev/null
+++ b/share/examples/tests/tests/atf/Makefile
@@ -0,0 +1,30 @@
+# $FreeBSD$
+
+.include <bsd.own.mk>
+
+# Directory into which the Kyuafile provided by this directory will be
+# installed.
+#
+# This is always a subdirectory of ${TESTSBASE}/.  The remainder of the
+# path has to match the relative path within the source tree in which
+# these files are found modulo the tests/ component at the end.
+#
+# For example: if this Makefile were in src/bin/cp/tests/, its TESTSDIR
+# would point at ${TESTSBASE}/bin/cp/.
+TESTSDIR=	${TESTSBASE}/share/examples/tests/atf
+
+# List of test programs to build.  Note that we can build more than one
+# test from a single directory, and this is expected.
+ATF_TESTS_C=	printf_test
+ATF_TESTS_SH=	cp_test
+
+# Tell bsd.test.mk that we are providing a hand-crafted Kyuafile in this
+# directory.  We do so because the file in this directory exists for
+# documentation purposes.
+#
+# In general, however, you should NOT define KYUAFILE at all to allow
+# bsd.test.mk auto-generate one for you based on the ATF_TESTS_*
+# definitions from above.
+KYUAFILE=	yes
+
+.include <bsd.test.mk>
diff --git a/share/examples/tests/tests/atf/cp_test.sh b/share/examples/tests/tests/atf/cp_test.sh
new file mode 100644
index 000000000000..83d691460d0f
--- /dev/null
+++ b/share/examples/tests/tests/atf/cp_test.sh
@@ -0,0 +1,119 @@
+# $FreeBSD$
+#
+# Copyright 2013 Google Inc.
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+# * Redistributions of source code must retain the above copyright
+#   notice, this list of conditions and the following disclaimer.
+# * Redistributions in binary form must reproduce the above copyright
+#   notice, this list of conditions and the following disclaimer in the
+#   documentation and/or other materials provided with the distribution.
+# * Neither the name of Google Inc. nor the names of its contributors
+#   may be used to endorse or promote products derived from this software
+#   without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+#
+# INTRODUCTION
+#
+# This sample test program implements various test cases for the cp(1)
+# utility in order to demonstrate the usage of the ATF shell API (see
+# atf-sh-api(3)).
+#
+
+#
+# Auxiliary function to compare two files for equality.
+#
+verify_copy() {
+	if ! cmp -s "${1}" "${2}"; then
+		echo "${1} and ${2} differ, but they should be equal"
+		diff -u "${1}" "${2}"
+		atf_fail "Original and copy do not match"
+	fi
+}
+
+#
+# This is the simplest form of a test case definition: a test case
+# without a header.
+#
+# In most cases, this is the definition you will want to use.  However,
+# make absolutely sure that the test case name is descriptive enough.
+# Multi-word test case names are encouraged.  Keep in mind that these
+# are exposed to the reader in the test reports, and the goal is for
+# the combination of the test program plus the name of the test case to
+# give a pretty clear idea of what specific condition the test is
+# validating.
+#
+atf_test_case simple
+simple_body() {
+	echo 'File 1' >file1
+
+	# The atf_check function is a very powerful function of atf-sh.
+	# It allows you to define checkers for the exit status, the
+	# stdout and the stderr of any command you execute.  If the
+	# result of the command does not match the expectations defined
+	# in the checkers, the test fails and verbosely reports data
+	# behind the problem.
+	#
+	# See atf-check(1) for details.
+	atf_check -s exit:0 -o empty -e empty cp file1 file2
+
+	verify_copy file1 file2
+
+	# Of special note here is that we are NOT deleting the temporary
+	# files we created in this test.  Kyua takes care of this
+	# cleanup automatically and tests can (and should) rely on this
+	# behavior.
+}
+
+#
+# This is a more complex form of a test case definition: a test case
+# with a header and a body.  You should always favor the simpler
+# definition above unless you have to override specific metadata
+# variables.
+#
+# See atf-test-case(4) and kyua-atf-interface(1) for details on all
+# available properties.
+#
+atf_test_case force
+force_head() {
+	# In this specific case, we define a textual description for
+	# the test case, which is later exported to the reports for
+	# documentation purposes.
+	#
+	# However, note again that you should favor highly descriptive
+	# test case names to textual descriptions.
+	atf_set "descr" "Tests that the -f flag causes cp to forcibly" \
+	    "override the destination file"
+}
+force_body() {
+	echo 'File 1' >file1
+	echo 'File 2' >file2
+	chmod 400 file2
+	atf_check cp -f file1 file2
+	verify_copy file1 file2
+}
+
+#
+# Lastly, we tell ATF which test cases exist in this program.  This
+# function should not do anything other than this registration.
+#
+atf_init_test_cases() {
+	atf_add_test_case simple
+	atf_add_test_case force
+}
diff --git a/share/examples/tests/tests/atf/printf_test.c b/share/examples/tests/tests/atf/printf_test.c
new file mode 100644
index 000000000000..04a5665cdd89
--- /dev/null
+++ b/share/examples/tests/tests/atf/printf_test.c
@@ -0,0 +1,155 @@
+/* $FreeBSD$
+ *
+ * Copyright 2013 Google Inc.
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are
+ * met:
+ *
+ * * Redistributions of source code must retain the above copyright
+ *   notice, this list of conditions and the following disclaimer.
+ * * Redistributions in binary form must reproduce the above copyright
+ *   notice, this list of conditions and the following disclaimer in the
+ *   documentation and/or other materials provided with the distribution.
+ * * Neither the name of Google Inc. nor the names of its contributors
+ *   may be used to endorse or promote products derived from this software
+ *   without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */
+
+/*
+ * INTRODUCTION
+ *
+ * This sample test program implements various test cases for the printf(3)
+ * family of functions in order to demonstrate the usage of the ATF C API
+ * (see atf-c-api(3)).
+ *
+ * Note that this test program is called printf_test because it is intended
+ * to validate various functions of the printf(3) family.  For this reason,
+ * each test is prefixed with the name of the function under test followed
+ * by a description of the specific condition being validated.  You should
+ * use a similar naming scheme for your own tests.
+ */
+
+#include <atf-c.h>
+#include <stdio.h>
+#include <string.h>
+
+/*
+ * This is the simplest form of a test case definition: a test case
+ * without a header.
+ *
+ * In most cases, this is the definition you will want to use.  However,
+ * make absolutely sure that the test case name is descriptive enough.
+ * Multi-word test case names are encouraged.  Keep in mind that these
+ * are exposed to the reader in the test reports, and the goal is for
+ * the combination of the test program plus the name of the test case to
+ * give a pretty clear idea of what specific condition the test is
+ * validating.
+ */
+ATF_TC_WITHOUT_HEAD(snprintf__two_formatters);
+ATF_TC_BODY(snprintf__two_formatters, tc)
+{
+	char buffer[128];
+
+	/* This first require-style check invokes the function we are
+	 * interested in testing.  This will cause the test to fail if
+	 * the condition provided to ATF_REQUIRE is not met. */
+	ATF_REQUIRE(snprintf(buffer, sizeof(buffer), "%s, %s!",
+	    "Hello", "tests") > 0);
+
+	/* This second check-style check compares that the result of the
+	 * snprintf call we performed above is correct.  We use a check
+	 * instead of a require. */
+	ATF_CHECK_STREQ("Hello, tests!", buffer);
+}
+
+/*
+ * This is a more complex form of a test case definition: a test case
+ * with a header and a body.  You should always favor the simpler
+ * definition above unless you have to override specific metadata
+ * variables.
+ *
+ * See atf-test-case(4) and kyua-atf-interface(1) for details on all
+ * available properties.
+ */
+ATF_TC(snprintf__overflow);
+ATF_TC_HEAD(snprintf__overflow, tc)
+{
+	/* In this specific case, we define a textual description for
+	 * the test case, which is later exported to the reports for
+	 * documentation purposes.
+	 *
+	 * However, note again that you should favor highly descriptive
+	 * test case names to textual descriptions.  */
+	atf_tc_set_md_var(tc, "descr", "This test case validates the proper "
+	    "truncation of the output string from snprintf when it does not "
+	    "fit the provided buffer.");
+}
+ATF_TC_BODY(snprintf__overflow, tc)
+{
+	char buffer[10];
+
+	/* This is a similar test to the above, but in this case we do the
+	 * test ourselves and forego the ATF_* macros.  Note that we use the
+	 * atf_tc_fail() function instead of exit(2) or similar because we
+	 * want Kyua to have access to the failure message.
+	 *
+	 * In general, prefer using the ATF_* macros wherever possible.  Only
+	 * resort to manual tests when the macros are unsuitable (and consider
+	 * filing a feature request to get a new macro if you think your case
+	 * is generic enough). */
+	if (snprintf(buffer, sizeof(buffer), "0123456789abcdef") != 16)
+		atf_tc_fail("snprintf did not return the expected number "
+		    "of characters");
+
+	ATF_CHECK(strcmp(buffer, "012345678") == 0);
+}
+
+/*
+ * Another simple test case, but this time with side-effects.  This
+ * particular test case modifies the contents of the current directory
+ * and does not clean up after itself, which is perfectly fine.
+ */
+ATF_TC_WITHOUT_HEAD(fprintf__simple_string);
+ATF_TC_BODY(fprintf__simple_string, tc)
+{
+	const char *contents = "This is a message\n";
+
+	FILE *output = fopen("test.txt", "w");
+	ATF_REQUIRE(fprintf(output, "%s", contents) > 0);
+	fclose(output);
+
+	/* The ATF C library provides more than just macros to verify the
+	 * outcome of expressions.  It also includes various helper functions
+	 * to work with files and processes.  Here is just a simple
+	 * example. */
+	ATF_REQUIRE(atf_utils_compare_file("test.txt", contents));
+
+	/* Of special note here is that we are NOT deleting the
+	 * temporary files we created in this test.  Kyua takes care of
+	 * this cleanup automatically and tests can (and should) rely on
+	 * this behavior. */
+}
+
+/*
+ * Lastly, we tell ATF which test cases exist in this program.  This
+ * function should not do anything other than this registration.
+ */
+ATF_TP_ADD_TCS(tp)
+{
+	ATF_TP_ADD_TC(tp, snprintf__two_formatters);
+	ATF_TP_ADD_TC(tp, snprintf__overflow);
+	ATF_TP_ADD_TC(tp, fprintf__simple_string);
+}
diff --git a/share/examples/tests/tests/plain/Kyuafile b/share/examples/tests/tests/plain/Kyuafile
new file mode 100644
index 000000000000..c9301b0ef97e
--- /dev/null
+++ b/share/examples/tests/tests/plain/Kyuafile
@@ -0,0 +1,47 @@
+-- $FreeBSD$
+--
+-- Copyright 2013 Google Inc.
+-- All rights reserved.
+--
+-- Redistribution and use in source and binary forms, with or without
+-- modification, are permitted provided that the following conditions are
+-- met:
+--
+-- * Redistributions of source code must retain the above copyright
+--   notice, this list of conditions and the following disclaimer.
+-- * Redistributions in binary form must reproduce the above copyright
+--   notice, this list of conditions and the following disclaimer in the
+--   documentation and/or other materials provided with the distribution.
+-- * Neither the name of Google Inc. nor the names of its contributors
+--   may be used to endorse or promote products derived from this software
+--   without specific prior written permission.
+--
+-- THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+-- "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+-- LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+-- A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+-- OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+-- SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+-- LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+-- DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+-- THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+-- (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+-- OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+syntax(2)
+
+-- All tests provided by the FreeBSD base system should set the test_suite
+-- property to FreeBSD.  This creates a namespace in the configuration file
+-- in which specific run-time properties can be passed to the tests below.
+test_suite('FreeBSD')
+
+-- Register the various test programs into the test suite defined in this
+-- directory.
+--
+-- Because plain test programs cannot define metadata in their code (they
+-- have no mechanism to communicate that to Kyua), we can instead define
+-- any metadata properties in here.  These have the exact same meaning as
+-- their ATF counterparts.  These properties are often useful to define
+-- prerequisites for the execution of the tests.
+plain_test_program{name='cp_test', required_programs='/bin/cp'}
+plain_test_program{name='printf_test'}
diff --git a/share/examples/tests/tests/plain/Makefile b/share/examples/tests/tests/plain/Makefile
new file mode 100644
index 000000000000..7348c5a970e5
--- /dev/null
+++ b/share/examples/tests/tests/plain/Makefile
@@ -0,0 +1,30 @@
+# $FreeBSD$
+
+.include <bsd.own.mk>
+
+# Directory into which the Kyuafile provided by this directory will be
+# installed.
+#
+# This is always a subdirectory of ${TESTSBASE}/.  The remainder of the
+# path has to match the relative path within the source tree in which
+# these files are found modulo the tests/ component at the end.
+#
+# For example: if this Makefile were in src/bin/cp/tests/, its TESTSDIR
+# would point at ${TESTSBASE}/bin/cp/.
+TESTSDIR=	${TESTSBASE}/share/examples/tests/plain
+
+# List of test programs to build.  Note that we can build more than one
+# test from a single directory, and this is expected.
+PLAIN_TESTS_C=	printf_test
+PLAIN_TESTS_SH=	cp_test
+
+# Tell bsd.test.mk that we are providing a hand-crafted Kyuafile in this
+# directory.  We do so because the file in this directory exists for
+# documentation purposes.
+#
+# In general, however, you should NOT define KYUAFILE at all to allow
+# bsd.test.mk auto-generate one for you based on the PLAIN_TESTS_*
+# definitions from above.
+KYUAFILE=	yes
+
+.include <bsd.test.mk>
diff --git a/share/examples/tests/tests/plain/cp_test.sh b/share/examples/tests/tests/plain/cp_test.sh
new file mode 100644
index 000000000000..ea6470518cda
--- /dev/null
+++ b/share/examples/tests/tests/plain/cp_test.sh
@@ -0,0 +1,84 @@
+# $FreeBSD$
+#
+# Copyright 2013 Google Inc.
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+# * Redistributions of source code must retain the above copyright
+#   notice, this list of conditions and the following disclaimer.
+# * Redistributions in binary form must reproduce the above copyright
+#   notice, this list of conditions and the following disclaimer in the
+#   documentation and/or other materials provided with the distribution.
+# * Neither the name of Google Inc. nor the names of its contributors
+#   may be used to endorse or promote products derived from this software
+#   without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+#
+# INTRODUCTION
+#
+# This plain test program mimics the structure and contents of its
+# ATF-based counterpart.  It attempts to represent various test cases
+# in different separate functions and just calls them all from main.
+#
+# In reality, plain test programs can be much simpler.  All they have
+# to do is return 0 on success and non-0 otherwise.
+#
+
+set -e
+
+# Prints an error message and exits.
+err() {
+	echo "${@}" 1>&2
+	exit 1
+}
+
+# Auxiliary function to compare two files for equality.
+verify_copy() {
+	if ! cmp -s "${1}" "${2}"; then
+		diff -u "${1}" "${2}"
+		err "${1} and ${2} differ, but they should be equal"
+	fi
+}
+
+simple_test() {
+	echo 'File 1' >file1
+	cp file1 file2 || err "cp failed"
+	verify_copy file1 file2
+}
+
+force_test() {
+	echo 'File 1' >file1
+	echo 'File 2' >file2
+	chmod 400 file2
+	cp -f file1 file2 || err "cp failed"
+	verify_copy file1 file2
+}
+
+# If you have read the cp_test.sh counterpart in the atf/ directory, you
+# may think that the sequencing of tests below and the exposed behavior
+# to the user is very similar.  But you'd be wrong.
+#
+# There are two major differences with this and the ATF version.  The
+# first is that the code below has no provisions to detect failures in
+# one test and continue running the other tests: the first failure
+# causes the whole test program to exit.  The second is that this
+# particular "main" has no arguments: without ATF, all test programs may
+# expose a different command-line interface, and this is an issue for
+# consistency purposes.
+simple_test
+force_test
diff --git a/share/examples/tests/tests/plain/printf_test.c b/share/examples/tests/tests/plain/printf_test.c
new file mode 100644
index 000000000000..c43269b2a73c
--- /dev/null
+++ b/share/examples/tests/tests/plain/printf_test.c
@@ -0,0 +1,119 @@
+/* $FreeBSD$
+ *
+ * Copyright 2013 Google Inc.
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are
+ * met:
+ *
+ * * Redistributions of source code must retain the above copyright
+ *   notice, this list of conditions and the following disclaimer.
+ * * Redistributions in binary form must reproduce the above copyright
+ *   notice, this list of conditions and the following disclaimer in the
+ *   documentation and/or other materials provided with the distribution.
+ * * Neither the name of Google Inc. nor the names of its contributors
+ *   may be used to endorse or promote products derived from this software
+ *   without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */
+
+/*
+ * INTRODUCTION
+ *
+ * This plain test program mimics the structure and contents of its
+ * ATF-based counterpart.  It attempts to represent various test cases
+ * in different separate functions and just calls them all from main().
+ *
+ * In reality, plain test programs can be much simpler.  All they have
+ * to do is return 0 on success and non-0 otherwise.
+ */
+
+#include <err.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+static void
+snprintf__two_formatters(void)
+{
+	char buffer[128];
+
+	if (snprintf(buffer, sizeof(buffer), "%s, %s!", "Hello",
+	    "tests") <= 0)
+		errx(EXIT_FAILURE, "snprintf with two formatters failed");
+
+	if (strcmp(buffer, "Hello, tests!") != 0)
+		errx(EXIT_FAILURE, "Bad formatting: got %s", buffer);
+}
+
+static void
+snprintf__overflow(void)
+{
+	char buffer[10];
+
+	if (snprintf(buffer, sizeof(buffer), "0123456789abcdef") != 16)
+		errx(EXIT_FAILURE, "snprintf did not return the expected "
+		    "number of characters");
+
+	if (strcmp(buffer, "012345678") != 0)
+		errx(EXIT_FAILURE, "Bad formatting: got %s", buffer);
+}
+
+static void
+fprintf__simple_string(void)
+{
+	FILE *file;
+	char buffer[128];
+	size_t length;
+	const char *contents = "This is a message\n";
+
+	file = fopen("test.txt", "w+");
+	if (fprintf(file, "%s", contents) <= 0)
+		err(EXIT_FAILURE, "fprintf failed to write to file");
+	rewind(file);
+	length = fread(buffer, 1, sizeof(buffer) - 1, file);
+	if (length != strlen(contents))
+		err(EXIT_FAILURE, "fread failed");
+	buffer[length] = '\0';
+	fclose(file);
+
+	if (strcmp(buffer, contents) != 0)
+		errx(EXIT_FAILURE, "Written and read data differ");
+
+	/* Of special note here is that we are NOT deleting the temporary
+	 * files we created in this test.  Kyua takes care of this cleanup
+	 * automatically and tests can (and should) rely on this behavior. */
+}
+
+int
+main(void)
+{
+	/* If you have read the printf_test.c counterpart in the atf/
+	 * directory, you may think that the sequencing of tests below and
+	 * the exposed behavior to the user is very similar.  But you'd be
+	 * wrong.
+	 *
+	 * There are two major differences with this and the ATF version.
+	 * The first is that the code below has no provisions to detect
+	 * failures in one test and continue running the other tests: the
+	 * first failure causes the whole test program to exit.  The second
+	 * is that this particular main() has no arguments: without ATF,
+	 * all test programs may expose a different command-line interface,
+	 * and this is an issue for consistency purposes. */
+	snprintf__two_formatters();
+	snprintf__overflow();
+	fprintf__simple_string();
+
+	return EXIT_SUCCESS;
+}