firmware(9) is a subsystem to load binary data into the kernel via a

specially crafted module.  There are several handrolled sollutions to this
problem in the tree already which will be replaced with this.  They include
iwi(4), ipw(4), ispfw(4) and digi(4).

No objection from:	arch
MFC after:		2 weeks
X-MFC after:		some drivers have been converted

6 files changed, 113 insertions, 0 deletions

diff --git a/share/examples/kld/firmware/Makefile b/share/examples/kld/firmware/Makefile
new file mode 100644
index 000000000000..b4b733faae98
--- /dev/null
+++ b/share/examples/kld/firmware/Makefile
@@ -0,0 +1,5 @@
+#	$FreeBSD$
+
+SUBDIR= fwimage fwconsumer
+
+.include <bsd.subdir.mk>
diff --git a/share/examples/kld/firmware/README b/share/examples/kld/firmware/README
new file mode 100644
index 000000000000..075c5e5723b5
--- /dev/null
+++ b/share/examples/kld/firmware/README
@@ -0,0 +1,18 @@
+$FreeBSD$
+
+This is a simple example of the firmware(9) system.  It consists of two
+parts:
+
+1) fwimage
+	This is the firmware image (the ascii art of beastie from the boot
+	menu).  The Makefile lists the firmware file "firmware.img" and the
+	short handle for this firmware image "beastie".
+	Note that the module is called "beastie" as well so that it can be
+	loaded automatically if requested.
+
+2) fwconsumer
+	This module tries to get the a firmware image called "beastie",
+	checks if the data is '\0'-terminated and prints it to the console.
+	It keeps a reference to the firmware until it is unloaded.
+
+This is mainly to demonstrate how to construct firmware image modules.
diff --git a/share/examples/kld/firmware/fwconsumer/Makefile b/share/examples/kld/firmware/fwconsumer/Makefile
new file mode 100644
index 000000000000..1dea0c7eab69
--- /dev/null
+++ b/share/examples/kld/firmware/fwconsumer/Makefile
@@ -0,0 +1,6 @@
+#	$FreeBSD$
+
+KMOD=	fw_consumer
+SRCS=	fw_consumer.c
+
+.include <bsd.kmod.mk>
diff --git a/share/examples/kld/firmware/fwconsumer/fw_consumer.c b/share/examples/kld/firmware/fwconsumer/fw_consumer.c
new file mode 100644
index 000000000000..97ab99aa0f7a
--- /dev/null
+++ b/share/examples/kld/firmware/fwconsumer/fw_consumer.c
@@ -0,0 +1,78 @@
+/*-
+ * Copyright (c) 2006, Max Laier <mlaier@FreeBSD.org>
+ * 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 unmodified, 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 ``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 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.
+ */
+
+#include <sys/cdefs.h>
+__FBSDID("$FreeBSD$");
+
+#include <sys/param.h>
+#include <sys/kernel.h>
+#include <sys/errno.h>
+#include <sys/systm.h>
+#include <sys/linker.h>
+#include <sys/firmware.h>
+#include <sys/proc.h>
+#include <sys/module.h>
+
+static struct firmware *fp;
+
+static int
+fw_consumer_modevent(module_t mod, int type, void *unused)
+{
+	switch (type) {
+	case MOD_LOAD:
+		fp = firmware_get("beastie");
+
+		if (fp == NULL)
+			return (ENOENT);
+
+		if (((const char *)fp->data)[fp->datasize - 1] != '\0') {
+			firmware_put(fp, FIRMWARE_UNLOAD);
+			return (EINVAL);
+		}
+		printf("%s", (const char *)fp->data);
+
+		return (0);
+	case MOD_UNLOAD:
+		printf("Bye!\n");
+
+		if (fp != NULL) {
+			printf("%s", (const char *)fp->data);
+			firmware_put(fp, FIRMWARE_UNLOAD);
+		}
+
+		return (0);
+	}
+	return (EINVAL);
+}
+
+static moduledata_t fw_consumer_mod = {
+	"fw_consumer",
+	fw_consumer_modevent,
+	0
+};
+DECLARE_MODULE(fw_consumer, fw_consumer_mod, SI_SUB_DRIVERS, SI_ORDER_ANY);
+MODULE_VERSION(fw_consumer, 1);
+MODULE_DEPEND(fw_consumer, firmware, 1, 1, 1);
diff --git a/share/examples/kld/firmware/fwimage/Makefile b/share/examples/kld/firmware/fwimage/Makefile
new file mode 100644
index 000000000000..5c0ad7a8b49b
--- /dev/null
+++ b/share/examples/kld/firmware/fwimage/Makefile
@@ -0,0 +1,6 @@
+#	$FreeBSD$
+
+KMOD=	beastie
+FIRMWS=	firmware.img:beastie
+
+.include <bsd.kmod.mk>
diff --git a/share/examples/kld/firmware/fwimage/firmware.img b/share/examples/kld/firmware/fwimage/firmware.img
new file mode 100644
index 000000000000..afc3c23287e7
--- /dev/null
+++ b/share/examples/kld/firmware/fwimage/firmware.img