path: root/usr/src/man/man9f/csx_RequestIO.9f

'\" te
.\"  Copyright (c) 1996, Sun Microsystems, Inc.  All Rights Reserved
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH CSX_REQUESTIO 9F "Jul 19, 1996"
.SH NAME
csx_RequestIO, csx_ReleaseIO \- request or release I/O resources for the client
.SH SYNOPSIS
.nf
#include <sys/pccard.h>



\fBint32_t\fR \fBcsx_RequestIO\fR(\fBclient_handle_t\fR \fIch\fR, \fBio_req_t *\fR\fIir\fR);
.fi

.LP
.nf
\fBint32_t\fR \fBcsx_ReleaseIO\fR(\fBclient_handle_t\fR \fIch\fR, \fBio_req_t *\fR\fIir\fR);
.fi

.SH INTERFACE LEVEL
illumos \fBDDI \fRSpecific (illumos \fBDDI\fR)
.SH PARAMETERS
.ne 2
.na
\fB\fIch\fR\fR
.ad
.RS 6n
Client handle returned from \fBcsx_RegisterClient\fR(9F).
.RE

.sp
.ne 2
.na
\fB\fIir\fR\fR
.ad
.RS 6n
Pointer to an \fBio_req_t\fR structure.
.RE

.SH DESCRIPTION
The functions \fBcsx_RequestIO()\fR and \fBcsx_ReleaseIO()\fR request or
release, respectively, \fBI/O\fR resources for the client.
.sp
.LP
If a client requires \fBI/O\fR resources, \fBcsx_RequestIO()\fR must be called
to request \fBI/O\fR resources from Card Services; then
\fBcsx_RequestConfiguration\fR(9F) must be used to establish the configuration.
\fBcsx_RequestIO()\fR can be called multiple times until a successful set of
\fBI/O\fR resources is found. \fBcsx_RequestConfiguration\fR(9F) only uses the
last configuration specified.
.sp
.LP
\fBcsx_RequestIO()\fR fails if it has already been called without a
corresponding \fBcsx_ReleaseIO()\fR.
.sp
.LP
\fBcsx_ReleaseIO()\fR releases previously requested \fBI/O\fR resources. The
Card Services window resource list is adjusted by this function. Depending on
the adapter hardware, the \fBI/O\fR window might also be disabled.
.SH STRUCTURE MEMBERS
The structure members of \fBio_req_t\fR are:
.sp
.in +2
.nf
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 */
.fi
.in -2

.sp
.LP
The fields are defined as follows:
.sp
.ne 2
.na
\fB\fBSocket\fR\fR
.ad
.RS 20n
Not used in illumos, but for portability with other Card Services
implementations, it should be set to the logical socket number.
.RE

.sp
.ne 2
.na
\fB\fBBasePort1.base\fR\fR
.ad
.br
.na
\fB\fBBasePort1.handle\fR\fR
.ad
.br
.na
\fB\fBBasePort2.base\fR\fR
.ad
.br
.na
\fB\fBBasePort2.handle\fR\fR
.ad
.RS 20n
Two \fBI/O\fR address ranges can be requested by \fBcsx_RequestIO()\fR. Each
\fBI/O\fR address range is specified by the \fBBasePort\fR, \fBNumPorts\fR, and
\fBAttributes\fR fields. If only a single \fBI/O\fR range is being requested,
the \fBNumPorts2\fR field must be reset to \fB0\fR.
.sp
When calling \fBcsx_RequestIO()\fR, the \fBBasePort.base\fR field specifies the
first port address requested. Upon successful return from
\fBcsx_RequestIO()\fR, the \fBBasePort.handle\fR field contains an access
handle, corresponding to the first byte of the allocated \fBI/O\fR window,
which the client must use when accessing the \fBPC\fR Card's \fBI/O\fR space
via the common access functions. A client \fImust not\fR make any assumptions
as to the format of the returned \fBBasePort.handle\fR field value.
.sp
If the \fBBasePort.base\fR field is set to \fB0\fR, Card Services returns an
\fBI/O\fR resource based on the available \fBI/O\fR resources and the number of
contiguous ports requested. When \fBBasePort.base\fR is \fB0\fR, Card Services
aligns the returned resource in the host system's \fBI/O\fR 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
\fBI/O\fR ports, the resource returned will be a multiple of two. If a client
requests five contiguous \fBI/O\fR ports, the resource returned will be a
multiple of eight.
.sp
If multiple ranges are being requested, at least one of the \fBBasePort.base\fR
fields must be non-zero.
.RE

.sp
.ne 2
.na
\fB\fBNumPorts\fR\fR
.ad
.RS 20n
This field is the number of contiguous ports being requested.
.RE

.sp
.ne 2
.na
\fB\fBAttributes\fR\fR
.ad
.RS 20n
This field is bit-mapped. The following bits are defined:
.sp
.ne 2
.na
\fB\fBIO_DATA_WIDTH_8\fR\fR
.ad
.RS 27n
\fBI/O\fR resource uses 8-bit data path.
.RE

.sp
.ne 2
.na
\fB\fBIO_DATA_WIDTH_16\fR\fR
.ad
.RS 27n
\fBI/O\fR resource uses 16-bit data path.
.RE

.sp
.ne 2
.na
\fB\fBWIN_ACC_NEVER_SWAP\fR\fR
.ad
.RS 27n
Host endian byte ordering.
.RE

.sp
.ne 2
.na
\fB\fBWIN_ACC_BIG_ENDIAN\fR\fR
.ad
.RS 27n
Big endian byte ordering
.RE

.sp
.ne 2
.na
\fB\fBWIN_ACC_LITTLE_ENDIAN\fR\fR
.ad
.RS 27n
Little endian byte ordering.
.RE

.sp
.ne 2
.na
\fB\fBWIN_ACC_STRICT_ORDER\fR\fR
.ad
.RS 27n
Program ordering references.
.RE

.sp
.ne 2
.na
\fB\fBWIN_ACC_UNORDERED_OK\fR\fR
.ad
.RS 27n
May re-order references.
.RE

.sp
.ne 2
.na
\fB\fBWIN_ACC_MERGING_OK\fR\fR
.ad
.RS 27n
Merge stores to consecutive locations.
.RE

.sp
.ne 2
.na
\fB\fBWIN_ACC_LOADCACHING_OK\fR\fR
.ad
.RS 27n
May cache load operations.
.RE

.sp
.ne 2
.na
\fB\fBWIN_ACC_STORECACHING_OK\fR\fR
.ad
.RS 27n
May cache store operations.
.RE

For some combinations of host system busses and adapter hardware, the width of
an \fBI/O\fR resource can not be set via \fBRequestIO()\fR; on those systems,
the host bus cycle access type determines the \fBI/O\fR resource data path
width on a per-cycle basis.
.sp
\fBWIN_ACC_BIG_ENDIAN\fR and \fBWIN_ACC_LITTLE\fR \fBENDIAN\fR 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
\fBI/O\fR processor that has opposite endian characteristics of the busses.
When \fBWIN_ACC_BIG_ENDIAN\fR or \fBWIN_ACC_LITTLE\fR \fBENDIAN\fR 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.
.sp
When \fBWIN_ACC_NEVER_SWAP\fR is specified, byte swapping will not be invoked
in the data access functions. The ability to specify the order in which the
\fBCPU\fR will reference data is provided by the following \fBAttributes\fR
bits. Only one of the following bits may be specified:
.sp
.ne 2
.na
\fB\fBWIN_ACC_STRICT_ORDER\fR\fR
.ad
.sp .6
.RS 4n
The data references must be issued by a \fBCPU\fR in program order. Strict
ordering is the default behavior.
.RE

.sp
.ne 2
.na
\fB\fBWIN_ACC_UNORDERED_OK\fR\fR
.ad
.sp .6
.RS 4n
The \fBCPU\fR 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).
.RE

.sp
.ne 2
.na
\fB\fBWIN_ACC_MERGING_OK\fR\fR
.ad
.sp .6
.RS 4n
The \fBCPU\fR may merge individual stores to consecutive locations. For
example, the \fBCPU\fR may turn two consecutive byte stores into one halfword
store. It may also batch individual loads. For example, the \fBCPU\fR may turn
two consecutive byte loads into one halfword load. \fBIO_MERGING_OK_ACC\fR also
implies re-ordering.
.RE

.sp
.ne 2
.na
\fB\fBWIN_ACC_LOADCACHING_OK\fR\fR
.ad
.sp .6
.RS 4n
The \fBCPU\fR may cache the data it fetches and reuse it until another store
occurs. The default behavior is to fetch new data on every load.
\fBWIN_ACC_LOADCACHING_OK\fR also implies merging and re-ordering.
.RE

.sp
.ne 2
.na
\fB\fBWIN_ACC_STORECACHING_OK\fR\fR
.ad
.sp .6
.RS 4n
The \fBCPU\fR 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. \fBWIN_ACC_STORECACHING_OK\fR also implies load caching, merging,
and re-ordering.
.RE

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 \fBAttributes\fR field must be set
to \fB0\fR.
.RE

.sp
.ne 2
.na
\fB\fBIOAddrLines\fR\fR
.ad
.RS 20n
This field is the number of \fBI/O\fR address lines decoded by the \fBPC\fR
Card in the specified socket.
.RE

.sp
.LP
On some systems, multiple calls to \fBcsx_RequestIO()\fR with different
\fBBasePort\fR, \fBNumPorts\fR, and/or \fBIOAddrLines\fR values will have to be
made to find an acceptable combination of parameters that can be used by Card
Services to allocate \fBI/O\fR resources for the client. (See \fBNOTES\fR).
.SH RETURN VALUES
.ne 2
.na
\fB\fBCS_SUCCESS\fR\fR
.ad
.RS 27n
Successful operation.
.RE

.sp
.ne 2
.na
\fB\fBCS_BAD_ATTRIBUTE\fR\fR
.ad
.RS 27n
Invalid \fBAttributes\fR specified.
.RE

.sp
.ne 2
.na
\fB\fBCS_BAD_BASE\fR\fR
.ad
.RS 27n
\fBBasePort\fR value is invalid.
.RE

.sp
.ne 2
.na
\fB\fBCS_BAD_HANDLE\fR\fR
.ad
.RS 27n
Client handle is invalid.
.RE

.sp
.ne 2
.na
\fB\fBCS_CONFIGURATION_LOCKED\fR\fR
.ad
.RS 27n
\fBcsx_RequestConfiguration\fR(9F) has already been done.
.RE

.sp
.ne 2
.na
\fB\fBCS_IN_USE\fR\fR
.ad
.RS 27n
\fBcsx_RequestIO()\fR has already been done without a corresponding
\fBcsx_ReleaseIO()\fR.
.RE

.sp
.ne 2
.na
\fB\fBCS_NO_CARD\fR\fR
.ad
.RS 27n
No \fBPC\fR Card in socket.
.RE

.sp
.ne 2
.na
\fB\fBCS_BAD_WINDOW\fR\fR
.ad
.RS 27n
Unable to allocate \fBI/O\fR resources.
.RE

.sp
.ne 2
.na
\fB\fBCS_OUT_OF_RESOURCE\fR\fR
.ad
.RS 27n
Unable to allocate \fBI/O\fR resources.
.RE

.sp
.ne 2
.na
\fB\fBCS_UNSUPPORTED_FUNCTION\fR\fR
.ad
.RS 27n
No \fBPCMCIA\fR hardware installed.
.RE

.SH CONTEXT
These functions may be called from user or kernel context.
.SH SEE ALSO
\fBcsx_RegisterClient\fR(9F), \fBcsx_RequestConfiguration\fR(9F)
.sp
.LP
\fIPC Card 95 Standard\fR, PCMCIA/JEIDA
.SH NOTES
It is important for clients to try to use the minimum amount of \fBI/O\fR
resources necessary. One way to do this is for the client to parse the
\fBCIS\fR of the \fBPC\fR Card and call \fBcsx_RequestIO()\fR first with any
\fBIOAddrLines\fR values that are \fB0\fR or that specify a minimum number of
address lines necessary to decode the \fBI/O\fR space on the \fBPC\fR Card.
Also, if no convenient minimum number of address lines can be used to decode
the \fBI/O\fR space on the \fBPC\fR Card, it is important to try to avoid
system conflicts with well-known architectural hardware features.