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