share/man/man9/cardbus.9

   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 .\"
  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
 132 The machine-independent
 133 .Nm
 134 subsystem provides support for CardBus devices.
 135 .Pp
 136 The CardBus interface is an improvement to the PC-Card interface
 137 supported by
 138 .Xr pcmcia 9 .
 139 It introduces several new capabilities such as 32-bit addressing,
 140 33MHz operation, busmaster operation and 3.3 volt low-voltage power.
 141 It remains compatible with all features of the PC-Card standard.
 142 .Pp
 143 The CardBus interface signaling protocol is derived from the PCI
 144 signaling protocol.
 145 There are some differences between PCI and CardBus, however operations
 146 are identical for most functions implemented.
 147 Since a 32-bit CardBus interface is also defined for 16-bit PC-Cards,
 148 the same Card Services client to be used to manage both CardBus and
 149 PCMCIA PC-Cards.
 150 By interrogating the card upon detection of an insertion event,
 151 .Nx
 152 determines whether the card requires
 153 .Nm
 154 support or not, and then applies the appropriate power and signaling
 155 protocol requirements.
 156 .Sh DATA TYPES
 157 Drivers attached to the CardBus will make use of the following
 158 data types:
 159 .Bl -tag -width compact
 160 .It struct cardbus_attach_args
 161 Devices have their identity recorded in this structure.
 162 It 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"
 179 Attaches the card on the slot by turning on the power, read and
 180 analyse the tuple and sets configuration index.
 181 This function returns the number of recognised device functions.
 182 If no device functions are recognised it returns zero.
 183 .It Fn cardbus_detach_card "csc"
 184 Detaches the card on the slot by release resources and turning off the
 185 power.
 186 This function must not be called under interrupt context.
 187 .It Fn cardbus_function_enable "csc" "function"
 188 Enables device function
 189 .Fa function
 190 on the card.
 191 Power will be applied if it hasn't already.
 192 .It Fn cardbus_function_disable "csc" "function"
 193 Disables device function
 194 .Fa function
 195 on the card.
 196 When 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"
 198 Maps bus-space on the value of Base Address Register (BAR) indexed by
 199 .Fa reg
 200 for device function
 201 .Fa cf .
 202 The bus-space configuration is returned in
 203 .Fa tagp ,
 204 .Fa handlep ,
 205 .Fa basep ,
 206 and
 207 .Fa sizep .
 208 .It Fn cardbus_mapreg_unmap "csc" "cf" "reg" "tag" "handle" "bus_size_t size"
 209 Releases bus-space region for device function
 210 .Fa cf
 211 specified by
 212 .Fa tag ,
 213 .Fa handle
 214 and
 215 .Fa size .
 216 .Fa reg
 217 is the offset of the BAR register.
 218 .It Fn cardbus_get_capability "cc" "cf" "tag" "capid" "offsetp" "valuep"
 219 Find the PCI capability for the device function
 220 .Fa cf
 221 specified by
 222 .Fa capid .
 223 Returns the capability in
 224 .Fa offsetp
 225 and
 226 .Fa valuep .
 227 .It Fn cardbus_make_tag "cc" "cf" "bus" "device" "function"
 228 Make a tag to access config space of a CardBus card.
 229 It works the same as
 230 .Fn pci_make_tag .
 231 .It Fn cardbus_free_tag "cc" "cf" "tag"
 232 Release a tag used to access the config space of a CardBus card.
 233 It works the same as
 234 .Fn pci_free_tag .
 235 .It Fn cardbus_conf_read "cc" "cf" "tag" "offs"
 236 Read the config space of a CardBus card.
 237 It works the same as
 238 .Fn pci_conf_read .
 239 .It Fn cardbus_conf_write "cc" "cf" "tag" "offs" "val"
 240 Write to the config space of a CardBus card.
 241 It works same as
 242 .Fn pci_conf_write .
 243 .It Fn cardbus_intr_establish "cc" "cf" "irq" "level" "handler" "arg"
 244 Establish an interrupt handler for device function
 245 .Fa cf .
 246 The priority of the interrupt is specified by
 247 .Fa level .
 248 When the interrupt occurs the function
 249 .Fa handler
 250 is called with argument
 251 .Fa arg .
 252 The return value is a handle for the interrupt handler.
 253 .Fn cardbus_intr_establish
 254 returns an opaque handle to an event descriptor if it succeeds, and
 255 returns NULL on failure.
 256 .It Fn cardbus_intr_disestablish "cc" "cf" "ih"
 257 Dis-establish the interrupt handler for device function
 258 .Fa cf
 259 with handle
 260 .Fa ih .
 261 The handle was returned from
 262 .Fn cardbus_intr_establish .
 263 .It Fn CARDBUS_VENDOR "id"
 264 Return the CardBus vendor ID for device
 265 .Fa id .
 266 .It Fn CARDBUS_PRODUCT "id"
 267 Return the CardBus product ID for device
 268 .Fa id .
 269 .El
 270 .Pp
 271 The
 272 .Fn Cardbus_*
 273 functions are convenience functions taking a
 274 .Fa cardbus_devfunc_t
 275 argument and perform the same operation as their namesake described
 276 above.
 277 .Sh AUTOCONFIGURATION
 278 During autoconfiguration, a
 279 .Nm
 280 driver will receive a pointer to
 281 .Fa struct isapnp_attach_args
 282 describing the device attaches to the CardBus.
 283 Drivers match the device using the
 284 .Fa ca_id
 285 member using
 286 .Fn CARDBUS_VENDOR
 287 and
 288 .Fn CARDBUS_PRODUCT .
 289 .Pp
 290 During the driver attach step, drivers should initially map the device
 291 I/O and memory resources using
 292 .Fn cardbus_mapreg_map
 293 or
 294 .Fn Cardbus_mapreg_map .
 295 Upon successful allocation of resources, power can be
 296 applied to the device with
 297 .Fn cardbus_function_enable
 298 or
 299 .Fn Cardbus_function_enable .
 300 so that device-specific interrogation can be performed.
 301 Finally, power should be removed from the device using
 302 .Fn cardbus_function_disable
 303 or
 304 .Fn Cardbus_function_disable .
 305 .Pp
 306 Since CardBus devices support dynamic configuration, drivers should
 307 make use of
 308 .Fn powerhook_establish 9 .
 309 Power can be applied and the interrupt handler should be established
 310 through this interface.
 311 .Sh DMA SUPPORT
 312 No additional support is provided for CardBus DMA beyond the
 313 facilities provided by the
 314 .Xr bus_dma 9
 315 interface.
 316 .Sh CODE REFERENCES
 317 This section describes places within the
 318 .Nx
 319 source tree where actual code implementing or using the
 320 machine-independent CardBus subsystem can be found.
 321 All pathnames are relative to
 322 .Pa /usr/src .
 323 .Pp
 324 The CardBus subsystem itself is implemented within the files
 325 .Pa sys/dev/cardbus/cardbus.c ,
 326 .Pa sys/dev/cardbus/cardbus_map.c
 327 and
 328 .Pa sys/dev/cardbus/cardslot.c .
 329 The database of known devices exists within the file
 330 .Pa sys/dev/cardbus/cardbus_data.h
 331 and is generated automatically from the file
 332 .Pa sys/dev/cardbus/cardbusdevs .
 333 New vendor and product identifiers should be added to this file.
 334 The 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
 346 The machine-independent
 347 .Nm
 348 subsystem appeared in
 349 .Nx 1.5 .