Device Registration Services
[Driver Development API]

Collaboration diagram for Device Registration Services:


Modules

 Synchronisation Services

Data Structures

struct  rtdm_operations
 Device operations. More...
struct  rtdm_dev_context
 Device context. More...
struct  rtdm_device
 RTDM device. More...

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, unsigned int request, void __user *arg)
 IOCTL handler.
typedef int(* rtdm_select_bind_handler_t )(struct rtdm_dev_context *context, rtdm_selector_t *selector, enum rtdm_selecttype type, unsigned fd_index)
 Select binding 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.

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 addressed via a clear-text name.
#define RTDM_PROTOCOL_DEVICE   0x0020
 If set, the device is addressed 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_USER_CONTEXT_FLAG   8
 Lowest bit number the driver developer can use freely.

Driver Versioning

Current revisions of RTDM structures, encoding of driver versions. See API Versioning for the interface revision.

#define RTDM_DEVICE_STRUCT_VER   5
 Version of struct rtdm_device.
#define RTDM_CONTEXT_STRUCT_VER   3
 Version of struct rtdm_dev_context.
#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.

Functions

static void * rtdm_context_to_private (struct rtdm_dev_context *context)
 Locate the driver private area associated to a device context structure.
static struct rtdm_dev_context * rtdm_private_to_context (void *dev_private)
 Locate a device context structure from its driver private area.
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.

Define Documentation

#define RTDM_CLOSING   1

Set by RTDM when the device is being closed.

Referenced by rtdm_context_get().

#define RTDM_CREATED_IN_NRT   0

Set by RTDM if the device instance was created in non-real-time context.

#define RTDM_DEVICE_TYPE_MASK   0x00F0

Mask selecting the device type.

Referenced by rtdm_dev_register(), and rtdm_dev_unregister().

#define RTDM_EXCLUSIVE   0x0001

If set, only a single instance of the device can be requested by an application.

Referenced by rtdm_dev_register().

#define RTDM_NAMED_DEVICE   0x0010

If set, the device is addressed via a clear-text name.

Referenced by rtdm_dev_register(), and rtdm_dev_unregister().

#define RTDM_PROTOCOL_DEVICE   0x0020

If set, the device is addressed via a combination of protocol ID and socket type.

Referenced by rtdm_dev_register().

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. On failure return either -ENOSYS, to request that this handler be called again from the opposite realtime/non-realtime context, or another 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, unsigned int request, void __user *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:
A positive value or 0 on success. On failure return either -ENOSYS, to request that the function be called again from the opposite realtime/non-realtime context, or another 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. On failure return either -ENOSYS, to request that this handler be called again from the opposite realtime/non-realtime context, or another 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. On failure return either -ENOSYS, to request that this handler be called again from the opposite realtime/non-realtime context, or another 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. On failure return either -ENOSYS, to request that this handler be called again from the opposite realtime/non-realtime context, or another negative error code.
See also:
recvmsg() in IEEE Std 1003.1, http://www.opengroup.org/onlinepubs/009695399

typedef int(* rtdm_select_bind_handler_t)(struct rtdm_dev_context *context, rtdm_selector_t *selector, enum rtdm_selecttype type, unsigned fd_index)

Select binding handler.

Parameters:
[in] context Context structure associated with opened device instance
[in,out] selector Object that shall be bound to the given event
[in] type Event type the selector is interested in
[in] fd_index Opaque value, to be passed to rtdm_event_select_bind or rtdm_sem_select_bind unmodfied
Returns:
0 on success. On failure return either -ENOSYS, to request that this handler be called again from the opposite realtime/non-realtime context, or another negative error code.

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. On failure return either -ENOSYS, to request that this handler be called again from the opposite realtime/non-realtime context, or another 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. On failure return either -ENOSYS, to request that this handler be called again from the opposite realtime/non-realtime context, or another 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. On failure return either -ENOSYS, to request that this handler be called again from the opposite realtime/non-realtime context, or another negative error code.
See also:
write() in IEEE Std 1003.1, http://www.opengroup.org/onlinepubs/009695399

Function Documentation

static void* rtdm_context_to_private ( struct rtdm_dev_context *  context  )  [inline, static]

Locate the driver private area associated to a device context structure.

Parameters:
[in] context Context structure associated with opened device instance
Returns:
The address of the private driver area associated to context.

References rtdm_dev_context::dev_private.

int rtdm_dev_register ( struct rtdm_device *  device  ) 

Register a RTDM device.

Parameters:
[in] device Pointer to structure describing the new device.
Returns:
0 is returned upon success. Otherwise:
  • -EINVAL is returned if the device structure contains invalid entries. Check kernel log in this case.

  • -ENOMEM is returned if the context for an exclusive device cannot be allocated.

  • -EEXIST is returned if the specified device name of protocol ID is already in use.

  • -EAGAIN is returned if some /proc entry cannot be created.

Environments:

This service can be called from:

  • Kernel module initialization/cleanup code

Rescheduling: never.

References rtdm_operations::close_nrt, rtdm_operations::close_rt, rtdm_device::context_size, rtdm_device::device_class, rtdm_device::device_flags, rtdm_device::device_name, rtdm_device::device_sub_class, rtdm_device::driver_version, rtdm_device::ops, rtdm_device::proc_name, rtdm_device::profile_version, rtdm_device::protocol_family, rtdm_device::reserved, RTDM_DEVICE_STRUCT_VER, RTDM_DEVICE_TYPE_MASK, RTDM_EXCLUSIVE, RTDM_NAMED_DEVICE, RTDM_PROTOCOL_DEVICE, rtdm_operations::select_bind, rtdm_device::socket_type, and rtdm_device::struct_version.

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

Unregisters a RTDM device.

Parameters:
[in] device Pointer to structure describing the device to be unregistered.
[in] poll_delay Polling delay in milliseconds to check repeatedly for open instances of device, or 0 for non-blocking mode.
Returns:
0 is returned upon success. Otherwise:
  • -ENODEV is returned if the device was not registered.

  • -EAGAIN is returned if the device is busy with open instances and 0 has been passed for poll_delay.

Environments:

This service can be called from:

  • Kernel module initialization/cleanup code

Rescheduling: never.

References rtdm_device::device_flags, rtdm_device::device_name, rtdm_device::proc_entry, rtdm_device::proc_name, rtdm_device::protocol_family, rtdm_device::reserved, RTDM_DEVICE_TYPE_MASK, RTDM_NAMED_DEVICE, and rtdm_device::socket_type.

static struct rtdm_dev_context* rtdm_private_to_context ( void *  dev_private  )  [static, read]

Locate a device context structure from its driver private area.

Parameters:
[in] dev_private Address of a private context area
Returns:
The address of the device context structure defining dev_private.

Generated on Sun Mar 28 19:46:53 2010 for Xenomai API by  doxygen 1.5.6