.\" jpman %Id: pccard.conf.5,v 1.3 1998/07/10 15:23:53 jsakai Stab %
.\"
.\" Copyright (c) 1994 Andrew McRae.  All rights reserved.
.\"
.\" 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. The name of the author may not be used to endorse or promote products
.\"    derived from this software without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``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 AUTHOR 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 November 2, 1994
.Dt PCCARD.CONF 5
.Os FreeBSD
.Sh NAME
.Nm pccard.conf
.Nd
.Xr pccardd 8
configuration file
.Sh DESCRIPTION
The
.Nm pccard.conf
file is the configuration file for the
.Xr pccardd 8
PC-CARD slot management daemon.
It provides information to allow card identification, and the matching of
drivers (along with driver resources) to the PC-CARD cards.
.Pp
There are four basic elements within the configuration file;
An optional
.Em "resource pool"
preceding the other sections, and one or more
.Em "card identifiers" ,
and
.Em "device instances" .
The latter two may appear in any order, and may be interspersed as desired.
.Pp
Each PC-CARD card contains configuration tuples
that provide the manufacturer and card version;
these are used to identify the card specification in the configuration file,
and from this find a driver that can be used to interface to the particular card.
There is a many-to-one mapping between cards to drivers
i.e a single driver may interface to multiple
types of cards. To aid this, card parameters may be specified separately
from the driver to initialize the card or extract (in the case of a network card)
an Ethernet address.
.Pp
Once a driver is allocated to a card, it stays allocated to that particular card.
However, multiple instances of the same type of driver can be configured,
so that if two cards are plugged in that map to a similar type of driver,
other driver instances of the same name can be configured.
.Pp
The
.Em insert
and 
.Em remove
commands allow a shell command line to be executed.
The command to be executed is the rest of the line after the keyword.
The line can be continued using a backslash.
A simple macro substitution allows the current kernel device name
.Em ( $device )
and network card Ethernet address
.Em ( $ether )
to be inserted into the command line.
.Xr pccardd 8
uses the
.Xr system 3
subroutine to execute the command line.
.Pp
Numeric values may be expressed as octal, hex or decimal.  If a decimal
number has
.Em k
or
.Em K
appended to it, the value is multiplied by 1024.
Names may be quoted using double quotes if spaces are required.
A hash character(#) comments out the rest of the line.

.Ss "Resource pool"
The (optional) section specifies a pool of system resources
such as ISA bus memory address space, Input/Output ports and interrupt request numbers.
This resource pool is used to allocate address space and interrupt
numbers dynamically according to the requirements specified in each driver description.
.Pp
The syntax of the resources is as follows:
.Pp
.Dl io Ar start - end ...
.Dl memory Ar address size ...
.Dl irq Ar irq-number ...
.Dl ignirq Ar irq-number ...
.Pp
Each of the statements define I/O, memory or IRQ blocks that can be used
to allocate to drivers when they are initialized.
.Pp
Multiple lines of any of the above statements may be present to allow
separate blocks of each resource to be defined.
.Pp
"irq" is an option which should not be used.
It is available if
.Fl I
is passed to
.Xr pccardd 8 ,
but use of this option is DISCOURAGED.
This allows
.Xr pccardd 8
to use
.Ar irq-number
as an available IRQs pool for PC-CARD card interface.
.Pp
"ignirq" prohibits
.Xr pccardd 8
to use
.Ar irq-number .
This corresponds to 
.Fl i Ar IRQ
of
.Xr pccardd 8 .
.Ss "Card Identifiers"
The syntax for card identifiers is:
.Pp
.Dl card Ar manufacturer version [ add_info1 [ add_info2 ]]
.Dl config Ar index driver interrupt [ flags ]
.Dl ether Ar offset [ macaddr ... ]
.Dl reset Ar time
.Dl cardio Ar iobase iosize
.Dl cardmem Ar memaddr cardaddr memsize [ memflags ]
.Dl insert Ar command
.Dl remove Ar command
.Pp
The first line is mandatory;
the latter statements are optional and can appear in
any order. 
There may be multiple
.Em config
lines.
The
.Em card
parameters are the Manufacturer name
.Ar manufacturer ,
card version
.Ar version 
and additional information
.Ar add_info1, add_info2
that are used to match the values from the card's CIS memory.
These parameter can be described in extended regular expression
.Xr regex 3 .
Each of the expressions is evaluated with a character '^' at top.
.Pp
The
.Em config
parameters select the particular card's configuration index
from the range available in the card's CIS, the driver that
is to be associated with this configuration, and the interrupt
level (if any) to be assigned. An optional set of flags may
be assigned.
In 
.Ar index ,
specify either ``auto'' or ``default'' or the range available in the card's CIS.
``auto'' allows to allocate resources automatically with information
from the CIS and status of using I/O resources.
In
.Ar interrupt ,
specify either ``any'' or ``pio'' or a irq number (decimal from 1 to 15).
.Pp
The optional
.Em ether
keyword is used when network cards have their physical Ethernet address
located within the attribute memory of the card. The parameter of this
statement indicates the offset within the attribute memory of the
Ethernet address and the three bytes of vender code.
If the physical address doesn't match any of
.Ar macaddr ,
the allocation aborts.
Each of 
.Ar macaddr
can accompany an
.Ar offset .
If
.Ar macaddr
with no
.Ar offset
appears,
the previous
.Ar offset
used as the offset address.
Special parameters ``attr2hex'' and ``wavelan'' are also available.
This Ethernet address can be used within insert/remove
commands using the
.Em $ether
macro.
.Pp
The optional
.Em reset
keyword specifies reset duration at a card insertion in 
.Ar time
(milli-second). Default is 100 msec.
.Pp
.Em cardio
and
.Em cardmem
keywords are used with cards whose resources such as I/O ports
and shared memory block, are not specified in the CIS tuple.
A base address and size of I/O ports are specified in
.Ar iobase
and
.Ar iosize ,
ones of shared memory block are specified in
.Ar cardaddr ,
.Ar memsize
and
.Ar memaddr .
An address of a card is
.Ar cardaddr ,
one of host is
.Ar memaddr .
Optional flags can be specified in
.Ar memflags .
.Pp
The
.Em insert
and
.Em remove
sections allow shell commands to be specified that are executed
when the card is inserted or removed. Multiple
.Em insert
and
.Em remove
commands are allowed, and they are executed in the order they
are listed.
.Ss "Wildcard entries"
Following two wildcard entries of card identifiers are available:
.Pp
.Dl function serial
.Dl function fixed_disk
.Pp
The keyword
.Em serial
matches ``Functional ID: Serial port/modem'' and
.Em fixed_disk
matches ``Fixed disk card''.
The syntax is the same of 
.Em "card identifiers"
but used ``function'' instead of ``card'' in the first line.
These are in the last of
.Nm
because unmatched cards with the other
.Em card
entries can match these entries secondly.
.Pp
.Sh EXAMPLE
A typical configuration file may appear thus:
.Bd -literal
#
# Sample configuration file.
#
# Pool parameters.
#
# Generally available IO ports
io      0x240-0x2e0 0x300-0x360
# Generally available IRQs (DEPRECATED, USE OF THE OPTION IS DISCOURAGED)
#irq    10 11
# Unavailable IRQs
#ignirq 9
# refrain from using SoundBlaster's IRQ, by default.
ignirq 5
# it may be helpful for most of notebook PCs
#ignirq 15
# Available memory slots
memory  0xd4000 96k
#
# Card database.
#
# PLANEX (PLANET) FNW-3600-T
card "Fast Ethernet" "Adapter"
        config  0x1 "ed0" any
        insert  echo PLANEX FNW-3600-T inserted
        insert  /etc/pccard_ether $device
        remove  echo PLANEX FNW-3600-T removed
        remove  /etc/pccard_ether_remove $device

# GENERIC PCMCIA modem
function serial
        config  0x23 "sio2" any
#       config  0x23 "sio2" pio         # alternative definitions
#       config  0x21 "sio2" any         # .........
#       config  0x22 "sio2" any
#       config  0x21 "sio2" pio
#       config  0x22 "sio2" pio
#       config  0x23 "sio2" 5
#       config  0x21 "sio2" 5
#       config  0x22 "sio2" 5
#       reset   100                     # default
        reset   1000                    # safety reset time
#       reset   10000                   # for unstable cards
        insert  echo PCMCIA Modem inserted
        remove  echo PCMCIA Modem removed
.Ed
.Sh FILES
.Bl -tag -width /etc/pccard.conf -compact
.It Pa /etc/pccard.conf
.Xr pccardd 8
configuration file.
.El
.Sh SEE ALSO
.Xr pccardc 8 ,
.Xr pccardd 8