I am sponsoring this Update Fast Track for behalf of James McPherson.
Template Version: @(#)sac_nextcase 1.68 02/23/09 SMI
This information is Copyright 2009 Sun Microsystems
1. Introduction
1.1. Project/Component Working Name:
Specification update for Pluggable fwflash
1.2. Name of Document Author/Supplier:
Author: James McPherson
1.3 Date of This Document:
08 March, 2009
4. Technical Description
Title
-----
Specification update for Pluggable fwflash(1M) PSARC/2008/151
Problem
-------
PSARC/2008/151 introduced Pluggable fwflash(1M), and defined a plugin
architecture to make supporting new hardware a straight-forward task.
It has become apparent as new plugins are defined that there are some
limitations in the existing specification, which requires updating.
Limitation #1 is that the identification plugin does not have a means
of managing its own memory. This opens the door to plugin memory leaks,
and core dumps if memory needs to be allocated inside the plugin rather
than depending on an external library which provides its own memory
management.
Limitation #2 is that when we have many different possible VENDOR types
reported for a driver (eg, SEAGATE, HITACHI, SAMSUNG, IBM....), then
we could create a link farm in /usr/lib/fwflash/verify for every possible
name, but this is tiresome and requires continual maintenance as new devices
or vendors are supported.
While writing a plugin to support flashing disks attached via sd(7D), we
discovered that there are some SATA disks which report their vendor
property inconsistently with others.
For example, note the inquiry-vendor-id for this Seagate 320Gb SATA disk:
name='inquiry-product-id' type=string items=1
value='ST3320620AS'
name='inquiry-device-type' type=int items=1
value=00000000
name='inquiry-revision-id' type=string items=1
value='3.AAK'
name='inquiry-vendor-id' type=string items=1
value='ST3320620AS'
name='pm-capable' type=int items=1
value=00000001
name='sas-mpt' type=boolean
name='compatible' type=string items=5
value='scsiclass,00.vATA.pST3320620AS.rK' +
'scsiclass,00.vATA.pST3320620AS' +
'scsa,00.bmpt' + 'scsiclass,00' + 'scsiclass'
Compared with a Samsung 320Gb SATA disk:
name='inquiry-revision-id' type=string items=1
value='CP100-12'
name='inquiry-product-id' type=string items=1
value='HD321KJ'
name='inquiry-vendor-id' type=string items=1
value='SAMSUNG'
name='pm-capable' type=int items=1
value=00000001
name='guid' type=string items=1
value='50000f001bb01248'
name='sas-mpt' type=boolean
name='port-wwn' type=byte items=8
value=48.12.b0.1b.00.0f.00.50
name='target-port' type=string items=1
value='4812b01b000f0050'
name='compatible' type=string items=5
value='scsiclass,00.vATA.pSAMSUNG_HD321KJ.r0-12' +
'scsiclass,00.vATA.pSAMSUNG_HD321KJ' +
'scsa,00.bmpt' + 'scsiclass,00' + 'scsiclass'
Also note the inquiry-revision-id property, which in both cases differs from
what is specified in the first 'compatible' property.
Just using libdevinfo properties to identify these devices results in
reporting information which is not as correct as possible, and which may
confuse the user:
Device[0] /dev/dsk/c4t5000CCA00510A7CCd0s2
Class [sd]
Vendor : HITACHI
Product : HUS1514SBSUN146G
Firmware revision : SA02
Inquiry Serial Number : 000742B94YPC J4V94YPC
GUID : 5000cca00510a7cc
...
Device[5] /dev/dsk/c3t5d0s2
Class [sd]
Vendor : SAMSUNG
Product : HD321KJ
Firmware revision : CP100-12
Inquiry Serial Number : S0MQJ1KPB01248
GUID : 50000f001bb01248
...
Device[7] /dev/dsk/c3t7d0s2
Class [sd]
Vendor : ST3320620AS
Product : ST3320620AS
Firmware revision : 3.AAK
Inquiry Serial Number : 6QF1N2MN
GUID : (not supported)
Allowing the identification plugin to manage its own memory allows us
to report more correct information for such devices, based on the
'compatible' property:
Device[5] /dev/dsk/c3t5d0s2
Class [sd]
Vendor : SAMSUNG
Product : HD321KJ
Firmware revision : 0-12
Inquiry Serial Number : S0MQJ1KPB01248
GUID : 50000f001bb01248
...
Device[7] /dev/dsk/c3t7d0s2
Class [sd]
Vendor : SEAGATE
Product : ST3320620AS
Firmware revision : K
Inquiry Serial Number : 6QF1N2MN
GUID : (not supported)
Proposed solution
-----------------
The proposal has two elements:
#1. Allow verification plugins to be named in the form
drivername-GENERIC.so
which will be used as a fallback filename option in the
verification loader. (For example, "sd-GENERIC.so"). This removes
the need for a link farm in /usr/lib/fwflash/verify and decreases
the maintenance burden.
#2. Add two definitions to fwflash.h. Firstly
#define FWPLUGIN_VERSION_2 2
and if an identification plugin defines
unsigned int plugin_version = FWPLUGIN_VERSION_2;
in its struct fw_plugin definition, then the fwflash cleanup function
will invoke the plugin cleanup function at the appropriate point:
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.
Diffs for <fwflash/fwflash.h> are found below.
Stability classifications
-------------------------
The precursor to this case, PSARC/2008/151 Pluggable fwflash(1m), indicated
that struct fw_plugin was Committed. This classification remains current.
Manpage changes
---------------
No manpage changes are required for this change.
<fwflash/fwflash.h> diffs
-------------------------
--- a/usr/src/cmd/fwflash/common/fwflash.h Tue Oct 14 20:37:29 2008 -0700
+++ b/usr/src/cmd/fwflash/common/fwflash.h Wed Mar 04 17:44:22 2009 +1000
@@ -19,7 +19,7 @@
* CDDL HEADER END
*/
/*
- * Copyright 2008 Sun Microsystems, Inc. All rights reserved.
+ * Copyright 2009 Sun Microsystems, Inc. All rights reserved.
* Use is subject to license terms.
*/
@@ -57,7 +57,8 @@
*/
#define FWPLUGIN_VERSION_1 1
-
+#define FWPLUGIN_VERSION_2 2
+
struct devicelist;
struct fw_plugin {
@@ -120,6 +121,16 @@
* All identification plugins must support this operation.
*/
int (*fw_devinfo)(struct devicelist *thisdev);
+
+ /*
+ * Function entry point to allow the plugin to clean up its
+ * data structure use IF plugin_version == FWPLUGIN_VERSION_2.
+ *
+ * If this function is not defined in the plugin, that is not
+ * an error condition unless the plugin_version variable is
+ * defined.
+ */
+ void (*fw_cleanup)(struct devicelist *thisdev);
};
6. Resources and Schedule
6.4. Steering Committee requested information
6.4.1. Consolidation C-team Name:
ON
6.5. ARC review type: FastTrack
6.6. ARC Exposure: open
