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