Event Source

User/Kernel Space

Common user/kernel-space event source declarations.

Event sources are used to wake up user-space tasks when a specific event (such as a hardware interrupt from a specific peripheral device) occurs.

This part of the API is technically available to both user-space and kernel-space code, however the only intended kernel-space usage of these declarations is to convey information to user-space applications.

enum cuddl_eventsrc_flags: Event source flags for user space.

Constants

CUDDL_EVENTSRCF_SHARED: Indicates that the associated event source may be claimed by more than one user-space application simultaneously.

CUDDL_EVENTSRCF_WAITABLE

Indicates that the event source can wake up a waiting user-space task.

If this flag is set, cuddl_eventsrc_wait() and cuddl_eventsrc_timed_wait() are supported.

On Linux and Xenomai, this feature is implemented via a 4-byte blocking read() operation on the file descriptor associated with the event source. The select() operation is used when a timeout is specified.

CUDDL_EVENTSRCF_HAS_DISABLE

Indicates that a user-space task may disable interrupt events through the event source.

If this flag is set, cuddl_eventsrc_disable() is supported.

On Linux and Xenomai, this feature is implemented via a 4-byte write() operation on file descriptor associated with the event source. If supported, writing a uint32_t value of 0 to the file descriptor masks (disables) interrupt events.

CUDDL_EVENTSRCF_HAS_ENABLE

Indicates that a user-space task may enable interrupt events through the event source.

If this flag is set, cuddl_eventsrc_enable() is supported.

On Linux and Xenomai, this feature is implemented via a 4-byte write() operation on file descriptor associated with the event source. If supported, writing a uint32_t value of 1 to the file descriptor unmasks (enables) interrupt events.

CUDDL_EVENTSRCF_HAS_IS_ENABLED

Indicates that a user-space task may query the interrupt enable status through the event source.

If this flag is set, cuddl_eventsrc_is_enabled() is supported.

On Linux and Xenomai, this feature is implemented via the manager interface (which involves acquiring a global lock), so real-time use of cuddl_eventsrc_is_enabled() is not recommended.

Description

Flags that describe the properties of an event source to user-space code.

enum cuddl_eventsrc_claim_flags: Flags used when claiming event sources.

Constants

CUDDL_EVENTSRC_CLAIMF_HOSTILE: Allows the claim operation to succeed, even if the event source has already been claimed by another application and the CUDDL_EVENTSRCF_SHARED flag has not been set. Specifying this flag is usually not the right thing to do.

Description

Flags that are applicable to the event source claim operation.

struct cuddl_eventsrc_info: Event source information for user space.

Definition

struct cuddl_eventsrc_info {
  int flags;
  struct cuddlci_eventsrc_info_priv priv;
};

Members

flags: Flags that describe the properties of the event source. This field may be a set of cuddl_eventsrc_flags ORed together.
priv: Private data reserved for internal use by the Cuddl implementation.

Description

Event source information that is exported to user-space code. Typically, the internal members of this structure do not need to be directly accessed from user-space applications.

On Linux and Xenomai systems, this information is retrieved from the kernel via an ioctl call.

User Space

User-space event source declarations.

Event sources are used to wake up user-space tasks when a specific event (such as a hardware interrupt from a specific peripheral device) occurs.

This part of the API is only available to user-space code.

type cuddl_time_t: Data type used to represent a time in seconds.

Description

This will be equivalent to time_t on POSIX systems.

struct cuddl_timespec: Represents time in seconds and nanoseconds.

Definition

struct cuddl_timespec {
  cuddl_time_t tv_sec;
  long tv_nsec;
};

Members

tv_sec: Seconds
tv_nsec: Nanoseconds

Description

This is equivalent to struct timespec on POSIX systems.

struct cuddl_eventsrc: User-space event source interface.

Definition

struct cuddl_eventsrc {
  int flags;
  struct cuddli_eventsrc_priv priv;
};

Members

flags: Flags that describe the properties of the event source. This field may be a set of cuddl_eventsrc_flags ORed together.
priv: Private data reserved for internal use by the Cuddl implementation.

Description

Provides user-space applications with an interface for receiving kernel-based (e.g. interrupt) events.

int cuddl_eventsrc_claim(struct cuddl_eventsrc_info *eventinfo, const char *group, const char *device, const char *eventsrc, int instance, int options): Claim an event source from user space.

Parameters

struct cuddl_eventsrc_info *eventinfo: Pointer to a data structure that will receive the information required to open the specified event source from user space. If the claim operation is successful, the required information will be copied into the data structure specified by this parameter.
const char *group: Name of the group in which the specified event source’s parent device resides. In some cases, the group is used to indicate the PCI card on which the parent device is located.
const char *device: Name of the specified event source’s parent device. (i.e. hardware peripheral).
const char *eventsrc: Name of the specific event source to be claimed.
int instance: Used to differentiate between event sources that are registered with identical group, device, and resource (i.e. eventsrc) fields.
int options: Input parameter specifying the set of flags to apply to this event source claim operation. This field may be a set of cuddl_eventsrc_claim_flags ORed together.

Description

Request ownership of a specific event source for the purpose of receiving events in user space. The particular event source is identified by the group, device, eventsrc, and instance arguments. If any of these arguments is NULL or contains an empty string (or is 0, in the case of instance), the parameter will be treated as a don’t care value when searching for a matching event source in the resource list.

This routine is automatically called from cuddl_eventsrc_claim_and_open(), so user-space applications do not typically need to call this routine directly.

Return

0 on success, or a negative error code.

Error codes:

-EBUSY: The specified event source is already in use.

-ENXIO: The specified event source was not found.

-ENOMEM: Error allocating memory in IOCTL call (Linux).

-EOVERFLOW: Error copying data to/from kernel space (Linux).

-ENOEXEC: User/kernel major version number mismatch (Linux).

Value of -errno resulting from from open() call on Cuddl manager device (Linux).

Value of -errno resulting from from ioctl() call on Cuddl manager device (Linux).

Value of -errno resulting from from close() call on Cuddl manager device (Linux).

int cuddl_eventsrc_release(struct cuddl_eventsrc_info *eventinfo): Release an event source from user space.

Parameters

struct cuddl_eventsrc_info *eventinfo: Input parameter identifying the event source to be released. The data structure pointed to by this parameter should contain the information returned by a successful call to cuddl_eventsrc_claim().

Description

Release ownership of the event source identified by eventinfo.

This routine is automatically called from cuddl_eventsrc_close_and_release(), so user-space applications do not typically need to call this routine directly.

Return

0 on success, or a negative error code.

Error codes:

Error code returned by cuddli_eventsrc_release_by_token() (Linux).

int cuddl_eventsrc_open(struct cuddl_eventsrc *eventsrc, const struct cuddl_eventsrc_info *eventinfo, int options): Open an event source from user space.

Parameters

struct cuddl_eventsrc *eventsrc: Pointer to a data structure that will receive the information required to receive events in user space. If the open operation is successful, the required information will be copied into the data structure specified by this parameter.
const struct cuddl_eventsrc_info *eventinfo: Input parameter identifying the event source to be opened. The data structure pointed to by this parameter should contain the information returned by a successful call to cuddl_eventsrc_claim().
int options: Input parameter consisting of a set of flags (ORed together) that are applicable to the event source open operation. No open flags are currently defined for event sources, so this parameter should be set to 0.

Description

Open the event source identified by eventinfo to enable reception of events in user space.

This routine is automatically called from cuddl_eventsrc_claim_and_open(), so user-space applications do not typically need to call this routine directly.

Return

0 on success, or a negative error code.

Error codes:

Value of -errno resulting from from open() call on UIO or UDD event source device (Linux).

int cuddl_eventsrc_close(struct cuddl_eventsrc *eventsrc): Close an event source from user space.

Parameters

struct cuddl_eventsrc *eventsrc: Input parameter identifying the event source to be closed. The data structure pointed to by this parameter should contain the information returned by a successful call to cuddl_eventsrc_open().

Description

Close the event source eventsrc to disable reception of events from this source in user space.

This routine is automatically called from cuddl_eventsrc_close_and_release(), so user-space applications do not typically need to call this routine directly.

Return

0 on success, or a negative error code.

Error codes:

Value of -errno resulting from from close() call on UIO or UDD event source file descriptor (Linux).

int cuddl_eventsrc_claim_and_open(struct cuddl_eventsrc *eventsrc, const char *group, const char *device, const char *resource, int instance, int claim_options, int open_options): Claim and open an event source.

Parameters

struct cuddl_eventsrc *eventsrc: See cuddl_eventsrc_open().
const char *group: See cuddl_eventsrc_claim().
const char *device: See cuddl_eventsrc_claim().
const char *resource: Name of the specific event source to be claimed.
int instance: See cuddl_eventsrc_claim().
int claim_options: See cuddl_eventsrc_claim().
int open_options: See cuddl_eventsrc_open().

Description

Request ownership of a specific event source and then open it for the purpose of receiving events in user space. See cuddl_eventsrc_claim() and cuddl_eventsrc_open() for more details.

Return

0 on success, or a negative error code.

Error codes:

Error code returned by cuddl_eventsrc_claim() (Linux).

Error code returned by cuddl_eventsrc_open() (Linux).

int cuddl_eventsrc_close_and_release(struct cuddl_eventsrc *eventsrc): Close and release an event source.

Parameters

struct cuddl_eventsrc *eventsrc: Input identifying the event source to be closed and released. The data structure pointed to by this parameter should contain the information returned by a successful call to cuddl_eventsrc_claim_and_open().

Description

Close the event source eventsrc (disabling the reception of events from this source in user space), and then release ownership of the event source.

Return

0 on success, or a negative error code.

Error codes:

Error code returned by cuddl_eventsrc_close() (Linux).

Error code returned by cuddli_eventsrc_release_by_token() (Linux).

int cuddl_eventsrc_wait(struct cuddl_eventsrc *eventsrc): Wait for an event in user space.

Parameters

struct cuddl_eventsrc *eventsrc: Input parameter identifying the source of the event to be waited on. The data structure pointed to by this parameter should contain the information returned by a successful call to cuddl_eventsrc_open() or cuddl_eventsrc_claim_and_open().

Description

Performs a blocking wait for events from eventsrc.

Return

Cumulative event source interrupt count on success (i.e. an event has occurred since the last check), or a negative error code.

Error codes:

Value of -errno resulting from from read() call on event source file descriptor (Linux).

int cuddl_eventsrc_try_wait(struct cuddl_eventsrc *eventsrc): Check for the occurance of a user-space event.

Parameters

struct cuddl_eventsrc *eventsrc: Input parameter identifying the event source to be polled for an event. The data structure pointed to by this parameter should contain the information returned by a successful call to cuddl_eventsrc_open().

Description

Performs a non-blocking check for events from eventsrc.

Return

Cumulative event source interrupt count on success (i.e. an event has occurred since the last check), or a negative error code.

Error codes:

Error code returned by cuddl_eventsrc_timed_wait() (Linux).

int cuddl_eventsrc_timed_wait(struct cuddl_eventsrc *eventsrc, const struct cuddl_timespec *timeout): Timed wait for an event in user space.

Parameters

struct cuddl_eventsrc *eventsrc: Input parameter identifying the source of the event to be waited on. The data structure pointed to by this parameter should contain the information returned by a successful call to cuddl_eventsrc_open() or cuddl_eventsrc_claim_and_open().
const struct cuddl_timespec *timeout: Relative time value specifying the maximum time to wait for an event.

Description

Performs a blocking wait for events from eventsrc with a timeout.

Return

Cumulative event source interrupt count on success (i.e. an event has occurred since the last check), or a negative error code.

Error codes:

-ETIMEDOUT: A timeout occurred.

Value of -errno resulting from from select() call on event source file descriptor (Linux).

Value of -errno resulting from from read() call on event source file descriptor (Linux).

int cuddl_eventsrc_enable(struct cuddl_eventsrc *eventsrc): Enable an event source from user space.

Parameters

struct cuddl_eventsrc *eventsrc: Input parameter identifying the source of the event to be enabled. The data structure pointed to by this parameter should contain the information returned by a successful call to cuddl_eventsrc_open() or cuddl_eventsrc_claim_and_open().

Description

Enables the event source if this operation is supported.

Return

0 on success, or a negative error code.

Error codes:

Value of -errno resulting from from write() call on event source file descriptor (Linux).

int cuddl_eventsrc_disable(struct cuddl_eventsrc *eventsrc): Disables an event source from user space.

Parameters

struct cuddl_eventsrc *eventsrc: Input parameter identifying the source of the event to be disabled. The data structure pointed to by this parameter should contain the information returned by a successful call to cuddl_eventsrc_open() or cuddl_eventsrc_claim_and_open().

Description

Disables the event source if this operation is supported.

Return

0 on success, or a negative error code.

Error codes:

Value of -errno resulting from from write() call on event source file descriptor (Linux).

int cuddl_eventsrc_is_enabled(struct cuddl_eventsrc *eventsrc): Check if an event source is enabled.

Parameters

struct cuddl_eventsrc *eventsrc: Input parameter identifying the event source to be queried. The data structure pointed to by this parameter should contain the information returned by a successful call to cuddl_eventsrc_open() or cuddl_eventsrc_claim_and_open().

Description

Checks if event source is currently enabled (if this operation is supported).

Return

0, 1, or a negative error code.

A value of 0 indicates that the event source is disabled, a value of 1 indicates that the event source is enabled, and a negative value indicates an error condition.

On some systems (e.g. Linux and Xenomai, at least), this feature is implemented via the manager interface (which involves acquiring a global lock), so real-time use of this function is not recommended.

Error codes:

-EINVAL: This functionality was not implemented by the kernel driver.

-ENODEV: The device slot associated with the specified resource id is empty.

-EBADSLT: The device slot associated with the specified resource id is out of range.

-ENOMEM: Error allocating memory in IOCTL call (Linux).

-EOVERFLOW: Error copying data to/from kernel space (Linux).

-ENOEXEC: User/kernel major version number mismatch (Linux).

Value of -errno resulting from from open() call on Cuddl manager device (Linux).

Value of -errno resulting from from ioctl() call on Cuddl manager device (Linux).

Value of -errno resulting from from close() call on Cuddl manager device (Linux).

int cuddl_eventsrc_get_resource_id(struct cuddl_eventsrc *eventsrc, struct cuddl_resource_id *id): Get the associated resource ID.

Parameters

struct cuddl_eventsrc *eventsrc: Input identifying the event source to be queried. The data structure pointed to by this parameter should contain the information returned by a successful call to cuddl_eventsrc_open() or cuddl_eventsrc_claim_and_open().
struct cuddl_resource_id *id: Pointer to a data structure that will receive the resource identifier information associated with the specified event source. On success, the required information will be copied into the data structure specified by this parameter.

Description

Retrieve the resource identifier associated with this event source.

Return

0 on success, or a negative error code.

Error codes:

Error code returned by cuddl_get_eventsrc_id_for_slot() (Linux).

struct cuddl_eventsrcset: Represents a set of event sources.

Definition

struct cuddl_eventsrcset {
  struct cuddli_eventsrcset_priv priv;
};

Members

priv: Private data reserved for internal use by the Cuddl implementation.

Description

Event source sets allow user-space tasks to be woken up when any one of a specified set of events (such as hardware interrupts from a specific set of peripheral devices) occurs.

void cuddl_eventsrcset_zero(struct cuddl_eventsrcset *set): Initialize an event source set.

Parameters

struct cuddl_eventsrcset *set: The event source set to initialize.

Description

After calling this function, the specified event source set will be valid and empty.

void cuddl_eventsrcset_add(struct cuddl_eventsrcset *set, const struct cuddl_eventsrc *eventsrc): Add an event source to an event source set.

Parameters

struct cuddl_eventsrcset *set: The event source set to be modified.
const struct cuddl_eventsrc *eventsrc: The event source to be added.

void cuddl_eventsrcset_remove(struct cuddl_eventsrcset *set, const struct cuddl_eventsrc *eventsrc): Remove an event source from an event src set.

Parameters

struct cuddl_eventsrcset *set: The event source set to be modified.
const struct cuddl_eventsrc *eventsrc: The event source to be removed.

int cuddl_eventsrcset_contains(struct cuddl_eventsrcset *set, const struct cuddl_eventsrc *eventsrc): Check if event src set contains an eventsrc.

Parameters

struct cuddl_eventsrcset *set: The event source set to be checked.
const struct cuddl_eventsrc *eventsrc: The event source to look for.

Return

1 if eventsrc is in the set, or 0 otherwise..

int cuddl_eventsrcset_timed_wait(struct cuddl_eventsrcset *eventsrcset, const struct cuddl_timespec *timeout, struct cuddl_eventsrcset *result): Timed wait for events in user space.

Parameters

struct cuddl_eventsrcset *eventsrcset: Input parameter identifying the sources of events to be waited on.
const struct cuddl_timespec *timeout: Relative time value specifying the maximum time to wait for an event.
struct cuddl_eventsrcset *result: Output parameter identifying the event sources that have triggered or NULL.

Description

Performs a blocking wait for events from eventsrcset with a timeout.

Return

The number of interrupting event sources on success (i.e. an event has occurred since the last check), or a negative error code.

Error codes:

-ETIMEDOUT: A timeout occurred.

Value of -errno resulting from from select() call on event source file descriptors (Linux).

Value of -errno resulting from from read() call on event source file descriptor (Linux).