357 lines
12 KiB
Groff
357 lines
12 KiB
Groff
.\" $NetBSD: cardbus.9,v 1.11 2004/07/03 17:40:31 mycroft Exp $
|
|
.\"
|
|
.\" Copyright (c) 2001 The NetBSD Foundation, Inc.
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" This code is derived from software contributed to The NetBSD Foundation
|
|
.\" by Gregory McGarry.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\" 3. All advertising materials mentioning features or use of this software
|
|
.\" must display the following acknowledgement:
|
|
.\" This product includes software developed by the NetBSD
|
|
.\" Foundation, Inc. and its contributors.
|
|
.\" 4. Neither the name of The NetBSD Foundation nor the names of its
|
|
.\" contributors may be used to endorse or promote products derived
|
|
.\" from this software without specific prior written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
|
|
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
|
|
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
|
|
.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
|
|
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
|
|
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
|
|
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
|
|
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
|
|
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
|
|
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
|
|
.\" POSSIBILITY OF SUCH DAMAGE.
|
|
.\"
|
|
.Dd July 3, 2004
|
|
.Dt CARDBUS 9
|
|
.Os
|
|
.Sh NAME
|
|
.Nm Cardbus ,
|
|
.Nm cardbus_attach_card ,
|
|
.Nm cardbus_detach_card ,
|
|
.Nm cardbus_function_enable ,
|
|
.Nm cardbus_function_disable ,
|
|
.Nm cardbus_mapreg_map ,
|
|
.Nm cardbus_mapreg_unmap ,
|
|
.Nm cardbus_get_capability ,
|
|
.Nm cardbus_make_tag ,
|
|
.Nm cardbus_free_tag ,
|
|
.Nm cardbus_conf_read ,
|
|
.Nm cardbus_conf_write ,
|
|
.Nm cardbus_intr_establish ,
|
|
.Nm cardbus_intr_disestablish ,
|
|
.Nm CARDBUS_VENDOR ,
|
|
.Nm CARDBUS_PRODUCT ,
|
|
.Nm Cardbus_function_enable ,
|
|
.Nm Cardbus_function_disable ,
|
|
.Nm Cardbus_mapreg_map ,
|
|
.Nm Cardbus_mapreg_unmap ,
|
|
.Nm Cardbus_make_tag ,
|
|
.Nm Cardbus_free_tag ,
|
|
.Nm Cardbus_conf_read ,
|
|
.Nm Cardbus_conf_write
|
|
.Nd support for CardBus PC-Card devices
|
|
.Sh SYNOPSIS
|
|
.In machine/bus.h
|
|
.In dev/cardbus/cardbusvar.h
|
|
.In dev/cardbus/cardbusreg.h
|
|
.In dev/cardbus/cardbusdevs.h
|
|
.Ft int
|
|
.Fn cardbus_attach_card "struct cardbus_softc *csc"
|
|
.Ft void
|
|
.Fn cardbus_detach_card "struct cardbus_softc *csc"
|
|
.Ft int
|
|
.Fn cardbus_function_enable "struct cardbus_softc *csc" "int function"
|
|
.Ft int
|
|
.Fn cardbus_function_disable "struct cardbus_softc *csc" "int function"
|
|
.Ft int
|
|
.Fo cardbus_mapreg_map
|
|
.Fa "struct cardbus_softc *csc" "int cf" "int reg"
|
|
.Fa "cardbusreg_t type" "int busflags" "bus_space_tag_t *tagp"
|
|
.Fa "bus_space_handle_t *handlep" "bus_addr_t *basep" "bus_size_t *sizep"
|
|
.Fc
|
|
.Ft int
|
|
.Fn cardbus_mapreg_unmap "struct cardbus_softc *csc" "int cf" \
|
|
"int reg" "bus_space_tag_t tag" "bus_space_handle_t handle" \
|
|
"bus_size_t size"
|
|
.Ft int
|
|
.Fn cardbus_get_capability "cardbus_chipset_tag_t cc" \
|
|
"cardbus_function_tag_t cf" "cardbustag_t tag" "int capid" \
|
|
"int *offsetp" "cardbusreg_t *valuep"
|
|
.Ft cardbustag_t
|
|
.Fn cardbus_make_tag "cardbus_chipset_tag_t cc" "int cf" "int bus" \
|
|
"int device" "int function"
|
|
.Ft void
|
|
.Fn cardbus_free_tag "cardbus_chipset_tag_t cc" "int cf" \
|
|
"cardbustag_t tag"
|
|
.Ft cardbusreg_t
|
|
.Fn cardbus_conf_read "cardbus_chipset_tag_t cc" "int cf" \
|
|
"cardbustag_t tag" "int offs"
|
|
.Ft void
|
|
.Fn cardbus_conf_write "cardbus_chipset_tag_t cc" "int cf" \
|
|
"cardbustag_t tag" "int offs" "busreg_t val"
|
|
.Ft void *
|
|
.Fn cardbus_intr_establish "cardbus_chipset_tag_t cc" \
|
|
"cardbus_function_tag_t cf" "cardbus_intr_handle_t irq" "int level" \
|
|
"int (*handler)(void *)" "void *arg"
|
|
.Ft void
|
|
.Fn cardbus_intr_disestablish "cardbus_chipset_tag_t cc" \
|
|
"cardbus_function_tag_t cf" "void *ih"
|
|
.Ft int
|
|
.Fn CARDBUS_VENDOR "cardbusreg_t id"
|
|
.Ft int
|
|
.Fn CARDBUS_PRODUCT "cardbusreg_t id"
|
|
.Ft int
|
|
.Fn Cardbus_function_enable "cardbus_devfunc_t ct"
|
|
.Ft int
|
|
.Fn Cardbus_function_disable "cardbus_devfunc_t ct"
|
|
.Ft int
|
|
.Fn Cardbus_mapreg_map "cardbus_devfunc_t ct" "int reg" \
|
|
"cardbusreg_t type" "int busflags" "bus_space_tag_t *tagp" \
|
|
"bus_space_handle_t *handlep" "bus_addr_t *basep" "bus_size_t *sizep"
|
|
.Ft int
|
|
.Fn Cardbus_mapreg_unmap "cardbus_devfunc_t ct" \
|
|
"int reg" "bus_space_tag_t tag" "bus_space_handle_t handle" \
|
|
"bus_size_t size"
|
|
.Ft cardbustag_t
|
|
.Fn Cardbus_make_tag "cardbus_devfunc_t ct "
|
|
.Ft void
|
|
.Fn Cardbus_free_tag "cardbus_devfunc_t ct" "cardbustag_t tag"
|
|
.Ft cardbusreg_t
|
|
.Fn Cardbus_conf_read "cardbus_devfunc_t ct" "cardbustag_t tag" \
|
|
"int offs"
|
|
.Ft void
|
|
.Fn Cardbus_conf_write "cardbus_devfunc_t ct" "cardbustag_t tag" \
|
|
"int offs" "busreg_t val"
|
|
.Sh DESCRIPTION
|
|
The machine-independent
|
|
.Nm
|
|
subsystem provides support for CardBus devices.
|
|
.Pp
|
|
The CardBus interface is an improvement to the PC-Card interface
|
|
supported by
|
|
.Xr pcmcia 9 .
|
|
It introduces several new capabilities such as 32-bit addressing,
|
|
33MHz operation, busmaster operation and 3.3 volt low-voltage power.
|
|
It remains compatible with all features of the PC-Card standard.
|
|
.Pp
|
|
The CardBus interface signaling protocol is derived from the PCI
|
|
signaling protocol.
|
|
There are some differences between PCI and CardBus, however operations
|
|
are identical for most functions implemented.
|
|
Since a 32-bit CardBus interface is also defined for 16-bit PC-Cards,
|
|
the same Card Services client to be used to manage both CardBus and
|
|
PCMCIA PC-Cards.
|
|
By interrogating the card upon detection of an insertion event,
|
|
.Nx
|
|
determines whether the card requires
|
|
.Nm
|
|
support or not, and then applies the appropriate power and signaling
|
|
protocol requirements.
|
|
.Sh DATA TYPES
|
|
Drivers attached to the CardBus will make use of the following
|
|
data types:
|
|
.Bl -tag -width compact
|
|
.It struct cardbus_attach_args
|
|
Devices have their identity recorded in this structure.
|
|
It contains the following members:
|
|
.Bd -literal
|
|
cardbus_devfunc_t ca_ct;
|
|
bus_space_tag_t ca_iot; /* CardBus I/O space tag */
|
|
bus_space_tag_t ca_memt; /* CardBus MEM space tag */
|
|
bus_dma_tag_t ca_dmat; /* DMA tag */
|
|
u_int ca_device;
|
|
cardbustag_t ca_tag;
|
|
cardbusreg_t ca_id;
|
|
cardbusreg_t ca_class;
|
|
cardbus_intr_line_t ca_intrline; /* interrupt info */
|
|
struct cardbus_cis_info ca_cis;
|
|
.Ed
|
|
.El
|
|
.Sh FUNCTIONS
|
|
.Bl -tag -width compact
|
|
.It Fn cardbus_attach_card "csc"
|
|
Attaches the card on the slot by turning on the power, read and
|
|
analyse the tuple and sets configuration index.
|
|
This function returns the number of recognised device functions.
|
|
If no device functions are recognised it returns zero.
|
|
.It Fn cardbus_detach_card "csc"
|
|
Detaches the card on the slot by release resources and turning off the
|
|
power.
|
|
This function must not be called under interrupt context.
|
|
.It Fn cardbus_function_enable "csc" "function"
|
|
Enables device function
|
|
.Fa function
|
|
on the card.
|
|
Power will be applied if it hasn't already.
|
|
.It Fn cardbus_function_disable "csc" "function"
|
|
Disables device function
|
|
.Fa function
|
|
on the card.
|
|
When no device functions are enabled, the turn is turned off.
|
|
.It Fn cardbus_mapreg_map "csc" "cf" "reg" "type" "busflags" "tagp" "handlep" "basep" "sizep"
|
|
Maps bus-space on the value of Base Address Register (BAR) indexed by
|
|
.Fa reg
|
|
for device function
|
|
.Fa cf .
|
|
The bus-space configuration is returned in
|
|
.Fa tagp ,
|
|
.Fa handlep ,
|
|
.Fa basep ,
|
|
and
|
|
.Fa sizep .
|
|
.It Fn cardbus_mapreg_unmap "csc" "cf" "reg" "tag" "handle" "bus_size_t size"
|
|
Releases bus-space region for device function
|
|
.Fa cf
|
|
specified by
|
|
.Fa tag ,
|
|
.Fa handle
|
|
and
|
|
.Fa size .
|
|
.Fa reg
|
|
is the offset of the BAR register.
|
|
.It Fn cardbus_get_capability "cc" "cf" "tag" "capid" "offsetp" "valuep"
|
|
Find the PCI capability for the device function
|
|
.Fa cf
|
|
specified by
|
|
.Fa capid .
|
|
Returns the capability in
|
|
.Fa offsetp
|
|
and
|
|
.Fa valuep .
|
|
.It Fn cardbus_make_tag "cc" "cf" "bus" "device" "function"
|
|
Make a tag to access config space of a CardBus card.
|
|
It works the same as
|
|
.Fn pci_make_tag .
|
|
.It Fn cardbus_free_tag "cc" "cf" "tag"
|
|
Release a tag used to access the config space of a CardBus card.
|
|
It works the same as
|
|
.Fn pci_free_tag .
|
|
.It Fn cardbus_conf_read "cc" "cf" "tag" "offs"
|
|
Read the config space of a CardBus card.
|
|
It works the same as
|
|
.Fn pci_conf_read .
|
|
.It Fn cardbus_conf_write "cc" "cf" "tag" "offs" "val"
|
|
Write to the config space of a CardBus card.
|
|
It works same as
|
|
.Fn pci_conf_write .
|
|
.It Fn cardbus_intr_establish "cc" "cf" "irq" "level" "handler" "arg"
|
|
Establish an interrupt handler for device function
|
|
.Fa cf .
|
|
The priority of the interrupt is specified by
|
|
.Fa level .
|
|
When the interrupt occurs the function
|
|
.Fa handler
|
|
is called with argument
|
|
.Fa arg .
|
|
The return value is a handle for the interrupt handler.
|
|
.Fn cardbus_intr_establish
|
|
returns an opaque handle to an event descriptor if it succeeds, and
|
|
returns NULL on failure.
|
|
.It Fn cardbus_intr_disestablish "cc" "cf" "ih"
|
|
Dis-establish the interrupt handler for device function
|
|
.Fa cf
|
|
with handle
|
|
.Fa ih .
|
|
The handle was returned from
|
|
.Fn cardbus_intr_establish .
|
|
.It Fn CARDBUS_VENDOR "id"
|
|
Return the CardBus vendor ID for device
|
|
.Fa id .
|
|
.It Fn CARDBUS_PRODUCT "id"
|
|
Return the CardBus product ID for device
|
|
.Fa id .
|
|
.El
|
|
.Pp
|
|
The
|
|
.Fn Cardbus_*
|
|
functions are convenience functions taking a
|
|
.Fa cardbus_devfunc_t
|
|
argument and perform the same operation as their namesake described
|
|
above.
|
|
.Sh AUTOCONFIGURATION
|
|
During autoconfiguration, a
|
|
.Nm
|
|
driver will receive a pointer to
|
|
.Fa struct isapnp_attach_args
|
|
describing the device attaches to the CardBus.
|
|
Drivers match the device using the
|
|
.Fa ca_id
|
|
member using
|
|
.Fn CARDBUS_VENDOR
|
|
and
|
|
.Fn CARDBUS_PRODUCT .
|
|
.Pp
|
|
During the driver attach step, drivers should initially map the device
|
|
I/O and memory resources using
|
|
.Fn cardbus_mapreg_map
|
|
or
|
|
.Fn Cardbus_mapreg_map .
|
|
Upon successful allocation of resources, power can be
|
|
applied to the device with
|
|
.Fn cardbus_function_enable
|
|
or
|
|
.Fn Cardbus_function_enable .
|
|
so that device-specific interrogation can be performed.
|
|
Finally, power should be removed from the device using
|
|
.Fn cardbus_function_disable
|
|
or
|
|
.Fn Cardbus_function_disable .
|
|
.Pp
|
|
Since CardBus devices support dynamic configuration, drivers should
|
|
make use of
|
|
.Fn powerhook_establish 9 .
|
|
Power can be applied and the interrupt handler should be established
|
|
through this interface.
|
|
.Sh DMA SUPPORT
|
|
No additional support is provided for CardBus DMA beyond the
|
|
facilities provided by the
|
|
.Xr bus_dma 9
|
|
interface.
|
|
.Sh CODE REFERENCES
|
|
This section describes places within the
|
|
.Nx
|
|
source tree where actual code implementing or using the
|
|
machine-independent CardBus subsystem can be found.
|
|
All pathnames are relative to
|
|
.Pa /usr/src .
|
|
.Pp
|
|
The CardBus subsystem itself is implemented within the files
|
|
.Pa sys/dev/cardbus/cardbus.c ,
|
|
.Pa sys/dev/cardbus/cardbus_map.c
|
|
and
|
|
.Pa sys/dev/cardbus/cardslot.c .
|
|
The database of known devices exists within the file
|
|
.Pa sys/dev/cardbus/cardbus_data.h
|
|
and is generated automatically from the file
|
|
.Pa sys/dev/cardbus/cardbusdevs .
|
|
New vendor and product identifiers should be added to this file.
|
|
The database can be regenerated using the Makefile
|
|
.Pa sys/dev/cardbus/Makefile.cardbusdevs .
|
|
.Sh SEE ALSO
|
|
.Xr cardbus 4 ,
|
|
.Xr pcmcia 4 ,
|
|
.Xr autoconf 9 ,
|
|
.Xr bus_dma 9 ,
|
|
.Xr bus_space 9 ,
|
|
.Xr driver 9 ,
|
|
.Xr pci 9 ,
|
|
.Xr pcmcia 9
|
|
.Sh HISTORY
|
|
The machine-independent
|
|
.Nm
|
|
subsystem appeared in
|
|
.Nx 1.5 .
|