1csx_RequestIO(9F) Kernel Functions for Drivers csx_RequestIO(9F)
2
6 csx_RequestIO, csx_ReleaseIO - request or release I/O resources for the
7 client
8
10 #include <sys/pccard.h>
11 int32_t csx_RequestIO(client_handle_t ch, io_req_t *ir);
15 int32_t csx_ReleaseIO(client_handle_t ch, io_req_t *ir);
18
21 Solaris DDI Specific (Solaris DDI)
22
24 ch Client handle returned from csx_RegisterClient(9F).
25 ir Pointer to an io_req_t structure.
28
31 The functions csx_RequestIO() and csx_ReleaseIO() request or release,
32 respectively, I/O resources for the client.
33 If a client requires I/O resources, csx_RequestIO() must be called to
36 request I/O resources from Card Services; then csx_RequestConfigura‐
37 tion(9F) must be used to establish the configuration. csx_RequestIO()
38 can be called multiple times until a successful set of I/O resources is
39 found. csx_RequestConfiguration(9F) only uses the last configuration
40 specified.
41 csx_RequestIO() fails if it has already been called without a corre‐
44 sponding csx_ReleaseIO().
45 csx_ReleaseIO() releases previously requested I/O resources. The Card
48 Services window resource list is adjusted by this function. Depending
49 on the adapter hardware, the I/O window might also be disabled.
50
52 The structure members of io_req_t are:
53 uint32_t Socket; /* socket number*/
55 uint32_t Baseport1.base; /* IO range base port address */
57 acc_handle_t Baseport1.handle; /* IO range base address
58 /* or port num */
59 uint32_t NumPorts1; /* first IO range number contiguous
60 /* ports */
61 uint32_t Attributes1; /* first IO range attributes */
62 uint32_t Baseport2.base; /* IO range base port address */
64 acc_handle_t Baseport2.handle; /* IO range base address or port num */
65 uint32_t NumPorts2; /* second IO range number contiguous
66 /* ports */
67 uint32_t Attributes2; /* second IO range attributes */
68 uint32_t IOAddrLines; /* number of IO address lines decoded */
70 The fields are defined as follows:
74 Socket Not used in Solaris, but for portability with other
76 Card Services implementations, it should be set to
77 the logical socket number.
78 BasePort1.base Two I/O address ranges can be requested by
81 BasePort1.handle csx_RequestIO(). Each I/O address range is speci‐
82 BasePort2.base fied by the BasePort, NumPorts, and Attributes
83 BasePort2.handle fields. If only a single I/O range is being
84 requested, the NumPorts2 field must be reset to 0.
85 When calling csx_RequestIO(), the BasePort.base
87 field specifies the first port address requested.
88 Upon successful return from csx_RequestIO(), the
89 BasePort.handle field contains an access handle,
90 corresponding to the first byte of the allocated
91 I/O window, which the client must use when access‐
92 ing the PC Card's I/O space via the common access
93 functions. A client must not make any assumptions
94 as to the format of the returned BasePort.handle
95 field value.
96 If the BasePort.base field is set to 0, Card Ser‐
98 vices returns an I/O resource based on the avail‐
99 able I/O resources and the number of contiguous
100 ports requested. When BasePort.base is 0, Card Ser‐
101 vices aligns the returned resource in the host sys‐
102 tem's I/O address space on a boundary that is a
103 multiple of the number of contiguous ports
104 requested, rounded up to the nearest power of two.
105 For example, if a client requests two I/O ports,
106 the resource returned will be a multiple of two. If
107 a client requests five contiguous I/O ports, the
108 resource returned will be a multiple of eight.
109 If multiple ranges are being requested, at least
111 one of the BasePort.base fields must be non-zero.
112 NumPorts This field is the number of contiguous ports being
115 requested.
116 Attributes This field is bit-mapped. The following bits are
119 defined:
120 IO_DATA_WIDTH_8 I/O resource uses 8-bit
122 data path.
123 IO_DATA_WIDTH_16 I/O resource uses 16-bit
126 data path.
127 WIN_ACC_NEVER_SWAP Host endian byte order‐
130 ing.
131 WIN_ACC_BIG_ENDIAN Big endian byte ordering
134 WIN_ACC_LITTLE_ENDIAN Little endian byte
137 ordering.
138 WIN_ACC_STRICT_ORDER Program ordering refer‐
141 ences.
142 WIN_ACC_UNORDERED_OK May re-order references.
145 WIN_ACC_MERGING_OK Merge stores to consecu‐
148 tive locations.
149 WIN_ACC_LOADCACHING_OK May cache load opera‐
152 tions.
153 WIN_ACC_STORECACHING_OK May cache store opera‐
156 tions.
157 For some combinations of host system busses and
159 adapter hardware, the width of an I/O resource can
160 not be set via RequestIO(); on those systems, the
161 host bus cycle access type determines the I/O
162 resource data path width on a per-cycle basis.
163 WIN_ACC_BIG_ENDIAN and WIN_ACC_LITTLE ENDIAN
165 describe the endian characteristics of the device
166 as big endian or little endian, respectively. Even
167 though most of the devices will have the same
168 endian characteristics as their busses, there are
169 examples of devices with an I/O processor that has
170 opposite endian characteristics of the busses. When
171 WIN_ACC_BIG_ENDIAN or WIN_ACC_LITTLE ENDIAN is set,
172 byte swapping will automatically be performed by
173 the system if the host machine and the device data
174 formats have opposite endian characteristics. The
175 implementation may take advantage of hardware plat‐
176 form byte swapping capabilities.
177 When WIN_ACC_NEVER_SWAP is specified, byte swapping
179 will not be invoked in the data access functions.
180 The ability to specify the order in which the CPU
181 will reference data is provided by the following
182 Attributes bits. Only one of the following bits may
183 be specified:
184 WIN_ACC_STRICT_ORDER
186 The data references must be issued by a CPU in
188 program order. Strict ordering is the default
189 behavior.
190 WIN_ACC_UNORDERED_OK
193 The CPU may re-order the data references. This
195 includes all kinds of re-ordering (that is, a
196 load followed by a store may be replaced by a
197 store followed by a load).
198 WIN_ACC_MERGING_OK
201 The CPU may merge individual stores to consecu‐
203 tive locations. For example, the CPU may turn
204 two consecutive byte stores into one halfword
205 store. It may also batch individual loads. For
206 example, the CPU may turn two consecutive byte
207 loads into one halfword load. IO_MERGING_OK_ACC
208 also implies re-ordering.
209 WIN_ACC_LOADCACHING_OK
212 The CPU may cache the data it fetches and reuse
214 it until another store occurs. The default
215 behavior is to fetch new data on every load.
216 WIN_ACC_LOADCACHING_OK also implies merging and
217 re-ordering.
218 WIN_ACC_STORECACHING_OK
221 The CPU may keep the data in the cache and push
223 it to the device (perhaps with other data) at a
224 later time. The default behavior is to push the
225 data right away. WIN_ACC_STORECACHING_OK also
226 implies load caching, merging, and re-ordering.
227 These values are advisory, not mandatory. For exam‐
229 ple, data can be ordered without being merged or
230 cached, even though a driver requests unordered,
231 merged and cached together. All other bits in the
232 Attributes field must be set to 0.
233 IOAddrLines This field is the number of I/O address lines
236 decoded by the PC Card in the specified socket.
237 On some systems, multiple calls to csx_RequestIO() with different Base‐
241 Port, NumPorts, and/or IOAddrLines values will have to be made to find
242 an acceptable combination of parameters that can be used by Card Ser‐
243 vices to allocate I/O resources for the client. (See NOTES).
244
246 CS_SUCCESS Successful operation.
247 CS_BAD_ATTRIBUTE Invalid Attributes specified.
250 CS_BAD_BASE BasePort value is invalid.
253 CS_BAD_HANDLE Client handle is invalid.
256 CS_CONFIGURATION_LOCKED csx_RequestConfiguration(9F) has already
259 been done.
260 CS_IN_USE csx_RequestIO() has already been done with‐
263 out a corresponding csx_ReleaseIO().
264 CS_NO_CARD No PC Card in socket.
267 CS_BAD_WINDOW Unable to allocate I/O resources.
270 CS_OUT_OF_RESOURCE Unable to allocate I/O resources.
273 CS_UNSUPPORTED_FUNCTION No PCMCIA hardware installed.
276
279 These functions may be called from user or kernel context.
280
282 csx_RegisterClient(9F), csx_RequestConfiguration(9F)
283 PC Card 95 Standard, PCMCIA/JEIDA
286
288 It is important for clients to try to use the minimum amount of I/O
289 resources necessary. One way to do this is for the client to parse the
290 CIS of the PC Card and call csx_RequestIO() first with any IOAddrLines
291 values that are 0 or that specify a minimum number of address lines
292 necessary to decode the I/O space on the PC Card. Also, if no conve‐
293 nient minimum number of address lines can be used to decode the I/O
294 space on the PC Card, it is important to try to avoid system conflicts
295 with well-known architectural hardware features.
296SunOS 5.11 19 Jul 1996 csx_RequestIO(9F)