fwflash.h revision d65b419ea7828ceaecc8f2ed7188237add6b14dc
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * CDDL HEADER START
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * The contents of this file are subject to the terms of the
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * Common Development and Distribution License (the "License").
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * You may not use this file except in compliance with the License.
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * See the License for the specific language governing permissions
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * and limitations under the License.
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * When distributing Covered Code, include this CDDL HEADER in each
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * If applicable, add the following below this CDDL HEADER, with the
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * fields enclosed by brackets "[]" replaced with your own identifying
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * information: Portions Copyright [yyyy] [name of copyright owner]
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * CDDL HEADER END
87d06e46cdea545c3c673120b7211158dcfd35ccpeihong huang * Copyright 2009 Sun Microsystems, Inc. All rights reserved.
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * Use is subject to license terms.
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcpextern "C" {
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * we search for a variable (fwplugin_version, type uint32_t)
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * which should equal FWPLUGIN_VERSION_1
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * An opaque handle for dlopen()/dlclose() to use.
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * fully-qualified filename in /usr/lib/fwflash/identify
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * made up of [drivername].so
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * is the identification plugin for devices attached to
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * the host using the ses(7D) driver.
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * The driver name that this plugin will search for in
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * the device tree snapshot using di_drv_first_node(3DEVINFO)
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * and di_drv_next_node(3DEVINFO).
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * Function entry point to support the command-line "-r"
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * option - read image from device to persistent storage.
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * Not all plugins and devices will support this operation.
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp int (*fw_readfw)(struct devicelist *device, char *filename);
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * Function entry point to support the command-line "-f"
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * option - writes from persistent storage to device
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * All identification plugins must support this operation.
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp int (*fw_writefw)(struct devicelist *device, char *filename);
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * Function entry point used to build the list of valid, flashable
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * devices attached to the system using the loadable module drvname.
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * (Not all devices attached using drvname will be valid for this
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * plugin to report.
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * start allows us to display flashable devices attached with
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * different drivers and provide the user with a visual clue
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * that these devices are different to others that are detected.
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * All identification plugins must support this operation.
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * Function entry point to support the command-line "-l"
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * option - list/report flashable devices attached to the system.
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * All identification plugins must support this operation.
d65b419ea7828ceaecc8f2ed7188237add6b14dcXinChen * Function entry point to allow the plugin to clean up its
d65b419ea7828ceaecc8f2ed7188237add6b14dcXinChen * data structure use IF plugin_version == FWPLUGIN_VERSION_2.
d65b419ea7828ceaecc8f2ed7188237add6b14dcXinChen * If this function is not defined in the plugin, that is not
d65b419ea7828ceaecc8f2ed7188237add6b14dcXinChen * an error condition unless the plugin_version variable is
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * fully qualified filename in /usr/lib/fwflash/identify
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * made up of fwflash-[drivername].so
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * is the identification plugin for devices attached to
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * the host using the ses(7D) driver.
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * The driver name that this plugin will search for in
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * the device tree snapshot using di_drv_first_node(3DEVINFO)
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * and di_drv_next_node(3DEVINFO).
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * pointer to the actual plugin, so we can access its
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * function entry points
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp /* pointer to the next element in the list */
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp /* vendor ID, eg "HITACHI " */
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp /* product ID, eg "DK32EJ36NSUN36G " */
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp /* revision, eg "PQ08" */
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * Additional, encapsulated identifying information.
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * This pointer allows us to add details such as the
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * IB hba sector size, which command set should be
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * used or a part number.
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * The fully qualified filename. No default location for
d65b419ea7828ceaecc8f2ed7188237add6b14dcXinChen * the firmware image file is mandated.
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp /* Pointer to the identification plugin required */
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp /* pointer to the identification summary structure */
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp struct vpr *ident;
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * fully qualified pathname, with /devices/.... prefix
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * Which drivername did we find this device attached with
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * in our device tree walk? Eg, ses or tavor or sgen...
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * What class of device is this? For tavor-attached devices,
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * we set this to "IB". For other devices, unless there is
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * a common name to use, just make this the same as the
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * drvname field.
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp /* pointer to the VPR structure */
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp struct vpr *ident;
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * In the original fwflash(1M), it was possible to select a
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * device for flashing by using an index number called a
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * dev_num. We retain that concept for pluggable fwflash, with
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * the following change - whenever our identification plugin has
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * finished and found at least one acceptable device, we bump the
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * index number by 100. This provides the user with another key
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * to distinguish the desired device from a potentially very large
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * list of similar-looking devices.
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp unsigned int index;
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * Contains SAS or FC Port-WWNs, or IB GUIDS. Both SAS and FC only
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * need one entry in this array since they really only have one
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * address which we should track. IB devices can have 4 GUIDs
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * (System Image, Node Image, Port 1 and Port 2).
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * Pointer to the plugin needed to flash this device, and
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * to use for printing appropriate device-specific information
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * as required by the "-l" option to fwflash(1M).
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp /* Next entry in the list */
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * this type of plugin is for the firmware image vendor-specific
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * verification functions, which we load from FWVERIFYPLUGINDIR
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * made up of [drivername]-[vendorname].so
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * is the verification plugin for ses-attached devices which
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * have a vendorname of "SUN".
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * The vendor name, such as "SUN" or "MELLANOX"
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * An opaque handle for dlopen()/dlclose() to use.
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * Firmware image size in bytes, as reported by
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp unsigned int imgsize;
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * Flashable devices frequently have different buffers
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * to use for different image types. We track the buffer
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * required for this particular image with this variable.
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * Once the verifier has figured out what sort of image
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * it's been passed, it will know what value to use for
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * this variable.
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp unsigned int flashbuf;
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * Points to the entire firmware image in memory.
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * We do this so we can avoid multiple open()/close()
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * operations, and to make it easier for checksum
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * calculations.
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * We also store the name of the firmware file that
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * we point to with *fwimage. This is needed in cases
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * where we need to key off the name of the file to
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * determine whether a different buffer in the target
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * device should be targeted.
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * For example, our "standard" firmware image (file.fw)
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * might require use of buffer id 0, but a boot image
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * (boot.fw) might require use of buffer id 17. In each
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * case, it is the verifier plugin that determines the
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * specific bufferid that is needed by that firmware image.
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * The verification function entry point. The code
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * in fwflash.c calls this function to verify that
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * the nominated firmware image file is valid for
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * the selected devicenode.
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * Note that if the verification fails, the image
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * does _not_ get force-flashed to the device.
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp/* Flags for argument parsing */
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp/* global variables for fwflash */
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * utility defines and macros, since the firmware image we get
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * from LSI is ARM-format and that means byte- and short-swapping
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp * on sparc
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp (BE_64(((bs) & LOWBITS64)) | BE_64(((bs) & HIGHBITS64)))
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp#define ARMSWAPBITS(bs) (LE_32(((bs) & LOWBITS32)) | LE_32(((bs) & HIGHBITS32)))
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp/* common functions for fwflash */
f1c2346531c82ed357422b37e6c09f7b692e0c45James C. McPhersonvoid logmsg(int severity, const char *msg, ...);
5a7763bf3e9db4cfe6cb523b096cb74af71e3793jmcp#endif /* _FWFLASH_H */