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

NAME

6       csx_RequestWindow,   csx_ReleaseWindow  -  request  or  release  window
7       resources
8

SYNOPSIS

10       #include <sys/pccard.h>
11
12
13
14       int32_t csx_RequestWindow(client_handle_t ch, window_handle_t *wh,
15            win_req_t *wr);
16
17
18       int32_t csx_ReleaseWindow(window_handle_t wh);
19
20

INTERFACE LEVEL

22       Solaris DDI Specific (Solaris DDI)
23

PARAMETERS

25       ch    Client handle returned from csx_RegisterClient(9F).
26
27
28       wh    Pointer to a window_handle_t structure.
29
30
31       wr    Pointer to a win_req_t structure.
32
33

DESCRIPTION

35       The function csx_RequestWindow() requests a  block  of  system  address
36       space be assigned to a PC Card in a socket.
37
38
39       The  function  csx_ReleaseWindow() releases window resources which were
40       obtained by a call to csx_RequestWindow(). No adapter or  socket  hard‐
41       ware is modified by this function.
42
43
44       The  csx_MapMemPage(9F) and csx_ModifyWindow(9F) functions use the win‐
45       dow handle returned by csx_RequestWindow(). This window handle must  be
46       freed by calling csx_ReleaseWindow() when the client is done using this
47       window.
48
49
50       The PC Card Attribute or Common Memory offset for this window is set by
51       csx_MapMemPage(9F).
52

STRUCTURE MEMBERS

54       The structure members of win_req_t are:
55
56         uint32_t      Socket;                  /* socket number */
57         uint32_t      Attributes;              /* window flags */
58         uint32_t      Base.base;               /* requested window */
59                                                 /*   base address */
60         acc_handle_t  Base.handle;             /* returned handle for
61                                                 /*   base of window */
62         uint32_t      Size;                    /* window size requested */
63                                                 /*   or granted */
64         uint32_t      win_params.AccessSpeed;  /* window access speed */
65         uint32_t      win_params.IOAddrLines;  /* IO address lines decoded */
66         uint32_t      ReqOffset;               /* required window offest */
67
68
69
70       The fields are defined as follows:
71
72       Socket                    Not used in Solaris, but for portability with
73                                 other  Card  Services   implementations,   it
74                                 should be set to the logical socket number.
75
76
77       Attributes                This  field  is  bit-mapped and is defined as
78                                 follows:
79
80                                 WIN_MEMORY_TYPE_IO
81
82                                     Points to I/O space.
83
84
85                                 WIN_MEMORY_TYPE_CM
86
87                                     Points to common memory space.
88
89
90                                 WIN_MEMORY_TYPE_AM
91
92                                     These bits select which type of window is
93                                     being  requested.  One of these bits must
94                                     be set.
95
96
97                                 WIN_ENABLE
98
99                                     The client must set this  bit  to  enable
100                                     the window.
101
102
103                                 WIN_ACC_BIG_ENDIAN
104
105                                     Describes device as big-endian.
106
107
108                                 WIN_ACC_LITTLE_ENDIAN
109
110                                     These bits describe the endian character‐
111                                     istics of the device  as  big  endian  or
112                                     little  endian, respectively. Even though
113                                     most of the devices will  have  the  same
114                                     endian  characteristics  as their busses,
115                                     there are examples of devices with an I/O
116                                     processor  that has opposite endian char‐
117                                     acteristics of the busses. When either of
118                                     these  bits  are  set, byte swapping will
119                                     automatically be performed by the  system
120                                     if  the  host machine and the device data
121                                     formats have opposite endian characteris‐
122                                     tics.  The implementation may take advan‐
123                                     tage of hardware platform  byte  swapping
124                                     capabilities.
125
126
127                                 WIN_ACC_NEVER_SWAP
128
129                                     When  this  is  specified,  byte swapping
130                                     will not be invoked in  the  data  access
131                                     functions.
132
133                                 The ability to specify the order in which the
134                                 CPU will reference data is  provided  by  the
135                                 following  Attributes bits, only one of which
136                                 may be specified:
137
138                                 WIN_ACC_STRICT_ORDER
139
140                                     The data references must be issued  by  a
141                                     CPU  in program order. Strict ordering is
142                                     the default behavior.
143
144
145                                 WIN_ACC_UNORDERED_OK
146
147                                     The CPU may re-order the data references.
148                                     This  includes  all  kinds of re-ordering
149                                     (that is, a load followed by a store  may
150                                     be  replaced  by  a  store  followed by a
151                                     load).
152
153
154                                 WIN_ACC_MERGING_OK
155
156                                     The CPU may merge  individual  stores  to
157                                     consecutive  locations.  For example, the
158                                     CPU may turn two consecutive byte  stores
159                                     into  one  halfword  store.  It  may also
160                                     batch individual loads. For example,  the
161                                     CPU  may  turn two consecutive byte loads
162                                     into one halfword  load.  This  bit  also
163                                     implies re-ordering.
164
165
166                                 WIN_ACC_LOADCACHING_OK
167
168                                     The CPU may cache the data it fetches and
169                                     reuse it until another store occurs.  The
170                                     default  behavior is to fetch new data on
171                                     every load. This bit also implies merging
172                                     and re-ordering.
173
174
175                                 WIN_ACC_STORECACHING_OK
176
177                                     The  CPU  may  keep the data in the cache
178                                     and push it to the device  (perhaps  with
179                                     other  data) at a later time. The default
180                                     behavior is to push the data right  away.
181                                     This bit also implies load caching, merg‐
182                                     ing, and re-ordering.
183
184                                 These values are advisory, not mandatory. For
185                                 example,  data  can  be ordered without being
186                                 merged  or  cached,  even  though  a   driver
187                                 requests   unordered,   merged   and   cached
188                                 together.
189
190                                 All other bits in the Attributes  field  must
191                                 be set to 0.
192
193                                 On  successful  return  from  csx_RequestWin‐
194                                 dow(),  WIN_OFFSET_SIZE   is   set   in   the
195                                 Attributes field when the client must specify
196                                 card offsets to csx_MapMemPage(9F) that are a
197                                 multiple of the window size.
198
199
200       Base.base                 This  field  must  be  set  to  0  on calling
201                                 csx_RequestWindow().
202
203
204       Base.handle               On  successful  return  from  csx_RequestWin‐
205                                 dow(),  the  Base.handle  field  contains  an
206                                 access handle corresponding to the first byte
207                                 of  the  allocated  memory  window  which the
208                                 client must use when accessing the PC  Card's
209                                 memory space via the common access functions.
210                                 A client must not make any assumptions as  to
211                                 the  format of the returned Base.handle field
212                                 value.
213
214
215       Size                      On  calling  csx_RequestWindow(),  the   Size
216                                 field is the size in bytes of the memory win‐
217                                 dow requested. Size may be zero  to  indicate
218                                 that  Card Services should provide the small‐
219                                 est sized  window  available.  On  successful
220                                 return  from  csx_RequestWindow(),  the  Size
221                                 field contains the actual size of the  window
222                                 allocated.
223
224
225       win_params.AccessSpeed    This  field specifies the access speed of the
226                                 window if the client is requesting  a  memory
227                                 window. The AccessSpeed field bit definitions
228                                 use the format of the extended speed byte  of
229                                 the  Device  ID  tuple.  If the mantissa is 0
230                                 (noted as reserved in the PC  Card  95  Stan‐
231                                 dard),  the lower bits are a binary code rep‐
232                                 resenting a speed from the following table:
233
234
235
236
237
238       ┌─────────────────────────────┬─────────────────────────────┐
239Code                         Speed                        
240       ├─────────────────────────────┼─────────────────────────────┤
241       │0                            │(Reserved - do not use).     │
242       ├─────────────────────────────┼─────────────────────────────┤
243       │1                            │250 nsec                     │
244       ├─────────────────────────────┼─────────────────────────────┤
245       │2                            │200 nsec                     │
246       ├─────────────────────────────┼─────────────────────────────┤
247       │3                            │150 nsec                     │
248       ├─────────────────────────────┼─────────────────────────────┤
249       │4                            │100 nse                      │
250       ├─────────────────────────────┼─────────────────────────────┤
251       │5-7                          │(Reserved—do not use.)       │
252       └─────────────────────────────┴─────────────────────────────┘
253
254
255       To  request  a  window  that  supports  the  WAIT  signal,  OR-in   the
256       WIN_USE_WAIT bit to the AccessSpeed value before calling this function.
257
258
259       It is recommended that clients use the csx_ConvertSpeed(9F) function to
260       generate the appropriate AccessSpeed values rather than  manually  per‐
261       turbing the AccessSpeed field.
262
263       win_params.IOAddrLines    If  the  client  is requesting an I/O window,
264                                 the IOAddrLines field is the  number  of  I/O
265                                 address  lines  decoded by the PC Card in the
266                                 specified socket. Access to the I/O window is
267                                 not   enabled   until   csx_RequestConfigura‐
268                                 tion(9F) has been invoked successfully.
269
270
271       ReqOffset                 This field is  a  Solaris-specific  extension
272                                 that can be used by clients to generate opti‐
273                                 mum  window  offsets  passed  to  csx_MapMem‐
274                                 Page(9F).
275
276

RETURN VALUES

278       CS_SUCCESS                 Successful operation.
279
280
281       CS_BAD_ATTRIBUTE           Attributes are invalid.
282
283
284       CS_BAD_SPEED               Speed is invalid.
285
286
287       CS_BAD_HANDLE              Client handle is invalid.
288
289
290       CS_BAD_SIZE                Window size is invalid.
291
292
293       CS_NO_CARD                 No PC Card in socket.
294
295
296       CS_OUT_OF_RESOURCE         Unable to allocate window.
297
298
299       CS_UNSUPPORTED_FUNCTION    No PCMCIA hardware installed.
300
301

CONTEXT

303       These functions may be called from user or kernel context.
304

SEE ALSO

306       csx_ConvertSpeed(9F),     csx_MapMemPage(9F),     csx_ModifyWindow(9F),
307       csx_RegisterClient(9F), csx_RequestConfiguration(9F)
308
309
310       PC Card 95 Standard, PCMCIA/JEIDA
311
312
313
314SunOS 5.11                        19 Jul 1996            csx_RequestWindow(9F)
Impressum