Kernel Functions for Drivers csxRequestIO(9F)
NAME
csxRequestIO, csxReleaseIO - request or release I/O
resources for the client
SYNOPSIS
#include
int32t csxRequestIO(clienthandlet ch, ioreqt *ir);
int32t csxReleaseIO(clienthandlet ch, ioreqt *ir);
INTERFACE LEVEL
Solaris DI Specific (Solaris DI)
PARAMETERS
ch Client handle returned from csxRegisterClient(9F).
ir Pointer to an ioreqt structure.
DESCRIPTION
The functions csxRequestIO() and csxReleaseIO() request or
release, respectively, I/O resources for the client.
If a client requires I/O resources, csxRequestIO() must be
called to request I/O resources from Card Services; then
csxRequestConfiguration(9F) must be used to establish the
configuration. csxRequestIO() can be called multiple times
until a successful set of I/O resources is found.
csxRequestConfiguration(9F) only uses the last configura-
tion specified.
csxRequestIO() fails if it has already been called without
a corresponding csxReleaseIO().
csxReleaseIO() 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 ioreqt are:
uint32t Socket; /* socket number*/
SunOS 5.11 Last change: 19 Jul 1996 1
Kernel Functions for Drivers csxRequestIO(9F)
uint32t Baseport1.base; /* IO range base port address */
acchandlet Baseport1.handle; /* IO range base address
/* or port num */
uint32t NumPorts1; /* first IO range number contiguous
/* ports */
uint32t Attributes1; /* first IO range attributes */
uint32t Baseport2.base; /* IO range base port address */
acchandlet Baseport2.handle; /* IO range base address or port num */
uint32t NumPorts2; /* second IO range number contiguous
/* ports */
uint32t Attributes2; /* second IO range attributes */
uint32t 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 implementa-
tions, it should be set to the logical
socket number.
BasePort1.base Two I/O address ranges can be requested
BasePort1.handle by csxRequestIO(). Each I/O address
BasePort2.base range is specified by the BasePort, Num-
BasePort2.handle Ports, and Attributes fields. If only a
single I/O range is being requested, the
NumPorts2 field must be reset to 0.
When calling csxRequestIO(), the
BasePort.base field specifies the first
port address requested. Upon successful
return from csxRequestIO(), 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
SunOS 5.11 Last change: 19 Jul 1996 2
Kernel Functions for Drivers csxRequestIO(9F)
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:
IODATAWIDTH8 I/O resource
uses 8-bit
data path.
IODATAWIDTH16 I/O resource
uses 16-bit
data path.
WINACNEVERSWAP Host endian
byte order-
ing.
WINACBIGENDIAN Big endian
byte ordering
WINACLITLENDIAN Little endian
byte order-
ing.
WINACSTRICTORDER Program ord-
ering refer-
ences.
WINACUNORDEREDOK May re-order
references.
SunOS 5.11 Last change: 19 Jul 1996 3
Kernel Functions for Drivers csxRequestIO(9F)
WINACMERGINGOK Merge stores
to consecu-
tive loca-
tions.
WINACLOADCACHINGOK May cache
load opera-
tions.
WINACSTORECACHINGOK May cache
store opera-
tions.
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.
WINACBIGENDIAN and WINACLITLE
ENDIAN describe the endian characteris-
tics of the device as big endian or lit-
tle 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
WINACBIGENDIAN or WINACLITLE
ENDIAN is set, byte swapping will
automatically be performed by the system
if the host machine and the device data
formats have opposite endian charac-
teristics. The implementation may take
advantage of hardware platform byte
swapping capabilities.
When WINACNEVERSWAP 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 fol-
lowing Attributes bits. Only one of the
following bits may be specified:
WINACSTRICTORDER
The data references must be issued
SunOS 5.11 Last change: 19 Jul 1996 4
Kernel Functions for Drivers csxRequestIO(9F)
by a CPU in program order. Strict
ordering is the default behavior.
WINACUNORDEREDOK
The CPU may re-order the data refer-
ences. This includes all kinds of
re-ordering (that is, a load fol-
lowed by a store may be replaced by
a store followed by a load).
WINACMERGINGOK
The CPU may merge individual stores
to consecutive locations. For exam-
ple, 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. IOMERGINGOKAC
also implies re-ordering.
WINACLOADCACHINGOK
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.
WINACLOADCACHINGOK also implies
merging and re-ordering.
WINACSTORECACHINGOK
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.
WINACSTORECACHINGOK also implies
load caching, merging, and re-
ordering.
These values are advisory, not manda-
tory. For example, data can be ordered
without being merged or cached, even
though a driver requests unordered,
merged and cached together. All other
SunOS 5.11 Last change: 19 Jul 1996 5
Kernel Functions for Drivers csxRequestIO(9F)
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 csxRequestIO() 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
CSUCES Successful operation.
CSBADATRIBUTE Invalid Attributes specified.
CSBADBASE BasePort value is invalid.
CSBADHANDLE Client handle is invalid.
CSCONFIGURATIONLOCKED csxRequestConfiguration(9F) has
already been done.
CSINUSE csxRequestIO() has already been
done without a corresponding
csxReleaseIO().
CSNOCARD No PC Card in socket.
CSBADWINDOW Unable to allocate I/O resources.
CSOUTOFRESOURCE Unable to allocate I/O resources.
CSUNSUPORTEDFUNCTION No PCMCIA hardware installed.
CONTEXT
SunOS 5.11 Last change: 19 Jul 1996 6
Kernel Functions for Drivers csxRequestIO(9F)
These functions may be called from user or kernel context.
SEE ALSO
csxRegisterClient(9F), csxRequestConfiguration(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
csxRequestIO() 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.
SunOS 5.11 Last change: 19 Jul 1996 7
|
