/******************************************************************************
* FILE PURPOSE: Netapi scheduler module
******************************************************************************
* FILE NAME: netapi_sched.h
*
* DESCRIPTION: Netapi sample event scheduler header file for user space transport library
*
* REVISION HISTORY:
*
* Copyright (c) Texas Instruments Incorporated 2010-2011
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
*
* 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.
*
* Neither the name of Texas Instruments Incorporated 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
* OWNER 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.
*
*/
/* ============================================================= */
/**
* @file netapi_sched.h
* @brief netapi scheduler header file for user space transport library
*/
#ifndef __NETAPI_SCHED__
#define __NETAPI_SCHED__
#include "netapi.h"
/**
* @brief This define the handle to the NETAPI scheduling context TBD
*/
struct NETAPI_SCHED_HANDLE_Tag;
/**
* @ingroup netapi_cb_functions
* @brief NETAPI_SCHED_CB Callback function for scheduling context hous keeping. TBD
*
* @details The application provides a callback function that NETAPI scheduling context to retrieve TBD
* @param[in] h The handle to the NETAPI scheduling context
* @retval none
* @pre @ref netapi_init
*/
typedef void (*NETAPI_SCHED_CB)(struct NETAPI_SCHED_HANDLE_Tag *h);
/**
* @ingroup sched_structures
* @brief NETAPI scheduler configuration structure.
*
* @details Pointer to this structure is passed in the call to @ref netapi_schedOpen API
*/
typedef struct NETAPI_SCHED_CONFIG_Tag
{
/**
* Valid flag options of scheduler context being configured.
*
* The following are flags used to configure the scheduler:
* @ref NETAPI_SCHED_DURATION , @ref NETAPI_SCHED_POWER, @ref NETAPI_SCHED_FINE, @ref NETAPI_SCHED_FINE
*/
int valid_flags;
/**
* @def NETAPI_SCHED_DURATION
* @ingroup sched_constants
* This defines the duration option of scheduler context being configured TBD
*/
#define NETAPI_SCHED_DURATION 0x1
/**
* @def NETAPI_SCHED_POWER
* @ingroup sched_constants
* This defines the Power option of scheduler context being configured. TBD
*/
#define NETAPI_SCHED_POWER 0x2
/**
* @def NETAPI_SCHED_FINE
* @ingroup sched_constants
* This defines the fine tune option of scheduler context being configured. TBD
*/
#define NETAPI_SCHED_FINE 0x4
/**
* @def NETAPI_SCHED_CBV
* @ingroup sched_constants
* This defines the call back option of scheduler context being configured. TBD.
*/
#define NETAPI_SCHED_CBV 0x8
/**
* @def NETAPI_SCHED_FOREVER
* @ingroup sched_constants
* This defines is used to configure scheduler to run forever.
*/
#define NETAPI_SCHED_FOREVER 0L
uint64_t duration; /**< Duration scheduler is configured to run, 0 == forever,
* non-zero value is ticks for scheduler to run
*/
NETAPI_SCHED_CB house_cb; /**< House keeping callback */
uint32_t interval; /**< How many poll loop intervals after which to call the house keeping callback */
/**
* Power control option configuration for scheduler
*
* The following are flags used to configure the power control option:
* @ref NETAPI_SCHED_POWER_ALWAYS_OFF , @ref NETAPI_SCHED_POWER_ALWAYS_OFF
*/
int power_control;
/**
* @def NETAPI_SCHED_POWER_ALWAYS_OFF
* @ingroup sched_constants
* This define is used to configure scheduler power_control option to be always off TBD
*/
#define NETAPI_SCHED_POWER_ALWAYS_OFF 0
/**
* @def NETAPI_SCHED_POWER_ALWAYS_ON
* @ingroup sched_constants
* This define is used to configure scheduler power_control option to be always on
*/
#define NETAPI_SCHED_POWER_ALWAYS_ON 100
int idle_time; /**< idle time TBD */
} NETAPI_SCHED_CONFIG_T;
/**
* @ingroup sched_structures
* @brief NETAPI scheduler context handle.
*
* @details This structure is returned from call to @ref netapi_schedOpen API
*/
typedef struct NETAPI_SCHED_HANDLE_Tag
{
/**
* State of the scheduler
*
* The following are valid states of the scheduler,
* @ref NETAPI_SCHED_STATE_CLOSE , @ref NETAPI_SCHED_STATE_CLOSE_IN_PROGRESS, @ref NETAPI_SCHED_STATE_OPEN
*/
volatile int state; /**< 0= shutdown, 1= shutting down, 2=active */
/**
* @def NETAPI_SCHED_STATE_CLOSE
* @ingroup sched_constants
* This define indicates the state of the scheduler to be CLOSE (idle) state TBD
*/
#define NETAPI_SCHED_STATE_CLOSE 0
/**
* @def NETAPI_SCHED_STATE_CLOSE_IN_PROGRESS
* @ingroup sched_constants
* This define indicates the state of the scheduler is being shutdown state TBD
*/
#define NETAPI_SCHED_STATE_CLOSE_IN_PROGRESS 1
/**
* @def NETAPI_SCHED_STATE_OPEN
* @ingroup sched_constants
* This define indicates the state of the scheduler is OPEN (running) TBD
*/
#define NETAPI_SCHED_STATE_OPEN 2
void * back; /**< Pointer back to NETAPI handle */
NETAPI_SCHED_CONFIG_T config; /**< NETAPI scheduler configuration */
uint64_t start; /**< Start time of NETAPI scheduler context TBD*/
volatile int shutdown_reason; /**< FUTURE-not implemented TBD */
volatile uint64_t shutdown_time; /**< Time till scheduler context will be shutdown/closed */
} NETAPI_SCHED_HANDLE_T;
/// @cond FUTURE
/* return codes for wait_for_events() TBD, currently not used*/
#define NETAPI_SCHED_RETURN_ERR 0 /**
* The following options of how to shutdown the scheduler
* @ref NETAPI_SCHED_SHUTDOWN_NOW , @ref NETAPI_SCHED_SHUTDOWN_TO, @ref NETAPI_SCHED_SHUTDOWN_NEXT_IDLE
*/
int shutdown_type; /**< shutdown type */
/**
* @def NETAPI_SCHED_SHUTDOWN_NOW
* @ingroup sched_constants
* This define is used to shudown the scheduling context immediately
*/
#define NETAPI_SCHED_SHUTDOWN_NOW 0
/**
* @def NETAPI_SCHED_SHUTDOWN_TO
* @ingroup sched_constants
* This define is used to shudown the scheduling context TBD
*/
#define NETAPI_SCHED_SHUTDOWN_TO 1
/**
* @def NETAPI_SCHED_SHUTDOWN_NEXT_IDLE
* @ingroup sched_constants
* This define is used to shudown the scheduling context during next idle period
*/
#define NETAPI_SCHED_SHUTDOWN_NEXT_IDLE 2
int timeout; /**< Ticks from now to close the scheduling context */
} NETAPI_SCHED_SHUTDOWN_T;
/**
* @ingroup sched_functions
* @brief netapi_schedOpen: API to open a scheduling context
*
* @details API to open a scheduling context
* @param[in] n the NETAPI handle, @ref NETAPI_T
* @param[in] p_config :pointer to @ref NETAPI_SCHED_CONFIG_T
* @param[out] p_err Pointer to error code.
* @retval Handle associated with created scheduler context, @ref NETAPI_SCHED_HANDLE_T
* @pre @ref netapi_init
*/
NETAPI_SCHED_HANDLE_T * netapi_schedOpen(NETAPI_T n,
NETAPI_SCHED_CONFIG_T * p_config,
int *p_err);
/**
* @ingroup sched_functions
* @brief netapi_schedControl: API to re-configure a scheduling context, FUTURE, not implemented
*
* @details API to re-configure a scheduling context
* @param[in] s The NETAPI scheduling context handle, @ref NETAPI_SCHED_HANDLE_T
* @param[in] p_config Pointer to @ref NETAPI_SCHED_CONFIG_T
* @param[out] p_err Pointer to error code.
* @retval Handle associated with created scheduler context, @ref NETAPI_SCHED_HANDLE_T
* @pre @ref netapi_schedOpen
*/
int netapi_schedControl(NETAPI_SCHED_HANDLE_T *s,
NETAPI_SCHED_CONFIG_T *p_config,
int *p_err);
/**
* @ingroup sched_functions
* @brief netapi_schedWaitForEvents: API for main entry point to scheduler.
*
* @details API for main entry point to scheduler. User application gives up control to scheduler.
* @param[in] s The NETAPI scheduling context handle, @ref NETAPI_SCHED_HANDLE_T
* @param[out] p_err: error code, zero on sucess, non-zero on failure
* @retval TBD
* @pre @ref netapi_schedOpen
*/
int netapi_schedWaitForEvents(NETAPI_SCHED_HANDLE_T *s,
int * p_err);
/**
* @ingroup sched_functions
* @brief netapi_schedShutdown: API to shutdown scheduling context
*
* @details API to shutdown scheduling context
* @param[in] s The NETAPI scheduling context handle, @ref NETAPI_SCHED_HANDLE_T
* @param[in] p_close @ref NETAPI_SCHED_SHUTDOWN_T
* @param[out] p_err Pointer to error code.
* @retval TBD
* @pre @ref netapi_schedOpen
*/
int netapi_schedShutdown(NETAPI_SCHED_HANDLE_T * s,
NETAPI_SCHED_SHUTDOWN_T * p_close,
int *p_err);
/**
* @ingroup sched_functions
* @brief netapi_schedShutdown: API to get the NETAPI handle from scheduling context
*
* @details API to get the NETAPI handle from scheduling context
* @param[in] s The NETAPI scheduling context handle, @ref NETAPI_SCHED_HANDLE_T
* @retval Handle to NETAPI instance
*/
static NETAPI_T netapi_schedGetNetapiHandle(NETAPI_SCHED_HANDLE_T *s)
{
return (NETAPI_T)s->back;
}
/**
* @ingroup sched_functions
* @brief netapi_sched_get_stats: API to tget NETAP scheduling context statistics
*
* @details API to tget NETAP scheduling context statistics
* @param[in] p_pkts TBD
* @param[in] p_cycles TBD
* @param[in] p_ccycles TBD
* @retval none
*/
void netapi_sched_get_stats(unsigned long long * p_pkts,
unsigned long long * p_cycles,
unsigned long long * p_ccycles);
#endif