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