+++ /dev/null
-/*-
- * Copyright (c) <2010>, Intel Corporation
- * All rights reserved.
- *
- * 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 Intel Corporation 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.
- */
-
-#ifndef _CALLOUT_H_
-#define _CALLOUT_H_
-
-#define CALLOUT_STATS
-//#define CALLOUT_DEBUG
-
-/**
- * @file
- * Callout
- *
- * This library provides a timer service to Aversive. Instead of beeing
- * called from interrupt (like the scheduler lib does), these kind of timers
- * are not preemptive and should (for instance) be called from a main-loop.
- *
- * - Timers can be periodic or single (one-shot).
- *
- * This library provides an interface to add, delete and restart a
- * timer. The API is based on the BSD callout(9) with few
- * differences.
- *
- */
-
-#ifdef CALLOUT_STATS
-/**
- * A structure that stores the timer statistics (per-lcore).
- */
-struct callout_debug_stats {
- uint16_t reset; /**< Number of success calls to callout_reset(). */
- uint16_t stop; /**< Number of success calls to callout_stop(). */
- uint16_t manage; /**< Number of calls to callout_manage(). */
- uint16_t pending; /**< Number of pending timers. */
- uint16_t running; /**< Number of running timers. */
-};
-extern struct callout_debug_stats callout_debug_stats;
-#endif
-
-struct callout;
-struct callout_manager;
-
-/**
- * Callback function for the timer.
- */
-typedef void (callout_cb_t)(struct callout_manager *, struct callout *, void *);
-
-/**
- * A structure describing a timer in RTE.
- */
-struct callout
-{
- TAILQ_ENTRY(callout) next; /**< Next and prev in list. */
-
- uint8_t periodical: 1; /**< timer is periodical or not */
- uint8_t scheduled: 1; /**< true if timer is scheduled */
- uint8_t running: 1; /**< true if cb func is beeing executed */
- uint8_t reserved: 5;
-
- uint16_t period; /**< Period of timer (0 if not periodic). */
- uint16_t expire; /**< Time when timer expire. */
- callout_cb_t *f; /**< Callback function. */
- void *arg; /**< Argument to callback function. */
-};
-
-/**
- * a list of timers
- */
-TAILQ_HEAD(callout_list, callout);
-
-/**
- * A static initializer for a timer structure.
- */
-#define CALLOUT_INITIALIZER { }
-
-/**
- * Function used by a callout manager to get a time reference
- */
-typedef uint16_t (get_time_t)(void);
-
-/**
- * A instance of callout manager (it is possible to have several)
- */
-struct callout_manager {
- get_time_t *get_time;
- uint8_t updated: 1;
- uint8_t reserved: 7;
- uint16_t prev_time;
- struct callout_list pending_list;
-#ifdef CALLOUT_STATS
- /* statistics */
- struct callout_debug_stats stats;
-#endif
-};
-
-/**
- * Initialize a callout manager
- *
- * @param cm
- * The uninitialized callout manager structure.
- * @param get_time
- * Pointer to a function that returns a time reference (unsigned 16 bits)
- * @return
- * - 0 on success
- * - negative on error
- */
-int
-callout_manager_init(struct callout_manager *cm, get_time_t *get_time);
-
-/**
- * Initialize a timer handle.
- *
- * The callout_init() function initializes the timer handle tim
- * for use. No operations can be performed on the timer before it is
- * initialized.
- *
- * @param tim
- * The timer to initialize.
- */
-void callout_init(struct callout *tim);
-
-/**
- * Timer type: Periodic or single (one-shot).
- */
-enum callout_type {
- SINGLE,
- PERIODICAL
-};
-
-/**
- * Reset and start the timer associated with the timer handle.
- *
- * The callout_reset() function resets and starts the timer
- * associated with the timer handle tim. When the timer expires after
- * ticks/hz seconds, the function specified by *fct* will be called
- * with the argument *arg* on core *tim_lcore*.
- *
- * If the timer associated with the timer handle is already running
- * (in the RUNNING state), the function will fail. The user has to check
- * the return value of the function to see if there is a chance that the
- * timer is in the RUNNING state.
- *
- * If the timer is being configured on another core (the CONFIG state),
- * it will also fail.
- *
- * If the timer is pending or stopped, it will be rescheduled with the
- * new parameters.
- *
- * @param tim
- * The timer handle.
- * @param ticks
- * The number of cycles (see rte_get_hpet_hz()) before the callback
- * function is called.
- * @param type
- * The type can be either:
- * - PERIODICAL: The timer is automatically reloaded after execution
- * (returns to the PENDING state)
- * - SINGLE: The timer is one-shot, that is, the timer goes to a
- * STOPPED state after execution.
- * @param tim_lcore
- * The ID of the lcore where the timer callback function has to be
- * executed. If tim_lcore is LCORE_ID_ANY, the timer library will
- * launch it on a different core for each call (round-robin).
- * @param fct
- * The callback function of the timer.
- * @param arg
- * The user argument of the callback function.
- * @return
- * - 0: Success; the timer is scheduled.
- * - (-1): Timer is in the RUNNING or CONFIG state.
- */
-int callout_reset(struct callout_manager *cm, struct callout *tim,
- uint16_t ticks, enum callout_type type,
- callout_cb_t fct, void *arg);
-
-
-/**
- * Stop a timer.
- *
- * The callout_stop() function stops the timer associated with the
- * timer handle tim. It may fail if the timer is currently running or
- * being configured.
- *
- * If the timer is pending or stopped (for instance, already expired),
- * the function will succeed. The timer handle tim must have been
- * initialized using callout_init(), otherwise, undefined behavior
- * will occur.
- *
- * This function can be called safely from a timer callback. If it
- * succeeds, the timer is not referenced anymore by the timer library
- * and the timer structure can be freed (even in the callback
- * function).
- *
- * @param tim
- * The timer handle.
- */
-void callout_stop(struct callout_manager *cm, struct callout *tim);
-
-
-/**
- * Test if a timer is pending.
- *
- * The callout_pending() function tests the PENDING status
- * of the timer handle tim. A PENDING timer is one that has been
- * scheduled and whose function has not yet been called.
- *
- * @param tim
- * The timer handle.
- * @return
- * - 0: The timer is not pending.
- * - 1: The timer is pending.
- */
-int callout_pending(struct callout *tim);
-
-/**
- * Manage the timer list and execute callback functions.
- *
- * This function must be called periodically from all cores
- * main_loop(). It browses the list of pending timers and runs all
- * timers that are expired.
- *
- * The precision of the timer depends on the call frequency of this
- * function. However, the more often the function is called, the more
- * it will use CPU resources.
- */
-void callout_manage(struct callout_manager *cm);
-
-/**
- * Dump statistics about timers.
- */
-void callout_dump_stats(struct callout_manager *cm);
-
-#endif /* _CALLOUT_H_ */
git.droids-corp.org / protos / xbee-avr.git / blobdiff