Xenomai  3.0.5
User-space driver core

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_deviceudd_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
uddThe UDD driver handling the IRQ to disable. If no IRQ was registered by the driver at the UDD core, this routine has no effect.
doneOptional 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
uddThe UDD driver handling the IRQ to disable. If no IRQ was registered by the driver at the UDD core, this routine has no effect.
doneOptional 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
fdFile 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
uddUDD 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
uddUDD 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
uddUDD 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.