/* **********************************************************
 * Copyright 2006-2010,2012 VMware, Inc.  All rights reserved.
 * **********************************************************/

/*
 * @VMKAPIMOD_LICENSE@
 */

/*
 ***********************************************************************
 * NetPoll                                                        */ /**
 * \addtogroup Network
 *@{
 * \defgroup NetPoll NetPoll
 *@{
 *
 * \par NetPoll:
 *
 * Create and access poll data structure for network devices. The net
 * poll routine polls packet from the device and pushes those packets
 * up the stack. It also performs tx completions for the device.
 *
 * The poll is initialized using vmk_NetPollCreate and takes two
 * callbacks. The first callback is used to poll packets from the
 * network device. Once the packets has been polled, the net poll
 * routine will either use the default push processing or call the
 * second callback to do custom push processing for these packets.
 * Once the poll is activated it will run while there are packets to
 * be processed.
 *
 ***********************************************************************
 */

#ifndef _VMKAPI_NET_POLL_H_
#define _VMKAPI_NET_POLL_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_pktlist.h"

/**
 * \ingroup NetPoll
 * \brief Net poll features.
 */
typedef enum {
   /**
    * \brief Use default push routine.
    */
   VMK_NETPOLL_NONE = 0,

   /**
    * \brief Use custom push routine.
    */
   VMK_NETPOLL_CUSTOM_DELIVERY_CALLBACK = 1,
} vmk_NetPollFeatures;

/**
 * \ingroup NetPoll
 * \brief Net poll state.
 */
typedef enum {
   /**
    * \brief Net poll is disabled.
    */
   VMK_NETPOLL_DISABLED = 0,

   /**
    * \brief Net poll is running or scheduled.
    */
   VMK_NETPOLL_ACTIVE = 1,
} vmk_NetPollState;


/**
 * \brief Net poll object.
 */
typedef struct vmk_NetPollInt *vmk_NetPoll;

/*
 ***********************************************************************
 * vmk_NetPollCallback --                                         */ /**
 *
 * \ingroup NetPoll
 * \brief Poll routine for the device
 *
 * \param[in] priv       Private data structure for device poll routine.
 * \param[in] budget     Maximum number of packets to be processed in
 *                       each invocation
 *
 * \retval               Whether to poll the device for more packets.
 *
 ***********************************************************************
 */

typedef vmk_Bool (*vmk_NetPollCallback) (vmk_AddrCookie priv,
                                         vmk_uint32 budget);

/*
 ***********************************************************************
 * vmk_NetPollDeliveryCallback --                                 */ /**
 *
 * \ingroup NetPoll
 * \brief Custom push routine for processing the packets received.
 *
 * \param[in] rxPktList  Packet list for the custom push routine.
 * \param[in] priv       Private data structure for device poll routine
 *
 ***********************************************************************
 */

typedef void (*vmk_NetPollDeliveryCallback) (vmk_PktList rxPktList,
                                             vmk_AddrCookie priv);

/**
 * \ingroup NetPoll
 * \brief Net poll initialization variables.
 */

typedef struct vmk_NetPollProperties {
   /**
    * \brief Device poll routine.
    */
   vmk_NetPollCallback poll;

   /**
    * \brief Custom device push routine.
    *
    * If this parameter is not NULL and
    * NETPOLL_CUSTOM_DELIVERY_Callback is set in the
    * features parameter then packets
    * will NOT be pushed up to the vmkernel
    * networking stack, they will be passed to this
    * callback instead.
    */
    vmk_NetPollDeliveryCallback deliveryCallback;

   /**
    * \brief Poll private data handler.
    */
   vmk_AddrCookie priv;

   /**
    * \brief Poll features.
    */
   vmk_NetPollFeatures features;
} vmk_NetPollProperties;

/*
 ***********************************************************************
 * vmk_NetPollActivate --                                         */ /**
 *
 * \ingroup NetPoll
 * \brief Activate the poll thread.
 *
 * The poll thread calls the device callback for polling packets.
 * These packets are pushed up the stack by the default push routine
 * or the custom callback used during the initialization. The poll
 * thread continues to push packets while the device has pending packets.
 *
 * \param[in] netPoll          Handler for the net poll.
 *
 * \retval VMK_OK              Success.
 * \retval VMK_INVALID_HANDLE  Invalid poll context.
 * \retval VMK_FAILURE         Poll could not be activated.

 ***********************************************************************
 */

VMK_ReturnStatus vmk_NetPollActivate(vmk_NetPoll netPoll);

/*
 ***********************************************************************
 * vmk_NetPollDeliveryCallbackSet --                              */ /**
 *
 * \ingroup NetPoll
 * \brief Set new delivery callback for net poll handler.
 *
 * Net poll routine will use the new callbacks.
 *
 * \param[in] netPoll          Handler for the net poll.
 * \param[in] init             New properties for the poll handler.
 *
 * \retval VMK_OK              Success.
 * \retval VMK_INVALID_HANDLE  Invalid poll context.
 *
 ***********************************************************************
 */

VMK_ReturnStatus vmk_NetPollDeliveryCallbackSet(vmk_NetPoll netPoll,
                                                vmk_NetPollProperties *init);

/*
 ***********************************************************************
 * vmk_NetPollDeliveryCallbackClear --                            */ /**
 *
 * \ingroup NetPoll
 * \brief Clear new delivery callback for net poll handler.
 *
 * Net poll routine will use the new callbacks.
 *
 * \param[in] netPoll          Handler for the net poll.
 *
 * \retval VMK_OK              Success.
 * \retval VMK_INVALID_HANDLE  Invalid poll context.
 *
 ***********************************************************************
 */

VMK_ReturnStatus vmk_NetPollDeliveryCallbackClear(vmk_NetPoll netPoll);


/*
 ***********************************************************************
 * vmk_NetPollCheckState --                                       */ /**
 *
 * \ingroup NetPoll
 * \brief Get the poll state.
 *
 * The state indicates whether the poll is active or suspended.
 *
 * \param[in] netPoll          Handler for the net poll.
 * \param[out] state           The state of the poll.
 *
 * \retval VMK_OK              Success.
 * \retval VMK_INVALID_HANDLE  Invalid poll context.
 *
 ***********************************************************************
 */

VMK_ReturnStatus vmk_NetPollCheckState(vmk_NetPoll netPoll,
                                       vmk_NetPollState *state);

/*
 ***********************************************************************
 * vmk_NetPollDestroy --                                          */ /**
 *
 * \ingroup NetPoll
 * \brief Destroy the poll thread.
 *
 * Destroys the netpoll synchronously by waiting for any active netpoll
 * context to complete processing packets and issueing poll callbacks
 *
 * \param[in] netPoll     Handler for the net poll.
 *
 ***********************************************************************
 */

void vmk_NetPollDestroy(vmk_NetPoll netPoll);

/*
 ************************************************************************
 * vmk_NetPollGetCurrent --                                        */ /**
 *
 * \ingroup NetPoll
 * \brief Get the current executing net poll context.
 *
 * \param[out] netPoll          Handler for the poll.
 *
 * \retval VMK_OK               Success.
 * \retval VMK_INVALID_HANDLE   Invalid poll context.
 *
 ***********************************************************************
 */

VMK_ReturnStatus vmk_NetPollGetCurrent(vmk_NetPoll *netPoll);

/*
 ************************************************************************
 * vmk_NetPollGetPrivate --                                        */ /**
 *
 * \ingroup NetPoll
 * \brief Return the private data registered for the device callback.
 *
 * \param[in] netPoll      Handler for the net poll.
 *
 * \return                 Void address registered with the
 *                         device callback.
 *
 ***********************************************************************
 */

vmk_AddrCookie vmk_NetPollGetPrivate(vmk_NetPoll netPoll);

/*
 ***********************************************************************
 * vmk_NetPollCreate --                                           */ /**
 *
 * \brief Create a net poll
 *
 * \param[in]  pollInit    Poll initialization parameters.
 * \param[in]  id          Vmkernel service account.
 * \param[in]  moduleID    module ID
 * \param[out] poll        Handler for the net poll.
 *
 * \retval VMK_OK          Success.
 * \retval VMK_NO_MEMORY   Cannot allocate net poll resource.
 * \retval VMK_FAILURE     Poll initialization failed.
 *
 ***********************************************************************
 */

VMK_ReturnStatus vmk_NetPollCreate(vmk_NetPollProperties *pollInit,
                                   vmk_ServiceAcctID id,
                                   vmk_ModuleID moduleID,
                                   vmk_NetPoll *poll);

/*
 ***********************************************************************
 * vmk_NetPollRxPktQueue --                                       */ /**
 *
 * \ingroup NetPoll
 * \brief Queue packets received from the NIC.
 *
 * \pre The poll should be in active state.
 *
 * \param[in] netPoll           Handler for the net poll.
 * \param[in] pkt               Packet to be queued.
 *
 * \retval VMK_OK               Success.
 * \retval VMK_INVALID_HANDLE   Invalid poll handle.
 *
 ***********************************************************************
 */

VMK_ReturnStatus vmk_NetPollRxPktQueue(vmk_NetPoll netPoll,
                                       vmk_PktHandle *pkt);

/*
 ***********************************************************************
 * vmk_NetPollQueueCompPkt --                                     */ /**
 *
 * \ingroup NetPoll
 * \brief Queue packets for tx completion or queue received packets that
 *        need to be released on error.
 *
 * \pre The poll should be in active state.
 *
 * \param[in] netPoll           Handler for the net poll.
 * \param[in] pkt               Packet to be queued.
 *
 * \retval VMK_OK               Success.
 * \retval VMK_INVALID_HANDLE   Invalid poll handle.
 *
 ***********************************************************************
 */

VMK_ReturnStatus vmk_NetPollQueueCompPkt(vmk_NetPoll netPoll,
                                         vmk_PktHandle *pkt);

/*
 ***********************************************************************
 * vmk_NetPollInterruptSet --                                     */ /**
 *
 * \ingroup NetPoll
 * \brief Set the associated interrupt cookie with the poll.
 *
 * Vmkernel can have an interrupt cookie be associated with the network
 * poll so that the interrupt handler can be affinitized with the poll
 * routine.
 *
 * \param[in] netPoll          Handler for the net poll.
 * \param[in] intrCookie       Interrupt cookie.
 *
 * \retval VMK_OK              Success.
 * \retval VMK_INVALID_HANDLE  Invalid Poll handle.
 * \retval VMK_BAD_PARAM       If invalid interrupt cookie specified or
 *                             cookie could not be controlled.
 *
 ***********************************************************************
 */

VMK_ReturnStatus vmk_NetPollInterruptSet(vmk_NetPoll netPoll,
                                         vmk_IntrCookie intrCookie);

/*
 ***********************************************************************
 * vmk_NetPollInterruptUnSet --                                   */ /**
 *
 * \ingroup NetPoll
 * \brief Clear the interrupt cookie registered with the poll.
 *
 * \param[in] netPoll          Handler for the net poll.
 *
 * \retval VMK_OK              Success.
 * \retval VMK_INVALID_HANDLE  Invalid Poll handle.
 *
 ***********************************************************************
 */

VMK_ReturnStatus vmk_NetPollInterruptUnSet(vmk_NetPoll netPoll);

/*
 ***********************************************************************
 * vmk_NetPollRegisterUplink --                                   */ /**
 *
 * \ingroup NetPoll
 * \brief Register the uplink for the poll.
 *
 * Each poll requires uplink port if they are to use the poll callback.
 * However if the device provides its own custom callback, no
 * registration for uplink is required.
 *
 * A poll can have just one uplink be registered. Adding another uplink
 * will return error. However an uplink can be shared by multiple
 * net polls. But the uplink can have only one default poll registered.
 * The default poll is registered using the defaultPoll during the
 * initialization process. Once a default poll is registered it cannot
 * be overwritten.
 *
 * \param[in] netPoll       Handler for the net poll.
 * \param[in] uplink        Uplink from where the packets came from.
 * \param[in] name          Descriptive name for the poll.
 * \param[in] defaultPoll   Whether the net poll is default poll for
 *                          the NIC.
 *
 * \retval VMK_OK           Success.
 * \retval VMK_BAD_PARAM    Invalid uplink assignment.
 *
 ***********************************************************************
 */

VMK_ReturnStatus vmk_NetPollRegisterUplink(vmk_NetPoll netPoll,
                                           vmk_Uplink uplink,
                                           vmk_Name name,
                                           vmk_Bool defaultPoll);

/*
 ***********************************************************************
 * vmk_NetPollUnregisterUplink --                                 */ /**
 *
 * \ingroup NetPoll
 * \brief Unregister the uplink for the poll.
 *
 * \param[in] netPoll       Handler for the net poll.
 *
 * \retval VMK_OK           Success.
 * \retval VMK_BAD_PARAM    Invalid uplink assignment.
 *
 ***********************************************************************
 */

VMK_ReturnStatus vmk_NetPollUnregisterUplink(vmk_NetPoll netPoll);

/*
 ************************************************************************
 * vmk_NetPollFlushRx --                                         */ /**
 *
 * \ingroup NetPoll
 * \brief Process packets stored in the net poll list.
 *
 * \param[in] netPoll        Handler for the net poll.
 *
 ***********************************************************************
 */

void vmk_NetPollFlushRx(vmk_NetPoll netPoll);

/*
 ***********************************************************************
 * vmk_NetPollRxPktListQueue --                                   */ /**
 *
 * \ingroup NetPoll
 * \brief Queue a packet list into the poll context
 *
 * \param[in]   netPoll     Handler for netpoll
 * \param[in]   pktList     packet list to be queued.
 *
 * \retval     VMK_OK       If queueing was successful
 * \retval     VMK_FAILURE  Otherwise.
 *
 ***********************************************************************
 */

VMK_ReturnStatus vmk_NetPollRxPktListQueue(vmk_NetPoll netPoll,
                                           vmk_PktList pktList);

/*
 ***********************************************************************
 * vmk_NetPollCompPktListQueue --                                 */ /**
 *
 * \ingroup NetPoll
 * \brief Queue a packet list for completion into the poll context
 *
 * \param[in]   netPoll     Handler for netpoll
 * \param[in]   pktList     packet list to be queued.
 *
 * \retval     VMK_OK       if queueing pkt list for completion was successful
 * \retval     VMK_FAILURE  Otherwise.
 *
 ***********************************************************************
 */

VMK_ReturnStatus vmk_NetPollCompPktListQueue(vmk_NetPoll netPoll,
                                             vmk_PktList pktList);

/*
 ***********************************************************************
 * vmk_NetPollDisable --                                          */ /**
 *
 * \ingroup     NetPoll
 * \brief       Disable NetPoll
 *
 * Disables the netpoll synchronously by coordinating with the netpoll
 * world/worldet.
 *
 * \param[in]   netPoll     Handler for netpoll
 *
 * \retval      None
 *
 ***********************************************************************
 */
void vmk_NetPollDisable(vmk_NetPoll netPoll);

/*
 ***********************************************************************
 * vmk_NetPollEnable --                                          */ /**
 *
 * \ingroup     NetPoll
 * \brief       Enable NetPoll
 *
 * Enables the netpoll and wakes up any waiting world/worldlet.
 *
 * \param[in]   netPoll     Handler for netpoll
 *
 * \retval      None
 *
 ***********************************************************************
 */
void vmk_NetPollEnable(vmk_NetPoll netPoll);

#endif /* _VMKAPI_NET_POLL_H_ */
/** @} */
/** @} */