'\" 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_DupHandle 9F "19 Jul 1996" "SunOS 5.11" "Kernel Functions for Drivers" .SH NAME csx_DupHandle \- duplicate access handle .SH SYNOPSIS .LP .nf #include \fBint32_t\fR \fBcsx_DupHandle\fR(\fBacc_handle_t\fR \fIhandle1\fR, \fBacc_handle_t *\fR\fIhandle2\fR, \fBuint32_t\fR \fIflags\fR); .fi .SH INTERFACE LEVEL .sp .LP Solaris \fBDDI \fRSpecific (Solaris \fBDDI) \fR .SH PARAMETERS .sp .ne 2 .mk .na \fB\fIhandle1\fR \fR .ad .RS 12n .rt The access handle returned from \fBcsx_RequestIO\fR(9F) or \fBcsx_RequestWindow\fR(9F) that is to be duplicated. .RE .sp .ne 2 .mk .na \fB\fIhandle2\fR \fR .ad .RS 12n .rt A pointer to the newly-created duplicated data access handle. .RE .sp .ne 2 .mk .na \fB\fIflags\fR \fR .ad .RS 12n .rt The access attributes that will be applied to the new handle. .RE .SH DESCRIPTION .sp .LP This function duplicates the handle, \fIhandle1\fR, into a new handle, \fIhandle2\fR, that has the access attributes specified in the \fIflags\fR argument. Both the original handle and the new handle are active and can be used with the common access functions. .sp .LP Both handles must be explicitly freed when they are no longer necessary. .sp .LP The \fIflags\fR argument is bit-mapped. The following bits are defined: .sp .in +2 .nf 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 .fi .in -2 .sp .LP \fBWIN_ACC_BIG_ENDIAN\fR and \fBWIN_ACC_LITTLE_ENDIAN\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 \fRprocessor that has opposite endian characteristics of the busses. When \fBWIN_ACC_BIG_ENDIAN\fR or \fBWIN_ACC_LITTLE_ENDIAN\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. 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 \fRwill reference data is provided by the following \fIflags\fR bits. Only one of the following bits may be specified: .sp .ne 2 .mk .na \fB\fBWIN_ACC_STRICT_ORDER\fR \fR .ad .RS 28n .rt The data references must be issued by a \fBCPU \fRin program order. Strict ordering is the default behavior. .RE .sp .ne 2 .mk .na \fB\fBWIN_ACC_UNORDERED_OK\fR \fR .ad .RS 28n .rt The \fBCPU \fRmay 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 .mk .na \fB\fBWIN_ACC_MERGING_OK\fR \fR .ad .RS 28n .rt 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. Setting this bit also implies re-ordering. .RE .sp .ne 2 .mk .na \fB\fBWIN_ACC_LOADCACHING_OK\fR \fR .ad .RS 28n .rt 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. Setting this bit also implies merging and re-ordering. .RE .sp .ne 2 .mk .na \fB\fBWIN_ACC_STORECACHING_OK\fR \fR .ad .RS 28n .rt 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. Setting this bit also implies load caching, merging, and re-ordering. .RE .sp .LP 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. .SH RETURN VALUES .sp .ne 2 .mk .na \fB\fBCS_SUCCESS\fR \fR .ad .RS 28n .rt Successful operation. .RE .sp .ne 2 .mk .na \fB\fBCS_FAILURE\fR \fR .ad .RS 28n .rt Error in \fIflags\fR argument or handle could not be duplicated for some reason. .RE .sp .ne 2 .mk .na \fB\fBCS_UNSUPPORTED_FUNCTION\fR \fR .ad .RS 28n .rt No \fBPCMCIA \fRhardware installed. .RE .SH CONTEXT .sp .LP This function may be called from user or kernel context. .SH SEE ALSO .sp .LP \fBcsx_Get8\fR(9F), \fBcsx_GetMappedAddr\fR(9F), \fBcsx_Put8\fR(9F), \fBcsx_RepGet8\fR(9F), \fBcsx_RepPut8\fR(9F), \fBcsx_RequestIO\fR(9F), \fBcsx_RequestWindow\fR(9F) .sp .LP \fIPC Card 95 Standard, PCMCIA/JEIDA\fR