Cleanup and document the implementation of firmware(9) based on

a version that i posted earlier on the -current mailing list,
and subsequent feedback received.

The core of the change is just in sys/firmware.h and kern/subr_firmware.c,
while other files are just adaptation of the clients to the ABI change
(const-ification of some parameters and hiding of internal info,
so this is fully compatible at the binary level).

In detail:
- reduce the amount of information exported to clients in struct firmware,
  and constify the pointer;

- internally, document and simplify the implementation of the various
  functions, and make sure error conditions are dealt with properly.

The diffs are large, but the code is really straightforward now (i hope).

Note also that there is a subtle issue with the implementation of
firmware_register(): currently, as in the previous version, we just
store a reference to the 'imagename' argument, but we should rather
copy it because there is no guarantee that this is a static string.
I realised this while testing this code, but i prefer to fix it in
a later commit -- there is no regression with respect to the past.

Note, too, that the version in RELENG_6 has various bugs including
missing locks around the module release calls, mishandling of modules
loaded by /boot/loader, and so on, so an MFC is absolutely necessary
there.  I was just postponing it until this cleanup to avoid doing
things twice.

MFC after: 1 week

6 files changed, 7 insertions, 7 deletions

diff --git a/sys/dev/ipw/if_ipw.c b/sys/dev/ipw/if_ipw.c
index 69761f6..7534949 100644
--- a/sys/dev/ipw/if_ipw.c
+++ b/sys/dev/ipw/if_ipw.c
@@ -1956,7 +1956,7 @@ ipw_init(void *priv)
 	struct ipw_softc *sc = priv;
 	struct ieee80211com *ic = &sc->sc_ic;
 	struct ifnet *ifp = ic->ic_ifp;
-	struct firmware *fp;
+	const struct firmware *fp;
 	const struct ipw_firmware_hdr *hdr;
 	const char *imagename, *fw;
 	int owned;
diff --git a/sys/dev/ipw/if_ipwvar.h b/sys/dev/ipw/if_ipwvar.h
index 3cfb77e..c97d6a8 100644
--- a/sys/dev/ipw/if_ipwvar.h
+++ b/sys/dev/ipw/if_ipwvar.h
@@ -99,7 +99,7 @@ struct ipw_softc {
 	bus_space_tag_t			sc_st;
 	bus_space_handle_t		sc_sh;
 	void 				*sc_ih;
-	struct firmware			*sc_firmware;
+	const struct firmware		*sc_firmware;
 
 	int				sc_tx_timer;
 
diff --git a/sys/dev/isp/isp_freebsd.h b/sys/dev/isp/isp_freebsd.h
index c9868ab..c8247e8 100644
--- a/sys/dev/isp/isp_freebsd.h
+++ b/sys/dev/isp/isp_freebsd.h
@@ -166,7 +166,7 @@ struct isposinfo {
 	struct callout_handle 	ldt;	/* loop down timer */
 	struct callout_handle	gdt;	/* gone device timer */
 #if __FreeBSD_version >= 500000  
-	struct firmware *	fw;
+	const struct firmware *	fw;
 	struct mtx		lock;
 	struct cv		kthread_cv;
 	union {
diff --git a/sys/dev/iwi/if_iwi.c b/sys/dev/iwi/if_iwi.c
index bf582aa..1f7f573 100644
--- a/sys/dev/iwi/if_iwi.c
+++ b/sys/dev/iwi/if_iwi.c
@@ -2169,7 +2169,7 @@ iwi_reset(struct iwi_softc *sc)
 static const struct iwi_firmware_ohdr *
 iwi_setup_ofw(struct iwi_softc *sc, struct iwi_fw *fw)
 {
-	struct firmware *fp = fw->fp;
+	const struct firmware *fp = fw->fp;
 	const struct iwi_firmware_ohdr *hdr;
 
 	if (fp->datasize < sizeof (struct iwi_firmware_ohdr)) {
@@ -2234,7 +2234,7 @@ iwi_get_firmware(struct iwi_softc *sc)
 {
 	struct ieee80211com *ic = &sc->sc_ic;
 	const struct iwi_firmware_hdr *hdr;
-	struct firmware *fp;
+	const struct firmware *fp;
 
 	/* invalidate cached firmware on mode change */
 	if (sc->fw_mode != ic->ic_opmode)
diff --git a/sys/dev/iwi/if_iwivar.h b/sys/dev/iwi/if_iwivar.h
index 3884a3a..6b5571e 100644
--- a/sys/dev/iwi/if_iwivar.h
+++ b/sys/dev/iwi/if_iwivar.h
@@ -108,7 +108,7 @@ struct iwi_node {
 };
 
 struct iwi_fw {
-	struct firmware		*fp;		/* image handle */
+	const struct firmware	*fp;		/* image handle */
 	const char		*data;		/* firmware image data */
 	size_t			size;		/* firmware image size */
 	const char		*name;		/* associated image name */
diff --git a/sys/dev/mxge/if_mxge.c b/sys/dev/mxge/if_mxge.c
index be8ab0e..52e64f0 100644
--- a/sys/dev/mxge/if_mxge.c
+++ b/sys/dev/mxge/if_mxge.c
@@ -512,7 +512,7 @@ mxge_validate_firmware(mxge_softc_t *sc, const mcp_gen_header_t *hdr)
 static int
 mxge_load_firmware_helper(mxge_softc_t *sc, uint32_t *limit)
 {
-	struct firmware *fw;
+	const struct firmware *fw;
 	const mcp_gen_header_t *hdr;
 	unsigned hdr_offset;
 	const char *fw_data;