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