elxu_mgmt.h

Go to the documentation of this file.

/*
 * Copyright (c) 2011-2015, Emulex
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *
 * 1. Redistributions of source code must retain the above copyright notice,
 *    this list of conditions and the following disclaimer.
 *
 * 2. Redistributions in binary form must reproduce the above copyright notice,
 *    this list of conditions and the following disclaimer in the documentation
 *    and/or other materials provided with the distribution.
 *
 * 3. Neither the name of the copyright holder nor the names of its contributors
 *    may be used to endorse or promote products derived from this software
 *    without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGE.
 *
 */

#ifndef __ELXU_MGMT_H__
#define __ELXU_MGMT_H__

#include "elxu_device.h"

/* Structures and functions used by driver / device management  */

/**
 * @brief mgmt_property is a name / value pair
 */
typedef struct mgmt_property {
    char *name;
    char *value;
    char *access;
    struct mgmt_property *next;
} mgmt_property_t;

/**
 * @brief mgmt_object is a list of properties
 */
typedef struct mgmt_object {
    struct mgmt_property *head;
    struct mgmt_object *next;
} mgmt_object_t;

/**
 * @brief mgmt_list is a  linked list of objects
 */
typedef struct mgmt_list {
    struct mgmt_object *head;
} mgmt_list_t;

extern char* mgmt_get_value(elxu_device_t *device, char *name);
extern int mgmt_set_value(elxu_device_t *device, char *name, char *value);
extern mgmt_list_t* mgmt_get_all(elxu_device_t* device);
extern int mgmt_exec(elxu_device_t *device, char *name, void* arg_in, int arg_in_len, void* arg_out, int arg_out_len);
void elxu_mgmt_info(elxu_device_t *device);

/* Helper functions */
extern mgmt_list_t* mgmt_new_list();
extern void mgmt_delete_list(mgmt_list_t *list);
extern void mgmt_list_add(mgmt_list_t *list, mgmt_object_t *object);
extern mgmt_object_t *mgmt_list_remove(mgmt_list_t *list, char *name);
extern void mgmt_list_sort(mgmt_list_t *list);
extern int mgmt_list_is_empty(mgmt_list_t *list);

extern mgmt_property_t *mgmt_new_property(char *name, char *value, char *access);
extern void mgmt_delete_property(mgmt_property_t *prop);

extern mgmt_object_t *mgmt_new_object();
extern void mgmt_delete_object(mgmt_object_t *obj);
extern void mgmt_object_add_property(mgmt_object_t *obj, char *name, char *value, char *access);

#endif

/**
* @page dev_mgmt.html Device Management API
*
* \li @ref mgmt_status
* \li @ref mgmt_config
* \li @ref mgmt_actions
* \li @ref data_formats
* \li @ref list_properties
* \li @ref ident_indiv_prop
* \li @ref data_structures
*
* The elxu_mgmt.c file contains helper functions for accessing the driver's device management API.
* Functions are provided to retrieve the various lists, parse and display results, and get
* individual status and configuration values.
*
* The OneCore Storage drivers provide an interface for managing the driver and the
* controlled device. This device management API consists of a set of seven IOCTL commands which can be
* used to query the driver for current state, update configuration values, and request that
* the driver perform management actions.
*
* @section mgmt_status Management Status
*
* A Status item is read-only information provided by the driver. This might include
* information about the driver, about the device being controlled by the driver, or
* dynamic information, such as currently open connections.
*
* The IOCTLs used to list and get status include:
* <ul class="devmgmt"><li>The OCS_IOCTL_CMD_GET_STATUS_LIST command returns a list of
* the available status items.</li>
* <li>The OCS_IOCTL_CMD_GET_STATUS command returns the current value for
* a particular status item.</li></ul>
*
* @section mgmt_config Management Configuration
*
* Configuration items are those which can be written or updated by the user. This might
* include debug settings, MAC addresses, world wide names, port speed, topology, and
* so on.
*
* The IOCTLs used to list, get status, and set values include:
* <ul class="devmgmt"><li>The OCS_IOCTL_CMD_GET_CONFIG_LIST command
* returns a list of the available configuration items.</li>
* <li>The OCS_IOCTL_CMD_GET_CONFIG command returns the current value for
* a particular configuration item.</li>
* <li>The OCS_IOCTL_CMD_SET_CONFIG command is used to provide a new
* value for a configuration item.</li></ul>
*
* @section mgmt_actions Management Actions
*
* Actions are functions which the driver can perform when requested by the user.
* Examples include firmware download, dump retrieval, and the starting and stopping
* of links.
*
* The IOCTLs used to list and perform actions include:
* <ul class="devmgmt"><li>The OCS_IOCTL_CMD_GET_ACTION_LIST command returns a list of
* the available actions.</li>
* <li>The OCS_IOCTL_CMD_DO_ACTION command runs a particular action.</li></ul>
*
* @section data_formats Data Formats
*
* Information passed from the driver to the user is presented in the form of an XML
* document. The user provides a buffer into which to store the response and the driver
* fills in the buffer. The structure of the XML document mirrors that of the OneCore
* Storage driver stack, which is a hierarchy of ocs, domain, node, sport, and IO.
*
* The XML document is made up of two kinds of elements: “section” and “property”. A
* “section” represents a collection of other elements, and can contain properties and
* other sections. A “property” has a name and a value.
*
* @subsection section_tags Section Tags
*
* The section tag contains the name of the section as an attribute, and is used to represent
* a level in the driver hierarchy: ocs, domain, node, and so on. The section name may
* have a number designating a particular instance of that type of section. For example, a
* sport could have three nodes named node0, node1, and node2.
*
* @subsubsection section_tags_eg Examples of Section Tags
*
* <tt><section name="ocs"></tt>
* @n <tt><section name="node2"></tt>
*
*
* @subsection property_tags Property Tags
*
* The property tag has a name attribute that indicates the name of the property. The
* contents of the tag are optional and, if present, contain the value of the property. Values
* can be in one of three formats: integer, boolean, or text. A text value is surrounded by
* quotes, a boolean is either “false” or “true”, and an integer value is a number with an
* optional leading “0x” to indicate hexadecimal.
*
* <b>Examples of Property Tags with Values</b>
* @n <tt><property name="is_loop">false</property></tt>
* @n <tt><property name="pci_vendor">0x10df</property></tt>
* @n <tt><property name="sn”>”FC23130739"</property></tt>
*
* <b>Examples of Property Tags without Values</b>
* @n <tt><property name="ox_id"&nbsp;/></tt>
* @n <tt><property name="wwpn"&nbsp;/></tt>
*
* @section list_properties Lists of Properties
*
* The APIs that request a list of items (OCS_IOCTL_CMD_GET_STATUS_LIST(),
* OCS_IOCTL_CMD_GET_CONFIG_LIST(), OCS_IOCTL_CMD_GET_ACTION_LIST())
* return a document which contains all of the available section names and property
* names, but no values.
* Example
*
* <b>Example</b>
*
* The following figure shows the driver's structure
* @image html driver_structure.jpg "Figure - Driver Structure"
*
* The following list shows the result of OCS_IOCTL_CMD_GET_STATUS_LIST() for the
* driver structure:
*
* <tt><section name="ocs">
* @n <property name="desc"&nbsp;/>
* @n <property name="fw_rev"&nbsp;/>
* @n <property name="wwnn"&nbsp;/>
* @n <property name="wwpn"&nbsp;/>
* @n <property name="sn"&nbsp;/>
* @n <section name="domain0">
* @n <property name="indicator"&nbsp;/>
* @n <property name="attached"&nbsp;/>
* @n <property name="is_loop"&nbsp;/>
* @n <property name="display_name"&nbsp;/>
* @n <section name="sport0">
* @n <property name="display_name"&nbsp;/>
* @n <property name="is_vport"&nbsp;/>
* @n <property name="enable_ini"&nbsp;/>
* @n <property name="enable_tgt"&nbsp;/>
* @n <property name="p2p"&nbsp;/>
* @n <section name="node0">
* @n <property name="display_name"&nbsp;/>
* @n <property name="indicator"&nbsp;/>
* @n <property name="fc_id"&nbsp;/>
* @n <property name="attached"&nbsp;/>
* @n </section>
* @n <section name="node1">
* @n <property name="display_name"&nbsp;/>
* @n <property name="indicator"&nbsp;/>
* @n <property name="fc_id"&nbsp;/>
* @n <property name="attached"&nbsp;/>
* @n </section>
* @n </section>
* @n </section>
* @n </section></tt>
*
*
* @section ident_indiv_prop Identifying Individual Properties
*
* The user can specify a particular property in the structure by listing the path to that
* property, using a period as a level separator. Using the example in @ref list_properties,
* the user can refer to the display_name property for node1 as
* “ocs.domain0.sport0.node1.display_name”.
* This is used for OCS_IOCTL_CMD_GET_STATUS(), OCS_IOCTL_CMD_GET_CONFIG(),
* OCS_IOCTL_CMD_SET_CONFIG(), and OCS_IOCTL_CMD_DO_ACTION() functions.
*
*
* @section data_structures Data Structures
* The following data structures are used to pass data between the user application and
* the driver.
*
* @subsection ocs_ioctl_mgmt_buffer_structure ocs_ioctl_mgmt_buffer_t
*
* <tt>typedef struct {
* @n uint8_t *user_buffer;
* @n uint32_t user_buffer_len;
* @n uint32_t bytes_written;
* @n } ocs_ioctl_mgmt_buffer_t;</tt>
*
* This structure is used by the list functions OCS_IOCTL_CMD_GET_STATUS_LIST(),
* OCS_IOCTL_CMD_GET_CONFIG_LIST(), and
* OCS_IOCTL_CMD_GET_ACTION_LIST() functions. The user provides a pointer to a buffer and
* the length of the buffer. The ioctl writes an XML document into the buffer and set
* bytes_written to the size of the response.
*
* @subsection ocs_ioctl_cmd_get_structure ocs_ioctl_cmd_get_t
*
* <tt>typedef struct {
* @n uint8_t *name;
* @n uint8_t *value;
* @n uint32_t value_length;
* @n } ocs_ioctl_cmd_get_t;</tt>
*
* This structure is used by the OCS_IOCTL_CMD_GET_STATUS() and
* OCS_IOCTL_CMD_GET_CONFIG() functions. The user provides the name of the
* property to retrieve, a buffer into which to put the response, and the size of the buffer.
* The ioctl fills the buffer with an XML document containing only that property along
* with its containing hierarchy.
*
* @subsection ocs_ioctl_cmd_set_structure ocs_ioctl_cmd_set_t
*
* <tt>typedef struct {
* @n uint8_t *name;
* @n uint8_t *value;
* @n uint32_tresult;
* @n } ocs_ioctl_cmd_set_t;</tt>
*
* This structure is used by the OCS_IOCTL_CMD_SET_CONFIG() function. The user
* provides the name of a property and the new value for that property. The function sets
* the result field to 0 on success or non-zero if the operation failed.
*
* @subsection ocs_ioctl_cmd_action_structure ocs_ioctl_cmd_action_t
*
* <tt>typedef struct {
* @n uint8_t*name;
* @n void*arg_in;
* @n uint32_targ_in_length;
* @n void*arg_out;
* @n uint32_targ_out_length;
* @n uint32_tresult;
* @n } ocs_ioctl_action_t;</tt>
*
* This structure is used by the OCS_IOCTL_CMD_DO_ACTION() function. The user
* provides the name of the action, a buffer with input arguments, and a buffer for output
* arguments. Depending on the action the buffers may be NULL if they are not used. For
* example, the “gendump” action requires no arguments so arg_in and arg_out are
* NULL. The “firmware_write” action requires a firmware image so arg_in points to that
* image and arg_out is NULL.
*
* On completion of the action, the result field is 0 for success and non-zero for an error.
*/