Xenomai API: Device Registration Services


Data Structures
struct	rtdm_operations
	Device operations. More...
struct	rtdm_dev_context
struct	rtdm_device
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 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 4
	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
int	rtdm_dev_register (struct rtdm_device *device)
int	rtdm_dev_unregister (struct rtdm_device *device, unsigned int poll_delay)

Define Documentation

#define RTDM_CLOSING 1

Set by RTDM when the device is being closed.

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

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

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, 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:: 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

Function Documentation

int rtdm_dev_register ( struct rtdm_device * 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.

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.

Device Registration Services [Driver Development API]

Data Structures

Operation Handler Prototypes

Device Flags

Context Flags

Driver Versioning

Functions

Define Documentation

Typedef Documentation

Function Documentation

Device Registration Services
[Driver Development API]