include/rtdm/rtdm_driver.h

Go to the documentation of this file.

#ifndef _RTDM_DRIVER_H
#define _RTDM_DRIVER_H

#ifndef __KERNEL__
#error This header is for kernel space usage only. \
       You are likely looking for rtdm/rtdm.h...
#endif /* !__KERNEL__ */

#include <asm/atomic.h>
#include <linux/list.h>

#include <nucleus/xenomai.h>
#include <nucleus/core.h>
#include <nucleus/heap.h>
#include <nucleus/pod.h>
#include <nucleus/synch.h>
#include <nucleus/select.h>
#include <rtdm/rtdm.h>

/* debug support */
#include <nucleus/assert.h>

#ifndef CONFIG_XENO_OPT_DEBUG_RTDM
#define CONFIG_XENO_OPT_DEBUG_RTDM      0
#endif

struct rtdm_dev_context;

#define RTDM_EXCLUSIVE                  0x0001

#define RTDM_NAMED_DEVICE               0x0010

#define RTDM_PROTOCOL_DEVICE            0x0020

#define RTDM_DEVICE_TYPE_MASK           0x00F0

#define RTDM_CREATED_IN_NRT             0

#define RTDM_CLOSING                    1

#define RTDM_USER_CONTEXT_FLAG          8  /* first user-definable flag */

#define RTDM_DEVICE_STRUCT_VER          4

#define RTDM_CONTEXT_STRUCT_VER         3

#define RTDM_SECURE_DEVICE              0x80000000

#define RTDM_DRIVER_VER(major, minor, patch) \
        (((major & 0xFF) << 16) | ((minor & 0xFF) << 8) | (patch & 0xFF))

#define RTDM_DRIVER_MAJOR_VER(ver)      (((ver) >> 16) & 0xFF)

#define RTDM_DRIVER_MINOR_VER(ver)      (((ver) >> 8) & 0xFF)

#define RTDM_DRIVER_PATCH_VER(ver)      ((ver) & 0xFF)

typedef int (*rtdm_open_handler_t)(struct rtdm_dev_context *context,
                                   rtdm_user_info_t *user_info, int oflag);

typedef int (*rtdm_socket_handler_t)(struct rtdm_dev_context *context,
                                     rtdm_user_info_t *user_info, int protocol);

typedef int (*rtdm_close_handler_t)(struct rtdm_dev_context *context,
                                    rtdm_user_info_t *user_info);

typedef int (*rtdm_ioctl_handler_t)(struct rtdm_dev_context *context,
                                    rtdm_user_info_t *user_info,
                                    unsigned int request, void __user *arg);

typedef ssize_t (*rtdm_read_handler_t)(struct rtdm_dev_context *context,
                                       rtdm_user_info_t *user_info,
                                       void *buf, size_t nbyte);

typedef ssize_t (*rtdm_write_handler_t)(struct rtdm_dev_context *context,
                                        rtdm_user_info_t *user_info,
                                        const void *buf, size_t nbyte);

typedef ssize_t (*rtdm_recvmsg_handler_t)(struct rtdm_dev_context *context,
                                          rtdm_user_info_t *user_info,
                                          struct msghdr *msg, int flags);

typedef ssize_t (*rtdm_sendmsg_handler_t)(struct rtdm_dev_context *context,
                                          rtdm_user_info_t *user_info,
                                          const struct msghdr *msg, int flags);
typedef int (*rtdm_rt_handler_t)(struct rtdm_dev_context *context,
                                 rtdm_user_info_t *user_info, void *arg);

typedef int (*rtdm_select_bind_handler_t)(struct rtdm_dev_context *context,
                                          struct xnselector *selector,
                                          unsigned type,
                                          unsigned index);
struct rtdm_operations {
        rtdm_close_handler_t close_rt;
        rtdm_close_handler_t close_nrt;

        rtdm_ioctl_handler_t ioctl_rt;
        rtdm_ioctl_handler_t ioctl_nrt;
        rtdm_read_handler_t read_rt;
        rtdm_read_handler_t read_nrt;

        rtdm_write_handler_t write_rt;
        rtdm_write_handler_t write_nrt;
        rtdm_recvmsg_handler_t recvmsg_rt;
        rtdm_recvmsg_handler_t recvmsg_nrt;

        rtdm_sendmsg_handler_t sendmsg_rt;
        rtdm_sendmsg_handler_t sendmsg_nrt;
        rtdm_select_bind_handler_t select_bind;
};

struct rtdm_devctx_reserved {
        void *owner;
};

struct rtdm_dev_context {
        unsigned long context_flags;

        int fd;

        atomic_t close_lock_count;

        struct rtdm_operations *ops;

        struct rtdm_device *device;

        struct rtdm_devctx_reserved reserved;

        char dev_private[0];
};

struct rtdm_dev_reserved {
        struct list_head entry;
        atomic_t refcount;
        struct rtdm_dev_context *exclusive_context;
};

struct rtdm_device {
        int struct_version;

        int device_flags;
        size_t context_size;

        char device_name[RTDM_MAX_DEVNAME_LEN + 1];

        int protocol_family;
        int socket_type;

        rtdm_open_handler_t open_rt;
        rtdm_open_handler_t open_nrt;

        rtdm_socket_handler_t socket_rt;
        rtdm_socket_handler_t socket_nrt;

        struct rtdm_operations ops;

        int device_class;
        int device_sub_class;
        int profile_version;
        const char *driver_name;
        int driver_version;
        const char *peripheral_name;
        const char *provider_name;

        const char *proc_name;
        struct proc_dir_entry *proc_entry;

        int device_id;
        void *device_data;

        struct rtdm_dev_reserved reserved;
};
/* --- device registration --- */

int rtdm_dev_register(struct rtdm_device *device);
int rtdm_dev_unregister(struct rtdm_device *device, unsigned int poll_delay);

/* --- inter-driver API --- */

#define rtdm_open               rt_dev_open
#define rtdm_socket             rt_dev_socket
#define rtdm_close              rt_dev_close
#define rtdm_ioctl              rt_dev_ioctl
#define rtdm_read               rt_dev_read
#define rtdm_write              rt_dev_write
#define rtdm_recvmsg            rt_dev_recvmsg
#define rtdm_recv               rt_dev_recv
#define rtdm_recvfrom           rt_dev_recvfrom
#define rtdm_sendmsg            rt_dev_sendmsg
#define rtdm_send               rt_dev_send
#define rtdm_sendto             rt_dev_sendto
#define rtdm_bind               rt_dev_bind
#define rtdm_listen             rt_dev_listen
#define rtdm_accept             rt_dev_accept
#define rtdm_getsockopt         rt_dev_getsockopt
#define rtdm_setsockopt         rt_dev_setsockopt
#define rtdm_getsockname        rt_dev_getsockname
#define rtdm_getpeername        rt_dev_getpeername
#define rtdm_shutdown           rt_dev_shutdown

struct rtdm_dev_context *rtdm_context_get(int fd);

#ifndef DOXYGEN_CPP /* Avoid static inline tags for RTDM in doxygen */
static inline void rtdm_context_lock(struct rtdm_dev_context *context)
{
        atomic_inc(&context->close_lock_count);
}

static inline void rtdm_context_unlock(struct rtdm_dev_context *context)
{
        atomic_dec(&context->close_lock_count);
}

/* --- clock services --- */
struct xntbase;
extern struct xntbase *rtdm_tbase;

static inline nanosecs_abs_t rtdm_clock_read(void)
{
        return xntbase_ticks2ns(rtdm_tbase, xntbase_get_time(rtdm_tbase));
}

static inline nanosecs_abs_t rtdm_clock_read_monotonic(void)
{
        return xntbase_ticks2ns(rtdm_tbase, xntbase_get_jiffies(rtdm_tbase));
}
#endif /* !DOXYGEN_CPP */

/* --- spin lock services --- */
#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 */
#define RTDM_EXECUTE_ATOMICALLY(code_block)     \
{                                               \
        spl_t s;                                \
                                                \
        xnlock_get_irqsave(&nklock, s);         \
        code_block;                             \
        xnlock_put_irqrestore(&nklock, s);      \
}
#endif

#define RTDM_LOCK_UNLOCKED      RTHAL_SPIN_LOCK_UNLOCKED

typedef rthal_spinlock_t rtdm_lock_t;

typedef unsigned long rtdm_lockctx_t;

#define rtdm_lock_init(lock)    rthal_spin_lock_init(lock)

#define rtdm_lock_get(lock)     rthal_spin_lock(lock)

#define rtdm_lock_put(lock)     rthal_spin_unlock(lock)

#define rtdm_lock_get_irqsave(lock, context)    \
        rthal_spin_lock_irqsave(lock, context)

#define rtdm_lock_put_irqrestore(lock, context) \
        rthal_spin_unlock_irqrestore(lock, context)

#define rtdm_lock_irqsave(context)      \
        rthal_local_irq_save(context)

#define rtdm_lock_irqrestore(context)   \
        rthal_local_irq_restore(context)

/* --- Interrupt management services --- */
typedef xnintr_t rtdm_irq_t;

#define RTDM_IRQTYPE_SHARED             XN_ISR_SHARED

#define RTDM_IRQTYPE_EDGE               XN_ISR_EDGE

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

#define RTDM_IRQ_NONE                   XN_ISR_NONE

#define RTDM_IRQ_HANDLED                XN_ISR_HANDLED

#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)
{
        return xnintr_detach(irq_handle);
}

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

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

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

typedef unsigned rtdm_nrtsig_t;

typedef void (*rtdm_nrtsig_handler_t)(rtdm_nrtsig_t nrt_sig, void *arg);
#ifndef DOXYGEN_CPP /* Avoid static inline tags for RTDM in doxygen */
static inline int rtdm_nrtsig_init(rtdm_nrtsig_t *nrt_sig,
                                   rtdm_nrtsig_handler_t handler, void *arg)
{
        *nrt_sig = rthal_alloc_virq();

        if (*nrt_sig == 0)
                return -EAGAIN;

        rthal_virtualize_irq(rthal_root_domain, *nrt_sig, handler, arg, NULL,
                             IPIPE_HANDLE_MASK);
        return 0;
}

static inline void rtdm_nrtsig_destroy(rtdm_nrtsig_t *nrt_sig)
{
        rthal_free_virq(*nrt_sig);
}

static inline void rtdm_nrtsig_pend(rtdm_nrtsig_t *nrt_sig)
{
        rthal_trigger_irq(*nrt_sig);
}
#endif /* !DOXYGEN_CPP */

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

typedef xntimer_t 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), rtdm_tbase, handler);     \
        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, xntbase_ns2ticks_ceil(rtdm_tbase, expiry),
                             xntbase_ns2ticks_ceil(rtdm_tbase, 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 xnthread_t rtdm_task_t;

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

#define RTDM_TASK_LOWEST_PRIORITY       XNCORE_LOW_PRIO
#define RTDM_TASK_HIGHEST_PRIORITY      XNCORE_HIGH_PRIO

#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)
{
        xnpod_delete_thread(task);
}

void rtdm_task_join_nrt(rtdm_task_t *task, unsigned int poll_delay);

static inline void rtdm_task_set_priority(rtdm_task_t *task, int priority)
{
        xnpod_renice_thread(task, priority);
        xnpod_schedule();
}

static inline int rtdm_task_set_period(rtdm_task_t *task,
                                       nanosecs_rel_t period)
{
        if (period < 0)
                period = 0;
        return xnpod_set_thread_periodic(task, XN_INFINITE,
                                         xntbase_ns2ticks_ceil
                                         (xnthread_time_base(task), period));
}

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

        xnpod_schedule();
        return res;
}

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

static inline int rtdm_task_wait_period(void)
{
        XENO_ASSERT(RTDM, !xnpod_unblockable_p(), return -EPERM;);
        return xnpod_wait_thread_period(NULL);
}

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);
}
#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);

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

typedef struct {
        xnsynch_t 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);
#ifdef CONFIG_XENO_OPT_RTDM_SELECT
int rtdm_event_select_bind(rtdm_event_t *event,
                           struct xnselector *selector,
                           unsigned type,
                           unsigned bit_index);
#else /* !CONFIG_XENO_OPT_RTDM_SELECT */
#define rtdm_event_select_bind(e, s, t, b) ({ -EBADF; })
#endif /* !CONFIG_XENO_OPT_RTDM_SELECT */
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);

#ifndef DOXYGEN_CPP /* Avoid static inline tags for RTDM in doxygen */
void __rtdm_synch_flush(xnsynch_t *synch, unsigned long reason);

static inline void rtdm_event_pulse(rtdm_event_t *event)
{
        trace_mark(xn_rtdm_event_pulse, "event %p", event);
        __rtdm_synch_flush(&event->synch_base, 0);
}

static inline void rtdm_event_destroy(rtdm_event_t *event)
{
        trace_mark(xn_rtdm_event_destroy, "event %p", event);
        __rtdm_synch_flush(&event->synch_base, XNRMID);
        xnselect_destroy(&event->select_block);
}
#endif /* !DOXYGEN_CPP */

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

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

void rtdm_sem_init(rtdm_sem_t *sem, unsigned long value);
#ifdef CONFIG_XENO_OPT_RTDM_SELECT
int rtdm_sem_select_bind(rtdm_sem_t *sem,
                         struct xnselector *selector,
                         unsigned type,
                         unsigned bit_index);
#else /* !CONFIG_XENO_OPT_RTDM_SELECT */
#define rtdm_sem_select_bind(s, se, t, b) ({ -EBADF; })
#endif /* !CONFIG_XENO_OPT_RTDM_SELECT */
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);

#ifndef DOXYGEN_CPP /* Avoid static inline tags for RTDM in doxygen */
static inline void rtdm_sem_destroy(rtdm_sem_t *sem)
{
        trace_mark(xn_rtdm_sem_destroy, "sem %p", sem);
        __rtdm_synch_flush(&sem->synch_base, XNRMID);
        xnselect_destroy(&sem->select_block);
}
#endif /* !DOXYGEN_CPP */

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

typedef struct {
        xnsynch_t synch_base;
} 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);

#ifndef DOXYGEN_CPP /* Avoid static inline tags for RTDM in doxygen */
static inline void rtdm_mutex_unlock(rtdm_mutex_t *mutex)
{
        XENO_ASSERT(RTDM, !xnpod_asynch_p(), return;);

        trace_mark(xn_rtdm_mutex_unlock, "mutex %p", mutex);

        if (unlikely(xnsynch_wakeup_one_sleeper(&mutex->synch_base) != NULL))
                xnpod_schedule();
}

static inline void rtdm_mutex_destroy(rtdm_mutex_t *mutex)
{
        trace_mark(xn_rtdm_mutex_destroy, "mutex %p", mutex);

        __rtdm_synch_flush(&mutex->synch_base, XNRMID);
}
#endif /* !DOXYGEN_CPP */

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

#define rtdm_printk(format, ...)        printk(format, ##__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);
}

#ifdef CONFIG_XENO_OPT_PERVASIVE
int rtdm_mmap_to_user(rtdm_user_info_t *user_info,
                      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(rtdm_user_info_t *user_info,
                       unsigned long src_addr, size_t len,
                       int prot, void **pptr,
                       struct vm_operations_struct *vm_ops,
                       void *vm_private_data);
int rtdm_munmap(rtdm_user_info_t *user_info, void *ptr, size_t len);

static inline int rtdm_read_user_ok(rtdm_user_info_t *user_info,
                                    const void __user *ptr, size_t size)
{
        return __xn_access_ok(user_info, VERIFY_READ, ptr, size);
}

static inline int rtdm_rw_user_ok(rtdm_user_info_t *user_info,
                                  const void __user *ptr, size_t size)
{
        return __xn_access_ok(user_info, VERIFY_WRITE, ptr, size);
}

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

static inline int rtdm_safe_copy_from_user(rtdm_user_info_t *user_info,
                                           void *dst, const void __user *src,
                                           size_t size)
{
        return (!__xn_access_ok(user_info, VERIFY_READ, src, size) ||
                __xn_copy_from_user(user_info, dst, src, size)) ? -EFAULT : 0;
}

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

static inline int rtdm_safe_copy_to_user(rtdm_user_info_t *user_info,
                                         void __user *dst, const void *src,
                                         size_t size)
{
        return (!__xn_access_ok(user_info, VERIFY_WRITE, dst, size) ||
                __xn_copy_to_user(user_info, dst, src, size)) ? -EFAULT : 0;
}

static inline int rtdm_strncpy_from_user(rtdm_user_info_t *user_info,
                                         char *dst,
                                         const char __user *src, size_t count)
{
        if (unlikely(!__xn_access_ok(user_info, VERIFY_READ, src, 1)))
                return -EFAULT;
        return __xn_strncpy_from_user(user_info, dst, src, count);
}
#else /* !CONFIG_XENO_OPT_PERVASIVE */
/* Define void user<->kernel services that simply fail */
#define rtdm_mmap_to_user(...)          ({ -ENOSYS; })
#define rtdm_munmap(...)                ({ -ENOSYS; })
#define rtdm_read_user_ok(...)          ({ 0; })
#define rtdm_rw_user_ok(...)            ({ 0; })
#define rtdm_copy_from_user(...)        ({ -ENOSYS; })
#define rtdm_safe_copy_from_user(...)   ({ -ENOSYS; })
#define rtdm_copy_to_user(...)          ({ -ENOSYS; })
#define rtdm_safe_copy_to_user(...)     ({ -ENOSYS; })
#define rtdm_strncpy_from_user(...)     ({ -ENOSYS; })
#endif /* CONFIG_XENO_OPT_PERVASIVE */

static inline int rtdm_in_rt_context(void)
{
        return (rthal_current_domain != rthal_root_domain);
}
#endif /* !DOXYGEN_CPP */

int rtdm_exec_in_rt(struct rtdm_dev_context *context,
                    rtdm_user_info_t *user_info, void *arg,
                    rtdm_rt_handler_t handler);

#endif /* _RTDM_DRIVER_H */

---