/* **********************************************************
 * Copyright 2013 VMware, Inc.  All rights reserved.
 * **********************************************************/

/*
 * @VMKAPIMOD_LICENSE@
 */

/*
 ***********************************************************************
 * Portset                                                        */ /**
 * \addtogroup Network
 * @{
 * \defgroup Portset Interface
 *
 * Portsets are groups of ports which, together with policies for frame
 * routing, form virtual networks. Virtual nics connected to the ports
 * may forward packets to each other. The analogy is to a box (like a
 * a hub or a switch) containing some type of backplane for connecting
 * multiple ports in the physical world.
 *
 * @{
 ***********************************************************************
 */

#ifndef _VMKAPI_NET_PORTSET_H_
#define _VMKAPI_NET_PORTSET_H_

/** \cond never */
#ifndef VMK_HEADER_INCLUDED_FROM_VMKAPI_H
#error This vmkapi file should never be included directly but only via vmkapi.h
#endif
/** \endcond never */

#include "net/vmkapi_net_types.h"
#include "net/vmkapi_net_uplink.h"


/*
 ***********************************************************************
 * vmk_PortsetAddUplink --                                        */ /**
 *
 * \brief Request to add an uplink to a portset.
 *
 * An vswitch implementation can use this API to add a named uplink to a
 * named portset.
 *
 * Vmkernel will connect the uplink to the relevant portset and enable
 * the port if connection is successful.
 *
 * \note This API is not to be used for VDS based vswitch. The operation
 *       will be triggered automatically from user space for VDS vswitch.
 *
 * \note If the uplink is already associated with a vSwitch, the operation
 *       may fail.
 *
 * \note The portset must be activated.
 *
 * \note Shouldn't be holding any handles to the portset.
 *
 * \note This function will not block.
 *
 * \param[in]  psName           portset name.
 * \param[in]  uplinkDevName    uplink device name (vmnic*)
 * \param[out] portID           This is optional, the portID the uplink
 *                              connect to.
 *
 * \retval VMK_BAD_PARAM        psName or uplinkDevName is NULL.
 * \retval VMK_NOT_FOUND        uplinkDevName not found
 * \retval VMK_BUSY             the uplink already connected to a portset
 * \retval VMK_LIMIT_EXCEEDED   no more port for the uplink.
 * \retval VMK_NO_MEMORY        memory allocation failure
 * \retval VMK_OK               Successfully add the uplink to the
 *                              portset.
 *
 ***********************************************************************
 */

VMK_ReturnStatus vmk_PortsetAddUplink(char *psName,
                                      char *uplinkDevName,
                                      vmk_SwitchPortID *portID);

/*
 ***********************************************************************
 * vmk_PortsetRemoveUplink --                                     */ /**
 *
 * \brief Request to remove an uplink from a portset.
 *
 * An vswitch implementation can use this API to remove a named uplink
 * from a named portset.
 *
 * Vmkernel will disable the uplink and disconnect from the relevant
 * portset.
 *
 * \note This API is not to be used for VDS based vswitch. The operation
 *       will be triggered automatically from user space.
 *
 * \note Shouldn't be holding any handles to the portset.
 *
 * \note The portset must be activated.
 *
 * \note This function will not block.
 *
 * \param[in]  psName           portset name.
 * \param[in]  uplinkDevName    uplink device name (vmnic*)
 *
 * \retval VMK_BAD_PARAM        psName or uplinkDevName is NULL.
 * \retval VMK_NOT_FOUND        named portset not found
 * \retval VMK_FAILURE          other errors.
 * \retval VMK_OK               The relevant uplink is removed from the
 *                              portset.
 *
 ***********************************************************************
 */

VMK_ReturnStatus vmk_PortsetRemoveUplink(char *psName,
                                         char *uplinkDevName);


/*
 ***********************************************************************
 * vmk_PortsetCreate --                                           */ /**
 *
 * \brief Request to create a portset
 *
 * External module can use this API to create a portset with a specific
 * calass.
 *
 * Vmkernel will create and activate a portset
 *
 * \note This API is not to be used for VDS based vswitch. The operation
 *       will be triggered automatically from user space.
 *
 * \note Shouldn't be holding any handles to the portset.
 *
 * \note This function will not block.
 *
 * \param[in]  psName           portset name.
 * \param[in]  className        portset class name.
 * \param[in]  numPorts         number of ports the new portset supports.
 * \param[in]  flags            reserved, set to zero
 *
 * \retval VMK_BAD_PARAM        psName or className is NULL or className
 *                              is null string
 * \retval VMK_NOT_SUPPORTED    The request portset class not found
 * \retval VMK_EXIST            portset with the request psName exists.
 * \retval VMK_NO_RESOURCES     no free portset available.
 * \retval VMK_LIMIT_EXCEEDED   the request numPort exceed the supported
 *                              limit.
 * \retval VMK_NO_MEMORY        memory allocation failure
 * \retval VMK_OK               Successfully create a portset.
 *
 ***********************************************************************
 */

VMK_ReturnStatus vmk_PortsetCreate(char *psName,
                                   char *className,
                                   vmk_uint32 numPorts,
                                   vmk_uint32 flags);

/*
 ***********************************************************************
 * vmk_PortsetDestroy --                                          */ /**
 *
 * \brief Request to destroy a portset
 *
 * External module can use this API to destroy a named portset.
 *
 * VMKernel will try to first disconnect all ports and deactivate the
 * portset.
 *
 * \note This API is not to be used for VDS based vswitch. The operation
 *       will be triggered automatically from user space.
 *
 * \note Shouldn't be holding any handles to the portset.
 *
 * \note This function will not block.
 *
 * \note All connected port will be disconnected. Normally the caller
 *       shoild make sure all clients are disabled and disconnected.
 *
 * \param[in]  psName           portset name.
 *
 * \retval VMK_BAD_PARAM        psName is NULL or length is too large.
 * \retval VMK_NOT_FOUND        named portset not found
 * \retval VMK_OK               Successfully destroyed the portset.
 *
 ***********************************************************************
 */

VMK_ReturnStatus vmk_PortsetDestroy(char *psName);


/*
 ***********************************************************************
 * vmk_PortsetGetMTU --                                           */ /**
 *
 * \brief Get MTU setting on a portset
 *
 * \nativedriversdisallowed
 *
 * \note This function will not block.
 *
 * \note The caller should hold at least an immutable portset handle
 *
 * \param[in]     ps             Handle to a portset
 * \param[out]    mtu            MTU setting on the portset
 *
 * \retval     VMK_OK         Success.
 * \retval     VMK_BAD_PARAM  An argument is NULL.
 * \retval     VMK_FAILURE    Improper portset handle is held
 *
 ***********************************************************************
 */
VMK_ReturnStatus vmk_PortsetGetMTU(vmk_Portset *ps,
                                   vmk_uint32 *mtu);

#endif /* _VMKAPI_NET_PORTSET_H_ */
/** @} */
/** @} */