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