/**
* @file main.doxygen
* @brief Overview page for the elxsdkutil
*
/
/** @mainpage Overview
*
* The Emulex SDK Utility (elxsdkutil)
* provides a working example of a management utility, including reference code.
* This utility can be used to incorporate similar functionality into an existing product or
* to develop a custom utility.
* The elxsdkutil is applicable to the Emulex Service Level Interface - 4
* (SLI-4) family of products (for example, Emulex LightPulse® LPe16000/LPe16002 16GFC host bus adapters).
*
* The following figure shows the high-level relationship between the elxsdkutil, a OneCore Storage driver
* (kernel space or user space), and an SLI-4 product.
*
* @image html elxsdkutil_basic.jpg "Relationship of the elxsdkutil with a OneCore Storage Driver"
*
* For detailed information about the elxsdkutil commands and design, also see
* the OneCore Storage Utilities Manual.
*
*
*
* The following figure shows the structure of the elxsdkutil.
*
* @image html elxsdkutil_structure.jpg "Structure of the elxsdkutil"
*
*/
/**
* @page elxsdkutil_commands.html CLI Commands and Their Usage
* This section describes the elxsdkutil’s command usage and details.
* The elxsdkutil provides a simple command line interface (CLI) to perform
* various functions, such as downloading firmware to the flash and retrieving dump files
* for debugging purposes.
*
* @section commands_usage_list List of Commands
*
*
*
Command
Name
Restrictions
*
@ref cmd_add_ip "add-ip"
Add IP
iSCSI only
*
@ref cmd_compare "cmp"
Compare
*
@ref cmd_connection_info "connection-info"
Connection Information
Linux and iSCSI only
*
@ref cmd_create_vport "create-vport"
Create VPort
LPe1600x HBAs only
*
@ref cmd_driver_dump "driver-dump"
Driver Dump
*
@ref cmd_driver_info "driver-info"
Driver Information
*
@ref cmd_dump "dump"
Firmware Dump
*
@ref cmd_dump_to_host "dump-to-host"
Generate Dump to Host
LPe1600x HBAs only
*
@ref cmd_efdc "efdc"
EFD Capabilities
OCe11102 adapters only
*
@ref cmd_file_info "file-info"
File Information of UFI
*
@ref cmd_gendump "gendump"
Generate Dump
LPe1600x HBAs only
*
@ref cmd_help "help"
Help
*
@ref cmd_linkcfg_get "linkcfg-get"
Get Link Configuration
LPe1600x HBAs only
*
@ref cmd_linkcfg_set "linkcfg-set"
Set Link Configuration
LPe1600x HBAs only
*
@ref cmd_list "list"
List Adapters
*
@ref cmd_mgmt_info "mgmt-info"
Management Information
*
@ref cmd_objenum "objenum"
Objects Enumerate
LPe1600x HBAs only
*
@ref cmd_read "read"
Read Object File
LPe1600x HBAs only
*
@ref cmd_read_link_status "read-link-status"
Read Link Status
LPe1600x HBAs only
*
@ref cmd_read_rev "read-rev"
Read Adapter Version
*
@ref cmd_read_status "read-status"
Read Device Status
LPe1600x HBAs only
*
@ref cmd_remove_vport "remove-vport"
Remove VPort
LPe1600x HBAs only
*
@ref cmd_set_mac "set-mac"
Set MAC Address
iSCSI only
*
@ref cmd_sfp "sfp"
SFP EEPROM Data
*
@ref cmd_show_ips "show-ips"
Show IPs
iSCSI only
*
@ref cmd_show_mac "show-mac"
Show MAC
iSCSI only
*
@ref cmd_version "version"
Version of Program
*
@ref cmd_write "write"
Write Firmware Image
*
*
*
*
* @section cmd_usage Command Usage
*
*
*
* @subsection cmd_syntax Syntax Information
* To invoke the CLI and run the elxsdkutil commands, use the following syntax:
* elxsdkutil [command] [option(s)]
* For example, to compare the data in the flash on device 2 to the data in the “myfile” file,
* use the following command:
* elxsdkutil cmp -d 2 -f myfile
*
* Syntax Notes
*
Angled brackets, “< >”, indicates a specific value to include with the option.
*
* @subsection cmd_options Common Command Options
*
* The Device Number, Filename, and Host options are used by multiple commands.
*
* @subsubsection dev_number Device Number (--device, -d)
* The Device Number option indicates the device number of the adapter’s port(s). The
* command line syntax is:
* --device
* -or-
* -d
* Where is a non-negative integer (0, 1, 2, and so on).
*
* @b Note: The default device number is 0. That is, if the devicenum is not specified for a
* command, it is assumed that the devicenum is 0.
*
* @subsubsection filename Filename (--file, -f)
* The Filename option indicates the filename for downloads, compares, saving dump
* information, and so on. The command line syntax is:
* --file
* -or-
* -f
*
* @subsubsection host_option Host (--host)
* The Host option is used with the OneCore Storage user space drivers. When using one
* of the user space drivers, this option specifies the host name or IP address of the system
* on which the user space driver is running. This option is required on all commands that
* access a device. The command line syntax is:
* --host
*
* For details on the user space drivers (Uspace ocs_fc_ramd and Uspace ocs_iscsi_ramd),
* see the latest OneCore Storage Reference Driver Manual.
*
*
* @subsection cmd_help_menu Help Menu
*
* See @ref cmd_help
*
*
*
* @section cmd_details Command Details
*
*
*
*
*
* @subsection cmd_add_ip add-ip (Add IP)
* This command adds an additional Internet Protocol (IP) address to an iSCSI adapter.
* The IP address () and network mask () values must be in the
* same IP version format, either IPv4 (###.###.###.###) or IPv6
* (####:####:####:####:####:####:####:####). Also see @ref cmd_show_ips,
*
* @b Note: This command is applicable to iSCSI adapters only.
*
* @b Syntax
* @n add-ip [-d ] [--host ]
*
* @b Example
* @n Add an additional IP address of 20.0.0.120 and net mask of 255.255.255.0 to device 2:
* elxsdkutil add-ip 20.0.0.120 255.255.255.0 -d 2
*
* @ref commands_usage_list "Back to List of Commands"
*
*
*
* @subsection cmd_compare cmp (Compare)
* This command compares the adapter flash data with the specified file data. The output
* indicates that the “Firmware verification was successful!” or the “Firmware verification
* failed,” including a list of the mismatched sections.
*
* @b Syntax
* @n cmp [-d ] -f [--host ]
*
* @b Example
* @n Compare the data stored in the device 2 flash to the data in the “myfile” file:
* @n elxsdkutil cmp -d 2 -f myfile
*
* @ref commands_usage_list "Back to List of Commands"
*
*
*
* @subsection cmd_connection_info connection-info (Connection Information)
* If a connection handle is provided, this command reports information on that
* Transmission Control Protocol (TCP) connection. If no connection handle is provided,
* this command displays a list of open TCP connections.
*
* @b Note: This command is applicable to Linux and iSCSI only.
*
* @b Syntax
* @n connection-info [-d ] [--host ]
* @n [--connection-handle ]
*
* @b Example
* @n Display information on TCP connections for device 1:
* @n elxsdkutil connection-info -d 1
*
* @ref commands_usage_list "Back to List of Commands"
*
*
*
* @subsection cmd_create_vport create-vport (Create Vport)
* This command creates a virtual port (Vport). The WWNN and WWPN values are in the
* format of eight pairs of hexadecimal digits separated by colons (for example,
* 10:00:00:00:c9:01:02:03).
*
* @b Notes
*
If values for WWNN and WWPN are not specified, then the SLI Port will assign
* the appropriate WWNN/WWPN values.
*
The syntax must include an “--initiator” or “--target,” or both.
*
This command is applicable to LPe16000/LPe16002 HBAs only
*
For the OneCore Storage SCST driver (ocs_fc_scst), this elxsdkutil command
* has no effect. To create a vport for the ocs_fc_scst driver, see section “3.2.7.1
* Creating a Virtual Port (vport)” in the OneCore Storage SCST Driver Guide,
* Revision 1.5 or later.
*
* @b Syntax
* @n create-vport [] [] [--initiator] [--target]
* @n [-d ] [--host ]
*
* @b Example
* @n Create a Vport on device 0:
* @n elxsdkutil create-vport 20:00:00:00:c9:01:02:03 10:00:00:00:c9:01:02:03 --target
*
* @ref commands_usage_list "Back to List of Commands"
*
*
*
* @subsection cmd_driver_dump driver-dump (Driver Dump)
* This command dumps the internal driver information.
*
* @b Options
* @n The following options are available for the driver-dump command.
*
If values for WWNN and WWPN are not specified, then the SLI Port will assign
* the appropriate WWNN/WWPN values.
*
bufsize – specifies the size of the memory buffer used to retrieve
* the dump. The is specified in units of bytes in the form of
* [k, M]. The default is “4M” (4 megabytes).
*
saved – dumps the contents from a previously-saved driver dump capture.
*
clrsaved – clears the previously-saved driver dump capture, so that a new one
* driver dump snapshot can be saved.
*
* Contents of various queue entries can be included in the driver dump by specifying
* the following queue options:
*
cqes – includes the contents of the completion queues entries (CQEs). It is
* dumped automatically when no queue options are specified. If other queue
* options are specified, then it is not dumped automatically.
*
eqes – includes the contents of the event queue entries (EQEs).
*
mqes – includes the contents of the mailbox queues entries (MQEs).
*
rqes – includes the contents of the receive queues entries (RQEs).
*
wqes – includes the contents of the work queues entries (WQEs). It is
* dumped automatically when no queue options are specified. If other queue
* options are specified, then it is not dumped automatically.
*
* The number of the latest queue entries can be specified using the following option:
*
qentries – specifies the number of the most recent queue
* entries to dump. To dump the entire queue, is “-1”. The
* default of is “32”.
*
* @b Syntax
* @n driver-dump [-d ] [--wqes] [--cqes] [--mqes] [--rqes]
* @n [--eqes] [--qentries ] [--host ]
* @n [--bufsize ] [--saved] [--clrsaved]
*
* @b Examples
*
* Dump the internal driver information, including the latest 32 queue entries of the CQ
* and WQ:
* @n elxsdkutil driver-dump
*
* Dump the internal driver information, including all of the CQ and WQ entries:
* @n elxsdkutil driver-dump --qentries -1
*
* Dump the internal driver information, including the latest twelve queue entries of the
* CQ, EQ, and MQ:
* @n elxsdkutil driver-dump --cqes --eqes --mqes --qentries 12
*
* @ref commands_usage_list "Back to List of Commands"
*
*
*
* @subsection cmd_driver_info driver-info (Driver Information)
* This command displays the parameters used when the driver was loaded (which may
* not be the current ones).
*
* @b Syntax
* @n driver-info [-d ] [--host ]
*
* @b Example
* @n Retrieve the module parameter values for a Linux target loaded with the ocs_fc_ramd
* driver:
* @n elxsdkutil driver-info
*
* @b Output
* ramdisc_size: 50m
* ramdisc_blocksize: 512
* num_luns: 1
* initiator: false
* target: true
* logmask: 0x0
* ctrlmask: 0x0
* wwn_bump: 0
* topology: 0
* speed: 0
* p_type: 0
* holdoff_link_online: false
* enable_hlm: false
* hlm_group_size: 8
* logdest: 1
* ramlog_size: 1048576
* hal_war_version: 0
* num_scsi_ios: 8192
* dif_separate: false
*
* @ref commands_usage_list "Back to List of Commands"
*
*
*
* @subsection cmd_dump dump (Firmware Dump)
* For LPe16000/LPe16002 HBAs, this command retrieves the dump.bin file for
* debugging purposes. The dump.bin file is generated by the @ref cmd_gendump command.
*
* For OCe11102 adapters, this command includes four dump options:
*
ecd – this Emulex core dump (ECD) option uses the XE4310R template to
* retrieve the XE4310R controller core dump diagnostic information from a device
* to a specified file. This is the default option.
*
ecdtest – this option creates an ECD test file that is used to verify the core dump
* operation. The result is a binary file that needs to be verified by Emulex.
*
efd – this option retrieves enhanced failure dump (EFD) data from the adapter
* to a specified file.
*
fat – this option retrieves failure analysis tool (FAT) data from the adapter to a
* specified file.
*
* @b Syntax
* @n dump [--fat | --efd | --ecd | --ecdtest ] [-d ]
* @n [--host ] [-f ]
*
* @b Examples
*
* For LPe16000/LPe16002 HBAs, the following example retrieves the dump.bin file from
* device 2 and saves it to the myfile file:
* @n elxsdkutil dump --ecd -f myfile
*
* For the OCe11102 adapters, the following examples show some of the command’s
* various options:
*
Use the ECD option from device 0, and save the data to the “myfile” file:
* @n elxsdkutil dump --ecd -f myfile
* @n Or since “ecd” is the default, you can simply use:
* @n elxsdkutil dump -f myfile
*
*
Save the EFD data of device 1 to the myfile file:
* @n elxsdkutil dump --efd -d 1 -f myfile
*
*
Save the FAT data of device 3 to the myfile file:
* @n elxsdkutil dump --fat -d 3 -f myfile
*
* @ref commands_usage_list "Back to List of Commands"
*
*
*
* @subsection cmd_dump_to_host dump-to-host (Generate Dump to Host)
* Enables a device to generate a dump and transfer it directly to host memory. This
* command combines the “gendump” and “dump” commands into a single operation. If
* a filename is not specified, the dump is written to the dump.bin file.
*
* @b Note: This command is applicable to LPe16000/LPe16002 HBAs only.
*
* @b Syntax
* @n dump-to-host [-d ] [--host ] [-f ]
*
* @b Example
* @n The following example generates a dump from device 2, saves it to the “myfile” file,
* and transfers this file to the host:
* @n elxsdkutil dump-to-host -d 2 -f myfile
*
* @ref commands_usage_list "Back to List of Commands"
*
*
*
* @subsection cmd_efdc efdc (EFD Capabilities)
* This command reports the EFD capabilities (firmware log settings) from the adapter.
*
* @b Note: This command is applicable to OCe11102 adapters only
*
* @b Syntax
* @n efdc [-d ] [--host ]
*
* @b Example
* @n Display the EFD capabilities of device 0:
* @n elxsdkutil efdc
*
* @ref commands_usage_list "Back to List of Commands"
*
*
*
* @subsection cmd_file_info file-info (File Information of UFI)
* This command provides information for an Emulex unified firmware image (.UFI),
* including the file signature, the version, file length, and other information.
*
* @b Syntax
* @n file-info -f
*
* @b Example
* @n Display the UFI file and image information for the myfile file:
* @n elxsdkutil file-info -f myfile
*
* @ref commands_usage_list "Back to List of Commands"
*
*
*
* @subsection cmd_gendump gendump (Generate Dump)
* This command instructs the adapter to generate a dump file. The dump file is stored on
* the adapter as the /dbg/dump.bin object. Once the dump file has been generated, it
* can be retrieved from the adapter using the dump command
* (@ref cmd_dump). Also see @ref cmd_dump_to_host.
*
* @b Note: This command is applicable to LPe16000/LPe16002 HBAs only.
*
* @b Syntax
* @n gendump
*
* @b Example
* @n Generate a dump:
* @n elxsdkutil gendump
*
* @ref commands_usage_list "Back to List of Commands"
*
*
*
* @subsection cmd_help help
* This command displays a list of the elxsdkutil commands with several examples.
* To get the syntax and usage for a particular command, add the command name.
*
* @b Syntax
* @n help []
*
* @b Example
* @n List the usage information for connection-info:
* @n elxsdkutil help connection-info
*
* @b Output
* @n Command: connection-info [-d ] [--host ]
* [--connection-handle ]
* Usage: If a connection handle is provided, reports information on
* that connection. If no connection handle is provided, displays a
* list of open connections.
*
* @ref commands_usage_list "Back to List of Commands"
*
*
*
* @subsection cmd_linkcfg_get linkcfg-get (Get Link Configuration)
* This command displays the link configuration. Also see @ref cmd_linkcfg_set.
*
* @b Note: This command is applicable to LPe16000/LPe16002 HBAs only.
*
* @b Syntax
* @n linkcfg-get [-d ] [--host ]
*
* @b Example
* @n Display the link configuration on device 0:
* @n elxsdkutil linkcfg-get
*
* @b Output
* @n Link config: FC_2x16G
*
* @ref commands_usage_list "Back to List of Commands"
*
*
*
* @subsection cmd_linkcfg_set linkcfg-set (Set Link Configuration)
* This command sets the Fibre Channel and Ethernet link configuration.
*
* The possible values are:
*
FC_2x16G
*
FC_4x1G
*
FC_4x8G
*
ETH_1x40G
*
ETH_2x10G
*
ETH_2x10G_FC_2x8G
*
ETH_4x10G
* Also see @ref cmd_linkcfg_get.
*
* @b Note: This command is applicable to LPe16000/LPe16002 HBAs only.
*
* @b Syntax
* @n linkcfg-set [-d device] [--host ] --linkcfg
*
* @b Example
* @n Set the link configuration on device 1 for two FC ports running at 16G each:
* @n elxsdkutil link-set -d 1 --linkcfg FC_2x16G
*
* @ref commands_usage_list "Back to List of Commands"
*
*
*
* @subsection cmd_list list (List Adapters)
* This command displays a list of the Emulex adapters installed in the system. This
* includes the model number, number of ports, firmware version, and serial number.
*
* @b Syntax
* @n list [--host ]
*
* @b Example
* @n List the Emulex adapters that are installed in a system:
* @n elxsdkutil list
*
* @ref commands_usage_list "Back to List of Commands"
*
*
*
* @subsection cmd_mgmt_info mgmt-info (Management Information)
* This command uses the management API (as described in @ref dev_mgmt)
* to retrieve all available status values, configuration
* values, and actions from the driver. For status, each property is displayed along with its
* current value. For actions, only the name of the action is displayed.
*
* @b Syntax
* @n mgmt-info [-d ] [--host ]
*
* @ref commands_usage_list "Back to List of Commands"
*
*
*
* @subsection cmd_objenum objenum (Objects Enumerate)
* This command enumerates the device file system objects.
*
* @b Note: This command is applicable to LPe16000/LPe16002 HBAs only.
*
* @b Syntax
* @n objenum [-d ] [--host ]
*
* @b Example
* @n List device file system objects on device 0:
* @n elxsdkutil objenum
*
* @ref commands_usage_list "Back to List of Commands"
*
*
*
* @subsection cmd_read read (Read Object File)
* This command reads an object file from an adapter’s flash.
*
* @b Note: This command is applicable to LPe16000/LPe16002 HBAs only.
*
* @b Syntax
* @n read [objname] [-d ] [-f ] [--host ]
*
* @b Example
* @n Read firmware dump file from device 0 into the “myfile” file:
* @n elxsdkutil read /dbg/dump.bin –d 0 –f myfile
*
* @ref commands_usage_list "Back to List of Commands"
*
*
*
* @subsection cmd_read_link_status read-link-status (Read Link Status)
* This command reads the status of the link. Using the “--clof” option clears the overflow
* flags and the “--clrc” option clears all counters.
*
* @b Note: This command is applicable to LPe16000/LPe16002 HBAs only.
*
* @b Syntax
* @n read-link-status [-d ] [--clof] [--clrc]
*
* @b Example
* @n Read the status of the link for device 0:
* @n elxsdkutil read-link-status
*
* @ref commands_usage_list "Back to List of Commands"
*
*
*
* @subsection cmd_read_rev read-rev (Read Adapter Version)
* This command reads the version of the adapter.
*
* @b Syntax
* @n read-rev [-d ] [--host ]
*
* @b Example
* @n Read the version of device 2:
* @n elxsdkutil read-rev -d 2
*
* @ref commands_usage_list "Back to List of Commands"
*
*
*
* @subsection cmd_read_status read-status (Read Device Status)
* This command reads the status of the device. Using the “--cc” option clears the
* counters.
*
* @b Note: This command is applicable to LPe16000/LPe16002 HBAs only.
*
* @b Syntax
* @n read-status [-d ] [--cc] [--host ]
*
* @b Example
* @n Read the status of device 0:
* @n elxsdkutil read-status
*
* @ref commands_usage_list "Back to List of Commands"
*
*
*
* @subsection cmd_remove_vport remove-vport (Remove Vport)
* This command removes a Vport. The WWNN and WWPN values are in a format of
* eight pairs of hexadecimal digits separated by colons (for example,
* 10:00:00:00:c9:01:02:03).
*
* If the WWNN and WWPN values were assigned by the SLI Port (for example, through
* @ref cmd_create_vport), these values can be found in
* /var/log/messages.
*
* @b Note: This command is applicable to LPe16000/LPe16002 HBAs only.
*
* @b Syntax
* @n remove-vport [-d ] [--host ]
*
* @b Example
* @n Remove a Vport from device 0:
* @n elxsdkutil remove 20:00:00:00:c9:01:02:03 10:00:00:00:c9:01:02:03
*
* @ref commands_usage_list "Back to List of Commands"
*
*
*
* @subsection cmd_set_mac set-mac (Set MAC Address)
* This command “soft” assigns a MAC address to a device. The MAC address is in a
* format of six pairs of hexadecimal digits separated colons, for example,
* 01:23:45:67:89:ab.
*
* @b Note: This command is applicable to iSCSI only.
*
* @b Syntax
* @n set-mac ##:##:##:##:##:## [-d ]
*
* @b Example
* @n Assign a MAC address to device 0:
* @n elxsdkutil set-mac 00:00:C9:D5:6A:A3
*
* @ref commands_usage_list "Back to List of Commands"
*
*
*
* @subsection cmd_sfp sfp (SFP EEPROM Data)
* This command retrieves the SFP serial EEPROM data. For OCe11102 adapters, the SFP
* pages A0 and A2 are returned. For LPe16000/LPe16002 HBAs, the SFP page A0 is
* returned.
*
* @b Syntax
* @n sfp [-d ] [--host ]
*
* @b Example
* @n Print hexadecimal diagnostic information from the transceiver (device 0):
* @n elxsdkutil sfp -d 0
*
* @ref commands_usage_list "Back to List of Commands"
*
*
*
* @subsection cmd_show_ips show-ips (Show IPs)
* Show the IP addresses, in IPv4 or IPv6 format, that are assigned to an iSCSI adapter.
* The value is either 4 (IPv4) or 6 (IPv6). Also see
* @ref cmd_add_ip.
*
* @b Note: This command is applicable to iSCSI only.
*
* @b Syntax
* @n show-ips [-d ] [--host ]
*
* @b Example
* @n The following sequence first shows the current IPs in IPv4 format on device 2; adds an
* additional IP address; and then shows the IPs again:
* @n elxsdkutil show-ip 4 -d 2
* @n IP addresses on device 2:
* @n 20.0.0.108 255.255.255.0
*
* elxsdkutil add-ip 20.0.0.120 255.255.255.0 -d 2
*
* elxsdkutil show-ips 4 -d 2
* @n IP addresses on device 2:
* @n 20.0.0.108 255.255.255.0
* @n 20.0.0.120 255.255.255.0
*
* @ref commands_usage_list "Back to List of Commands"
*
*
*
* @subsection cmd_show_mac show-mac (Show MAC)
* This command displays the MAC address of a device.
*
* @b Note: This command is applicable to iSCSI only.
*
* @b Syntax
* @n show-mac [-d ] [--host ]
*
* @b Example
* @n Display the MAC address of device 3:
* @n elxsdkutil show-mac -d 3
*
* @ref commands_usage_list "Back to List of Commands"
*
*
*
* @subsection cmd_version version (Version of Program)
* This command prints the program version and exits.
*
* @b Syntax
* @n version [--host ]
*
* @b Example
* @n Print the program version:
* @n elxsdkutil version
*
* @ref commands_usage_list "Back to List of Commands"
*
*
*
* @subsection cmd_write write (Write Firmware Image)
* This command downloads firmware from a file to the adapter’s flash.
*
* @b Syntax
* @n write -f [-d ] [--host ]
*
* @b Example
* @n Write firmware image to device 0:
* @n elxsdkutil write -f myfile -d 0
*
* @ref commands_usage_list "Back to List of Commands"
*
*
*
*