1csx_RequestIO(9F)        Kernel Functions for Drivers        csx_RequestIO(9F)
2
3
4

NAME

6       csx_RequestIO, csx_ReleaseIO - request or release I/O resources for the
7       client
8

SYNOPSIS

10       #include <sys/pccard.h>
11
12
13
14       int32_t csx_RequestIO(client_handle_t ch, io_req_t *ir);
15
16
17       int32_t csx_ReleaseIO(client_handle_t ch, io_req_t *ir);
18
19

INTERFACE LEVEL

21       Solaris DDI Specific (Solaris DDI)
22

PARAMETERS

24       ch    Client handle returned from csx_RegisterClient(9F).
25
26
27       ir    Pointer to an io_req_t structure.
28
29

DESCRIPTION

31       The functions csx_RequestIO() and csx_ReleaseIO() request  or  release,
32       respectively, I/O resources for the client.
33
34
35       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
42
43       csx_RequestIO() fails if it has already been called  without  a  corre‐
44       sponding csx_ReleaseIO().
45
46
47       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

STRUCTURE MEMBERS

52       The structure members of io_req_t are:
53
54         uint32_t      Socket;            /* socket number*/
55
56         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
63         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
69         uint32_t      IOAddrLines;       /* number of IO address lines decoded */
70
71
72
73       The fields are defined as follows:
74
75       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
79
80       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
86                           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
97                           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
110                           If  multiple  ranges  are being requested, at least
111                           one of the BasePort.base fields must be non-zero.
112
113
114       NumPorts            This field is the number of contiguous ports  being
115                           requested.
116
117
118       Attributes          This  field  is  bit-mapped. The following bits are
119                           defined:
120
121                           IO_DATA_WIDTH_8            I/O resource uses  8-bit
122                                                      data path.
123
124
125                           IO_DATA_WIDTH_16           I/O resource uses 16-bit
126                                                      data path.
127
128
129                           WIN_ACC_NEVER_SWAP         Host endian byte  order‐
130                                                      ing.
131
132
133                           WIN_ACC_BIG_ENDIAN         Big endian byte ordering
134
135
136                           WIN_ACC_LITTLE_ENDIAN      Little    endian    byte
137                                                      ordering.
138
139
140                           WIN_ACC_STRICT_ORDER       Program ordering  refer‐
141                                                      ences.
142
143
144                           WIN_ACC_UNORDERED_OK       May re-order references.
145
146
147                           WIN_ACC_MERGING_OK         Merge stores to consecu‐
148                                                      tive locations.
149
150
151                           WIN_ACC_LOADCACHING_OK     May  cache  load  opera‐
152                                                      tions.
153
154
155                           WIN_ACC_STORECACHING_OK    May  cache  store opera‐
156                                                      tions.
157
158                           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
164                           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
178                           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
185                           WIN_ACC_STRICT_ORDER
186
187                               The  data references must be issued by a CPU in
188                               program order. Strict ordering is  the  default
189                               behavior.
190
191
192                           WIN_ACC_UNORDERED_OK
193
194                               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
199
200                           WIN_ACC_MERGING_OK
201
202                               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
210
211                           WIN_ACC_LOADCACHING_OK
212
213                               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
219
220                           WIN_ACC_STORECACHING_OK
221
222                               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
228                           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
234
235       IOAddrLines         This field is  the  number  of  I/O  address  lines
236                           decoded by the PC Card in the specified socket.
237
238
239
240       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

RETURN VALUES

246       CS_SUCCESS                 Successful operation.
247
248
249       CS_BAD_ATTRIBUTE           Invalid Attributes specified.
250
251
252       CS_BAD_BASE                BasePort value is invalid.
253
254
255       CS_BAD_HANDLE              Client handle is invalid.
256
257
258       CS_CONFIGURATION_LOCKED    csx_RequestConfiguration(9F)   has   already
259                                  been done.
260
261
262       CS_IN_USE                  csx_RequestIO()  has already been done with‐
263                                  out a corresponding csx_ReleaseIO().
264
265
266       CS_NO_CARD                 No PC Card in socket.
267
268
269       CS_BAD_WINDOW              Unable to allocate I/O resources.
270
271
272       CS_OUT_OF_RESOURCE         Unable to allocate I/O resources.
273
274
275       CS_UNSUPPORTED_FUNCTION    No PCMCIA hardware installed.
276
277

CONTEXT

279       These functions may be called from user or kernel context.
280

SEE ALSO

282       csx_RegisterClient(9F), csx_RequestConfiguration(9F)
283
284
285       PC Card 95 Standard, PCMCIA/JEIDA
286

NOTES

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.
296
297
298
299SunOS 5.11                        19 Jul 1996                csx_RequestIO(9F)
Impressum