| blob | 2ff830e93c76d8305ecd2fc31479377b2b2a50e2 |
1 .\" $NetBSD: pcmcia.9,v 1.16 2008/04/30 13:10:58 martin Exp $
2 .\"
3 .\" Copyright (c) 2001 The NetBSD Foundation, Inc.
4 .\" All rights reserved.
5 .\"
6 .\" This code is derived from software contributed to The NetBSD Foundation
7 .\" by Gregory McGarry.
8 .\"
9 .\" Redistribution and use in source and binary forms, with or without
10 .\" modification, are permitted provided that the following conditions
11 .\" are met:
12 .\" 1. Redistributions of source code must retain the above copyright
13 .\" notice, this list of conditions and the following disclaimer.
14 .\" 2. Redistributions in binary form must reproduce the above copyright
15 .\" notice, this list of conditions and the following disclaimer in the
16 .\" documentation and/or other materials provided with the distribution.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
21 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
28 .\" POSSIBILITY OF SUCH DAMAGE.
29 .\"
30 .Dd November 2, 2005
31 .Dt PCMCIA 9
32 .Os
33 .Sh NAME
34 .Nm PCMCIA
35 .Nm pcmcia_function_init ,
36 .Nm pcmcia_function_enable ,
37 .Nm pcmcia_function_disable ,
38 .Nm pcmcia_io_alloc ,
39 .Nm pcmcia_io_free ,
40 .Nm pcmcia_io_map ,
41 .Nm pcmcia_io_unmap ,
42 .Nm pcmcia_mem_alloc ,
43 .Nm pcmcia_mem_free ,
44 .Nm pcmcia_mem_map ,
45 .Nm pcmcia_mem_unmap ,
46 .Nm pcmcia_intr_establish ,
47 .Nm pcmcia_intr_disestablish ,
48 .Nm pcmcia_cis_read_1 ,
49 .Nm pcmcia_cis_read_2 ,
50 .Nm pcmcia_cis_read_3 ,
51 .Nm pcmcia_cis_read_4 ,
52 .Nm pcmcia_cis_read_n ,
53 .Nm pcmcia_scan_cis
54 .Nd support for PCMCIA PC-Card devices
55 .Sh SYNOPSIS
56 .In machine/bus.h
57 .In dev/pcmcia/pcmciareg.h
58 .In dev/pcmcia/pcmciavar.h
59 .In dev/pcmcia/pcmciadevs.h
60 .Ft void
61 .Fn pcmcia_function_init "struct pcmcia_function *pf" \
62 "struct pcmcia_config_entry *cfe"
63 .Ft int
64 .Fn pcmcia_function_enable "struct pcmcia_function *pf"
65 .Ft void
66 .Fn pcmcia_function_disable "struct pcmcia_function *pf"
67 .Ft int
68 .Fn pcmcia_io_alloc "struct pcmcia_function *pf" "bus_addr_t start" \
69 "bus_size_t size" "bus_size_t align" "struct pcmcia_io_handle *pciop"
70 .Ft void
71 .Fn pcmcia_io_free "struct pcmcia_function *pf" \
72 "struct pcmcia_io_handle *pcihp"
73 .Ft int
74 .Fn pcmcia_io_map "struct pcmcia_function *pf" "int width" \
75 "struct pcmcia_io_handle *pcihp" "int *windowp"
76 .Ft void
77 .Fn pcmcia_io_unmap "struct pcmcia_function *pf" "int window"
78 .Ft int
79 .Fn pcmcia_mem_alloc "struct pcmcia_function *pf" "bus_size_t size" \
80 "struct pcmcia_mem_handle *pcmhp"
81 .Ft void
82 .Fn pcmcia_mem_free "struct pcmcia_function *pf" \
83 "struct pcmcia_mem_handle *pcmhp"
84 .Ft int
85 .Fn pcmcia_mem_map "struct pcmcia_function *pf" "int width" \
86 "bus_addr_t card_addr" "bus_size_t size" "struct pcmcia_mem_handle *pcmhp" \
87 "bus_size_t *offsetp" "int *windowp"
88 .Ft void
89 .Fn pcmcia_mem_unmap "struct pcmcia_function *pf" "int window"
90 .Ft void *
91 .Fn pcmcia_intr_establish "struct pcmcia_function *pf" "int level" \
92 "int (*handler)(void *)" "void *arg"
93 .Ft void
94 .Fn pcmcia_intr_disestablish "struct pcmcia_function *pf" "void *ih"
95 .Ft uint8_t
96 .Fn pcmcia_cis_read_1 "struct pcmcia_tuple *tuple" "int index"
97 .Ft uint16_t
98 .Fn pcmcia_cis_read_2 "struct pcmcia_tuple *tuple" "int index"
99 .Ft uint32_t
100 .Fn pcmcia_cis_read_3 "struct pcmcia_tuple *tuple" "int index"
101 .Ft uint32_t
102 .Fn pcmcia_cis_read_4 "struct pcmcia_tuple *tuple" "int index"
103 .Ft uint32_t
104 .Fn pcmcia_cis_read_n "struct pcmcia_tuple *tuple" "int number" "int index"
105 .Ft int
106 .Fn pcmcia_scan_cis "struct device *dev" \
107 "int (*func)(struct pcmcia_tuple *, void *)" "void *arg"
108 .Sh DESCRIPTION
109 The machine-independent
110 .Nm
111 subsystem provides support for PC-Card devices defined by the Personal
112 Computer Memory Card International Assocation (PCMCIA).
113 The
114 .Nm
115 bus supports insertion and removal of cards while a system is
116 powered-on (ie, dynamic reconfiguration).
117 The socket must be powered-off when a card is not present.
118 To the user, this appears as though the socket is "hot" during
119 insertion and removal events.
120 .Pp
121 A PCMCIA controller interfaces the PCMCIA bus with the ISA or PCI
122 busses on the host system.
123 The controller is responsible for detecting and enabling devices and
124 for allocating and mapping resources such as memory and interrupts
125 to devices on the PCMCIA bus.
126 .Pp
127 Each device has a table called the Card Information Structure (CIS)
128 which contains configuration information.
129 The tuples in the CIS are used by the controller to uniquely identify
130 the device.
131 Additional information may be present in the CIS, such as the ethernet
132 MAC address, that can be accessed and used within a device driver.
133 .Pp
134 Devices on the PCMCIA bus are uniquely identified by a 32-bit
135 manufacturer ID and a 32-bit product ID.
136 Additionally, devices can perform multiple functions (such as ethernet
137 and modem) and these functions are identified by a function ID.
138 .Pp
139 PCMCIA devices do not support DMA, however memory on the device can be
140 mapped into the address space of the host.
141 .Sh DATA TYPES
142 Drivers attached to the
143 .Nm
144 bus will make use of the following data types:
145 .Bl -tag -width compact
146 .It Fa struct pcmcia_card
147 Devices (cards) have their identity recorded in this structure.
148 It contains the following members:
149 .Bd -literal
150 char *cis1_info[4];
151 int32_t manufacturer;
152 int32_t product;
153 uint16_t error;
154 SIMPLEQ_HEAD(, pcmcia_function) pf_head;
155 .Ed
156 .It Fa struct pcmcia_function
157 Identifies the function of the devices.
158 A device can have multiple functions.
159 Consider it an opaque type for identifying a particular function
160 of a device.
161 .It struct pcmcia_config_entry
162 Contains information about the resources requested by the device.
163 It contains the following members:
164 .Bd -literal
165 int number;
166 uint32_t flags;
167 int iftype;
168 int num_iospace;
169 u_long iomask;
170 struct {
171 u_long length;
172 u_long start;
173 } iospace[4];
174 uint16_t irqmask;
175 int num_memspace;
176 struct {
177 u_long length;
178 u_long cardaddr;
179 u_long hostaddr;
180 } memspace[2];
181 int maxtwins;
182 SIMPLEQ_ENTRY(pcmcia_config_entry) cfe_list;
183 .Ed
184 .It Fa struct pcmcia_tuple
185 A handle for identifying an entry in the CIS.
186 .It Fa struct pcmcia_io_handle
187 A handle for mapping and allocating I/O address spaces.
188 It contains the tag and handle for accessing the bus-space.
189 .It Fa struct pcmcia_mem_handle
190 A handle for mapping and allocating memory address spaces.
191 It contains the tag and handle for accessing the bus-space.
192 .It Fa struct pcmcia_attach_args
193 A structure used to inform the driver of the
194 device properties.
195 It contains the following members:
196 .Bd -literal
197 int32_t manufacturer;
198 int32_t product;
199 struct pcmcia_card *card;
200 struct pcmcia_function *pf;
201 .Ed
202 .El
203 .Sh FUNCTIONS
204 .Bl -tag -width compact
205 .It Fn pcmcia_function_init "pf" "cfe"
206 Initialise the machine-independent
207 .Nm
208 state with the config entry
209 .Fa cfe .
210 .It Fn pcmcia_function_enable "pf"
211 Provide power to the socket containing the device specified by
212 device function
213 .Fa pf .
214 .It Fn pcmcia_function_disable "pf"
215 Remove power from the socket containing the device specified by
216 device function
217 .Fa pf .
218 .It Fn pcmcia_io_alloc "pf" "start" "size" "align" "pciop"
219 Request I/O space for device function
220 .Fa pf
221 at address
222 .Fa start
223 of size
224 .Fa size .
225 Alignment is specified by
226 .Fa align .
227 A handle for the I/O space is returned in
228 .Fa pciop .
229 .It Fn pcmcia_io_free "pf" "pcihp"
230 Release I/O space with handle
231 .Fa pcihp
232 for device function
233 .Fa pf .
234 .It Fn pcmcia_io_map "pf" "width" "pcihp" "windowp"
235 Map device I/O for device function
236 .Fa pf
237 to the I/O space with handle
238 .Fa pcihp .
239 The width of data access is specified by
240 .Fa width .
241 Valid values for the width are:
242 .Bl -tag -width PCMCIA_WIDTH_AUTO
243 .It PCMCIA_WIDTH_AUTO
244 Use the largest I/O width reported by the device.
245 .It PCMCIA_WIDTH_IO8
246 Force 8-bit I/O width.
247 .It PCMCIA_WIDTH_IO16
248 Force 16-bit I/O width.
249 .El
250 .Pp
251 A handle for the mapped I/O window is returned in
252 .Fa windowp .
253 .It Fn pcmcia_io_unmap "pf" "window"
254 Unmap the I/O window
255 .Fa window
256 for device function
257 .Fa pf .
258 .It Fn pcmcia_mem_alloc "pf" "size" "pcmhp"
259 Request memory space for device function
260 .Fa pf
261 of size
262 .Fa size .
263 A handle for the memory space is returned in
264 .Fa pcmhp .
265 .It Fn pcmcia_mem_free "pf" "pcmhp"
266 Release memory space with handle
267 .Fa pcmhp
268 for device function
269 .Fa pf .
270 .It Fn pcmcia_mem_map "pf" "width" "card_addr" "size" "pcmhp" "offsetp" \
271 "windowp"
272 Map device memory for device function
273 .Fa pf
274 to the memory space with handle
275 .Fa pcmhp .
276 The address of the device memory starts at
277 .Fa card_addr
278 and is size
279 .Fa size .
280 The width of data access is specified by
281 .Fa width .
282 Valid values for the width are:
283 .Bl -tag -width PCMCIA_WIDTH_MEM16
284 .It PCMCIA_WIDTH_MEM8
285 Force 8-bit memory width.
286 .It PCMCIA_WIDTH_MEM16
287 Force 16-bit memory width.
288 .El
289 .Pp
290 A handle for the mapped memory window is returned in
291 .Fa windowp
292 and a bus-space offset into the memory window is returned in
293 .Fa offsetp .
294 .It Fn pcmcia_mem_unmap "pf" "window"
295 Unmap the memory window
296 .Fa window
297 for device function
298 .Fa pf .
299 .It Fn pcmcia_intr_establish "pf" "level" "handler" "arg"
300 Establish an interrupt handler for device function
301 .Fa pf .
302 The priority of the interrupt is specified by
303 .Fa level .
304 When the interrupt occurs the function
305 .Fa handler
306 is called with argument
307 .Fa arg .
308 The return value is a handle for the interrupt handler.
309 .Fn pcmcia_intr_establish
310 returns an opaque handle to an event descriptor if it succeeds, and
311 returns NULL on failure.
312 .It Fn pcmcia_intr_disestablish "pf" "ih"
313 Dis-establish the interrupt handler for device function
314 .Fa pf
315 with handle
316 .Fa ih .
317 The handle was returned from
318 .Fn pcmcia_intr_establish .
319 .It Fn pcmcia_cis_read_1 "tuple" "index"
320 Read one byte from tuple
321 .Fa tuple
322 at index
323 .Fa index
324 in the CIS.
325 .It Fn pcmcia_cis_read_2 "tuple" "index"
326 Read two bytes from tuple
327 .Fa tuple
328 at index
329 .Fa index
330 in the CIS.
331 .It Fn pcmcia_cis_read_3 "tuple" "index"
332 Read three bytes from tuple
333 .Fa tuple
334 at index
335 .Fa index
336 in the CIS.
337 .It Fn pcmcia_cis_read_4 "tuple" "index"
338 Read four bytes from tuple
339 .Fa tuple
340 at index
341 .Fa index
342 in the CIS.
343 .It Fn pcmcia_cis_read_n "tuple" "number" "index"
344 Read
345 .Fa n
346 bytes from tuple
347 .Fa tuple
348 at index
349 .Fa index
350 in the CIS.
351 .It Fn pcmcia_scan_cis "dev" "func" "arg"
352 Scan the CIS for device
353 .Fa dev .
354 For each tuple in the CIS, function
355 .Fa func
356 is called with the tuple and the argument
357 .Fa arg .
358 .Fa func
359 should return 0 if the tuple it was called with is the one it was
360 looking for, or 1 otherwise.
361 .El
362 .Sh AUTOCONFIGURATION
363 During autoconfiguration, a
364 .Nm
365 driver will receive a pointer to
366 .Fa struct pcmcia_attach_args
367 describing the device attached to the PCMCIA bus.
368 Drivers match the device using the
369 .Em manufacturer
370 and
371 .Em product
372 members.
373 .Pp
374 During the driver attach step, drivers will use the pcmcia function
375 .Em pf .
376 The driver should traverse the list of config entries searching for a
377 useful configuration.
378 This config entry is passed to
379 .Fn pcmcia_function_init
380 to initialise the machine-independent interface.
381 I/O and memory resources should be initialised using
382 .Fn pcmcia_io_alloc
383 and
384 .Fn pcmcia_mem_alloc
385 using the specified resources in the config entry.
386 These resources can then be mapped into processor bus space using
387 .Fn pcmcia_io_map
388 and
389 .Fn pcmcia_mem_map
390 respectively.
391 Upon successful allocation of resources, power can be applied to the
392 device with
393 .Fn pcmcia_function_enable
394 so that device-specific interrogation can be performed.
395 Finally, power should be removed from the device using
396 .Fn pcmcia_function_disable .
397 .Pp
398 Since PCMCIA devices support dynamic configuration, drivers should
399 make use of
400 .Fn powerhook_establish 9 .
401 Power can be applied and the interrupt handler should be established
402 through this interface.
403 .Sh DMA SUPPORT
404 PCMCIA devices do not support DMA.
405 .Sh CODE REFERENCES
406 This section describes places within the
407 .Nx
408 source tree where actual code implementing or using the
409 machine-independent PCMCIA subsystem can be found.
410 All pathnames are relative to
411 .Pa /usr/src .
412 .Pp
413 The PCMCIA subsystem itself is implemented within the file
414 .Pa sys/dev/pcmcia/pcmcia.c .
415 The database of known devices exists within the file
416 .Pa sys/dev/pcmcia/pcmciadevs_data.h
417 and is generated automatically from the file
418 .Pa sys/dev/pcmcia/pcmciadevs .
419 New manufacturer and product identifiers should be added to this file.
420 The database can be regenerated using the Makefile
421 .Pa sys/dev/pcmcia/Makefile.pcmciadevs .
422 .Sh SEE ALSO
423 .Xr pcic 4 ,
424 .Xr pcmcia 4 ,
425 .Xr tcic 4 ,
426 .Xr autoconf 9 ,
427 .Xr bus_dma 9 ,
428 .Xr bus_space 9 ,
429 .Xr driver 9
430 .Rs
431 .%A Personal Computer Memory Card International Association (PCMCIA)
432 .%T "PC Card 95 Standard"
433 .%D 1995
434 .Re
435 .Sh HISTORY
436 The machine-independent PCMCIA subsystem appeared in
437 .Nx 1.3 .