uiomux.h File Reference

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.

Detailed Description

The libuiomux C API.

Query

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().

Locking and unlocking

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.


Function Documentation

unsigned long uiomux_all_virt_to_phys ( void *  virt_address  ) 

Convert a virtual address to a physical address.

Parameters:
virt_address Virtual address to convert
Returns:
Physical address corresponding to mapped virtual address
Return values:
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.

Parameters:
uiomux A UIOMux handle
resource Resource identifer.
Return values:
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.

Parameters:
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.
Return values:
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.

Parameters:
uiomux A UIOMux handle
Return values:
0 Success
void uiomux_free ( UIOMux *  uiomux,
uiomux_resource_t  resource,
void *  address,
size_t  size 
)

Free iomem from a UIO managed resource.

Parameters:
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.

Parameters:
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)
Returns:
Address of user memory region
Return values:
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.

Parameters:
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)
Returns:
Address of MMIO region
Return values:
0 Failure: resource not managed, or more than one resource given.
int uiomux_info ( UIOMux *  uiomux  ) 

Print info about UIO maps to stdout.

Parameters:
uiomux A UIOMux handle
Return values:
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.

Parameters:
names List of IP blocks available. The array is terminated with NULL.
count Number of IP blocks.
Return values:
0 on success; -1 on failure.
int uiomux_lock ( UIOMux *  uiomux,
uiomux_resource_t  resources 
)

Lock a UIOMux handle for access to specified blocks.

Parameters:
uiomux A UIOMux handle
resources A named resource, or multiple OR'd together
Return values:
0 Success
void* uiomux_malloc ( UIOMux *  uiomux,
uiomux_resource_t  resource,
size_t  size,
int  align 
)

Allocate iomem from a UIO managed resource.

Parameters:
uiomux A UIOMux handle
resource A single named resource
size Size of memory region
align Alignment of memory region
Returns:
Address of allocated memory
Return values:
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.

Parameters:
uiomux A UIOMux handle
resource A single named resource
size Size of memory region
align Alignment of memory region
Returns:
Address of allocated memory
Return values:
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.

Parameters:
uiomux A UIOMux handle
Return values:
0 Success
UIOMux* uiomux_open ( void   ) 

Create a new UIOMux object,.

Return values:
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,.

Parameters:
resources A named resource, or multiple OR'd together
Return values:
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).

Parameters:
name A list of IP block names. List shall be terminated with NULL pointer.
Return values:
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.

Parameters:
uiomux A UIOMux handle
resource A single named resource
phys_address Physical address to convert
Returns:
Virtual address corresponding to physical address
Return values:
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.

Return values:
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.

Parameters:
virt Virtual address of memory region
phys_address Physical address of memory region
size Size of memory region
Return values:
0 Success
int uiomux_sleep ( UIOMux *  uiomux,
uiomux_resource_t  resource 
)

Wait for a UIO managed resource to complete its activity.

Parameters:
uiomux A UIOMux handle
resource A named resource
Return values:
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.

Parameters:
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)
Return values:
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.

Parameters:
uiomux A UIOMux handle
resources A named resource, or multiple OR'd together
Return values:
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.

Parameters:
virt Virtual address of memory region
Return values:
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.

Parameters:
uiomux A UIOMux handle
resource A single named resource
virt_address Virtual address to convert
Returns:
Physical address corresponding to mapped virtual address
Return values:
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.

Parameters:
uiomux A UIOMux handle
resource A single named resource
Return values:
0 Success
Generated on Fri Aug 26 14:32:28 2011 for libuiomux by  doxygen 1.6.3