[src/uebayasi-xip]: src/share/man/man9 Remove references to the deprecated po...

[jruoho <jruoho%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/0d0aa5dfc7ed
branches:  uebayasi-xip
changeset: 751664:0d0aa5dfc7ed
user:      jruoho <jruoho%NetBSD.org@localhost>
date:      Thu Apr 15 08:40:47 2010 +0000

description:
Remove references to the deprecated powerhook_establish(9).

diffstat:

 share/man/man9/cardbus.9 |  339 ++++++++++++++++++++++++
 share/man/man9/intro.9   |  648 +++++++++++++++++++++++++++++++++++++++++++++++
 share/man/man9/pcmcia.9  |  438 +++++++++++++++++++++++++++++++
 3 files changed, 1425 insertions(+), 0 deletions(-)

diffs (truncated from 1437 to 300 lines):

diff -r 0fbfb881bbe5 -r 0d0aa5dfc7ed share/man/man9/cardbus.9
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man9/cardbus.9  Thu Apr 15 08:40:47 2010 +0000
@@ -0,0 +1,339 @@
+.\"     $NetBSD: cardbus.9,v 1.15.2.2 2010/04/15 08:40:47 jruoho 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 April 15, 2010
+.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 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 "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 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