driver.h

Go to the documentation of this file.

#ifndef _COBALT_RTDM_DRIVER_H
#define _COBALT_RTDM_DRIVER_H

#include <asm/atomic.h>
#include <linux/list.h>
#include <linux/module.h>
#include <linux/cdev.h>
#include <linux/wait.h>
#include <linux/notifier.h>
#include <xenomai/version.h>
#include <cobalt/kernel/heap.h>
#include <cobalt/kernel/sched.h>
#include <cobalt/kernel/intr.h>
#include <cobalt/kernel/synch.h>
#include <cobalt/kernel/select.h>
#include <cobalt/kernel/clock.h>
#include <cobalt/kernel/apc.h>
#include <cobalt/kernel/init.h>
#include <cobalt/kernel/ancillaries.h>
#include <cobalt/kernel/tree.h>
#include <rtdm/fd.h>
#include <rtdm/rtdm.h>

/* debug support */
#include <cobalt/kernel/assert.h>
#include <trace/events/cobalt-rtdm.h>
#ifdef CONFIG_PCI
#include <asm-generic/xenomai/pci_ids.h>
#endif /* CONFIG_PCI */
#include <asm/xenomai/syscall.h>

struct class;
typedef struct xnselector rtdm_selector_t;
enum rtdm_selecttype;

#define RTDM_EXCLUSIVE                  0x0001

#define RTDM_FIXED_MINOR                0x0002

#define RTDM_NAMED_DEVICE               0x0010

#define RTDM_PROTOCOL_DEVICE            0x0020

#define RTDM_DEVICE_TYPE_MASK           0x00F0

#define RTDM_SECURE_DEVICE              0x80000000

#define RTDM_MAX_MINOR  1024

enum rtdm_selecttype {
        RTDM_SELECTTYPE_READ = XNSELECT_READ,

        RTDM_SELECTTYPE_WRITE = XNSELECT_WRITE,

        RTDM_SELECTTYPE_EXCEPT = XNSELECT_EXCEPT
};
struct rtdm_dev_context {
        struct rtdm_fd fd;

        struct rtdm_device *device;

        char dev_private[0];
};

static inline struct rtdm_dev_context *rtdm_fd_to_context(struct rtdm_fd *fd)
{
        return container_of(fd, struct rtdm_dev_context, fd);
}

static inline void *rtdm_fd_to_private(struct rtdm_fd *fd)
{
        return &rtdm_fd_to_context(fd)->dev_private[0];
}

static inline struct rtdm_fd *rtdm_private_to_fd(void *dev_private)
{
        struct rtdm_dev_context *ctx;
        ctx = container_of(dev_private, struct rtdm_dev_context, dev_private);
        return &ctx->fd;
}

static inline bool rtdm_fd_is_user(struct rtdm_fd *fd)
{
        return rtdm_fd_owner(fd) != &cobalt_kernel_ppd;
}

static inline struct rtdm_device *rtdm_fd_device(struct rtdm_fd *fd)
{
        return rtdm_fd_to_context(fd)->device;
}

struct rtdm_profile_info {
        const char *name;
        int class_id;
        int subclass_id;
        int version;
        unsigned int magic;
        struct module *owner;
        struct class *kdev_class;
};

struct rtdm_driver;

struct rtdm_sm_ops {
        int (*start)(struct rtdm_driver *drv);
        int (*stop)(struct rtdm_driver *drv);
};

struct rtdm_driver {
        struct rtdm_profile_info profile_info;
        int device_flags;
        size_t context_size;
        int protocol_family;
        int socket_type;
        struct rtdm_fd_ops ops;
        struct rtdm_sm_ops smops;
        int device_count;
        int base_minor;
        struct {
                union {
                        struct {
                                struct cdev cdev;
                                int major;
                        } named;
                };
                atomic_t refcount;
                struct notifier_block nb_statechange;
                DECLARE_BITMAP(minor_map, RTDM_MAX_MINOR);
        };
};

#define RTDM_CLASS_MAGIC        0x8284636c

#define RTDM_PROFILE_INFO(__name, __id, __subid, __version)     \
{                                                               \
        .name = ( # __name ),                                   \
        .class_id = (__id),                                     \
        .subclass_id = (__subid),                               \
        .version = (__version),                                 \
        .magic = ~RTDM_CLASS_MAGIC,                             \
        .owner = THIS_MODULE,                                   \
        .kdev_class = NULL,                                     \
}

int rtdm_drv_set_sysclass(struct rtdm_driver *drv, struct class *cls);

struct rtdm_device {
        struct rtdm_driver *driver;
        void *device_data;
        const char *label;
        int minor;
        struct {
                unsigned int magic;
                char *name;
                union {
                        struct {
                                xnhandle_t handle;
                        } named;
                        struct {
                                struct xnid id;
                        } proto;
                };
                dev_t rdev;
                struct device *kdev;
                struct class *kdev_class;
                atomic_t refcount;
                struct rtdm_fd_ops ops;
                wait_queue_head_t putwq;
        };
};

/* --- device registration --- */

int rtdm_dev_register(struct rtdm_device *device);

void rtdm_dev_unregister(struct rtdm_device *device);

#ifndef DOXYGEN_CPP /* Avoid static inline tags for RTDM in doxygen */

static inline struct device *rtdm_dev_to_kdev(struct rtdm_device *device)
{
        return device->kdev;
}

/* --- clock services --- */
static inline nanosecs_abs_t rtdm_clock_read(void)
{
        return xnclock_read_realtime(&nkclock);
}

static inline nanosecs_abs_t rtdm_clock_read_monotonic(void)
{
        return xnclock_read_monotonic(&nkclock);
}
#endif /* !DOXYGEN_CPP */

/* --- timeout sequences */

typedef nanosecs_abs_t rtdm_toseq_t;

void rtdm_toseq_init(rtdm_toseq_t *timeout_seq, nanosecs_rel_t timeout);

#define cobalt_atomic_enter(__context)                          \
        do {                                                    \
                xnlock_get_irqsave(&nklock, (__context));       \
                xnsched_lock();                                 \
        } while (0)

#define cobalt_atomic_leave(__context)                          \
        do {                                                    \
                xnsched_unlock();                               \
                xnlock_put_irqrestore(&nklock, (__context));    \
        } while (0)

#ifdef DOXYGEN_CPP /* Beautify doxygen output */
#define RTDM_EXECUTE_ATOMICALLY(code_block)     \
{                                               \
        <ENTER_ATOMIC_SECTION>                  \
        code_block;                             \
        <LEAVE_ATOMIC_SECTION>                  \
}
#else /* This is how it really works */
static inline __attribute__((deprecated)) void
rtdm_execute_atomically(void) { }

#define RTDM_EXECUTE_ATOMICALLY(code_block)             \
{                                                       \
        spl_t __rtdm_s;                                 \
                                                        \
        rtdm_execute_atomically();                      \
        xnlock_get_irqsave(&nklock, __rtdm_s);          \
        xnsched_lock();                                 \
        code_block;                                     \
        xnsched_unlock();                               \
        xnlock_put_irqrestore(&nklock, __rtdm_s);       \
}
#endif

#define RTDM_LOCK_UNLOCKED(__name)      IPIPE_SPIN_LOCK_UNLOCKED

#define DEFINE_RTDM_LOCK(__name)                \
        rtdm_lock_t __name = RTDM_LOCK_UNLOCKED(__name)

typedef ipipe_spinlock_t rtdm_lock_t;

typedef unsigned long rtdm_lockctx_t;

static inline void rtdm_lock_init(rtdm_lock_t *lock)
{
        raw_spin_lock_init(lock);
}

static inline void rtdm_lock_get(rtdm_lock_t *lock)
{
        XENO_BUG_ON(COBALT, !spltest());
        raw_spin_lock(lock);
        xnsched_lock();
}

static inline void rtdm_lock_put(rtdm_lock_t *lock)
{
        raw_spin_unlock(lock);
        xnsched_unlock();
}

#define rtdm_lock_get_irqsave(__lock, __context)        \
        ((__context) = __rtdm_lock_get_irqsave(__lock))

static inline rtdm_lockctx_t __rtdm_lock_get_irqsave(rtdm_lock_t *lock)
{
        rtdm_lockctx_t context;

        context = ipipe_test_and_stall_head();
        raw_spin_lock(lock);
        xnsched_lock();

        return context;
}

static inline
void rtdm_lock_put_irqrestore(rtdm_lock_t *lock, rtdm_lockctx_t context)
{
        raw_spin_unlock(lock);
        xnsched_unlock();
        ipipe_restore_head(context);
}

#define rtdm_lock_irqsave(__context)    \
        splhigh(__context)

#define rtdm_lock_irqrestore(__context) \
        splexit(__context)

#ifndef DOXYGEN_CPP

struct rtdm_waitqueue {
        struct xnsynch wait;
};
typedef struct rtdm_waitqueue rtdm_waitqueue_t;

#define RTDM_WAITQUEUE_INITIALIZER(__name) {             \
            .wait = XNSYNCH_WAITQUEUE_INITIALIZER((__name).wait), \
        }

#define DEFINE_RTDM_WAITQUEUE(__name)                           \
        struct rtdm_waitqueue __name = RTDM_WAITQUEUE_INITIALIZER(__name)

#define DEFINE_RTDM_WAITQUEUE_ONSTACK(__name)   \
        DEFINE_RTDM_WAITQUEUE(__name)

static inline void rtdm_waitqueue_init(struct rtdm_waitqueue *wq)
{
        *wq = (struct rtdm_waitqueue)RTDM_WAITQUEUE_INITIALIZER(*wq);
}

static inline void rtdm_waitqueue_destroy(struct rtdm_waitqueue *wq)
{
        xnsynch_destroy(&wq->wait);
}

static inline int __rtdm_dowait(struct rtdm_waitqueue *wq,
                                nanosecs_rel_t timeout, xntmode_t timeout_mode)
{
        int ret;
        
        ret = xnsynch_sleep_on(&wq->wait, timeout, timeout_mode);
        if (ret & XNBREAK)
                return -EINTR;
        if (ret & XNTIMEO)
                return -ETIMEDOUT;
        if (ret & XNRMID)
                return -EIDRM;
        return 0;
}

static inline int __rtdm_timedwait(struct rtdm_waitqueue *wq,
                                   nanosecs_rel_t timeout, rtdm_toseq_t *toseq)
{
        if (toseq && timeout > 0)
                return __rtdm_dowait(wq, *toseq, XN_ABSOLUTE);

        return __rtdm_dowait(wq, timeout, XN_RELATIVE);
}

#define rtdm_timedwait_condition_locked(__wq, __cond, __timeout, __toseq) \
        ({                                                              \
                int __ret = 0;                                          \
                while (__ret == 0 && !(__cond))                         \
                        __ret = __rtdm_timedwait(__wq, __timeout, __toseq); \
                __ret;                                                  \
        })

#define rtdm_wait_condition_locked(__wq, __cond)                        \
        ({                                                              \
                int __ret = 0;                                          \
                while (__ret == 0 && !(__cond))                         \
                        __ret = __rtdm_dowait(__wq,                     \
                                              XN_INFINITE, XN_RELATIVE); \
                __ret;                                                  \
        })

#define rtdm_timedwait_condition(__wq, __cond, __timeout, __toseq)      \
        ({                                                              \
                spl_t __s;                                              \
                int __ret;                                              \
                xnlock_get_irqsave(&nklock, __s);                       \
                __ret = rtdm_timedwait_condition_locked(__wq, __cond,   \
                                              __timeout, __toseq);      \
                xnlock_put_irqrestore(&nklock, __s);                    \
                __ret;                                                  \
        })

#define rtdm_timedwait(__wq, __timeout, __toseq)                        \
        __rtdm_timedwait(__wq, __timeout, __toseq)

#define rtdm_timedwait_locked(__wq, __timeout, __toseq)                 \
        rtdm_timedwait(__wq, __timeout, __toseq)

#define rtdm_wait_condition(__wq, __cond)                               \
        ({                                                              \
                spl_t __s;                                              \
                int __ret;                                              \
                xnlock_get_irqsave(&nklock, __s);                       \
                __ret = rtdm_wait_condition_locked(__wq, __cond);       \
                xnlock_put_irqrestore(&nklock, __s);                    \
                __ret;                                                  \
        })

#define rtdm_wait(__wq)                                                 \
        __rtdm_dowait(__wq, XN_INFINITE, XN_RELATIVE)

#define rtdm_wait_locked(__wq)  rtdm_wait(__wq)

#define rtdm_waitqueue_lock(__wq, __context)  cobalt_atomic_enter(__context)

#define rtdm_waitqueue_unlock(__wq, __context)  cobalt_atomic_leave(__context)

#define rtdm_waitqueue_signal(__wq)                                     \
        ({                                                              \
                struct xnthread *__waiter;                              \
                __waiter = xnsynch_wakeup_one_sleeper(&(__wq)->wait);   \
                xnsched_run();                                          \
                __waiter != NULL;                                       \
        })

#define __rtdm_waitqueue_flush(__wq, __reason)                          \
        ({                                                              \
                int __ret;                                              \
                __ret = xnsynch_flush(&(__wq)->wait, __reason);         \
                xnsched_run();                                          \
                __ret == XNSYNCH_RESCHED;                               \
        })

#define rtdm_waitqueue_broadcast(__wq)  \
        __rtdm_waitqueue_flush(__wq, 0)

#define rtdm_waitqueue_flush(__wq)      \
        __rtdm_waitqueue_flush(__wq, XNBREAK)

#define rtdm_waitqueue_wakeup(__wq, __waiter)                           \
        do {                                                            \
                xnsynch_wakeup_this_sleeper(&(__wq)->wait, __waiter);   \
                xnsched_run();                                          \
        } while (0)

#define rtdm_for_each_waiter(__pos, __wq)               \
        xnsynch_for_each_sleeper(__pos, &(__wq)->wait)

#define rtdm_for_each_waiter_safe(__pos, __tmp, __wq)   \
        xnsynch_for_each_sleeper_safe(__pos, __tmp, &(__wq)->wait)

#endif /* !DOXYGEN_CPP */

/* --- Interrupt management services --- */
typedef struct xnintr rtdm_irq_t;

#define RTDM_IRQTYPE_SHARED             XN_IRQTYPE_SHARED

#define RTDM_IRQTYPE_EDGE               XN_IRQTYPE_EDGE

typedef int (*rtdm_irq_handler_t)(rtdm_irq_t *irq_handle);

#define RTDM_IRQ_NONE                   XN_IRQ_NONE

#define RTDM_IRQ_HANDLED                XN_IRQ_HANDLED

#define RTDM_IRQ_DISABLE                XN_IRQ_DISABLE

#define rtdm_irq_get_arg(irq_handle, type)      ((type *)irq_handle->cookie)

int rtdm_irq_request(rtdm_irq_t *irq_handle, unsigned int irq_no,
                     rtdm_irq_handler_t handler, unsigned long flags,
                     const char *device_name, void *arg);

#ifndef DOXYGEN_CPP /* Avoid static inline tags for RTDM in doxygen */
static inline int rtdm_irq_free(rtdm_irq_t *irq_handle)
{
        if (!XENO_ASSERT(COBALT, xnsched_root_p()))
                return -EPERM;
        xnintr_detach(irq_handle);
        return 0;
}

static inline int rtdm_irq_enable(rtdm_irq_t *irq_handle)
{
        xnintr_enable(irq_handle);
        return 0;
}

static inline int rtdm_irq_disable(rtdm_irq_t *irq_handle)
{
        xnintr_disable(irq_handle);
        return 0;
}
#endif /* !DOXYGEN_CPP */

/* --- non-real-time signalling services --- */

typedef struct rtdm_nrtsig rtdm_nrtsig_t;
typedef void (*rtdm_nrtsig_handler_t)(rtdm_nrtsig_t *nrt_sig, void *arg);

struct rtdm_nrtsig {
        rtdm_nrtsig_handler_t handler;
        void *arg;
};

void rtdm_schedule_nrt_work(struct work_struct *lostage_work);
#ifndef DOXYGEN_CPP /* Avoid static inline tags for RTDM in doxygen */
static inline void rtdm_nrtsig_init(rtdm_nrtsig_t *nrt_sig,
                                rtdm_nrtsig_handler_t handler, void *arg)
{
        nrt_sig->handler = handler;
        nrt_sig->arg = arg;
}

static inline void rtdm_nrtsig_destroy(rtdm_nrtsig_t *nrt_sig)
{
        nrt_sig->handler = NULL;
        nrt_sig->arg = NULL;
}

void rtdm_nrtsig_pend(rtdm_nrtsig_t *nrt_sig);
#endif /* !DOXYGEN_CPP */

/* --- timer services --- */

typedef struct xntimer rtdm_timer_t;

typedef void (*rtdm_timer_handler_t)(rtdm_timer_t *timer);

enum rtdm_timer_mode {
        RTDM_TIMERMODE_RELATIVE = XN_RELATIVE,

        RTDM_TIMERMODE_ABSOLUTE = XN_ABSOLUTE,

        RTDM_TIMERMODE_REALTIME = XN_REALTIME
};
#ifndef DOXYGEN_CPP /* Avoid broken doxygen output */
#define rtdm_timer_init(timer, handler, name)                           \
({                                                                      \
        xntimer_init((timer), &nkclock, handler,                        \
                     NULL, XNTIMER_IGRAVITY);                           \
        xntimer_set_name((timer), (name));                              \
        0;                                                              \
})

#endif /* !DOXYGEN_CPP */

void rtdm_timer_destroy(rtdm_timer_t *timer);

int rtdm_timer_start(rtdm_timer_t *timer, nanosecs_abs_t expiry,
                     nanosecs_rel_t interval, enum rtdm_timer_mode mode);

void rtdm_timer_stop(rtdm_timer_t *timer);

#ifndef DOXYGEN_CPP /* Avoid static inline tags for RTDM in doxygen */
static inline int rtdm_timer_start_in_handler(rtdm_timer_t *timer,
                                              nanosecs_abs_t expiry,
                                              nanosecs_rel_t interval,
                                              enum rtdm_timer_mode mode)
{
        return xntimer_start(timer, expiry, interval, (xntmode_t)mode);
}

static inline void rtdm_timer_stop_in_handler(rtdm_timer_t *timer)
{
        xntimer_stop(timer);
}
#endif /* !DOXYGEN_CPP */

/* --- task services --- */
typedef struct xnthread rtdm_task_t;

typedef void (*rtdm_task_proc_t)(void *arg);

#define RTDM_TASK_LOWEST_PRIORITY       0
#define RTDM_TASK_HIGHEST_PRIORITY      99

#define RTDM_TASK_RAISE_PRIORITY        (+1)
#define RTDM_TASK_LOWER_PRIORITY        (-1)

int rtdm_task_init(rtdm_task_t *task, const char *name,
                   rtdm_task_proc_t task_proc, void *arg,
                   int priority, nanosecs_rel_t period);
int __rtdm_task_sleep(xnticks_t timeout, xntmode_t mode);
void rtdm_task_busy_sleep(nanosecs_rel_t delay);

#ifndef DOXYGEN_CPP /* Avoid static inline tags for RTDM in doxygen */
static inline void rtdm_task_destroy(rtdm_task_t *task)
{
        xnthread_cancel(task);
        xnthread_join(task, true);
}

static inline int rtdm_task_should_stop(void)
{
        return xnthread_test_info(xnthread_current(), XNCANCELD);
}

void rtdm_task_join(rtdm_task_t *task);

static inline void __deprecated rtdm_task_join_nrt(rtdm_task_t *task,
                                                   unsigned int poll_delay)
{
        rtdm_task_join(task);
}

static inline void rtdm_task_set_priority(rtdm_task_t *task, int priority)
{
        union xnsched_policy_param param = { .rt = { .prio = priority } };
        xnthread_set_schedparam(task, &xnsched_class_rt, &param);
        xnsched_run();
}

static inline int rtdm_task_set_period(rtdm_task_t *task,
                                       nanosecs_abs_t start_date,
                                       nanosecs_rel_t period)
{
        if (period < 0)
                period = 0;
        if (start_date == 0)
                start_date = XN_INFINITE;

        return xnthread_set_periodic(task, start_date, XN_ABSOLUTE, period);
}

static inline int rtdm_task_unblock(rtdm_task_t *task)
{
        int res = xnthread_unblock(task);

        xnsched_run();
        return res;
}

static inline rtdm_task_t *rtdm_task_current(void)
{
        return xnthread_current();
}

static inline int rtdm_task_wait_period(unsigned long *overruns_r)
{
        if (!XENO_ASSERT(COBALT, !xnsched_unblockable_p()))
                return -EPERM;
        return xnthread_wait_period(overruns_r);
}

static inline int rtdm_task_sleep(nanosecs_rel_t delay)
{
        return __rtdm_task_sleep(delay, XN_RELATIVE);
}

static inline int
rtdm_task_sleep_abs(nanosecs_abs_t wakeup_date, enum rtdm_timer_mode mode)
{
        /* For the sake of a consistent API usage... */
        if (mode != RTDM_TIMERMODE_ABSOLUTE && mode != RTDM_TIMERMODE_REALTIME)
                return -EINVAL;
        return __rtdm_task_sleep(wakeup_date, (xntmode_t)mode);
}

/* rtdm_task_sleep_abs shall be used instead */
static inline int __deprecated rtdm_task_sleep_until(nanosecs_abs_t wakeup_time)
{
        return __rtdm_task_sleep(wakeup_time, XN_REALTIME);
}

#define rtdm_task_busy_wait(__condition, __spin_ns, __sleep_ns)                 \
        ({                                                                      \
                __label__ done;                                                 \
                nanosecs_abs_t __end;                                           \
                int __ret = 0;                                                  \
                for (;;) {                                                      \
                        __end = rtdm_clock_read_monotonic() + __spin_ns;        \
                        for (;;) {                                              \
                                if (__condition)                                \
                                        goto done;                              \
                                if (rtdm_clock_read_monotonic() >= __end)       \
                                        break;                                  \
                        }                                                       \
                        __ret = rtdm_task_sleep(__sleep_ns);                    \
                        if (__ret)                                              \
                                break;                                          \
                }                                                               \
        done:                                                                   \
                __ret;                                                          \
        })

#define rtdm_wait_context       xnthread_wait_context

static inline
void rtdm_wait_complete(struct rtdm_wait_context *wc)
{
        xnthread_complete_wait(wc);
}

static inline
int rtdm_wait_is_completed(struct rtdm_wait_context *wc)
{
        return xnthread_wait_complete_p(wc);
}

static inline void rtdm_wait_prepare(struct rtdm_wait_context *wc)
{
        xnthread_prepare_wait(wc);
}

static inline
struct rtdm_wait_context *rtdm_wait_get_context(rtdm_task_t *task)
{
        return xnthread_get_wait_context(task);
}

#endif /* !DOXYGEN_CPP */

/* --- event services --- */

typedef struct rtdm_event {
        struct xnsynch synch_base;
        DECLARE_XNSELECT(select_block);
} rtdm_event_t;

#define RTDM_EVENT_PENDING              XNSYNCH_SPARE1

void rtdm_event_init(rtdm_event_t *event, unsigned long pending);
int rtdm_event_select(rtdm_event_t *event, rtdm_selector_t *selector,
                      enum rtdm_selecttype type, unsigned fd_index);
int rtdm_event_wait(rtdm_event_t *event);
int rtdm_event_timedwait(rtdm_event_t *event, nanosecs_rel_t timeout,
                         rtdm_toseq_t *timeout_seq);
void rtdm_event_signal(rtdm_event_t *event);

void rtdm_event_clear(rtdm_event_t *event);

void rtdm_event_pulse(rtdm_event_t *event);

void rtdm_event_destroy(rtdm_event_t *event);

/* --- semaphore services --- */

typedef struct rtdm_sem {
        unsigned long value;
        struct xnsynch synch_base;
        DECLARE_XNSELECT(select_block);
} rtdm_sem_t;

void rtdm_sem_init(rtdm_sem_t *sem, unsigned long value);
int rtdm_sem_select(rtdm_sem_t *sem, rtdm_selector_t *selector,
                    enum rtdm_selecttype type, unsigned fd_index);
int rtdm_sem_down(rtdm_sem_t *sem);
int rtdm_sem_timeddown(rtdm_sem_t *sem, nanosecs_rel_t timeout,
                       rtdm_toseq_t *timeout_seq);
void rtdm_sem_up(rtdm_sem_t *sem);

void rtdm_sem_destroy(rtdm_sem_t *sem);

/* --- mutex services --- */

typedef struct rtdm_mutex {
        struct xnsynch synch_base;
        atomic_t fastlock;
} rtdm_mutex_t;

void rtdm_mutex_init(rtdm_mutex_t *mutex);
int rtdm_mutex_lock(rtdm_mutex_t *mutex);
int rtdm_mutex_timedlock(rtdm_mutex_t *mutex, nanosecs_rel_t timeout,
                         rtdm_toseq_t *timeout_seq);
void rtdm_mutex_unlock(rtdm_mutex_t *mutex);
void rtdm_mutex_destroy(rtdm_mutex_t *mutex);

/* --- utility functions --- */

#define rtdm_printk(format, ...)        printk(format, ##__VA_ARGS__)

struct rtdm_ratelimit_state {
        rtdm_lock_t     lock;           /* protect the state */
        nanosecs_abs_t  interval;
        int             burst;
        int             printed;
        int             missed;
        nanosecs_abs_t  begin;
};

int rtdm_ratelimit(struct rtdm_ratelimit_state *rs, const char *func);

#define DEFINE_RTDM_RATELIMIT_STATE(name, interval_init, burst_init)    \
        struct rtdm_ratelimit_state name = {                            \
                .lock           = RTDM_LOCK_UNLOCKED((name).lock),      \
                .interval       = interval_init,                        \
                .burst          = burst_init,                           \
        }

/* We use the Linux defaults */
#define DEF_RTDM_RATELIMIT_INTERVAL     5000000000LL
#define DEF_RTDM_RATELIMIT_BURST        10

#define rtdm_printk_ratelimited(fmt, ...)  ({                           \
        static DEFINE_RTDM_RATELIMIT_STATE(_rs,                         \
                                           DEF_RTDM_RATELIMIT_INTERVAL, \
                                           DEF_RTDM_RATELIMIT_BURST);   \
                                                                        \
        if (rtdm_ratelimit(&_rs, __func__))                             \
                printk(fmt, ##__VA_ARGS__);                             \
})

#ifndef DOXYGEN_CPP /* Avoid static inline tags for RTDM in doxygen */
static inline void *rtdm_malloc(size_t size)
{
        return xnmalloc(size);
}

static inline void rtdm_free(void *ptr)
{
        xnfree(ptr);
}

int rtdm_mmap_to_user(struct rtdm_fd *fd,
                      void *src_addr, size_t len,
                      int prot, void **pptr,
                      struct vm_operations_struct *vm_ops,
                      void *vm_private_data);

int rtdm_iomap_to_user(struct rtdm_fd *fd,
                       phys_addr_t src_addr, size_t len,
                       int prot, void **pptr,
                       struct vm_operations_struct *vm_ops,
                       void *vm_private_data);

int rtdm_mmap_kmem(struct vm_area_struct *vma, void *va);

int rtdm_mmap_vmem(struct vm_area_struct *vma, void *va);

int rtdm_mmap_iomem(struct vm_area_struct *vma, phys_addr_t pa);

int rtdm_munmap(void *ptr, size_t len);

static inline int rtdm_read_user_ok(struct rtdm_fd *fd,
                                    const void __user *ptr, size_t size)
{
        return access_rok(ptr, size);
}

static inline int rtdm_rw_user_ok(struct rtdm_fd *fd,
                                  const void __user *ptr, size_t size)
{
        return access_wok(ptr, size);
}

static inline int rtdm_copy_from_user(struct rtdm_fd *fd,
                                      void *dst, const void __user *src,
                                      size_t size)
{
        return __xn_copy_from_user(dst, src, size) ? -EFAULT : 0;
}

static inline int rtdm_safe_copy_from_user(struct rtdm_fd *fd,
                                           void *dst, const void __user *src,
                                           size_t size)
{
        return cobalt_copy_from_user(dst, src, size);
}

static inline int rtdm_copy_to_user(struct rtdm_fd *fd,
                                    void __user *dst, const void *src,
                                    size_t size)
{
        return __xn_copy_to_user(dst, src, size) ? -EFAULT : 0;
}

static inline int rtdm_safe_copy_to_user(struct rtdm_fd *fd,
                                         void __user *dst, const void *src,
                                         size_t size)
{
        return cobalt_copy_to_user(dst, src, size);
}

static inline int rtdm_strncpy_from_user(struct rtdm_fd *fd,
                                         char *dst,
                                         const char __user *src, size_t count)
{
        return cobalt_strncpy_from_user(dst, src, count);
}

static inline int rtdm_rt_capable(struct rtdm_fd *fd)
{
        if (!XENO_ASSERT(COBALT, !xnsched_interrupt_p()))
                return 0;

        if (!rtdm_fd_is_user(fd))
                return !xnsched_root_p();

        return xnthread_current() != NULL;
}

static inline int rtdm_in_rt_context(void)
{
        return (ipipe_current_domain != ipipe_root_domain);
}

#endif /* !DOXYGEN_CPP */

#endif /* _COBALT_RTDM_DRIVER_H */