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

'\" te
.\"  Copyright (c) 1999, 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_REQUESTWINDOW 9F "Jul 19, 1996"
.SH NAME
csx_RequestWindow, csx_ReleaseWindow \- request or release window resources
.SH SYNOPSIS
.nf
#include <sys/pccard.h>



\fBint32_t\fR \fBcsx_RequestWindow\fR(\fBclient_handle_t\fR \fIch\fR, \fBwindow_handle_t *\fR\fIwh\fR,
     \fBwin_req_t *\fR\fIwr\fR);
.fi

.LP
.nf
\fBint32_t\fR \fBcsx_ReleaseWindow\fR(\fBwindow_handle_t\fR \fIwh\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\fIwh\fR\fR
.ad
.RS 6n
Pointer to a \fBwindow_handle_t\fR structure.
.RE

.sp
.ne 2
.na
\fB\fIwr\fR\fR
.ad
.RS 6n
Pointer to a \fBwin_req_t\fR structure.
.RE

.SH DESCRIPTION
The function \fBcsx_RequestWindow()\fR requests a block of system address space
be assigned to a \fBPC \fRCard in a socket.
.sp
.LP
The function \fBcsx_ReleaseWindow()\fR releases window resources which were
obtained by a call to \fBcsx_RequestWindow()\fR. No adapter or socket hardware
is modified by this function.
.sp
.LP
The \fBcsx_MapMemPage\fR(9F) and \fBcsx_ModifyWindow\fR(9F) functions use the
window handle returned by \fBcsx_RequestWindow()\fR. This window handle must be
freed by calling \fBcsx_ReleaseWindow()\fR when the client is done using this
window.
.sp
.LP
The \fBPC\fR Card Attribute or Common Memory offset for this window is set by
\fBcsx_MapMemPage\fR(9F).
.SH STRUCTURE MEMBERS
The structure members of \fBwin_req_t\fR are:
.sp
.in +2
.nf
uint32_t      Socket;                  /* socket number */
uint32_t      Attributes;              /* window flags */
uint32_t      Base.base;               /* requested window */
                                        /*   base address */
acc_handle_t  Base.handle;             /* returned handle for
                                        /*   base of window */
uint32_t      Size;                    /* window size requested */
                                        /*   or granted */
uint32_t      win_params.AccessSpeed;  /* window access speed */
uint32_t      win_params.IOAddrLines;  /* IO address lines decoded */
uint32_t      ReqOffset;               /* required window offest */
.fi
.in -2

.sp
.LP
The fields are defined as follows:
.sp
.ne 2
.na
\fB\fBSocket\fR\fR
.ad
.RS 26n
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\fBAttributes\fR\fR
.ad
.RS 26n
This field is bit-mapped and is defined as follows:
.sp
.ne 2
.na
\fB\fBWIN_MEMORY_TYPE_IO\fR\fR
.ad
.sp .6
.RS 4n
Points to I/O space.
.RE

.sp
.ne 2
.na
\fB\fBWIN_MEMORY_TYPE_CM\fR\fR
.ad
.sp .6
.RS 4n
Points to common memory space.
.RE

.sp
.ne 2
.na
\fB\fBWIN_MEMORY_TYPE_AM\fR\fR
.ad
.sp .6
.RS 4n
These bits select which type of window is being requested. One of these bits
must be set.
.RE

.sp
.ne 2
.na
\fB\fBWIN_ENABLE\fR\fR
.ad
.sp .6
.RS 4n
The client must set this bit to enable the window.
.RE

.sp
.ne 2
.na
\fB\fBWIN_ACC_BIG_ENDIAN\fR\fR
.ad
.sp .6
.RS 4n
Describes device as big-endian.
.RE

.sp
.ne 2
.na
\fB\fBWIN_ACC_LITTLE_ENDIAN\fR\fR
.ad
.sp .6
.RS 4n
These bits 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 \fRprocessor that has opposite endian characteristics of the busses.
When either of these bits are 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.
.RE

.sp
.ne 2
.na
\fB\fBWIN_ACC_NEVER_SWAP\fR\fR
.ad
.sp .6
.RS 4n
When this is specified, byte swapping will not be invoked in the data access
functions.
.RE

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 which 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 \fRmay merge individual stores to consecutive locations. For
example, the \fBCPU \fRmay turn two consecutive byte stores into one halfword
store. It may also batch individual loads. For example, the \fBCPU \fRmay turn
two consecutive byte loads into one halfword load. This bit also implies
re-ordering.
.RE

.sp
.ne 2
.na
\fB\fBWIN_ACC_LOADCACHING_OK\fR\fR
.ad
.sp .6
.RS 4n
The \fBCPU \fRmay cache the data it fetches and reuse it until another store
occurs. The default behavior is to fetch new data on every load. This bit 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 \fRmay 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. This bit 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.
.sp
All other bits in the \fBAttributes\fR field must be set to \fB0\fR.
.sp
On successful return from \fBcsx_RequestWindow()\fR, \fBWIN_OFFSET_SIZE\fR is
set in the \fBAttributes\fR field when the client must specify card offsets to
\fBcsx_MapMemPage\fR(9F) that are a multiple of the window size.
.RE

.sp
.ne 2
.na
\fB\fBBase.base\fR\fR
.ad
.RS 26n
This field must be set to \fB0\fR on calling \fBcsx_RequestWindow()\fR.
.RE

.sp
.ne 2
.na
\fB\fBBase.handle\fR\fR
.ad
.RS 26n
On successful return from \fBcsx_RequestWindow()\fR, the \fBBase.handle\fR
field contains an access handle corresponding to the first byte of the
allocated memory window which the client must use when accessing the \fBPC
\fRCard's memory space via the common access functions. A client must \fBnot\fR
make any assumptions as to the format of the returned \fBBase.handle\fR field
value.
.RE

.sp
.ne 2
.na
\fB\fBSize\fR\fR
.ad
.RS 26n
On calling \fBcsx_RequestWindow()\fR, the \fBSize\fR field is the size in bytes
of the memory window requested. \fBSize\fR may be zero to indicate that Card
Services should provide the smallest sized window available. On successful
return from \fBcsx_RequestWindow()\fR, the \fBSize\fR field contains the actual
size of the window allocated.
.RE

.sp
.ne 2
.na
\fB\fBwin_params.AccessSpeed\fR\fR
.ad
.RS 26n
This field specifies the access speed of the window if the client is requesting
a memory window. The \fBAccessSpeed\fR field bit definitions use the format of
the extended speed byte of the Device \fBID \fRtuple. If the mantissa is
\fB0\fR (noted as reserved in the \fBPC Card 95 Standard\fR), the lower bits
are a binary code representing a speed from the following table:
.RE

.sp

.sp
.TS
box;
l | l
l | l .
\fBCode\fR	\fBSpeed\fR
_
0	(Reserved - do not use).
_
1	250 nsec
_
2	200 nsec
_
3	150 nsec
_
4	100 nse
_
5-7	(Reserved\(emdo not use.)
.TE

.sp
.LP
To request a window that supports the \fBWAIT\fR signal, \fBOR-in\fR the
\fBWIN_USE_WAIT\fR bit to the \fBAccessSpeed\fR value before calling this
function.
.sp
.LP
It is recommended that clients use the \fBcsx_ConvertSpeed\fR(9F) function to
generate the appropriate \fBAccessSpeed\fR values rather than manually
perturbing the \fBAccessSpeed\fR field.
.sp
.ne 2
.na
\fB\fBwin_params.IOAddrLines\fR\fR
.ad
.RS 26n
If the client is requesting an \fBI/O \fRwindow, the \fBIOAddrLines\fR field is
the number of \fBI/O \fRaddress lines decoded by the \fBPC \fRCard in the
specified socket. Access to the \fBI/O \fRwindow is not enabled until
\fBcsx_RequestConfiguration\fR(9F) has been invoked successfully.
.RE

.sp
.ne 2
.na
\fB\fBReqOffset\fR\fR
.ad
.RS 26n
This field is an illumos-specific extension that can be used by clients to
generate optimum window offsets passed to \fBcsx_MapMemPage\fR(9F).
.RE

.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
\fBAttributes\fR are invalid.
.RE

.sp
.ne 2
.na
\fB\fBCS_BAD_SPEED\fR\fR
.ad
.RS 27n
Speed 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_BAD_SIZE\fR\fR
.ad
.RS 27n
Window size is invalid.
.RE

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

.sp
.ne 2
.na
\fB\fBCS_OUT_OF_RESOURCE\fR\fR
.ad
.RS 27n
Unable to allocate window.
.RE

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

.SH CONTEXT
These functions may be called from user or kernel context.
.SH SEE ALSO
.BR csx_ConvertSpeed (9F),
.BR csx_MapMemPage (9F),
.BR csx_ModifyWindow (9F),
.BR csx_RegisterClient (9F),
.BR csx_RequestConfiguration (9F)
.sp
.LP
\fIPC\fR \fICard\fR \fI95\fR \fIStandard,\fR PCMCIA/JEIDA