This profile includes all mini-drivers sitting on top of the User-space Device Driver framework (UDD). More...

Collaboration diagram for User-space driver core:

Data Structures
struct	udd_memregion

struct	udd_device

struct	udd_signotify
	UDD event notification descriptor. More...

Functions
int	udd_register_device (struct udd_device *udd)
	Register a UDD device. More...

int	udd_unregister_device (struct udd_device *udd)
	Unregister a UDD device. More...

struct udd_device *	udd_get_device (struct rtdm_fd *fd)
	RTDM file descriptor to target UDD device. More...

void	udd_notify_event (struct udd_device *udd)
	Notify an IRQ event for an unmanaged interrupt. More...

void	udd_enable_irq (struct udd_device udd, rtdm_event_t done)
	Enable the device IRQ line. More...

void	udd_disable_irq (struct udd_device udd, rtdm_event_t done)
	Disable the device IRQ line. More...

#define	UDD_IRQ_NONE 0
	No IRQ managed. More...

#define	UDD_IRQ_CUSTOM (-1)
	IRQ directly managed from the mini-driver on top of the UDD core. More...

Memory types for mapping
Types of memory for mapping The UDD core implements a default ->mmap() handler which first attempts to hand over the request to the corresponding handler defined by the mini-driver. If not present, the UDD core establishes the mapping automatically, depending on the memory type defined for the region.
#define	UDD_MEM_NONE 0
	No memory region. More...

#define	UDD_MEM_PHYS 1
	Physical I/O memory region. More...

#define	UDD_MEM_LOGICAL 2
	Kernel logical memory region (e.g. More...

#define	UDD_MEM_VIRTUAL 3
	Virtual memory region with no direct physical mapping (e.g. More...

UDD_IOCTL
IOCTL requests
#define	UDD_RTIOC_IRQEN _IO(RTDM_CLASS_UDD, 0)
	Enable the interrupt line. More...

#define	UDD_RTIOC_IRQDIS _IO(RTDM_CLASS_UDD, 1)
	Disable the interrupt line. More...

#define	UDD_RTIOC_IRQSIG _IOW(RTDM_CLASS_UDD, 2, struct udd_signotify)
	Enable/Disable signal notification upon interrupt event. More...

Detailed Description

This profile includes all mini-drivers sitting on top of the User-space Device Driver framework (UDD).

The generic UDD core driver enables interrupt control and I/O memory access interfaces to user-space device drivers, as defined by the mini-drivers when registering.

A mini-driver supplements the UDD core with ancillary functions for dealing with memory mappings and interrupt control for a particular I/O card/device.

UDD-compliant mini-drivers only have to provide the basic support for dealing with the interrupt sources present in the device, so that most part of the device requests can be handled from a Xenomai application running in user-space. Typically, a mini-driver would handle the interrupt top-half, and the user-space application would handle the bottom-half.

This profile is reminiscent of the UIO framework available with the Linux kernel, adapted to the dual kernel Cobalt environment.

Macro Definition Documentation

◆ UDD_IRQ_CUSTOM

#define UDD_IRQ_CUSTOM (-1)

IRQ directly managed from the mini-driver on top of the UDD core.

The mini-driver is in charge of attaching the handler(s) to the IRQ(s) it manages, notifying the Cobalt threads waiting for IRQ events by calling the udd_notify_event() service.

Referenced by udd_disable_irq(), udd_enable_irq(), udd_register_device(), and udd_unregister_device().

◆ UDD_IRQ_NONE

#define UDD_IRQ_NONE 0

No IRQ managed.

Special IRQ values for udd_device.irq Passing this code implicitly disables all interrupt-related services, including control (disable/enable) and notification.

Referenced by udd_disable_irq(), udd_enable_irq(), udd_register_device(), and udd_unregister_device().

◆ UDD_MEM_LOGICAL

#define UDD_MEM_LOGICAL 2

Kernel logical memory region (e.g.

kmalloc()). By default, the UDD core maps such memory to a virtual user range by calling the rtdm_mmap_kmem() service.

◆ UDD_MEM_NONE

#define UDD_MEM_NONE 0

No memory region.

Use this type code to disable an entry in the array of memory mappings, i.e. udd_device.mem_regions[].

◆ UDD_MEM_PHYS

#define UDD_MEM_PHYS 1

Physical I/O memory region.

By default, the UDD core maps such memory to a virtual user range by calling the rtdm_mmap_iomem() service.

◆ UDD_MEM_VIRTUAL

#define UDD_MEM_VIRTUAL 3

Virtual memory region with no direct physical mapping (e.g.

vmalloc()). By default, the UDD core maps such memory to a virtual user range by calling the rtdm_mmap_vmem() service.

◆ UDD_RTIOC_IRQDIS

#define UDD_RTIOC_IRQDIS _IO(RTDM_CLASS_UDD, 1)

Disable the interrupt line.

The UDD-class mini-driver should handle this request when received through its ->ioctl() handler if provided. Otherwise, the UDD core disables the interrupt line in the interrupt controller before returning to the caller.

Note: The mini-driver must handle the UDD_RTIOC_IRQEN request for a custom IRQ from its ->ioctl() handler, otherwise such request receives -EIO from the UDD core.

◆ UDD_RTIOC_IRQEN

#define UDD_RTIOC_IRQEN _IO(RTDM_CLASS_UDD, 0)

Enable the interrupt line.

The UDD-class mini-driver should handle this request when received through its ->ioctl() handler if provided. Otherwise, the UDD core enables the interrupt line in the interrupt controller before returning to the caller.

◆ UDD_RTIOC_IRQSIG

#define UDD_RTIOC_IRQSIG _IOW(RTDM_CLASS_UDD, 2, struct udd_signotify)

Enable/Disable signal notification upon interrupt event.

A valid notification descriptor must be passed along with this request, which is handled by the UDD core directly.

Note: The mini-driver must handle the UDD_RTIOC_IRQDIS request for a custom IRQ from its ->ioctl() handler, otherwise such request receives -EIO from the UDD core.

Function Documentation

◆ udd_disable_irq()

void udd_disable_irq	(	struct udd_device *	udd,
		rtdm_event_t *	done
	)

Disable the device IRQ line.

This service issues a request to the regular kernel for disabling the IRQ line registered by the driver. If the caller runs in primary mode, the request is scheduled but deferred until the current CPU leaves the real-time domain (see note). Otherwise, the request is immediately handled.

Parameters

udd	The UDD driver handling the IRQ to disable. If no IRQ was registered by the driver at the UDD core, this routine has no effect.
done	Optional event to signal upon completion. If non-NULL, done will be posted by a call to rtdm_event_signal() after the interrupt line is disabled.

Tags: unrestricted

Note: The deferral is required as some interrupt management code involved in disabling interrupt lines may not be safely executed from primary mode. By passing a valid done object address, the caller can wait for the request to complete, by sleeping on rtdm_event_wait().

References udd_device::irq, UDD_IRQ_CUSTOM, and UDD_IRQ_NONE.

◆ udd_enable_irq()

void udd_enable_irq	(	struct udd_device *	udd,
		rtdm_event_t *	done
	)

Enable the device IRQ line.

This service issues a request to the regular kernel for enabling the IRQ line registered by the driver. If the caller runs in primary mode, the request is scheduled but deferred until the current CPU leaves the real-time domain (see note). Otherwise, the request is immediately handled.

Parameters

udd	The UDD driver handling the IRQ to disable. If no IRQ was registered by the driver at the UDD core, this routine has no effect.
done	Optional event to signal upon completion. If non-NULL, done will be posted by a call to rtdm_event_signal() after the interrupt line is enabled.

Tags: unrestricted

Note: The deferral is required as some interrupt management code involved in enabling interrupt lines may not be safely executed from primary mode. By passing a valid done object address, the caller can wait for the request to complete, by sleeping on rtdm_event_wait().

References udd_device::irq, UDD_IRQ_CUSTOM, and UDD_IRQ_NONE.

◆ udd_get_device()

struct udd_device* udd_get_device ( struct rtdm_fd * fd )

RTDM file descriptor to target UDD device.

Retrieves the UDD device from a RTDM file descriptor.

Parameters

fd	File descriptor received by an ancillary I/O handler from a mini-driver based on the UDD core.

Returns: A pointer to the UDD device to which fd refers to.

Note: This service is intended for use by mini-drivers based on the UDD core exclusively. Passing file descriptors referring to other RTDM devices will certainly lead to invalid results.

Tags: mode-unrestricted

References rtdm_device::driver, rtdm_driver::profile_info, and rtdm_fd_device().

◆ udd_notify_event()

void udd_notify_event ( struct udd_device * udd )

Notify an IRQ event for an unmanaged interrupt.

When the UDD core shall hand over the interrupt management for a device to the mini-driver (see UDD_IRQ_CUSTOM), the latter should notify the UDD core when IRQ events are received by calling this service.

As a result, the UDD core wakes up any Cobalt thread waiting for interrupts on the device via a read(2) or select(2) call.

Parameters

udd	UDD device descriptor receiving the IRQ.

Tags: coreirq-only

Note: In case the IRQ handler from the mini-driver requested the UDD core not to re-enable the interrupt line, the application may later request the unmasking by issuing the UDD_RTIOC_IRQEN ioctl(2) command. Writing a non-zero integer to the device via the write(2) system call has the same effect.

References rtdm_event_signal(), rtdm_irq_disable(), and rtdm_irq_enable().

◆ udd_register_device()

int udd_register_device ( struct udd_device * udd )

Register a UDD device.

This routine registers a mini-driver at the UDD core.

Parameters

udd	UDD device descriptor which should describe the new device properties.

Returns: Zero is returned upon success, otherwise a negative error code is received, from the set of error codes defined by rtdm_dev_register(). In addition, the following error codes can be returned:

-EINVAL, some of the memory regions declared in the udd_device.mem_regions[] array have invalid properties, i.e. bad type, NULL name, zero length or address. Any undeclared region entry from the array must bear the UDD_MEM_NONE type.
-EINVAL, if udd_device.irq is different from UDD_IRQ_CUSTOM and UDD_IRQ_NONE but invalid, causing rtdm_irq_request() to fail.
-EINVAL, if udd_device.device_flags contains invalid flags.
-ENXIO can be received if this service is called while the Cobalt kernel is disabled.

Tags: secondary-only

References udd_device::device_flags, udd_device::interrupt, udd_device::irq, RTDM_PROTOCOL_DEVICE, UDD_IRQ_CUSTOM, and UDD_IRQ_NONE.

◆ udd_unregister_device()

int udd_unregister_device ( struct udd_device * udd )

Unregister a UDD device.

This routine unregisters a mini-driver from the UDD core. This routine waits until all connections to udd have been closed prior to unregistering.

Parameters

udd	UDD device descriptor

Returns: Zero is returned upon success, otherwise -ENXIO is received if this service is called while the Cobalt kernel is disabled.

Tags: secondary-only

References udd_device::irq, rtdm_event_destroy(), rtdm_irq_free(), UDD_IRQ_CUSTOM, and UDD_IRQ_NONE.

Data Structures

Functions

Memory types for mapping

UDD_IOCTL

Detailed Description

Macro Definition Documentation

◆ UDD_IRQ_CUSTOM

◆ UDD_IRQ_NONE

◆ UDD_MEM_LOGICAL

◆ UDD_MEM_NONE

◆ UDD_MEM_PHYS

◆ UDD_MEM_VIRTUAL

◆ UDD_RTIOC_IRQDIS

◆ UDD_RTIOC_IRQEN

◆ UDD_RTIOC_IRQSIG

Function Documentation

◆ udd_disable_irq()

◆ udd_enable_irq()

◆ udd_get_device()

◆ udd_notify_event()

◆ udd_register_device()

◆ udd_unregister_device()