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 <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_FORCED_CLOSING         2

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

#define RTDM_DEVICE_STRUCT_VER      3

#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,
                                      int                       request,
                                      void                      *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);


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

struct rtdm_dev_context {
    unsigned long                   context_flags;
    int                             fd;
    atomic_t                        close_lock_count;
    struct rtdm_operations          *ops;
    struct rtdm_device              *device;
    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;
    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;

    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 --- */
static inline nanosecs_abs_t rtdm_clock_read(void)
{
    return xnpod_ticks2ns(xnpod_get_time());
}
#endif /* !DOXYGEN_CPP */


/* --- spin lock services --- */
#define RTDM_EXECUTE_ATOMICALLY(code_block)                                 \
{                                                                           \
    spl_t   s;                                                              \
                                                                            \
    xnlock_get_irqsave(&nklock, s);                                         \
    code_block;                                                             \
    xnlock_put_irqrestore(&nklock, s);                                      \
}

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

#ifndef DOXYGEN_CPP /* Avoid static inline tags for RTDM in doxygen */
static inline 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)
{
    xnintr_init(irq_handle, device_name, irq_no, handler, NULL, flags);
    return xnintr_attach(irq_handle, arg);
}

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);
#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)
{
    *nrt_sig = rthal_alloc_virq();

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

    rthal_virtualize_irq(rthal_root_domain, *nrt_sig, (rthal_irq_handler_t)handler, NULL, 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 */


/* --- task and timing 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);

#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,
                                     xnpod_ns2ticks(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);
}
#endif /* !DOXYGEN_CPP */

int rtdm_task_sleep(nanosecs_rel_t delay);
int rtdm_task_sleep_until(nanosecs_abs_t wakeup_time);
void rtdm_task_busy_sleep(nanosecs_rel_t delay);


/* --- timeout sequences */

typedef nanosecs_abs_t              rtdm_toseq_t;

#ifndef DOXYGEN_CPP /* Avoid static inline tags for RTDM in doxygen */
static inline void rtdm_toseq_init(rtdm_toseq_t *timeout_seq,
                                   nanosecs_rel_t timeout)
{
    *timeout_seq = xnpod_get_time() + xnpod_ns2ticks(timeout);
}
#endif /* !DOXYGEN_CPP */


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

typedef struct {
    xnsynch_t                       synch_base;
} rtdm_event_t;

#define RTDM_EVENT_PENDING          XNSYNCH_SPARE1

#ifndef DOXYGEN_CPP /* Avoid static inline tags for RTDM in doxygen */
static inline void rtdm_event_init(rtdm_event_t *event, unsigned long pending)
{
    xnsynch_init(&event->synch_base, XNSYNCH_PRIO);
    if (pending)
        xnsynch_set_flags(&event->synch_base, RTDM_EVENT_PENDING);
}

void _rtdm_synch_flush(xnsynch_t *synch, unsigned long reason);

static inline void rtdm_event_destroy(rtdm_event_t *event)
{
    _rtdm_synch_flush(&event->synch_base, XNRMID);
}

static inline void rtdm_event_pulse(rtdm_event_t *event)
{
    _rtdm_synch_flush(&event->synch_base, 0);
}
#endif /* !DOXYGEN_CPP */

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


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

typedef struct {
    unsigned long                   value;
    xnsynch_t                       synch_base;
} rtdm_sem_t;

#ifndef DOXYGEN_CPP /* Avoid static inline tags for RTDM in doxygen */
static inline void rtdm_sem_init(rtdm_sem_t *sem, unsigned long value)
{
    sem->value = value;
    xnsynch_init(&sem->synch_base, XNSYNCH_PRIO);
}

static inline void rtdm_sem_destroy(rtdm_sem_t *sem)
{
    _rtdm_synch_flush(&sem->synch_base, XNRMID);
}
#endif /* !DOXYGEN_CPP */

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


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

typedef struct {
    xnsynch_t                       synch_base;
} rtdm_mutex_t;

#ifndef DOXYGEN_CPP /* Avoid static inline tags for RTDM in doxygen */
static inline void rtdm_mutex_init(rtdm_mutex_t *mutex)
{
    xnsynch_init(&mutex->synch_base, XNSYNCH_PRIO|XNSYNCH_PIP);
}

static inline void rtdm_mutex_destroy(rtdm_mutex_t *mutex)
{
    _rtdm_synch_flush(&mutex->synch_base, XNRMID);
}

static inline void rtdm_mutex_unlock(rtdm_mutex_t *mutex)
{
    XENO_ASSERT(RTDM, !xnpod_asynch_p(), return;);

    if (unlikely(xnsynch_wakeup_one_sleeper(&mutex->synch_base) != NULL))
        xnpod_schedule();
}
#endif /* !DOXYGEN_CPP */

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


/* --- 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 */

---