1.\" $NetBSD: pcmcia.9,v 1.8 2002/02/13 08:18:48 ross 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). The 121.Nm 122bus supports insertion and removal of cards while a system is 123powered-on (ie, dynamic reconfiguration). The socket must be 124powered-off when a card is not present. To the user, this appears as 125though the socket is "hot" during insertion and removal events. 126.Pp 127A PCMCIA controller interfaces the PCMCIA bus with the ISA or PCI 128busses on the host system. The controller is responsible for 129detecting and enabling devices and for allocating and mapping 130resources such as memory and interrupts to devices on the 131PCMCIA bus. 132.Pp 133Each device has a table called the Card Information Structure (CIS) 134which contains configuration information. The tuples in the CIS are 135used by the controller to uniquely identify the device. Additional 136information may be present in the CIS, such as the ethernet MAC 137address, that can be accessed and utilised within a device driver. 138.Pp 139Devices on the PCMCIA bus are uniquely identified by a 32-bit 140manufacturer ID and a 32-bit product ID. Additionally, devices can 141perform multiple functions (such a ethernet and modem) and these 142functions are identified by a function ID. 143.Pp 144PCMCIA devices do not support DMA, however memory on the device can be 145mapped into the address space of the host. 146.Sh DATA TYPES 147Drivers attached to the 148.Nm 149bus will make use of the following data types: 150.Bl -tag -width compact 151.It Fa struct pcmcia_card 152Devices (cards) have their identity recorded in this structure. It 153contains the following members: 154.Bd -literal 155 char *cis1_info[4]; 156 int32_t manufacturer; 157 int32_t product; 158 u_int16_t error; 159 SIMPLEQ_HEAD(, pcmcia_function) pf_head; 160.Ed 161.It Fa struct pcmcia_function 162Identifies the function of the devices. A device can have multiple 163functions. Consider it an opaque type for identifying a particular 164function of a device. 165.It struct pcmcia_config_entry 166Contains information about the resources requested by the device. 167It contains the following members: 168.Bd -literal 169 int number; 170 u_int32_t flags; 171 int iftype; 172 int num_iospace; 173 u_long iomask; 174 struct { 175 u_long length; 176 u_long start; 177 } iospace[4]; 178 u_int16_t irqmask; 179 int num_memspace; 180 struct { 181 u_long length; 182 u_long cardaddr; 183 u_long hostaddr; 184 } memspace[2]; 185 int maxtwins; 186 SIMPLEQ_ENTRY(pcmcia_config_entry) cfe_list; 187.Ed 188.It Fa struct pcmcia_tuple 189A handle for identifying an entry in the CIS. 190.It Fa struct pcmcia_io_handle 191A handle for mapping and allocating I/O address spaces. It contains 192the tag and handle for accessing the bus-space. 193.It Fa struct pcmcia_mem_handle 194A handle for mapping and allocating memory address spaces. It contains 195the tag and handle for accessing the bus-space. 196.It Fa struct pcmcia_attach_args 197A structure used to inform the driver of the 198device properties. It contains the following members: 199.Bd -literal 200 int32_t manufacturer; 201 int32_t product; 202 struct pcmcia_card *card; 203 struct pcmcia_function *pf; 204.Ed 205.El 206.Sh FUNCTIONS 207.Bl -tag -width compact 208.It Fn pcmcia_function_init "pf" "cfe" 209Initialise the machine-independent 210.Nm 211state with the config entry 212.Fa cfe . 213.It Fn pcmcia_function_enable "pf" 214Provide power to the socket containing the device specified by 215device function 216.Fa pf . 217.It Fn pcmcia_function_disable "pf" 218Remove power from the socket containing the device specified by 219device function 220.Fa pf . 221.It Fn pcmcia_io_alloc "pf" "start" "size" "align" "pciop" 222Request I/O space for device function 223.Fa pf 224at address 225.Fa start 226of size 227.Fa size . 228Alignment is specified by 229.Fa align . 230A handle for the I/O space is returned in 231.Fa pciop . 232.It Fn pcmcia_io_free "pf" "pcihp" 233Release I/O space with handle 234.Fa pcihp 235for device function 236.Fa pf . 237.It Fn pcmcia_io_map "pf" "width" "offset" "size" "pcihp" "windowp" 238Map device I/O for device function 239.Fa pf 240to the I/O space with handle 241.Fa pcihp . 242An I/O window of size 243.Fa size 244is mapped at offset 245.Fa offset 246in the chipset I/O window. The 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. Drivers match the 375device 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. This config entry is passed to 385.Fn pcmcia_function_init 386to initialise the machine-independent interface. I/O and memory 387resources should be initialised using 388.Fn pcmcia_io_alloc 389and 390.Fn pcmcia_mem_alloc 391using the specified resources in the config entry. These resources 392can then be mapped into processor bus space using 393.Fn pcmcia_io_map 394and 395.Fn pcmcia_mem_map 396respectively. Upon successful allocation of resources, power can be 397applied to the device with 398.Fn pcmcia_function_enable 399so that device-specific interrogation can be performed. Finally, 400power should be removed from the device using 401.Fn pcmcia_function_disable . 402.Pp 403Since PCMCIA devices support dynamic configuration, drivers should 404make use of 405.Fn powerhook_establish 9 . 406Power can be applied and the interrupt handler should be established 407through this interface. 408.Sh DMA SUPPORT 409PCMCIA devices do not support DMA. 410.Sh CODE REFERENCES 411This section describes places within the 412.Nx 413source tree where actual code implementing or utilising the 414machine-independent PCMCIA subsystem can be found. All pathnames are 415relative to 416.Pa /usr/src . 417.Pp 418The PCMCIA subsystem itself is implemented within the file 419.Pa sys/dev/pcmcia/pcmcia.c . 420The database of known devices exists within the file 421.Pa sys/dev/pcmcia/pcmciadevs_data.h 422and is generated automatically from the file 423.Pa sys/dev/pcmcia/pcmciadevs . 424New manufacturer and product identifiers should be added to this 425file. The database can be regenerated using the Makefile 426.Pa sys/dev/pcmcia/Makefile.pcmciadevs . 427.Sh SEE ALSO 428.Xr pcic 4 , 429.Xr pcmcia 4 , 430.Xr tcic 4 , 431.Xr autoconf 9 , 432.Xr bus_dma 9 , 433.Xr bus_space 9 , 434.Xr driver 9 435.Rs 436.%A Personal Computer Memory Card International Association (PCMCIA) 437.%T "PC Card 95 Standard" 438.%D 1995 439.Re 440.Sh HISTORY 441The machine-independent PCMCIA subsystem appeared in 442.Nx 1.3 . 443