Specification update for Pluggable fwflash [PSARC/2009/163 FastTrack timeout 03/16/2009]

[James Carlson]

Alan Hargreaves writes:
>     and if an identification plugin defines
> 
> 	unsigned int plugin_version = FWPLUGIN_VERSION_2;
> 
>     in its struct fw_plugin definition, then the fwflash cleanup function

I don't think I understand that.  First of all (as a nit), 2008/151
didn't include versioning, so it'd be good to describe how it works
here.

Reading the existing header file, it seems that plugins must define a
uint32_t variable (not a struct) that has the name "fwplugin_version",
and that's what's used for the versioning, not "plugin_version" as
above.

Is that correct, or are there other changes here?  Does the integer
change to a structure?  Is there a new variable?

I would have expected just a new #define.

> 	int (*fw_cleanup)(struct devicelist *thisdev);
>     
>     It is an error condition for an identification plugin to define
>     plugin_version >= FWPLUGIN_VERSION_2, and to not also define the
>     fw_cleanup() function.

One tiny nit here: I think you'd probably be better off making it so
that plugins simply use FWPLUGIN_VERSION_CURRENT, and the framework
calls fw_cleanup if the version is >=2 and the function pointer is
non-NULL.

That way, old plugins will correctly inform the framework that they've
been compiled with an old version of this structure (and thus the new
fw_cleanup member is located one word off the end) by saying version
1, and new plugins that don't need to clean anything up won't be
forced into providing a dummy function.

(The real issue here is that structures like this should be allocated
by the framework so that you don't have to bump a version number when
new members are allocated.  The versioning needs to be tied with the
allocation of space for that structure.  But I guess it's too late to
fix that ...)

-- 
James Carlson, Solaris Networking              <james.d.carlson at sun.com>
Sun Microsystems / 35 Network Drive        71.232W   Vox +1 781 442 2084
MS UBUR02-212 / Burlington MA 01803-2757   42.496N   Fax +1 781 442 1677