sys/man/3/pnp

   1 .TH PNP 3
   2 .SH NAME
   3 pnp \- Plug 'n' Play ISA and PCI Interfaces
   4 .SH SYNOPSIS
   5 .nf
   6 .B bind -a '#$' /dev
   7 .sp 0.3v
   8 .BI /dev/pci/ bus\fL.\fPdev\fL.\fPfn ctl
   9 .BI /dev/pci/ bus\fL.\fPdev\fL.\fPfn raw
  10 .sp 0.3v
  11 .BI /dev/pnp/ctl
  12 .BI /dev/pnp/csn n ctl
  13 .BI /dev/pnp/csn n raw
  14 \&...
  15 .sp 0.3v
  16 .fi
  17 .SH DESCRIPTION
  18 .PP
  19 This device provides a limited interface to the PCI bus and
  20 Plug 'n' Play ISA devices.
  21 .SS PCI Interface
  22 .PP
  23 PCI devices are addressed logically by a bus number,
  24 a device number on that bus, and a function number
  25 within the device.
  26 The set of all such device functions may be enumerated
  27 by traversing the
  28 .B /dev/pci
  29 directory; the driver serves two files for each function.
  30 These are a control file
  31 .RL ( /dev/pci/\fIbus\fP.\fIdev\fP.\fIfn\fPctl )
  32 which may be read for a textual summary of the device function,
  33 and a `raw' file
  34 .RL ( /dev/pci/\fIbus\fP.\fIdev\fP.\fIfn\fPraw )
  35 which may be used to read or write the raw contents of PCI configuration space.
  36 .PP
  37 The first field of a PCI control file contains the class, sub-class and
  38 programming interface values for the device function, expressed
  39 as 2-digit hexadecimal values, and separated by periods.
  40 The second field yields the vendor ID and device ID, each as 4-digit
  41 hex numbers, separated by a slash.
  42 The third field is the associated interrupt line in decimal.
  43 The remainder of the line enumerates any valid base address
  44 registers for the function, using two fields for each.
  45 In the first field, the index of the register is followed by
  46 a colon, and then the value of the register itself.
  47 The following field gives the associated size of the memory
  48 (or I/O space) that is mapped by the register.
  49 .SS Plug 'n' Play
  50 .PP
  51 Plug 'n' Play ISA devices are discovered by sending a fixed `unlock' sequence
  52 over an I/O port, and then reading back data from another port.
  53 An arbitration algorithm is used to separate out the individual
  54 cards and enumerate them in turn.
  55 Each card is assigned a unique number, called a CSN, in the range 1-255 as a
  56 result of enumeration.
  57 Cards also have a fixed 64 bit identification number, set by the
  58 manufacturer, which is used by the arbitration algorithm to
  59 resolve conflicts.
  60 The first 32 bits describe the type of the card, and the second
  61 32 bits form a serial number for the particular instance of that card type.
  62 When formatted textually, it appears as 3 upper-case letters
  63 (typically representing the manufacturer),
  64 followed by 4 hex digits, then a period, then 8 hex digits.
  65 The substring before the period is the card type, and the substring
  66 after the period is the serial number.
  67 .PP
  68 The enumeration algorithm needs to be enabled by specifying the
  69 port number to write the unlock sequence out on.
  70 This can be configured to take place at boot time by adding a line
  71 like the following to
  72 .IR plan9.ini :
  73 .IP
  74 .EX
  75 pnp0=port=0x203
  76 .EE
  77 .PP
  78 Here
  79 .B port
  80 should be chosen to not conflict with any existing devices.
  81 It must be in the range
  82 .BR 0x203-0x3ff .
  83 Alternatively, one can use the following command:
  84 .IP
  85 .EX
  86 echo port 0x203 >/dev/pnp/ctl
  87 .EE
  88 .PP
  89 Note that a side-effect of PnP enumeration is to reset the configuration
  90 state of all such cards; any settings made by a Plug and Play BIOS will be lost.
  91 Reading the file
  92 .B /dev/pnp/ctl
  93 returns one of the strings
  94 .B "enabled\fI port\fP"
  95 or
  96 .BR "disabled" .
  97 .PP
  98 For each enumerated card, two files are served in
  99 .BR /dev/pnp .
 100 A control file
 101 .RL ( /dev/pnp/csn\fIn\fPctl )
 102 may be read to determine the ID of the card, and a raw file
 103 .RL ( /dev/pnp/csn\fIn\fPraw )
 104 may be read to obtain the configuration data associated with the card.
 105 It is intended that the control file should take commands which set the
 106 various configurable resources of the card, but this has not been
 107 implemented yet.
 108 .PP
 109 A mechanism is provided for configuring cards via
 110 .IR plan9.ini (8).
 111 A line of the form
 112 .BI pnp n = "idstring ..."
 113 will cause the driver to look for the card named by
 114 .I idstring
 115 and, if found, assign it the CSN
 116 .IR n .
 117 The intention is that
 118 any additional text after the idstring is interpreted as if it
 119 was written to the card's
 120 .B ctl
 121 file, but this is not yet implemented.
 122 .SH EXAMPLES
 123 .PP
 124 To list all PCI functions:
 125 .IP
 126 .EX
 127 cat /dev/pci/*ctl
 128 .EE
 129 .PP
 130 To find just the PCI video card (class 3):
 131 .IP
 132 .EX
 133 grep '^03' /dev/pci/*ctl
 134 .EE
 135 .SH SOURCE
 136 .B /sys/src/9/port/devpnp.c
 137 .SH SEE ALSO
 138 .IR pci (8)
 139 .SH BUGS
 140 Access to the I/O and memory regions of a PCI device is not provided.
 141 .PP
 142 The ability to set a Plug 'n' Play card's configurable settings has not been
 143 implemented.
 144 .PP
 145 There should be a user program for identifying and configuring
 146 Plug 'n' Play cards.