The libuiomux C API. More...
#include <stdlib.h>
#include <uiomux/resource.h>
#include <sys/time.h>
#include <uiomux/system.h>
#include <uiomux/dump.h>
Go to the source code of this file.
Typedefs | |
typedef struct uiomux | UIOMux |
Functions | |
uiomux_resource_t | uiomux_query (void) |
Query which blocks are available on this platform. | |
const char * | uiomux_name (uiomux_resource_t resource) |
Retrieve a printable name for an IP block: | |
int | uiomux_list_device (char ***names, int *count) |
Query which blocks are available on this platform. | |
int | uiomux_info (UIOMux *uiomux) |
Print info about UIO maps to stdout. | |
int | uiomux_meminfo (UIOMux *uiomux) |
Print info about UIO memory allocations to stdout. | |
UIOMux * | uiomux_open (void) |
Create a new UIOMux object,. | |
UIOMux * | uiomux_open_blocks (uiomux_resource_t resources) |
Create a new UIOMux object for specified IP blocks,. | |
UIOMux * | uiomux_open_named (const char *name[]) |
Create a new UIOMux object for named IP blocks, When UIOMux object is created with this function, each bit in uiomux_resource_t refer to the corresponding element in the list. | |
int | uiomux_close (UIOMux *uiomux) |
Close a UIOMux handle, removing exclusive access, removing memory maps, etc. | |
uiomux_resource_t | uiomux_check_resource (struct uiomux *uiomux, uiomux_resource_t resource) |
Check if passed resource is available on the UIOMux object. | |
char * | uiomux_check_name (struct uiomux *uiomux, uiomux_resource_t resource) |
Check the name of the IP block corrensponding to the passed resource identifier. | |
int | uiomux_lock (UIOMux *uiomux, uiomux_resource_t resources) |
Lock a UIOMux handle for access to specified blocks. | |
int | uiomux_unlock (UIOMux *uiomux, uiomux_resource_t resources) |
Unlock a UIOMux handle for access to specified blocks. | |
int | uiomux_sleep (UIOMux *uiomux, uiomux_resource_t resource) |
Wait for a UIO managed resource to complete its activity. | |
int | uiomux_sleep_timeout (UIOMux *uiomux, uiomux_resource_t resource, struct timeval *timeout) |
Wait for a UIO managed resource to complete its activity. | |
int | uiomux_wakeup (struct uiomux *uiomux, uiomux_resource_t resource) |
Wake up any processes waiting for UIO events via a uiomux_sleep* command. | |
unsigned long | uiomux_get_mmio (UIOMux *uiomux, uiomux_resource_t resource, unsigned long *address, unsigned long *size, void **iomem) |
Get the address and size of the MMIO region for a UIO managed resource. | |
unsigned long | uiomux_get_mem (UIOMux *uiomux, uiomux_resource_t resource, unsigned long *address, unsigned long *size, void **iomem) |
Get the address and size of the user memory region for a UIO managed resource. | |
unsigned long | uiomux_virt_to_phys (UIOMux *uiomux, uiomux_resource_t resource, void *virt_address) |
Convert a virtual address to a physical address. | |
unsigned long | uiomux_all_virt_to_phys (void *virt_address) |
Convert a virtual address to a physical address. | |
void * | uiomux_phys_to_virt (UIOMux *uiomux, uiomux_resource_t resource, unsigned long phys_address) |
Convert a physical address to a virtual address. | |
void * | uiomux_malloc (UIOMux *uiomux, uiomux_resource_t resource, size_t size, int align) |
Allocate iomem from a UIO managed resource. | |
void * | uiomux_malloc_shared (UIOMux *uiomux, uiomux_resource_t resource, size_t size, int align) |
Allocate shared iomem from a UIO managed resource. | |
void | uiomux_free (UIOMux *uiomux, uiomux_resource_t resource, void *address, size_t size) |
Free iomem from a UIO managed resource. | |
int | uiomux_register (void *virt, unsigned long phys_address, size_t size) |
Register a region of memory as accessible by the resources. | |
int | uiomux_unregister (void *virt) |
Unregister a region of memory as accessible by the resources. |
The libuiomux C API.
At any time, an application may retrieve a printable name for a resource by calling uiomux_name(). To query which resources are available on the running system, call uiomux_query().
A process or thread wishing to use the locking facilities of libuiomux should start by calling uiomux_open() to obtain a UIOMux* handle.
To request exclusive access to a resource or a set of resources, call uiomux_lock(), passing as argument the name of a resource, or multiple resource names OR'd together. Each call to uiomux_lock() must be paired with a corresponding call to uiomux_unlock(). Failure to unlock can lead to system-wide starvation of the locked resource. Note however that all locks obtained via libuiomux will be automatically unlocked on program termination to minimize the potential damage caused by rogue processes.
Finally, each process or thread that opened a UIOMux* handle should close it by calling uiomux_close(). This will remove associated memory maps, unlock locked resources and mark used memory for deallocation.
unsigned long uiomux_all_virt_to_phys | ( | void * | virt_address | ) |
Convert a virtual address to a physical address.
virt_address | Virtual address to convert |
0 | Failure: virtual address is not managed by UIOMux. |
char* uiomux_check_name | ( | struct uiomux * | uiomux, | |
uiomux_resource_t | resource | |||
) |
Check the name of the IP block corrensponding to the passed resource identifier.
uiomux | A UIOMux handle | |
resource | Resource identifer. |
Name | of the IP block; when multiple bits are set resource , the information on those corresponding to the only lesser significant bit is returned. |
uiomux_resource_t uiomux_check_resource | ( | struct uiomux * | uiomux, | |
uiomux_resource_t | resource | |||
) |
Check if passed resource is available on the UIOMux object.
The function can be used to test if intended IP blocks are made available.
uiomux | A UIOMux handle | |
resource | Multiple OR'd resource list. When UIOMux handle is create with uiomux_open_named() , this depends on the list of name passed to the function. See uiomux_open_named() for details. |
Or'd | named resources; bits are set for resources available. |
int uiomux_close | ( | UIOMux * | uiomux | ) |
Close a UIOMux handle, removing exclusive access, removing memory maps, etc.
uiomux | A UIOMux handle |
0 | Success |
void uiomux_free | ( | UIOMux * | uiomux, | |
uiomux_resource_t | resource, | |||
void * | address, | |||
size_t | size | |||
) |
Free iomem from a UIO managed resource.
uiomux | A UIOMux handle | |
resource | A single named resource | |
address | The address to free | |
size | The size to free |
unsigned long uiomux_get_mem | ( | UIOMux * | uiomux, | |
uiomux_resource_t | resource, | |||
unsigned long * | address, | |||
unsigned long * | size, | |||
void ** | iomem | |||
) |
Get the address and size of the user memory region for a UIO managed resource.
uiomux | A UIOMux handle | |
resource | A single named resource | |
address | Return for address (ignored if NULL) | |
size | Return for size (ignored if NULL) | |
iomem | Return for iomem (ignored if NULL) |
0 | Failure: resource not managed, or more than one resource given. |
unsigned long uiomux_get_mmio | ( | UIOMux * | uiomux, | |
uiomux_resource_t | resource, | |||
unsigned long * | address, | |||
unsigned long * | size, | |||
void ** | iomem | |||
) |
Get the address and size of the MMIO region for a UIO managed resource.
uiomux | A UIOMux handle | |
resource | A single named resource | |
address | Return for address (ignored if NULL) | |
size | Return for size (ignored if NULL) | |
iomem | Return for iomem (ignored if NULL) |
0 | Failure: resource not managed, or more than one resource given. |
int uiomux_info | ( | UIOMux * | uiomux | ) |
Print info about UIO maps to stdout.
uiomux | A UIOMux handle |
0 | Success |
int uiomux_list_device | ( | char *** | names, | |
int * | count | |||
) |
Query which blocks are available on this platform.
Returns the references to the names of IP avialable IP blocks. If you need to modify the returned array of strings, please copy the array and strings before you do so. The result is shared by all callers of this API in the same process context.
names | List of IP blocks available. The array is terminated with NULL. | |
count | Number of IP blocks. |
0 | on success; -1 on failure. |
int uiomux_lock | ( | UIOMux * | uiomux, | |
uiomux_resource_t | resources | |||
) |
Lock a UIOMux handle for access to specified blocks.
uiomux | A UIOMux handle | |
resources | A named resource, or multiple OR'd together |
0 | Success |
void* uiomux_malloc | ( | UIOMux * | uiomux, | |
uiomux_resource_t | resource, | |||
size_t | size, | |||
int | align | |||
) |
Allocate iomem from a UIO managed resource.
uiomux | A UIOMux handle | |
resource | A single named resource | |
size | Size of memory region | |
align | Alignment of memory region |
NULL | Failure: unable to allocate, or attempt to allocate from more than one resource. |
void* uiomux_malloc_shared | ( | UIOMux * | uiomux, | |
uiomux_resource_t | resource, | |||
size_t | size, | |||
int | align | |||
) |
Allocate shared iomem from a UIO managed resource.
There can only be one shared memory region for a UIO device.
uiomux | A UIOMux handle | |
resource | A single named resource | |
size | Size of memory region | |
align | Alignment of memory region |
NULL | Failure: unable to allocate, or attempt to allocate from more than one resource. |
int uiomux_meminfo | ( | UIOMux * | uiomux | ) |
Print info about UIO memory allocations to stdout.
uiomux | A UIOMux handle |
0 | Success |
UIOMux* uiomux_open | ( | void | ) |
Create a new UIOMux object,.
NULL | on system error; check errno for details. |
UIOMux* uiomux_open_blocks | ( | uiomux_resource_t | resources | ) |
Create a new UIOMux object for specified IP blocks,.
resources | A named resource, or multiple OR'd together |
NULL | on system error; check errno for details. |
UIOMux* uiomux_open_named | ( | const char * | name[] | ) |
Create a new UIOMux object for named IP blocks, When UIOMux object is created with this function, each bit in uiomux_resource_t
refer to the corresponding element in the list.
For instance, name
[n] is refered with the bit (1 << n).
name | A list of IP block names. List shall be terminated with NULL pointer. |
NULL | on system error; check errno for details. |
void* uiomux_phys_to_virt | ( | UIOMux * | uiomux, | |
uiomux_resource_t | resource, | |||
unsigned long | phys_address | |||
) |
Convert a physical address to a virtual address.
uiomux | A UIOMux handle | |
resource | A single named resource | |
phys_address | Physical address to convert |
NULL | Failure: resource not managed, or more than one resource given, or physical address is not in range mapped for given resource. |
uiomux_resource_t uiomux_query | ( | void | ) |
Query which blocks are available on this platform.
Bitwise | OR of available resource names. |
int uiomux_register | ( | void * | virt, | |
unsigned long | phys_address, | |||
size_t | size | |||
) |
Register a region of memory as accessible by the resources.
This region is included in the list of regions covered by uiomux_all_virt_to_phys.
virt | Virtual address of memory region | |
phys_address | Physical address of memory region | |
size | Size of memory region |
0 | Success |
int uiomux_sleep | ( | UIOMux * | uiomux, | |
uiomux_resource_t | resource | |||
) |
Wait for a UIO managed resource to complete its activity.
uiomux | A UIOMux handle | |
resource | A named resource |
0 | Success |
int uiomux_sleep_timeout | ( | UIOMux * | uiomux, | |
uiomux_resource_t | resource, | |||
struct timeval * | timeout | |||
) |
Wait for a UIO managed resource to complete its activity.
uiomux | A UIOMux handle | |
resource | A single named resource | |
timeout | A timeval structure to specify length of timeout NULL -> no timeout 0 -> return immediately (after checking interrupt status) |
0 | Success | |
-1 | No interrupt occured before the timeout expired or uiomux was closed |
int uiomux_unlock | ( | UIOMux * | uiomux, | |
uiomux_resource_t | resources | |||
) |
Unlock a UIOMux handle for access to specified blocks.
uiomux | A UIOMux handle | |
resources | A named resource, or multiple OR'd together |
0 | Success |
int uiomux_unregister | ( | void * | virt | ) |
Unregister a region of memory as accessible by the resources.
This region is removed from the list of regions covered by uiomux_all_virt_to_phys.
virt | Virtual address of memory region |
0 | Success |
unsigned long uiomux_virt_to_phys | ( | UIOMux * | uiomux, | |
uiomux_resource_t | resource, | |||
void * | virt_address | |||
) |
Convert a virtual address to a physical address.
uiomux | A UIOMux handle | |
resource | A single named resource | |
virt_address | Virtual address to convert |
0 | Failure: resource not managed, or more than one resource given, or virtual address is not in range mapped for given resource. |
int uiomux_wakeup | ( | struct uiomux * | uiomux, | |
uiomux_resource_t | resource | |||
) |
Wake up any processes waiting for UIO events via a uiomux_sleep* command.
The woken processes should be all confirm being woken before uiomux_close is called.
uiomux | A UIOMux handle | |
resource | A single named resource |
0 | Success |