/* * 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: * * * @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: * * * @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: * * * @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 * *
* @n
* * * @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. * * Examples of Property Tags with Values * @n false * @n 0x10df * @n * * Examples of Property Tags without Values * @n * @n * * @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 * * Example * * 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: * *
* @n * @n * @n * @n * @n * @n
* @n * @n * @n * @n * @n
* @n * @n * @n * @n * @n * @n
* @n * @n * @n * @n * @n
* @n
* @n * @n * @n * @n * @n
* @n
* @n
* @n
* * * @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 * * typedef struct { * @n uint8_t *user_buffer; * @n uint32_t user_buffer_len; * @n uint32_t bytes_written; * @n } ocs_ioctl_mgmt_buffer_t; * * 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 * * typedef struct { * @n uint8_t *name; * @n uint8_t *value; * @n uint32_t value_length; * @n } ocs_ioctl_cmd_get_t; * * 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 * * typedef struct { * @n uint8_t *name; * @n uint8_t *value; * @n uint32_tresult; * @n } ocs_ioctl_cmd_set_t; * * 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 * * 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; * * 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. */