/*
* 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:
*
- The OCS_IOCTL_CMD_GET_STATUS_LIST command returns a list of
* the available status items.
* - The OCS_IOCTL_CMD_GET_STATUS command returns the current value for
* a particular status item.
*
* @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:
* - The OCS_IOCTL_CMD_GET_CONFIG_LIST command
* returns a list of the available configuration items.
* - The OCS_IOCTL_CMD_GET_CONFIG command returns the current value for
* a particular configuration item.
* - The OCS_IOCTL_CMD_SET_CONFIG command is used to provide a new
* value for a configuration item.
*
* @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:
* - The OCS_IOCTL_CMD_GET_ACTION_LIST command returns a list of
* the available actions.
* - The OCS_IOCTL_CMD_DO_ACTION command runs a particular action.
*
* @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
*
*
* @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.
*/