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