rtdm_driver.h File Reference


Detailed Description

Real-Time Driver Model for RTAI, driver API header.

Note:
Copyright (C) 2005 Jan Kiszka <jan.kiszka@web.de>

Copyright (C) 2005 Joerg Langenberg <joerg.langenberg@gmx.net>

RTAI/fusion is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

RTAI/fusion is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with RTAI/fusion; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

Include dependency graph for rtdm_driver.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Device Flags

Static flags describing a RTDM device

#define RTDM_EXCLUSIVE   0x0001
 If set, only a single instance of the device can be requested by an application.
#define RTDM_NAMED_DEVICE   0x0010
 If set, the device is addresses via a clear-text name.
#define RTDM_PROTOCOL_DEVICE   0x0020
 If set, the device is addresses via a combination of protocol ID and socket type.
#define RTDM_DEVICE_TYPE_MASK   0x00F0
 Mask selecting the device type.

Context Flags

Dynamic flags describing the state of an open RTDM device (bit numbers)

#define RTDM_CREATED_IN_NRT   0
 Set by RTDM if the device instance was created in non-real-time context.
#define RTDM_CLOSING   1
 Set by RTDM when the device is being closed.
#define RTDM_FORCED_CLOSING   2
 Set by RTDM if the device has to be closed regardless of possible pending locks held by other users.
#define RTDM_USER_CONTEXT_FLAG   8
 Lowest bit number the driver developer can use freely.

Versioning

Current revisions of RTDM structures and interfaces, encoding of driver versions.

#define RTDM_DEVICE_STRUCT_VER   3
 Version of struct rtdm_device.
#define RTDM_CONTEXT_STRUCT_VER   3
 Version of struct rtdm_dev_context.
#define RTDM_API_VER   3
 Driver API version.
#define RTDM_API_MIN_COMPAT_VER   3
 Minimum API revision compatible with the current release.
#define RTDM_SECURE_DEVICE   0x80000000
 Flag indicating a secure variant of RTDM (not supported here).
#define RTDM_DRIVER_VER(major, minor, patch)   (((major & 0xFF) << 16) | ((minor & 0xFF) << 8) | (patch & 0xFF))
 Version code constructor for driver revisions.
#define RTDM_DRIVER_MAJOR_VER(ver)   (((ver) >> 16) & 0xFF)
 Get major version number from driver revision code.
#define RTDM_DRIVER_MINOR_VER(ver)   (((ver) >> 8) & 0xFF)
 Get minor version number from driver revision code.
#define RTDM_DRIVER_PATCH_VER(ver)   ((ver) & 0xFF)
 Get patch version number from driver revision code.

Global Lock across Scheduler Invocation

#define RTDM_EXECUTE_ATOMICALLY(code_block)
 Execute code block atomically.

Spinlock with Preemption Deactivation

#define RTDM_LOCK_UNLOCKED   SPIN_LOCK_UNLOCKED
 Static lock initialisation.
#define rtdm_lock_init(lock)   spin_lock_init(lock)
 Dynamic lock initialisation.
#define rtdm_lock_get(lock)   rthal_spin_lock(lock)
 Acquire lock from non-preemptible contexts.
#define rtdm_lock_put(lock)   rthal_spin_unlock(lock)
 Release lock without preemption restoration.
#define rtdm_lock_get_irqsave(lock, context)   rthal_spin_lock_irqsave(lock, context)
 Acquire lock and disable preemption.
#define rtdm_lock_put_irqrestore(lock, context)   rthal_spin_unlock_irqrestore(lock, context)
 Release lock and restore preemption state.
#define rtdm_lock_irqsave(context)   rthal_local_irq_save(context)
 Disable preemption locally.
#define rtdm_lock_irqrestore(context)   rthal_local_irq_restore(context)
 Restore preemption state.
typedef spinlock_t rtdm_lock_t
 Lock variable.
typedef unsigned long rtdm_lockctx_t
 Variable to save the context while holding a lock.

RTDM_IRQ_xxx

Return flags of interrupt handlers

#define RTDM_IRQ_PROPAGATE   XN_ISR_CHAINED
 Propagate unhandled interrupt to possible other handlers.
#define RTDM_IRQ_ENABLE   XN_ISR_ENABLE
 Re-enable interrupt line on return.

Task Priority Range

Maximum and minimum task priorities

#define RTDM_TASK_LOWEST_PRIORITY   FUSION_LOW_PRIO
#define RTDM_TASK_HIGHEST_PRIORITY   FUSION_HIGH_PRIO

Operation Handler Prototypes

typedef int(* rtdm_open_handler_t )(struct rtdm_dev_context *context, rtdm_user_info_t *user_info, int oflag)
 Named device open handler.
typedef int(* rtdm_socket_handler_t )(struct rtdm_dev_context *context, rtdm_user_info_t *user_info, int protocol)
 Socket creation handler for protocol devices.
typedef int(* rtdm_close_handler_t )(struct rtdm_dev_context *context, rtdm_user_info_t *user_info)
 Close handler.
typedef int(* rtdm_ioctl_handler_t )(struct rtdm_dev_context *context, rtdm_user_info_t *user_info, int request, void *arg)
 IOCTL handler.
typedef ssize_t(* rtdm_read_handler_t )(struct rtdm_dev_context *context, rtdm_user_info_t *user_info, void *buf, size_t nbyte)
 Read handler.
typedef ssize_t(* rtdm_write_handler_t )(struct rtdm_dev_context *context, rtdm_user_info_t *user_info, const void *buf, size_t nbyte)
 Write handler.
typedef ssize_t(* rtdm_recvmsg_handler_t )(struct rtdm_dev_context *context, rtdm_user_info_t *user_info, struct msghdr *msg, int flags)
 Receive message handler.
typedef ssize_t(* rtdm_sendmsg_handler_t )(struct rtdm_dev_context *context, rtdm_user_info_t *user_info, const struct msghdr *msg, int flags)
 Transmit message handler.

Defines

#define rtdm_irq_get_arg(irq_handle, type)   ((type *)irq_handle->cookie)
 Retrieve IRQ handler argument.

Typedefs

typedef int(* rtdm_irq_handler_t )(rtdm_irq_t *irq_handle)
 Interrupt handler.
typedef void(* rtdm_nrtsig_handler_t )(rtdm_nrtsig_t nrt_sig)
 Non-real-time signal handler.
typedef void(* rtdm_task_proc_t )(void *arg)
 Real-time task procedure.

Functions

int rtdm_dev_register (struct rtdm_device *device)
 Register a RTDM device.
int rtdm_dev_unregister (struct rtdm_device *device, unsigned int poll_delay)
 Unregisters a RTDM device.
rtdm_dev_contextrtdm_context_get (int fd)
 Resolve file descriptor to device context.
void rtdm_task_join_nrt (rtdm_task_t *task, unsigned int poll_delay)
 Wait on a real-time task to terminate.
int rtdm_task_sleep (__u64 delay)
 Sleep a specified amount of time.
int rtdm_task_sleep_until (__u64 wakeup_time)
 Sleep until a specified absolute time.
void rtdm_task_busy_sleep (__u64 delay)
 Busy-wait a specified amount of time.
int rtdm_event_wait (rtdm_event_t *event)
 Wait on event occurrence.
int rtdm_event_timedwait (rtdm_event_t *event, __s64 timeout, rtdm_toseq_t *timeout_seq)
 Wait on event occurrence with timeout.
void rtdm_event_signal (rtdm_event_t *event)
 Signal an event occurrence.
int rtdm_sem_down (rtdm_sem_t *sem)
 Decrement a semaphore.
int rtdm_sem_timeddown (rtdm_sem_t *sem, __s64 timeout, rtdm_toseq_t *timeout_seq)
 Decrement a semaphore with timeout.
void rtdm_sem_up (rtdm_sem_t *sem)
 Increment a semaphore.
int rtdm_mutex_lock (rtdm_mutex_t *mutex)
 Request a mutex.
int rtdm_mutex_timedlock (rtdm_mutex_t *mutex, __s64 timeout, rtdm_toseq_t *timeout_seq)
 Request a mutex with timeout.
void rtdm_mutex_unlock (rtdm_mutex_t *mutex)
 Release a mutex.


Typedef Documentation

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

Close handler.

Parameters:
[in] context Context structure associated with opened device instance
[in] user_info Opaque pointer to information about user mode caller, NULL if kernel mode call
Returns:
0 on success, otherwise negative error code
See also:
close() in IEEE Std 1003.1, http://www.opengroup.org/onlinepubs/009695399

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

IOCTL handler.

Parameters:
[in] context Context structure associated with opened device instance
[in] user_info Opaque pointer to information about user mode caller, NULL if kernel mode call
[in] request Request number as passed by the user
[in,out] arg Request argument as passed by the user
Returns:
Positiv value on success, otherwise negative error code
See also:
ioctl() in IEEE Std 1003.1, http://www.opengroup.org/onlinepubs/009695399

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

Named device open handler.

Parameters:
[in] context Context structure associated with opened device instance
[in] user_info Opaque pointer to information about user mode caller, NULL if kernel mode call
[in] oflag Open flags as passed by the user
Returns:
0 on success, otherwise negative error code
See also:
open() in IEEE Std 1003.1, http://www.opengroup.org/onlinepubs/009695399

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

Read handler.

Parameters:
[in] context Context structure associated with opened device instance
[in] user_info Opaque pointer to information about user mode caller, NULL if kernel mode call
[out] buf Input buffer as passed by the user
[in] nbyte Number of bytes the user requests to read
Returns:
On success, the number of bytes read, otherwise negative error code
See also:
read() in IEEE Std 1003.1, http://www.opengroup.org/onlinepubs/009695399

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

Receive message handler.

Parameters:
[in] context Context structure associated with opened device instance
[in] user_info Opaque pointer to information about user mode caller, NULL if kernel mode call
[in,out] msg Message descriptor as passed by the user, automatically mirrored to safe kernel memory in case of user mode call
[in] flags Message flags as passed by the user
Returns:
On success, the number of bytes received, otherwise negative error code
See also:
recvmsg() in IEEE Std 1003.1, http://www.opengroup.org/onlinepubs/009695399

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

Transmit message handler.

Parameters:
[in] context Context structure associated with opened device instance
[in] user_info Opaque pointer to information about user mode caller, NULL if kernel mode call
[in] msg Message descriptor as passed by the user, automatically mirrored to safe kernel memory in case of user mode call
[in] flags Message flags as passed by the user
Returns:
On success, the number of bytes transmitted, otherwise negative error code
See also:
sendmsg() in IEEE Std 1003.1, http://www.opengroup.org/onlinepubs/009695399

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

Socket creation handler for protocol devices.

Parameters:
[in] context Context structure associated with opened device instance
[in] user_info Opaque pointer to information about user mode caller, NULL if kernel mode call
[in] protocol Protocol number as passed by the user
Returns:
0 on success, otherwise negative error code
See also:
socket() in IEEE Std 1003.1, http://www.opengroup.org/onlinepubs/009695399

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

Write handler.

Parameters:
[in] context Context structure associated with opened device instance
[in] user_info Opaque pointer to information about user mode caller, NULL if kernel mode call
[in] buf Output buffer as passed by the user
[in] nbyte Number of bytes the user requests to write
Returns:
On success, the number of bytes written, otherwise negative error code
See also:
write() in IEEE Std 1003.1, http://www.opengroup.org/onlinepubs/009695399


Generated on Sat Sep 3 12:32:49 2005 for RTAI Fusion API by  doxygen 1.4.2