man/man9/cardbus.9

.\"     $NetBSD: cardbus.9,v 1.6 2002/10/14 13:43:17 wiz 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 June 20, 2001
.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
.Fd #include \*[Lt]machine/bus.h\*[Gt]
.Fd #include \*[Lt]dev/cardbus/cardbusvar.h\*[Gt]
.Fd #include \*[Lt]dev/cardbus/cardbusdevs.h\*[Gt]
.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 bus 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 Fo cardbus_mapreg_map
.Fa "csc" "cf" "reg" "type" "busflags"
.Fa "tagp" "handlep" "basep" "sizep"
.Fc
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 bus.
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 utilising 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 .