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