1.\" $NetBSD: cardbus.9,v 1.16 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 CARDBUS 9 32.Os 33.Sh NAME 34.Nm Cardbus , 35.Nm cardbus_attach_card , 36.Nm cardbus_detach_card , 37.Nm cardbus_function_enable , 38.Nm cardbus_function_disable , 39.Nm cardbus_mapreg_map , 40.Nm cardbus_mapreg_unmap , 41.Nm cardbus_get_capability , 42.Nm cardbus_make_tag , 43.Nm cardbus_conf_read , 44.Nm cardbus_conf_write , 45.Nm cardbus_intr_establish , 46.Nm cardbus_intr_disestablish , 47.Nm CARDBUS_VENDOR , 48.Nm CARDBUS_PRODUCT , 49.Nm Cardbus_function_enable , 50.Nm Cardbus_function_disable , 51.Nm Cardbus_mapreg_map , 52.Nm Cardbus_mapreg_unmap , 53.Nm Cardbus_make_tag , 54.Nm Cardbus_conf_read , 55.Nm Cardbus_conf_write 56.Nd support for CardBus PC-Card devices 57.Sh SYNOPSIS 58.In machine/bus.h 59.In dev/cardbus/cardbusvar.h 60.In dev/cardbus/cardbusreg.h 61.In dev/cardbus/cardbusdevs.h 62.Ft int 63.Fn cardbus_attach_card "struct cardbus_softc *csc" 64.Ft void 65.Fn cardbus_detach_card "struct cardbus_softc *csc" 66.Ft int 67.Fn cardbus_function_enable "struct cardbus_softc *csc" "int function" 68.Ft int 69.Fn cardbus_function_disable "struct cardbus_softc *csc" "int function" 70.Ft int 71.Fo cardbus_mapreg_map 72.Fa "struct cardbus_softc *csc" "int cf" "int reg" 73.Fa "pcireg_t type" "int busflags" "bus_space_tag_t *tagp" 74.Fa "bus_space_handle_t *handlep" "bus_addr_t *basep" "bus_size_t *sizep" 75.Fc 76.Ft int 77.Fn cardbus_mapreg_unmap "struct cardbus_softc *csc" "int cf" \ 78"int reg" "bus_space_tag_t tag" "bus_space_handle_t handle" \ 79"bus_size_t size" 80.Ft int 81.Fn cardbus_get_capability "cardbus_chipset_tag_t cc" \ 82"cardbus_function_tag_t cf" "pcitag_t tag" "int capid" \ 83"int *offsetp" "pcireg_t *valuep" 84.Ft pcitag_t 85.Fn cardbus_make_tag "cardbus_chipset_tag_t cc" "int cf" "int bus" \ 86"int device" "int function" 87.Ft pcireg_t 88.Fn cardbus_conf_read "cardbus_chipset_tag_t cc" "int cf" \ 89"pcitag_t tag" "int offs" 90.Ft void 91.Fn cardbus_conf_write "cardbus_chipset_tag_t cc" "int cf" \ 92"pcitag_t tag" "int offs" "busreg_t val" 93.Ft void * 94.Fn cardbus_intr_establish "cardbus_chipset_tag_t cc" \ 95"cardbus_function_tag_t cf" "cardbus_intr_handle_t irq" "int level" \ 96"int (*handler)(void *)" "void *arg" 97.Ft void 98.Fn cardbus_intr_disestablish "cardbus_chipset_tag_t cc" \ 99"cardbus_function_tag_t cf" "void *ih" 100.Ft int 101.Fn CARDBUS_VENDOR "pcireg_t id" 102.Ft int 103.Fn CARDBUS_PRODUCT "pcireg_t id" 104.Ft int 105.Fn Cardbus_function_enable "cardbus_devfunc_t ct" 106.Ft int 107.Fn Cardbus_function_disable "cardbus_devfunc_t ct" 108.Ft int 109.Fn Cardbus_mapreg_map "cardbus_devfunc_t ct" "int reg" \ 110"pcireg_t type" "int busflags" "bus_space_tag_t *tagp" \ 111"bus_space_handle_t *handlep" "bus_addr_t *basep" "bus_size_t *sizep" 112.Ft int 113.Fn Cardbus_mapreg_unmap "cardbus_devfunc_t ct" \ 114"int reg" "bus_space_tag_t tag" "bus_space_handle_t handle" \ 115"bus_size_t size" 116.Ft pcitag_t 117.Fn Cardbus_make_tag "cardbus_devfunc_t ct " 118.Ft pcireg_t 119.Fn Cardbus_conf_read "cardbus_devfunc_t ct" "pcitag_t tag" \ 120"int offs" 121.Ft void 122.Fn Cardbus_conf_write "cardbus_devfunc_t ct" "pcitag_t tag" \ 123"int offs" "busreg_t val" 124.Sh DESCRIPTION 125The machine-independent 126.Nm 127subsystem provides support for CardBus devices. 128.Pp 129The CardBus interface is an improvement to the PC-Card interface 130supported by 131.Xr pcmcia 9 . 132It introduces several new capabilities such as 32-bit addressing, 13333MHz operation, busmaster operation and 3.3 volt low-voltage power. 134It remains compatible with all features of the PC-Card standard. 135.Pp 136The CardBus interface signaling protocol is derived from the PCI 137signaling protocol. 138There are some differences between PCI and CardBus, however operations 139are identical for most functions implemented. 140Since a 32-bit CardBus interface is also defined for 16-bit PC-Cards, 141the same Card Services client to be used to manage both CardBus and 142PCMCIA PC-Cards. 143By interrogating the card upon detection of an insertion event, 144.Nx 145determines whether the card requires 146.Nm 147support or not, and then applies the appropriate power and signaling 148protocol requirements. 149.Sh DATA TYPES 150Drivers attached to the CardBus will make use of the following 151data types: 152.Bl -tag -width compact 153.It struct cardbus_attach_args 154Devices have their identity recorded in this structure. 155It contains the following members: 156.Bd -literal 157 cardbus_devfunc_t ca_ct; 158 bus_space_tag_t ca_iot; /* CardBus I/O space tag */ 159 bus_space_tag_t ca_memt; /* CardBus MEM space tag */ 160 bus_dma_tag_t ca_dmat; /* DMA tag */ 161 u_int ca_device; 162 pcitag_t ca_tag; 163 pcireg_t ca_id; 164 pcireg_t ca_class; 165 cardbus_intr_line_t ca_intrline; /* interrupt info */ 166 struct cardbus_cis_info ca_cis; 167.Ed 168.El 169.Sh FUNCTIONS 170.Bl -tag -width compact 171.It Fn cardbus_attach_card "csc" 172Attaches the card on the slot by turning on the power, read and 173analyse the tuple and sets configuration index. 174This function returns the number of recognised device functions. 175If no device functions are recognised it returns zero. 176.It Fn cardbus_detach_card "csc" 177Detaches the card on the slot by release resources and turning off the 178power. 179This function must not be called under interrupt context. 180.It Fn cardbus_function_enable "csc" "function" 181Enables device function 182.Fa function 183on the card. 184Power will be applied if it hasn't already. 185.It Fn cardbus_function_disable "csc" "function" 186Disables device function 187.Fa function 188on the card. 189When no device functions are enabled, the turn is turned off. 190.It Fn cardbus_mapreg_map "csc" "cf" "reg" "type" "busflags" "tagp" "handlep" "basep" "sizep" 191Maps bus-space on the value of Base Address Register (BAR) indexed by 192.Fa reg 193for device function 194.Fa cf . 195The bus-space configuration is returned in 196.Fa tagp , 197.Fa handlep , 198.Fa basep , 199and 200.Fa sizep . 201.It Fn cardbus_mapreg_unmap "csc" "cf" "reg" "tag" "handle" "bus_size_t size" 202Releases bus-space region for device function 203.Fa cf 204specified by 205.Fa tag , 206.Fa handle 207and 208.Fa size . 209.Fa reg 210is the offset of the BAR register. 211.It Fn cardbus_get_capability "cc" "cf" "tag" "capid" "offsetp" "valuep" 212Find the PCI capability for the device function 213.Fa cf 214specified by 215.Fa capid . 216Returns the capability in 217.Fa offsetp 218and 219.Fa valuep . 220.It Fn cardbus_make_tag "cc" "cf" "bus" "device" "function" 221Make a tag to access config space of a CardBus card. 222It works the same as 223.Fn pci_make_tag . 224.It Fn cardbus_conf_read "cc" "cf" "tag" "offs" 225Read the config space of a CardBus card. 226It works the same as 227.Fn pci_conf_read . 228.It Fn cardbus_conf_write "cc" "cf" "tag" "offs" "val" 229Write to the config space of a CardBus card. 230It works same as 231.Fn pci_conf_write . 232.It Fn cardbus_intr_establish "cc" "cf" "irq" "level" "handler" "arg" 233Establish an interrupt handler for device function 234.Fa cf . 235The priority of the interrupt is specified by 236.Fa level . 237When the interrupt occurs the function 238.Fa handler 239is called with argument 240.Fa arg . 241The return value is a handle for the interrupt handler. 242.Fn cardbus_intr_establish 243returns an opaque handle to an event descriptor if it succeeds, and 244returns NULL on failure. 245.It Fn cardbus_intr_disestablish "cc" "cf" "ih" 246Dis-establish the interrupt handler for device function 247.Fa cf 248with handle 249.Fa ih . 250The handle was returned from 251.Fn cardbus_intr_establish . 252.It Fn CARDBUS_VENDOR "id" 253Return the CardBus vendor ID for device 254.Fa id . 255.It Fn CARDBUS_PRODUCT "id" 256Return the CardBus product ID for device 257.Fa id . 258.El 259.Pp 260The 261.Fn Cardbus_* 262functions are convenience functions taking a 263.Fa cardbus_devfunc_t 264argument and perform the same operation as their namesake described 265above. 266.Sh AUTOCONFIGURATION 267During autoconfiguration, a 268.Nm 269driver will receive a pointer to 270.Fa struct isapnp_attach_args 271describing the device attaches to the CardBus. 272Drivers match the device using the 273.Fa ca_id 274member using 275.Fn CARDBUS_VENDOR 276and 277.Fn CARDBUS_PRODUCT . 278.Pp 279During the driver attach step, drivers should initially map the device 280I/O and memory resources using 281.Fn cardbus_mapreg_map 282or 283.Fn Cardbus_mapreg_map . 284Upon successful allocation of resources, power can be 285applied to the device with 286.Fn cardbus_function_enable 287or 288.Fn Cardbus_function_enable . 289so that device-specific interrogation can be performed. 290Finally, power should be removed from the device using 291.Fn cardbus_function_disable 292or 293.Fn Cardbus_function_disable . 294.Pp 295Since CardBus devices support dynamic configuration, drivers should 296make use of 297.Fn pmf 9 298framework. 299Power can be applied and the interrupt handler should be established 300through this interface. 301.Sh DMA SUPPORT 302No additional support is provided for CardBus DMA beyond the 303facilities provided by the 304.Xr bus_dma 9 305interface. 306.Sh CODE REFERENCES 307The CardBus subsystem itself is implemented within the files 308.Pa sys/dev/cardbus/cardbus.c , 309.Pa sys/dev/cardbus/cardbus_map.c 310and 311.Pa sys/dev/cardbus/cardslot.c . 312The database of known devices exists within the file 313.Pa sys/dev/cardbus/cardbus_data.h 314and is generated automatically from the file 315.Pa sys/dev/cardbus/cardbusdevs . 316New vendor and product identifiers should be added to this file. 317The database can be regenerated using the Makefile 318.Pa sys/dev/cardbus/Makefile.cardbusdevs . 319.Sh SEE ALSO 320.Xr cardbus 4 , 321.Xr pcmcia 4 , 322.Xr autoconf 9 , 323.Xr bus_dma 9 , 324.Xr bus_space 9 , 325.Xr driver 9 , 326.Xr pci 9 , 327.Xr pcmcia 9 328.Sh HISTORY 329The machine-independent 330.Nm 331subsystem appeared in 332.Nx 1.5 . 333