Manager

User-space device manager declarations.

The Cuddl device manager exposes device memory regions and event sources to user-space applications. The routines described here may be used to query the device memory regions and event sources that have been made available to user-space applications by Cuddl kernel drivers.

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

int cuddl_get_max_managed_devices(void): Get max number of managed devices.

Parameters

void: no arguments

Description

Retrieve the number of slots in the device manager’s array of devices. This is the maximum number of devices that can be managed (i.e. CUDDLK_MAX_MANAGED_DEVICES).

Return

Positive count of device slots or negative error code.

Error codes:

-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_get_max_dev_mem_regions(void): Get max number of device mem regions.

Parameters

void: no arguments

Description

Retrieve the number of memory region slots in a device’s mem array. This is the maximum number of memory regions that can be associated with a single device (i.e. CUDDLK_MAX_DEV_MEM_REGIONS).

Return

Positive count of memory region slots or negative error code.

Error codes:

-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_get_max_dev_events(void): Get max number of device event sources.

Parameters

void: no arguments

Description

Retrieve the number of event source slots in a device’s events array. This is the maximum number of event sources that can be associated with a single device (i.e. CUDDLK_MAX_DEV_EVENTS).

Return

Positive count of event source slots or negative error code.

Error codes:

-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_get_memregion_id_for_slot(struct cuddl_resource_id *id, int device_slot, int mem_slot): Get ID describing a mem region by slot.

Parameters

struct cuddl_resource_id *id: Pointer to a data structure that will receive the resource identifier information associated with the specified device / memory region slot. If a memory region is found in the specified slot, the required information will be copied into the data structure specified by this parameter.
int device_slot: Device slot number (non-negative integer).
int mem_slot: Memory region slot number (non-negative integer).

Description

Retrieve a resource identifier describing the memory region associated with the specified device and memory region slots.

Return

0 on success, or a negative error code.

Error codes:

-ENODEV: The specified device slot is empty.

-EINVAL: The specified memory slot is empty.

-EBADSLT: The specified device or mem slot 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_get_eventsrc_id_for_slot(struct cuddl_resource_id *id, int device_slot, int event_slot): Get ID describing an event src by slot.

Parameters

struct cuddl_resource_id *id: Pointer to a data structure that will receive the resource identifier information associated with the specified device / event source slot. If an event source is found in the specified slot, the required information will be copied into the data structure specified by this parameter.
int device_slot: Device slot number (non-negative integer).
int event_slot: Event source slot number (non-negative integer).

Description

Retrieve a resource identifier describing the event source associated with the specified device and event source slots.

Return

0 on success, or a negative error code.

Error codes:

-ENODEV: The specified device slot is empty.

-EINVAL: The specified event slot is empty.

-EBADSLT: The specified device or event slot 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_get_memregion_info_for_id(struct cuddl_memregion_info *meminfo, const struct cuddl_resource_id *memregion_id): Retrieve memory region information.

Parameters

struct cuddl_memregion_info *meminfo: Pointer to a data structure that will receive the memory region information. If the call is successful, the required information will be copied into the data structure specified by this parameter.
const struct cuddl_resource_id *memregion_id: Resource identifier input identifying the memory region to be queried.

Description

Retrieve the properties of the specified memory region.

Return

0 on success, or a negative error code.

Error codes:

-ENXIO: The specified memory region 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_get_eventsrc_info_for_id(struct cuddl_eventsrc_info *eventinfo, const struct cuddl_resource_id *eventsrc_id): Retrieve event source information.

Parameters

struct cuddl_eventsrc_info *eventinfo: Pointer to a data structure that will receive the event source information. If the call is successful, the required information will be copied into the data structure specified by this parameter.
const struct cuddl_resource_id *eventsrc_id: Resource identifier input identifying the event source to be queried.

Description

Retrieve the properties of the specified event source.

Return

0 on success, or a negative error code.

Error codes:

-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_get_memregion_ref_count_for_id(const struct cuddl_resource_id *memregion_id): Return the memregion ref count.

Parameters

const struct cuddl_resource_id *memregion_id: Resource identifier input identifying the memory region to be queried.

Description

Return the reference count associated with the specified memory region.

Return

Positive (or zero) reference count or negative error code.

Error codes:

-ENXIO: The specified memory region 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_get_eventsrc_ref_count_for_id(const struct cuddl_resource_id *eventsrc_id): Return the eventsrc ref count.

Parameters

const struct cuddl_resource_id *eventsrc_id: Resource identifier input identifying the event source to be queried.

Description

Return the reference count associated with the specified event source.

Return

Positive (or zero) reference count or negative error code.

Error codes:

-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_decrement_memregion_ref_count_for_id(const struct cuddl_resource_id *memregion_id): Decrement mem ref count.

Parameters

const struct cuddl_resource_id *memregion_id: Resource identifier input identifying the memory region to be queried.

Description

Decrement the reference count associated with the specified memory region. This functionality should only used to free resources when the standard mechanism has failed for some reason.

Return

0 on success, or a negative error code.

Error codes:

-ENXIO: The specified memory region 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_decrement_eventsrc_ref_count_for_id(const struct cuddl_resource_id *eventsrc_id): Decrement event ref count.

Parameters

const struct cuddl_resource_id *eventsrc_id: Resource identifier input identifying the event source to be queried.

Description

Decrement the reference count associated with the specified event source. This functionality should only used to free resources when the standard mechanism has failed for some reason.

Return

0 on success, or a negative error code.

Error codes:

-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_get_driver_info_for_memregion_id(char *info_str, cuddl_size_t info_len, const struct cuddl_resource_id *memregion_id): Get the driver info string associated with the mem region.

Parameters

char *info_str: Pointer to the buffer to be used for returning the info string.
cuddl_size_t info_len: Input parameter specifying the size of the buffer used for returning the info string.
const struct cuddl_resource_id *memregion_id: Resource identifier input identifying the memory region to be queried.

Description

Retrieve the driver information string associated with the specified memory region.

Return

0 on success, or a negative error code.

Error codes:

Error code returned by cuddl_get_memregion_info_for_id() (Linux).

-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_get_driver_info_for_eventsrc_id(char *info_str, cuddl_size_t info_len, const struct cuddl_resource_id *eventsrc_id): Get the driver info string associated with the event source.

Parameters

char *info_str: Pointer to the buffer to be used for returning the info string.
cuddl_size_t info_len: Input parameter specifying the size of the buffer used for returning the info string.
const struct cuddl_resource_id *eventsrc_id: Resource identifier input identifying the event source to be queried.

Description

Retrieve the driver information string associated with the specified event source.

Return

0 on success, or a negative error code.

Error codes:

Error code returned by cuddl_get_eventsrc_info_for_id() (Linux).

-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_get_hw_info_for_memregion_id(char *info_str, cuddl_size_t info_len, const struct cuddl_resource_id *memregion_id): Get the hardware info string associated with the mem region.

Parameters

char *info_str: Pointer to the buffer to be used for returning the info string.
cuddl_size_t info_len: Input parameter specifying the size of the buffer used for returning the info string.
const struct cuddl_resource_id *memregion_id: Resource identifier input identifying the memory region to be queried.

Description

Retrieve the hardware information string associated with the specified memory region.

Return

0 on success, or a negative error code.

Error codes:

Error code returned by cuddl_get_memregion_info_for_id() (Linux).

-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_get_hw_info_for_eventsrc_id(char *info_str, cuddl_size_t info_len, const struct cuddl_resource_id *eventsrc_id): Get the hardware info string associated with the event source.

Parameters

char *info_str: Pointer to the buffer to be used for returning the info string.
cuddl_size_t info_len: Input parameter specifying the size of the buffer used for returning the info string.
const struct cuddl_resource_id *eventsrc_id: Resource identifier input identifying the event source to be queried.

Description

Retrieve the hardware information string associated with the specified event source.

Return

0 on success, or a negative error code.

Error codes:

Error code returned by cuddl_get_eventsrc_info_for_id() (Linux).

-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_get_memregion_id_for_match(struct cuddl_resource_id *id, struct cuddl_resource_id *match): Get matching memregion ID.

Parameters

struct cuddl_resource_id *id: Pointer to a data structure that will receive the resource identifier information associated with the specified device / memory region. If a matching memory region is found, the required information will be copied into the data structure specified by this parameter.
struct cuddl_resource_id *match: Resource identifier input with the fields to be matched.

Description

Retrieve a fully-specified resource identifier for the first memory region that matches the partially specified resource identifier (i.e. it may contain wildcard fields.).

Return

0 on success, or a negative error code.

Error codes:

Error code returned by cuddl_get_memregion_info_for_id() (Linux).

Error code returned by cuddl_get_memregion_id_for_slot() (Linux).

int cuddl_get_eventsrc_id_for_match(struct cuddl_resource_id *id, struct cuddl_resource_id *match): Get matching eventsrc ID.

Parameters

struct cuddl_resource_id *id: Pointer to a data structure that will receive the resource identifier information associated with the specified device / event source. If a matching event source is found, the required information will be copied into the data structure specified by this parameter.
struct cuddl_resource_id *match: Resource identifier input with the fields to be matched.

Description

Retrieve a fully-specified resource identifier for the first event source that matches the partially specified resource identifier (i.e. it may contain wildcard fields.).

Return

0 on success, or a negative error code.

Error codes:

Error code returned by cuddl_get_eventsrc_info_for_id() (Linux).

Error code returned by cuddl_get_eventsrc_id_for_slot() (Linux).