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
Solaris DDI Specific (Solaris 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 configura-
tion 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 Solaris, 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 Num-
Ports2 field must be reset to 0.
When calling csx_RequestIO(), the BasePort.base field
specifies the first port address requested. Upon suc-
cessful 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 contigu-
ous I/O ports, the resource returned will be a multi-
ple 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 oppo-
site 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 advan-
tage 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 fol-
lowed by a load).
WIN_ACC_MERGING_OK
The CPU may merge individual stores to consecutive
locations. For example, the CPU may turn two consecu-
tive 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 dif-
ferent BasePort, NumPorts, and/or IOAddrLines values will
have to be made to find an acceptable combination of parame-
ters 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.
SEE ALSO
csx_RegisterClient(9F), csx_RequestConfiguration(9F)
PC Card 95 Standard, PCMCIA/JEIDA
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 con-
venient 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.
Man(1) output converted with
man2html