1.\" $NetBSD: cardbus.9,v 1.11 2004/07/03 17:40:31 mycroft 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 July 3, 2004 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 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 Fn cardbus_mapreg_map "csc" "cf" "reg" "type" "busflags" "tagp" "handlep" "basep" "sizep" 205Maps bus-space on the value of Base Address Register (BAR) indexed by 206.Fa reg 207for device function 208.Fa cf . 209The bus-space configuration is returned in 210.Fa tagp , 211.Fa handlep , 212.Fa basep , 213and 214.Fa sizep . 215.It Fn cardbus_mapreg_unmap "csc" "cf" "reg" "tag" "handle" "bus_size_t size" 216Releases bus-space region for device function 217.Fa cf 218specified by 219.Fa tag , 220.Fa handle 221and 222.Fa size . 223.Fa reg 224is the offset of the BAR register. 225.It Fn cardbus_get_capability "cc" "cf" "tag" "capid" "offsetp" "valuep" 226Find the PCI capability for the device function 227.Fa cf 228specified by 229.Fa capid . 230Returns the capability in 231.Fa offsetp 232and 233.Fa valuep . 234.It Fn cardbus_make_tag "cc" "cf" "bus" "device" "function" 235Make a tag to access config space of a CardBus card. 236It works the same as 237.Fn pci_make_tag . 238.It Fn cardbus_free_tag "cc" "cf" "tag" 239Release a tag used to access the config space of a CardBus card. 240It works the same as 241.Fn pci_free_tag . 242.It Fn cardbus_conf_read "cc" "cf" "tag" "offs" 243Read the config space of a CardBus card. 244It works the same as 245.Fn pci_conf_read . 246.It Fn cardbus_conf_write "cc" "cf" "tag" "offs" "val" 247Write to the config space of a CardBus card. 248It works same as 249.Fn pci_conf_write . 250.It Fn cardbus_intr_establish "cc" "cf" "irq" "level" "handler" "arg" 251Establish an interrupt handler for device function 252.Fa cf . 253The priority of the interrupt is specified by 254.Fa level . 255When the interrupt occurs the function 256.Fa handler 257is called with argument 258.Fa arg . 259The return value is a handle for the interrupt handler. 260.Fn cardbus_intr_establish 261returns an opaque handle to an event descriptor if it succeeds, and 262returns NULL on failure. 263.It Fn cardbus_intr_disestablish "cc" "cf" "ih" 264Dis-establish the interrupt handler for device function 265.Fa cf 266with handle 267.Fa ih . 268The handle was returned from 269.Fn cardbus_intr_establish . 270.It Fn CARDBUS_VENDOR "id" 271Return the CardBus vendor ID for device 272.Fa id . 273.It Fn CARDBUS_PRODUCT "id" 274Return the CardBus product ID for device 275.Fa id . 276.El 277.Pp 278The 279.Fn Cardbus_* 280functions are convenience functions taking a 281.Fa cardbus_devfunc_t 282argument and perform the same operation as their namesake described 283above. 284.Sh AUTOCONFIGURATION 285During autoconfiguration, a 286.Nm 287driver will receive a pointer to 288.Fa struct isapnp_attach_args 289describing the device attaches to the CardBus. 290Drivers match the device using the 291.Fa ca_id 292member using 293.Fn CARDBUS_VENDOR 294and 295.Fn CARDBUS_PRODUCT . 296.Pp 297During the driver attach step, drivers should initially map the device 298I/O and memory resources using 299.Fn cardbus_mapreg_map 300or 301.Fn Cardbus_mapreg_map . 302Upon successful allocation of resources, power can be 303applied to the device with 304.Fn cardbus_function_enable 305or 306.Fn Cardbus_function_enable . 307so that device-specific interrogation can be performed. 308Finally, power should be removed from the device using 309.Fn cardbus_function_disable 310or 311.Fn Cardbus_function_disable . 312.Pp 313Since CardBus devices support dynamic configuration, drivers should 314make use of 315.Fn powerhook_establish 9 . 316Power can be applied and the interrupt handler should be established 317through this interface. 318.Sh DMA SUPPORT 319No additional support is provided for CardBus DMA beyond the 320facilities provided by the 321.Xr bus_dma 9 322interface. 323.Sh CODE REFERENCES 324This section describes places within the 325.Nx 326source tree where actual code implementing or using the 327machine-independent CardBus subsystem can be found. 328All pathnames are relative to 329.Pa /usr/src . 330.Pp 331The CardBus subsystem itself is implemented within the files 332.Pa sys/dev/cardbus/cardbus.c , 333.Pa sys/dev/cardbus/cardbus_map.c 334and 335.Pa sys/dev/cardbus/cardslot.c . 336The database of known devices exists within the file 337.Pa sys/dev/cardbus/cardbus_data.h 338and is generated automatically from the file 339.Pa sys/dev/cardbus/cardbusdevs . 340New vendor and product identifiers should be added to this file. 341The database can be regenerated using the Makefile 342.Pa sys/dev/cardbus/Makefile.cardbusdevs . 343.Sh SEE ALSO 344.Xr cardbus 4 , 345.Xr pcmcia 4 , 346.Xr autoconf 9 , 347.Xr bus_dma 9 , 348.Xr bus_space 9 , 349.Xr driver 9 , 350.Xr pci 9 , 351.Xr pcmcia 9 352.Sh HISTORY 353The machine-independent 354.Nm 355subsystem appeared in 356.Nx 1.5 . 357