diff options
Diffstat (limited to 'static/netbsd/man9/cardbus.9')
| -rw-r--r-- | static/netbsd/man9/cardbus.9 | 328 |
1 files changed, 328 insertions, 0 deletions
diff --git a/static/netbsd/man9/cardbus.9 b/static/netbsd/man9/cardbus.9 new file mode 100644 index 00000000..bda79d1f --- /dev/null +++ b/static/netbsd/man9/cardbus.9 @@ -0,0 +1,328 @@ +.\" $NetBSD: cardbus.9,v 1.20 2016/02/15 22:37:54 riastradh 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. +.\" +.\" 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 13, 2014 +.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_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_conf_read , +.Nm Cardbus_conf_write +.Nd support for CardBus PC-Card devices +.Sh SYNOPSIS +.In sys/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 "pcireg_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" "pcitag_t tag" "int capid" \ +"int *offsetp" "pcireg_t *valuep" +.Ft pcitag_t +.Fn cardbus_make_tag "cardbus_chipset_tag_t cc" "int cf" "int bus" \ +"int device" "int function" +.Ft pcireg_t +.Fn cardbus_conf_read "cardbus_chipset_tag_t cc" "int cf" \ +"pcitag_t tag" "int offs" +.Ft void +.Fn cardbus_conf_write "cardbus_chipset_tag_t cc" "int cf" \ +"pcitag_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 "pcireg_t id" +.Ft int +.Fn CARDBUS_PRODUCT "pcireg_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" \ +"pcireg_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 pcitag_t +.Fn Cardbus_make_tag "cardbus_devfunc_t ct" +.Ft pcireg_t +.Fn Cardbus_conf_read "cardbus_devfunc_t ct" "pcitag_t tag" \ +"int offs" +.Ft void +.Fn Cardbus_conf_write "cardbus_devfunc_t ct" "pcitag_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; + pcitag_t ca_tag; + pcireg_t ca_id; + pcireg_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_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 cardbus_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 pmf 9 +framework. +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 +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 for PCI devices is also used for known CardBus devices. +For more details see +.Xr pci 9 . +.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 . |