Tribblix: manual page: csx

CSX_DUPHANDLE(9F) Kernel Functions for Drivers CSX_DUPHANDLE(9F)

NAME

csx_DupHandle - duplicate access handle

SYNOPSIS

#include <sys/pccard.h>

int32_t csx_DupHandle(acc_handle_t handle1, acc_handle_t *handle2,
uint32_t flags);

INTERFACE LEVEL

illumos DDI Specific (illumos DDI)

PARAMETERS

handle1
The access handle returned from csx_RequestIO(9F) or
csx_RequestWindow(9F) that is to be duplicated.

handle2
A pointer to the newly-created duplicated data access
handle.

flags
The access attributes that will be applied to the new
handle.

DESCRIPTION

This function duplicates the handle, handle1, into a new handle,
handle2, that has the access attributes specified in the flags
argument. Both the original handle and the new handle are active and
can be used with the common access functions.

Both handles must be explicitly freed when they are no longer
necessary.

The flags argument is bit-mapped. The following bits are defined:

WIN_ACC_NEVER_SWAP Host endian byte ordering
WIN_ACC_BIG_ENDIAN Big endian byte ordering
WIN_ACC_LITTLE_ENDIAN Little endian byte ordering
WIN_ACC_STRICT_ORDER Program ordering references
WIN_ACC_UNORDERED_OK May re-order references
WIN_ACC_MERGING_OK Merge stores to consecutive locations
WIN_ACC_LOADCACHING_OK May cache load operations
WIN_ACC_STORECACHING_OK May cache store operations

WIN_ACC_BIG_ENDIAN and WIN_ACC_LITTLE_ENDIAN describe the endian
characteristics of the device as big endian or little endian,
respectively. Even though most of the devices will have the same
endian characteristics as their busses, there are examples of devices
with an I/O processor that has opposite endian characteristics of the
busses. When WIN_ACC_BIG_ENDIAN or WIN_ACC_LITTLE_ENDIAN is set,
byte swapping will automatically be performed by the system if the
host machine and the device data formats have opposite endian
characteristics. The implementation may take advantage of hardware
platform byte swapping capabilities. When WIN_ACC_NEVER_SWAP is
specified, byte swapping will not be invoked in the data access
functions. The ability to specify the order in which the CPU will
reference data is provided by the following flags bits. Only one of
the following bits may be specified:

WIN_ACC_STRICT_ORDER
The data references must be issued by a
CPU in program order. Strict ordering is
the default behavior.

WIN_ACC_UNORDERED_OK
The CPU may re-order the data
references. This includes all kinds of
re-ordering (that is, a load followed by
a store may be replaced by a store
followed by a load).

WIN_ACC_MERGING_OK
The CPU may merge individual stores to
consecutive locations. For example, the
CPU may turn two consecutive byte stores
into one halfword store. It may also
batch individual loads. For example, the
CPU may turn two consecutive byte loads
into one halfword load. Setting this bit
also implies re-ordering.

WIN_ACC_LOADCACHING_OK
The CPU may cache the data it fetches and
reuse it until another store occurs. The
default behavior is to fetch new data on
every load. Setting this bit also implies
merging and re-ordering.

WIN_ACC_STORECACHING_OK
The CPU may keep the data in the cache
and push it to the device (perhaps with
other data) at a later time. The default
behavior is to push the data right away.
Setting this bit also implies load
caching, merging, and re-ordering.

These values are advisory, not mandatory. For example, data can be
ordered without being merged or cached, even though a driver requests
unordered, merged and cached together.

RETURN VALUES

CS_SUCCESS
Successful operation.

CS_FAILURE
Error in flags argument or handle could
not be duplicated for some reason.

CS_UNSUPPORTED_FUNCTION
No PCMCIA hardware installed.

CONTEXT

This function may be called from user or kernel context.