Tribblix: manual page: csx

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

NAME

csx_RequestIO, csx_ReleaseIO - request or release I/O resources for
the client

SYNOPSIS

#include <sys/pccard.h>

int32_t csx_RequestIO(client_handle_t ch, io_req_t *ir);

int32_t csx_ReleaseIO(client_handle_t ch, io_req_t *ir);

INTERFACE LEVEL

illumos DDI Specific (illumos DDI)

PARAMETERS

ch
Client handle returned from csx_RegisterClient(9F).

ir
Pointer to an io_req_t structure.

DESCRIPTION

The functions csx_RequestIO() and csx_ReleaseIO() request or release,
respectively, I/O resources for the client.

If a client requires I/O resources, csx_RequestIO() must be called to
request I/O resources from Card Services; then
csx_RequestConfiguration(9F) must be used to establish the
configuration. csx_RequestIO() can be called multiple times until a
successful set of I/O resources is found.
csx_RequestConfiguration(9F) only uses the last configuration
specified.

csx_RequestIO() fails if it has already been called without a
corresponding csx_ReleaseIO().

csx_ReleaseIO() releases previously requested I/O resources. The Card
Services window resource list is adjusted by this function. Depending
on the adapter hardware, the I/O window might also be disabled.

STRUCTURE MEMBERS

The structure members of io_req_t are:

uint32_t Socket; /* socket number*/

uint32_t Baseport1.base; /* IO range base port address */
acc_handle_t Baseport1.handle; /* IO range base address
/* or port num */
uint32_t NumPorts1; /* first IO range number contiguous
/* ports */
uint32_t Attributes1; /* first IO range attributes */

uint32_t Baseport2.base; /* IO range base port address */
acc_handle_t Baseport2.handle; /* IO range base address or port num */
uint32_t NumPorts2; /* second IO range number contiguous
/* ports */
uint32_t Attributes2; /* second IO range attributes */

uint32_t IOAddrLines; /* number of IO address lines decoded */

The fields are defined as follows:

Socket
Not used in illumos, but for portability with
other Card Services implementations, it should be
set to the logical socket number.

BasePort1.base
BasePort1.handle
BasePort2.base
BasePort2.handle
Two I/O address ranges can be requested by
csx_RequestIO(). Each I/O address range is
specified by the BasePort, NumPorts, and
Attributes fields. If only a single I/O range is
being requested, the NumPorts2 field must be
reset to 0.

When calling csx_RequestIO(), the BasePort.base
field specifies the first port address requested.
Upon successful return from csx_RequestIO(), the
BasePort.handle field contains an access handle,
corresponding to the first byte of the allocated
I/O window, which the client must use when
accessing the PC Card's I/O space via the common
access functions. A client must not make any
assumptions as to the format of the returned
BasePort.handle field value.

If the BasePort.base field is set to 0, Card
Services returns an I/O resource based on the
available I/O resources and the number of
contiguous ports requested. When BasePort.base is
0, Card Services aligns the returned resource in
the host system's I/O address space on a boundary
that is a multiple of the number of contiguous
ports requested, rounded up to the nearest power
of two. For example, if a client requests two I/O
ports, the resource returned will be a multiple
of two. If a client requests five contiguous I/O
ports, the resource returned will be a multiple
of eight.

If multiple ranges are being requested, at least
one of the BasePort.base fields must be non-zero.

NumPorts
This field is the number of contiguous ports
being requested.

Attributes
This field is bit-mapped. The following bits are
defined:

IO_DATA_WIDTH_8
I/O resource uses
8-bit data path.

IO_DATA_WIDTH_16
I/O resource uses
16-bit data path.

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.

For some combinations of host system busses and
adapter hardware, the width of an I/O resource
can not be set via RequestIO(); on those systems,
the host bus cycle access type determines the I/O
resource data path width on a per-cycle basis.

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 Attributes 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. IO_MERGING_OK_ACC 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. WIN_ACC_LOADCACHING_OK 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.
WIN_ACC_STORECACHING_OK 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. All other
bits in the Attributes field must be set to 0.

IOAddrLines
This field is the number of I/O address lines
decoded by the PC Card in the specified socket.

On some systems, multiple calls to csx_RequestIO() with different
BasePort, NumPorts, and/or IOAddrLines values will have to be made to
find an acceptable combination of parameters that can be used by Card
Services to allocate I/O resources for the client. (See NOTES).

RETURN VALUES

CS_SUCCESS
Successful operation.

CS_BAD_ATTRIBUTE
Invalid Attributes specified.

CS_BAD_BASE
BasePort value is invalid.

CS_BAD_HANDLE
Client handle is invalid.

CS_CONFIGURATION_LOCKED
csx_RequestConfiguration(9F) has already
been done.

CS_IN_USE
csx_RequestIO() has already been done
without a corresponding csx_ReleaseIO().

CS_NO_CARD
No PC Card in socket.

CS_BAD_WINDOW
Unable to allocate I/O resources.

CS_OUT_OF_RESOURCE
Unable to allocate I/O resources.

CS_UNSUPPORTED_FUNCTION
No PCMCIA hardware installed.

CONTEXT

These functions may be called from user or kernel context.

NOTES

It is important for clients to try to use the minimum amount of I/O
resources necessary. One way to do this is for the client to parse
the CIS of the PC Card and call csx_RequestIO() first with any
IOAddrLines values that are 0 or that specify a minimum number of
address lines necessary to decode the I/O space on the PC Card.
Also, if no convenient minimum number of address lines can be used to
decode the I/O space on the PC Card, it is important to try to avoid
system conflicts with well-known architectural hardware features.

July 19, 1996 CSX_REQUESTIO(9F)