Penguin
Recent Changes
Blame: isapnp.conf(5)
EditPageHistoryDiffInfoLikePages
Annotated edit history of isapnp.conf(5) version 1, including all changes. View license author blame.
Rev Author # Line
1 perry 1 ISAPNP.CONF
2 !!!ISAPNP.CONF
3 NAME
4 SYNOPSIS
5 DESCRIPTION
6 FILE FORMAT
7 SECTIONS
8 INITIALISATION
9 CONFIGURATION
10 TIDY UP
11 LIST OF KEYWORDS
12 KEYWORDS
13 BUGS
14 AUTHOR
15 AVAILABILITY
16 REFERENCES
17 SEE ALSO
18 ----
19 !!NAME
20
21
22 isapnp.conf - File format used by isapnp.
23 !!SYNOPSIS
24
25
26 __/etc/isapnp.conf__
27 !!DESCRIPTION
28
29
30 The __isapnp.conf__ file is a configuration file for
31 __isapnp__.
32
33
34 __isapnp.conf__ provides instructions for isapnp. This
35 includes how to identify the cards present, and
36 configuration information for each one.
37 !!FILE FORMAT
38
39
40 The file consists of comments and instructions.
41 Comments start with a ''#'' character, and continue to
42 the end of the line.
43 Instructions consist of keywords and parameters, enclosed in
44 pairs of parentheses, with nesting as appropriate to show
45 context. For example:
46
47
48 (ISOLATE) (VERBOSITY 2) (CONFLICT (__IO__ FATAL))
49 (CONFIGURE DFX0000/1493 (LD 0 (IO 0 (BASE 0x3e8)) (ACT
50 Y)))
51
52
53 Instructions can be spread across many lines, and include
54 comments if required.
55 !!SECTIONS
56
57
58 The file conceptually has three sections:
59
60
61 Initialisation
62
63
64 Which is the set of keywords associated with identifying the
65 Plug-and-Play cards. These usually come at the beginning of
66 the configuration file.
67
68
69 Configuration
70
71
72 Which is the set of keywords used to select a card and write
73 values to its configuration registers.
74
75
76 Tidy up
77
78
79 Which is the set of keywords used to finish the Plug and
80 Play configuration process.
81
82
83 There are also some keywords for debugging
84 purposes.
85 !!INITIALISATION
86
87
88 There are two ways to initialise the configuration
89 mechanism, corresponding to using __pnpdump__ with and
90 without the two optional parameters.
91
92
93 BIOS does ISOLATION
94
95
96 This method assumes the BIOS has already carried out the
97 isolation process, and allocated Card Select Numbers (CSNs)
98 to each card.
99 The configuration file specifies the number of cards and the
100 readport address, and then __isapnp__ reads the serial
101 identifier from the beginning of the resource data to find
102 out the identity of each card.
103 A configuration file using this method will start
104 like:
105
106
107 (READPORT 0x3bb) (CSN 2) (IDENTIFY *)
108
109
110 Using this method, and PEEK instructions instead of the
111 configuration setting instructions, it is possible to
112 examine the configuration of the Plug-and-Play cards,
113 without upsetting normal system operation. This can be
114 useful for example to check how the BIOS has configured the
115 hardware. (If you want to get really fancy, you could pipe
116 the output through a script to configure the kernel
117 driver(s) to match).
118 Note that some cards appear to be broken in that they don't
119 follow the requirement in the second paragraph of section
120 4.5 of the PnP ISA Spec. (They start returning resource data
121 immediately when entering the ''Config'' state from the
122 ''Sleep'' state, rather than the 9 byte serial
123 identifier). These cards may not be able to use this
124 method.
125 Due to the difficulty of determining the correct READPORT
126 address to use (which must be the same as the one the BIOS
127 used), this method may be tricky to get
128 working.
129
130
131 __isapnp__ does ISOLATION
132
133
134 With this method, __isapnp__ carries out the isolation
135 process. This will be required for example on those systems
136 without a Plug and Play BIOS, or with a broken BIOS.
137 The configuration file simply includes the line
138
139
140 (ISOLATE)
141
142
143 which will scan for a suitable readport address and identify
144 all the devices. You may still want to include (IDENTIFY *)
145 however, as it will printout the names of the devices found.
146 Putting a (READPORT xxx) before the (ISOLATE) will prevent
147 the scanning process.
148 Note that as of the 1.12 release of isapnptools, ISOLATE can
149 now take an optional parameter which determines whether the
150 existing hardware configuration settings are preserved or
151 not. The default is now to preserve the
152 settings.
153 !!CONFIGURATION
154
155
156 This is the core of the process. For each card to be
157 configured (not all need to be), it is first selected using
158 the CONFIGURE keyword. (Cards can be selected using the CSN
159 keyword, but the CSN numbers will change when Plug and Play
160 cards are added and removed, which could result in
161 configuration register settings going to the wrong
162 card).
163 After this, each logical device on the card is selected in
164 turn using the LD keyword. The registers for that device are
165 programmed using the IO, INT, DMA, MEM keywords and their
166 subwords. Finally the logical device is enabled using the
167 ACT keyword.
168 For debugging purposes, or to access non-standard
169 configuration registers or vendor specific registers, the
170 REG keyword may be used to directly access the configuration
171 registers by address.
172 A couple of examples of this part of the configuration file
173 look like this:
174
175
176 # Card 1: (serial identifier 13 0e 1e 37 b4 19 01 89 14) #
177 EDI0119 Serial No 236861364 [[checksum 13] # Version 1.0,
178 Vendor version 1.0 # ANSI string --
179
180
181 (CONFIGURE DFX0000/1493 (LD 0 (IO 0 (SIZE 8)(BASE 0x3e8))
182 (INT 0 (IRQ 11 (MODE +E))) (NAME
183 !!TIDY UP
184
185
186 This is just the keyword WAITFORKEY, which returns the Plug
187 and Play configuration mechanism to the ''Wait for Key''
188 state.
189 The configuration file thus ends with
190
191
192 (WAITFORKEY)
193 !!LIST OF KEYWORDS
194
195
196 The following is a complete list of the keywords, showing
197 the heirarchy of validity.
198
199
200 CONFIGURE (or CSN) LD ACT PEEK DMA CHANNEL PEEK INT IRQ MODE
201 PEEK IO BASE SIZE PEEK CHECK NAME MEM BASE MODE PEEK UPPER
202 REG PEEK POKE CONFLICT IO IRQ DMA MEM DEBUG IDENTIFY
203 IDENTIFY-FORMAT ISOLATE IGNORECRC READPORT VERBOSITY
204 VERIFYLD WAITFORKEY
205 !!KEYWORDS
206
207
208 In alphabetical order. The ... in the parentheses implies
209 that the instruction is merely a selector of some sort, and
210 further instructions are required to do something
211 useful.
212
213
214 __(ACT__ ''arg''__)__
215
216
217 Context: within (LD ...).''
218 arg'' can be ''Y'' or ''N''. ''Y'' will cause the
219 logical device to be activated and respond to accesses.
220 ''N'' will cause the logical device to be deactivated and
221 isolated from the bus.
222 If a __NAME__ has been specified, and __VERBOSITY__ is
223 greater than 1, a status message will be output to stdout,
224 summarising the device configuration settings.
225
226
227 __(BASE__ ''arg''__)__
228
229
230 Context: within (IO ...) or (MEM ...).''
231 arg'' specifies the base address of the region. Prefix a
232 hex address with ''0x''.
233
234
235 __(CHANNEL__ ''arg''__)__
236
237
238 Context: within (DMA ...).''
239 arg'' specifies the DMA channel to use. Valid settings are
240 0..7. Channel 4 means no DMA used. Channels 0..3 are for 8
241 bit DMA, Channels 5..7 are for 16 bit DMA.
242
243
244 __(CHECK)__
245
246
247 Context: within (IO ...).
248 Carry out an IO range check to ensure no bus contention with
249 any other device. Only valid if the device supports it, and
250 the device is not already activated.
251
252
253 __(CONFIGURE__ ''arg'' __...)__
254
255
256 Context: Global.''
257 arg'' specifies the card Vendor Id and serial number in
258 the form
259 [[A-Z][[A-Z][[A-Z][[0-9A-F][[0-9A-F][[0-9A-F][[0-9A-F]/[[-#]?[[1-9][[0-9]*.
260 For example
261 ''-1'' implies that the device does not have a serial
262 number; in this case, only one card can of this type can be
263 supported in the system. Some cards appear to include an
264 underscore character as one of the initial three letters of
265 the Vendor ID, this is outside the specification, though
266 supported.
267 To allow the same configuration files on multiple machines,
268 two additional features have been added from release
269 1.12:
270 If the specified device is not found, the device is skipped.
271 Rather than the script aborting.
272 The serial number of the device may be specified as #n,
273 meaning the nth device found with the given Vendor Id,
274 independent of its actual serial number. Each card must
275 still have a unique serial number to be separately
276 identified.
277
278
279 __(CONFLICT ...)__
280
281
282 Context: Global.
283 This keyword is used to select whether resource conflicts
284 for each of __DMA__, __MEM__, __IO__ or __IRQ__
285 are a ''Warning'' or ''Fatal''. Resource conflicts
286 will cause a message to be output, but if the resource is
287 set as Fatal on conflict, the program will immediately
288 abort.
289 The default is equivalent to
290
291
292 (CONFLICT (DMA WARNING)(MEM WARNING)(IO WARNING)(IRQ
293 WARNING))
294
295
296 __(CSN__ ''arg'' __...)__
297
298
299 Context: Global.''
300 arg'' specifies the Card Select Number of the card to
301 select for access. __isapnp__ assumes you know what you
302 are doing if you use this instruction, and will assume the
303 card exists (and all the cards with lower CSNs). ''arg''
304 must be in the range 1..32, this is a compiled in
305 limit.
306
307
308 __(DEBUG)__
309
310
311 Context: Global.
312 This turns on debugging immediately. Diagnostic messages
313 will be produced as soon as this instruction is read
314 in.
315
316
317 __(DMA__ ''arg'' __...)__
318
319
320 Context: within (LD ...).''
321 arg'' specifies the DMA register to configure, in the
322 range 0..1. Each logical device can use up to 2 DMA
323 channels.
324 Note there is another ''DMA'' described in
325 __CONFLICT__.
326
327
328 __(IDENTIFY__ ''arg''__)__
329
330
331 Context: Global.''
332 arg'' specifies the Card Select Number of the card to
333 identify. Identification consists of reading the card's
334 resource data, updating internal tables so that
335 __CONFIGURE__ can find the card, and printing the results
336 (the format of the results can be changed using
337 __IDENTIFY-FORMAT__). ''arg'' must be in the range of
338 valid CSNs (ie number of boards found), or can be specified
339 as ''*'' to operate on each card in turn.
340 Note:__VERBOSITY__ must be greater than 2 to see the
341 results on stdout.
342
343
344 __(IDENTIFY-FORMAT__ ''arg''__)__
345
346
347 Context: Global.''
348 arg'' specifies the format string to be used by
349 __IDENTIFY__ when outputting the data for each card, it
350 must be a string enclosed in double quotes. The
351 __IDENTIFY-FORMAT__ command must precede __IDENTIFY__
352 if it going to have any effect.
353 The default format string is:
354
355
356 The following format escapes are recognised:__
357 %b__ - Card Select (board) Number [[Decimal number]__
358 %s__ - Board serial number [[Decimal number]__
359 %v__ - Board vendor Id [[7 character string]__
360 %x__ - where __x__ is __0..8__ - Identification byte
361 x, 8 is the checksum [[2 Hex digits]
362
363
364 __(IGNORECRC)__
365
366
367 Context: Global.
368 Normally, cards which have a CRC error during the reading of
369 the serial identifier in the isolation process are not
370 counted, and the __READPORT__ is assumed bad. Setting
371 this flag means they will be treated as good, and you have
372 to hope that __IDENTIFY__ will fix the identifier. This
373 must therefore come before __ISOLATE__ if it is to have
374 any effect.
375
376
377 __(INT__ ''arg'' __...)__
378
379
380 Context: within (LD ...).''
381 arg'' specifies the INT register set to configure, in the
382 range 0..1. Each logical device can use up to two interrupt
383 lines.
384
385
386 __(IO__ ''arg'' __...)__
387
388
389 Context: within (LD ...).''
390 arg'' specifies the IO register set to configure, in the
391 range 0..7. Each logical device can use up to eight IO
392 regions. The size of the IO region should be specified using
393 the SIZE keyword. The size of the IO region can be found by
394 examining the output of __pnpdump__.
395 Note there is another ''IO'' described in
396 __CONFLICT__.
397
398
399 __(IRQ__ ''arg'' __...)__
400
401
402 Context: within (INT ...).''
403 arg'' specifies the interrupt line to use for the
404 interrupt, in the range 0..15. No interrupt is specified
405 using 0. To use interrupts a value in the range 1..15 must
406 be specified. Note that not all interrupt lines are
407 connected, so the resource data must be consulted to get a
408 list of valid settings.
409 Note there is another ''IRQ'' described in
410 __CONFLICT__.
411
412
413 __(ISOLATE__ ''arg''__)__
414
415
416 Context: Global.
417 This carries out the full isolation protocol. First it
418 resets all the Card Serial Numbers, then isolates them one
419 by one, allocating each one a Card Select Number. If a
420 __READPORT__ hasn't already been specified, it will also
421 search for a valid readport address.
422 The optional ''arg'' may be __PRESERVE__, the default,
423 in which case the existing configuration settings are
424 preserved, or it may be __CLEAR__, in which case all the
425 Plug and Play devices are reset to their power-on default
426 configurations.
427
428
429 __(LD__ ''arg'' __...)__
430
431
432 Context: within (CONFIGURE ...) or (CSN ...).''
433 arg'' specifies the logical device to configure, in the
434 range 0..n, where n is one less than the number of logical
435 devices on the card. After setting the register to select
436 the logical device, it is read back and checked; an error is
437 generated if there is a mismatch. This behaviour can be
438 changed using the global command __VERIFYLD__. The number
439 of logical devices on a card can be found by examining the
440 output of __pnpdump__.
441
442
443 __(MEM__ ''arg'' __...)__
444
445
446 Context: within (LD ...).''
447 arg'' specifies the memory register set to configure, in
448 the range 0..3. The memory register sets are the normal
449 range (24 bit addresses). Each logical device can support up
450 to 4 memory regions. There is no direct support for the 32
451 bit memory descriptors, though __POKE__ could be used if
452 required.
453 Note there is another ''MEM'' described in
454 __CONFLICT__.
455
456
457 __(MODE__ ''arg''__)__
458
459
460 Context: within (IRQ ...) or (MEM ...).
461 Within __IRQ__, ''arg'' specifies the interrupt line
462 polarity and sensitivity using two characters [[+-][[EL] for
463 [[positive|negative][[Edge|Level] sensitivity. In most ISA
464 situations this will be ''+E''.
465 Within __MEM__, ''arg'' specifies memory width and the
466 meaning of the value written to the __UPPER__ register.
467 ''arg'' is of the form [[BW][[RU] for
468 [[Byte|Word][[Range|Upper]. Note that often these values
469 cannot be set, but they are checked with the hardware value
470 and an error is generated if they don't match.
471
472
473 __(NAME__ ''arg''__)__
474
475
476 Context: within (LD ...).''
477 arg'' specifies the name of the logical device to be
478 output when the device is __ACT__ivated. The ''arg''
479 is a string in double quotes.
480
481
482 __(PEEK)__
483
484
485 Context: within most register access keywords.
486 This instruction causes the register value to be read and a
487 suitable message output to stdout. __VERBOSITY__ must be
488 greater than 0 to see the output.
489
490
491 __(POKE__ ''arg''__)__
492
493
494 Context: within (REG ...).''
495 arg'' specifies the value to write to the selected
496 register in the range 0..255.
497
498
499 __(READPORT__ ''arg''__)__
500
501
502 Context: Global.''
503 arg'' specifies the address of the readport register to
504 use in the range 0x203..0x3ff. The address chosen must be
505 unused by any other hardware. The bottom two bits are set to
506 ensure the port is on the correct address boundary. This
507 should be the first instruction if used (except perhaps for
508 DEBUG).
509 The Plug and Play specification specifies three registers.
510 Two of them are write only, at images of the printer status
511 port (so were previously read only), at addresses 0x279 and
512 0xA79. However, the protocol requires a single readable
513 register. The location of this register cannot be
514 standardised due to the impossibility of finding a single
515 unused address which is common to all systems.
516 For this reason the address of the readable register is
517 specified in one of the configuration registers, and an
518 algorithm specified to find a suitable non-conflicting
519 location. If you know a good value to use, it can be
520 specified with this command to prevent having to try to
521 discover it.
522
523
524 __(REG__ ''arg'' __...)__
525
526
527 Context: within (LD ...).''
528 arg'' specifies the address of the register to configure,
529 in the range 0..255. This may be used to access the various
530 reserved and vendor defined registers on a logical
531 device.
532
533
534 __(SIZE__ ''arg''__)__
535
536
537 Context: within (IO ...).''
538 arg'' specifies the size of the region in bytes. Prefix a
539 hex size with ''0x''. This keyword does not affect any
540 PnP configuration registers, it is simply information for
541 resource conflict checking. If the __SIZE__ is
542 unspecified, 8 will be assumed.
543
544
545 __(UPPER__ ''arg''__)__
546
547
548 Context: within (MEM ...).''
549 arg'' specifies the memory range the device can use. The
550 value is either an upper address, or a range (offset) value,
551 depending on the device. Consult the resource data as dumped
552 by __pnpdump__ to find out what the device
553 supports.
554
555
556 __(VERBOSITY__ ''arg''__)__
557
558
559 Context: Global.''
560 arg'' is a number from 0 to 3, which represents the amount
561 of status output the program should provide. 0 is mininum, 3
562 is maximum. The default is 3 for backwards
563 compatibility.
564
565
566 __(VERIFYLD__ ''arg''__)__
567
568
569 Context: Global.
570 Normally, __isapnp__ attempts to verify the logical
571 device exists by reading back the the value in the logical
572 device register after setting it. The standard seems rather
573 vague on whether this is a requirement, and it would appear
574 that some hardware fails to read back correctly, so this
575 instruction allows the verification to be turned on and
576 off.
577 Within __VERIFYLD__, ''arg'' may be [[Y|N] to turn
578 verification on and off respectively. If no parameter is
579 supplied, verification will be turned on.
580
581
582 __(WAITFORKEY)__
583
584
585 Context: Global.
586 Returns all cards to the ''Wait for Key'' state, as
587 required by the specification.
588 !!BUGS
589
590
591 Check http://www.roestock.demon.co.uk/isapnptools/ for
592 latest information and FAQ.
593
594
595 If you think you have found a problem not mentioned in the
596 latest version, please send a report to
597 isapnp@roestock.demon.co.uk.
598 !!AUTHOR
599
600
601 __isapnp.conf__ has been written by Peter Fox
602 __
603 !!AVAILABILITY
604
605
606 The latest version of the sources may be obtained by ftp
607 from ftp://ftp.demon.co.uk/pub/unix/linux/utils
608 Or follow one of the pointers to various ftp sites carrying
609 isapnptools from my web page at
610 http://www.roestock.demon.co.uk/
611 !!REFERENCES
612
613
614 Plug and Play ISA Specification, Version 1.0a, May 5, 1994.
615 Available from
616 ftp://ftp.microsoft.com/developr/drg/Plug-and-Play/Pnpspecs
617 !!SEE ALSO
618
619
620 pnpdump(8), isapnp(8)
621 ----
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.