tlib.h

/* SPDX-License-Identifier: BSD-2-Clause */
 
/*
 *  Timer Library (TLIB)
 *
 *  The Library rely on timer drivers, the timer presented by the
 *  timer driver must look like a down-counter timer, which generates
 *  interrupt (if configured) when underflown.
 *
 *  If Timer hardware is an up-counter the Timer driver must recalculate
 *  into values that would match as if it was a down-counter.
 *
 *  COPYRIGHT (c) 2011.
 *  Cobham Gaisler AB.
 *
 * 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.
 *
 * 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 __TLIB_H__
#define __TLIB_H__
 
#ifdef __cplusplus
extern "C" {
#endif
 
struct tlib_dev;
 
typedef void (*tlib_isr_t)(void *data);
 
enum {
    TLIB_FLAGS_BROADCAST = 0x01
};
 
struct tlib_drv {
    /*** Functions ***/
    void    (*reset)(struct tlib_dev *hand);
    void    (*get_freq)(
        struct tlib_dev *hand,
        unsigned int *basefreq,
        unsigned int *tickrate);
    int (*set_freq)(struct tlib_dev *hand, unsigned int tickrate);
    void    (*irq_reg)(struct tlib_dev *hand, tlib_isr_t func, void *data, int flags);
    void    (*irq_unreg)(struct tlib_dev *hand, tlib_isr_t func,void *data);
    void    (*start)(struct tlib_dev *hand, int once);
    void    (*stop)(struct tlib_dev *hand);
    void    (*restart)(struct tlib_dev *hand);
    void    (*get_counter)(struct tlib_dev *hand, unsigned int *counter);
    int (*custom)(struct tlib_dev *hand, int cmd, void *arg);
    int (*int_pend)(struct tlib_dev *hand, int ack);
    void    (*get_widthmask)(struct tlib_dev *hand, unsigned int *widthmask);
};
 
struct tlib_dev {
    struct tlib_dev *next;
    char status; /* 0=closed, 1=open, 2=timer started */
    char index; /* Timer Index */
    tlib_isr_t isr_func;
    void *isr_data;
    struct tlib_drv *drv;
};
 
#ifdef RTEMS_DRVMGR_STARTUP
/* Clock Driver Timer register function. Only used when the TLIB-Clock
 * driver is used. A specific Timer is registered as the System Clock
 * timer.
 */
extern void Clock_timer_register(int timer_number);
#endif
 
/* Register Timer. Called by Timer Drivers in order to register
 * a Timer to the Timer Library. The registration order determines
 * the Timer Number used in tlib_open() to identify a specific
 * Timer.
 */
extern int tlib_dev_reg(struct tlib_dev *newdev);
 
/* Allocate a Timer.
 *
 * A Timer handle is returned identifying the timer in later calls.
 */
extern void *tlib_open(int timer_no);
 
/* Close Timer */
extern void tlib_close(void *hand);
 
/* Returns Number of Timers currently registered to Timer Library */
extern int tlib_ntimer(void);
 
static inline void tlib_reset(void *hand)
{
    struct tlib_dev *dev = hand;
 
    dev->drv->reset(dev);
}
/* Get Frequencies:
 *   - Base Frequency (unchangable base freq rate of timer, prescaler, clkinput)
 *   - Current Tick Rate [in multiples of Base Frequency]
 */
static inline void tlib_get_freq(
    void *hand,
    unsigned int *basefreq,
    unsigned int *tickrate)
{
    struct tlib_dev *dev = hand;
 
    dev->drv->get_freq(dev, basefreq, tickrate);
}
 
/* Set current Tick Rate in number of "Base-Frequency ticks" */
static inline int tlib_set_freq(void *hand, unsigned int tickrate)
{
    struct tlib_dev *dev = hand;
 
    return dev->drv->set_freq(dev, tickrate);
}
 
/* Register ISR at Timer ISR */
static inline void tlib_irq_unregister(void *hand)
{
    struct tlib_dev *dev = hand;
 
    if ( dev->isr_func ) {
        dev->drv->irq_unreg(dev, dev->isr_func, dev->isr_data);
        dev->isr_func = NULL;
    }
}
 
/* Register ISR at Timer ISR */
static inline void tlib_irq_register(void *hand, tlib_isr_t func, void *data, int flags)
{
    struct tlib_dev *dev = hand;
 
    /* Unregister previous ISR if installed */
    tlib_irq_unregister(hand);
    dev->isr_func = func;
    dev->isr_data = data;
    dev->drv->irq_reg(dev, func, data, flags);
}
 
/* Start Timer, ISRs will be generated if enabled.
 *
 * once determines if timer should restart (=0) on underflow automatically,
 * or stop when underflow is reached (=1).
 */
static inline void tlib_start(void *hand, int once)
{
    struct tlib_dev *dev = hand;
 
    dev->drv->start(dev, once);
}
 
/* Stop Timer, no more ISRs will be generated */
static inline void tlib_stop(void *hand)
{
    struct tlib_dev *dev = hand;
 
    dev->drv->stop(dev);
}
 
/* Restart/Reload Timer, may be usefull if a Watchdog Timer */
static inline void tlib_restart(void *hand)
{
    struct tlib_dev *dev = hand;
 
    dev->drv->restart(dev);
}
 
/* Get current counter value (since last tick) */
static inline void tlib_get_counter(void *hand, unsigned int *counter)
{
    struct tlib_dev *dev = hand;
 
    dev->drv->get_counter(dev, counter);
}
 
/* Do a custom operation  */
static inline void tlib_custom(void *hand, int cmd, void *arg)
{
    struct tlib_dev *dev = hand;
 
    dev->drv->custom(dev, cmd, arg);
}
 
static inline int tlib_interrupt_pending(void *hand, int ack)
{
    struct tlib_dev *dev = hand;
 
    return dev->drv->int_pend(dev, ack);
}
 
static inline void tlib_get_widthmask(void *hand, unsigned int *widthmask)
{
    struct tlib_dev *dev = hand;
 
    dev->drv->get_widthmask(dev, widthmask);
}
 
#ifdef __cplusplus
}
#endif
 
#endif