usr.sbin/pccard/pccardd/pccard.conf.5

   1 .\"
   2 .\" Copyright (c) 1994 Andrew McRae.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. The name of the author may not be used to endorse or promote products
  13 .\"    derived from this software without specific prior written permission.
  14 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  16 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  17 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  18 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  19 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  20 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  21 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  22 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  23 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  24 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  25 .\"
  26 .\" $FreeBSD: src/usr.sbin/pccard/pccardd/pccard.conf.5,v 1.12.2.10 2002/04/07 04:57:14 dd Exp $
  27 .\"
  28 .Dd November 2, 1994
  29 .Dt PCCARD.CONF 5
  30 .Os
  31 .Sh NAME
  32 .Nm pccard.conf
  33 .Nd
  34 .Xr pccardd 8
  35 configuration file
  36 .Sh DESCRIPTION
  37 The
  38 .Nm
  39 file is the configuration file for the
  40 .Xr pccardd 8
  41 PC-CARD slot management daemon.
  42 It provides information to allow card
  43 identification, and the matching of drivers (along
  44 with driver resources) to the PC-CARD cards.
  45 .Pp
  46 There are four basic elements within the configuration file;
  47 An optional
  48 .Em "resource pool"
  49 preceding the other sections,
  50 and one or more
  51 .Em "card identifiers" ,
  52 and
  53 .Em "device instances" .
  54 The latter two may appear in any order, and may be
  55 interspersed as desired.
  56 .Pp
  57 The
  58 .Pa /etc/pccard.conf
  59 file is included from the file
  60 .Pa /etc/defaults/pccard.conf ,
  61 which contains the default resource pool settings and
  62 pccard identifiers database.
  63 The user specific configuration can be specified in
  64 .Pa /etc/pccard.conf
  65 when the user wishes to override these defaults and/or
  66 add additional entries.
  67 .Pp
  68 Each PC-CARD card contains configuration tuples that provide
  69 the manufacturer and card version; these are used
  70 to identify the card specification in the configuration
  71 file, and from this find a driver that can be used to
  72 interface to the particular card.
  73 There is a many-to-one mapping
  74 between cards to drivers i.e a single driver may interface to
  75 multiple types of cards.
  76 To aid this, card parameters may be
  77 specified separately from the driver to initialize the card or
  78 extract (in the case of a network card) an Ethernet address.
  79 .Pp
  80 Once a driver is allocated to a card, it stays
  81 allocated to that particular card.
  82 However, multiple instances of the same type of driver can be
  83 configured, so that if two cards are plugged in that map to a
  84 similar type of driver, other driver instances of the same name
  85 can be configured.
  86 .Pp
  87 The
  88 .Em insert
  89 and
  90 .Em remove
  91 commands allow a shell command line to be executed.
  92 The command to be executed is the rest of the line after
  93 the keyword.
  94 The line can be continued using a backslash.
  95 A simple
  96 macro substitution allows the current kernel device name
  97 .Em ( $device )
  98 and
  99 network card Ethernet address
 100 .Em ( $ether )
 101 to be inserted into the command line.
 102 .Xr pccardd 8
 103 uses the
 104 .Xr system 3
 105 subroutine to execute the command line.
 106 .Pp
 107 .Xr pccardd 8
 108 will use syslog to announce the insertion and removal of cards.
 109 It uses either the string set by the
 110 .Em logstr
 111 command, or the manufacturer and card version strings if none has
 112 been set.
 113 .Pp
 114 Numeric values may be expressed as octal, hex or decimal.
 115 If a decimal number has
 116 .Em k
 117 or
 118 .Em K
 119 appended to it, the value is multiplied by 1024. Names may be
 120 quoted using double quotes if spaces are required.
 121 A hash character comments out the rest of the line.
 122 .Ss "Resource pool"
 123 The (optional) section specifies a pool of system resources
 124 such as ISA bus memory address space, Input/Output ports and
 125 interrupt request numbers.
 126 This resource pool is used
 127 to allocate address space and interrupt numbers dynamically
 128 according to the requirements specified in each driver
 129 description.
 130 .Pp
 131 The syntax of the resources is as follows:
 132 .Pp
 133 .Dl io Ar start - end ...
 134 .Dl memory Ar address size ...
 135 .Dl irq Ar irq-number ...
 136 .Pp
 137 Each of the statements define I/O, memory or IRQ
 138 blocks that can be used to allocate to drivers when
 139 they are initialized.
 140 .Pp
 141 The syntax of the debuglevel parameter:
 142 .Pp
 143 .Dl debuglevel Ar level
 144 .Pp
 145 Multiple lines of any of the above statements may be
 146 present to allow separate blocks of each resource to be
 147 defined.
 148 .Ss "Card Identifiers"
 149 The syntax for card identifiers is:
 150 .Pp
 151 .Dl card Ar manufacturer version [ add_info1 [ add_info2 ]]
 152 .Dl config Ar index driver interrupt [ flags ]
 153 .Dl ether Ar offset
 154 .Dl reset Ar time
 155 .Dl iosize Ar size
 156 .Dl memsize Ar size
 157 .Dl insert Ar command
 158 .Dl remove Ar command
 159 .Dl logstr Ar string
 160 .Pp
 161 The first line is mandatory;
 162 the latter statements are optional and can appear in
 163 any order.
 164 There may be multiple
 165 .Em config
 166 lines.
 167 The
 168 .Em card
 169 parameters are the Manufacturer name, card version and
 170 additional information add_info1, add_info2 that
 171 is used to match the values from the card's CIS memory.
 172 These parameter can be described in extended regular expression
 173 .Xr regex 3
 174 if the string is enclosed by '/' like "/.*/".
 175 Each of the expressions is evaluated with a character '^' at top.
 176 .Pp
 177 The
 178 .Em config
 179 parameters select the particular card's configuration index
 180 from the range available in the card's CIS, the driver that
 181 is to be associated with this configuration, and the interrupt
 182 level (if any) to be assigned.
 183 An optional set of flags may
 184 be assigned.
 185 In
 186 .Ar index ,
 187 specify either ``auto'' or ``default'' or the range available in the card's CIS.
 188 ``auto'' allows to allocate resources automatically with information
 189 from the CIS and status of using I/O resources.
 190 .Pp
 191 The optional
 192 .Em ether
 193 keyword is used when network cards have their physical Ethernet address
 194 located within the attribute memory of the card.
 195 The parameter of this
 196 statement indicates the offset within the attribute memory of the
 197 Ethernet address.
 198 This value can be used within insert/remove
 199 commands using the
 200 .Em $ether
 201 macro.
 202 .Pp
 203 The optional
 204 .Em reset
 205 keyword specifies reset duration at a card insertion in
 206 .Ar time
 207 milliseconds.
 208 Default is 100msec.
 209 .Pp
 210 .Em iosize
 211 and
 212 .Em memsize
 213 keywords are used with cards whose resources such as I/O ports and
 214 shared memory block are not specified in the CIS tuple.
 215 .Pp
 216 The
 217 .Em insert
 218 and
 219 .Em remove
 220 sections allow shell commands to be specified that are executed
 221 when the card is inserted or removed.
 222 Multiple
 223 .Em insert
 224 and
 225 .Em remove
 226 commands are allowed, and they are executed in the order they
 227 are listed.
 228 .Pp
 229 The
 230 .Em logstr
 231 command allows the user to set the string to be logged when this card is
 232 inserted or removed.
 233 If
 234 .Em logstr
 235 isn't specified, then the manufacturer and
 236 card version strings from the CIS are used to synthesize the string issued.
 237 .Ss "Wildcard entries"
 238 Following two wildcard entries of card identifiers are available
 239 for generic type of the cards:
 240 .Pp
 241 .Dl generic serial
 242 .Dl generic fixed_disk
 243 .Pp
 244 The keyword
 245 .Em serial
 246 matches ``Functional ID: Serial port/modem'' and
 247 .Em fixed_disk
 248 matches ``Fixed disk card''.
 249 The syntax is the same of
 250 .Em "card identifiers"
 251 but used ``generic'' instead of ``card'' in the first line.
 252 These are in the last of
 253 .Nm
 254 because unmatched cards with the other
 255 .Em card
 256 entries can match these entries secondly.
 257 The alias ``function'' can be used instead of ``generic'' because of
 258 the historical reason.
 259 .Sh EXAMPLES
 260 A typical configuration file may appear thus:
 261 .Bd -literal
 262 #
 263 # Sample configuration file.
 264 #
 265 # Pool parameters.
 266 #
 267 io 0x280 - 0x2F0 0x300 - 0x360
 268 irq 5 6 8 9 10 15
 269 memory 0xd4000 96k
 270 memory 0xc4000 32k
 271 #
 272 # Card database.
 273 #
 274 card "RPTI LTD." "EP400"  # NE2000 clone
 275        ether 0x110
 276        config 0x21 "ed0" 5
 277        insert ifconfig $device physical $ether
 278        insert ifconfig $device bean
 279        remove ifconfig $device down
 280
 281 card "XYZZY" "FAX/1.0"
 282        config 0x30 "sio1" 11
 283        insert echo start getty
 284        remove echo stop getty
 285
 286 .Ed
 287 .Sh FILES
 288 .Bl -tag -width /etc/defaults/pccard.conf -compact
 289 .It Pa /etc/defaults/pccard.conf
 290 The
 291 .Xr pccardd 8
 292 default configuration file.
 293 .It Pa /etc/pccard.conf
 294 The
 295 user configuration file.
 296 .El
 297 .Sh SEE ALSO
 298 .Xr pccardd 8