Documentation/isapnp.txt

   1 ISA Plug & Play support by Jaroslav Kysela <perex@suse.cz>
   2 ==========================================================
   3
   4 Interface /proc/isapnp
   5 ======================
   6
   7 Read commands:
   8 --------------
   9
  10 No comment.
  11
  12 Write commands:
  13 ---------------
  14
  15 With the write interface you can activate or modify the configuration of
  16 ISA Plug & Play devices.  It is mainly useful for drivers which have not
  17 been rewritten to use the ISA Plug & Play kernel support yet.
  18
  19 card <idx> <vendor>     - select PnP device by vendor identification
  20 csn <CSN>               - select PnP device by CSN
  21 dev <idx> <logdev>      - select logical device
  22 auto                    - run autoconfigure
  23 activate                - activate logical device
  24 deactivate              - deactivate logical device
  25 port <idx> <value>      - set port 0-7 to value
  26 irq <idx> <value>       - set IRQ 0-1 to value
  27 dma <idx> <value>       - set DMA 0-1 to value
  28 memory <idx> <value>    - set memory 0-3 to value
  29 poke <reg> <value>      - poke configuration byte to selected register
  30 pokew <reg> <value>     - poke configuration word to selected register
  31 poked <reg> <value>     - poke configuration dword to selected register
  32 allow_dma0 <value>      - allow dma channel 0 during auto activation: 0=off, 1=on
  33
  34 Explanation:
  35         - variable <idx> begins with zero
  36         - variable <CSN> begins with one
  37         - <vendor> is in the standard format 'ABC1234'
  38         - <logdev> is in the standard format 'ABC1234'
  39
  40 Example:
  41
  42 cat > /proc/isapnp <<EOF
  43 card 0 CSC7537
  44 dev 0 CSC0000
  45 port 0 0x534
  46 port 1 0x388
  47 port 2 0x220
  48 irq 0 5
  49 dma 0 1
  50 dma 1 3
  51 poke 0x70 9
  52 activate
  53 logdev 0 CSC0001
  54 port 0 0x240
  55 activate
  56 EOF
  57
  58
  59 Information for developers
  60 ==========================
  61
  62 Finding a device
  63 ----------------
  64
  65 extern struct pci_bus *isapnp_find_card(unsigned short vendor,
  66                                         unsigned short device,
  67                                         struct pci_bus *from);
  68
  69 This function finds an ISA PnP card.  For the vendor argument, the
  70 ISAPNP_VENDOR(a,b,c) macro should be used, where a,b,c are characters or
  71 integers.  For the device argument the ISAPNP_DEVICE(x) macro should be
  72 used, where x is an integer value.  Both vendor and device arguments
  73 can be taken from contents of the /proc/isapnp file.
  74
  75 extern struct pci_dev *isapnp_find_dev(struct pci_bus *card,
  76                                        unsigned short vendor,
  77                                        unsigned short function,
  78                                        struct pci_dev *from);
  79
  80 This function finds an ISA PnP device. If card is NULL, then the global
  81 search mode is used (all devices are used for the searching).  Otherwise
  82 only devices which belong to the specified card are checked.  For the
  83 function number the ISAPNP_FUNCTION(x) macro can be used; it works
  84 similarly to the ISAPNP_DEVICE(x) macro.
  85
  86 extern int isapnp_probe_cards(const struct isapnp_card_id *ids,
  87                               int (*probe)(struct pci_bus *card,
  88                               const struct isapnp_card_id *id));
  89
  90
  91 This function is a helper for drivers which need to use more than
  92 one device from an ISA PnP card.  The probe callback is called with
  93 appropriate arguments for each card.
  94
  95 Example for ids parameter initialization:
  96
  97 static struct isapnp_card_id card_ids[] __devinitdata = {
  98         {
  99                 ISAPNP_CARD_ID('A','D','V', 0x550a),
 100                 devs: {
 101                         ISAPNP_DEVICE_ID('A', 'D', 'V', 0x0010),
 102                         ISAPNP_DEVICE_ID('A', 'D', 'V', 0x0011)
 103                 },
 104                 driver_data: 0x1234,
 105         },
 106         {
 107                 ISAPNP_CARD_END,
 108         }
 109 };
 110 ISAPNP_CARD_TABLE(card_ids);
 111
 112 extern int isapnp_probe_devs(const struct isapnp_device_id *ids,
 113                              int (*probe)(struct pci_bus *card,
 114                              const struct isapnp_device_id *id));
 115
 116
 117 This function is a helper for drivers which need to use one
 118 device from an ISA PnP card.  The probe callback is called with
 119 appropriate arguments for each matched device.
 120
 121 Example for ids parameter initialization:
 122
 123 static struct isapnp_device_id device_ids[] __devinitdata = {
 124         { ISAPNP_DEVICE_SINGLE('E','S','S', 0x0968, 'E','S','S', 0x0968), },
 125         { ISAPNP_DEVICE_SINGLE_END, }
 126 };
 127 MODULE_DEVICE_TABLE(isapnp, device_ids);
 128
 129
 130 ISA PnP configuration
 131 =====================
 132
 133 There are two ways in which the ISA PnP interface can be used.
 134
 135 First way: low-level
 136 --------------------
 137
 138 All ISA PNP configuration registers are accessible via the low-level
 139 isapnp_(read|write)_(byte|word|dword) functions.
 140
 141 The function isapnp_cfg_begin() must be called before any lowlevel function.
 142 The function isapnp_cfg_end() must be always called after configuration
 143 otherwise the access to the ISA PnP configuration functions will be blocked.
 144
 145 Second way: auto-configuration
 146 ------------------------------
 147
 148 This feature gives to the driver the real power of the ISA PnP driver.
 149 The function dev->prepare() initializes the resource members in the device
 150 structure.  This structure contains all resources set to auto configuration
 151 values after the initialization.  The device driver may modify some resources
 152 to skip the auto configuration for a given resource.
 153
 154 Once the device structure contains all requested resource values, the function
 155 dev->activate() must be called to assign free resources to resource members
 156 with the auto configuration value.
 157
 158 Function dev->activate() does:
 159    - resources with the auto configuration value are configured
 160    - the auto configuration is created using ISA PnP resource map
 161    - the function writes configuration to ISA PnP configuration registers
 162    - the function returns to the caller actual used resources
 163
 164 When the device driver is removed, function dev->deactivate() has to be
 165 called to free all assigned resources.
 166
 167 Example (game port initialization)
 168 ==================================
 169
 170 /*** initialization ***/
 171
 172         struct pci_dev *dev;
 173
 174         /* find the first game port, use standard PnP IDs */
 175         dev = isapnp_find_dev(NULL,
 176                               ISAPNP_VENDOR('P','N','P'),
 177                               ISAPNP_FUNCTION(0xb02f),
 178                               NULL);
 179         if (!dev)
 180                 return -ENODEV;
 181         if (dev->active)
 182                 return -EBUSY;
 183         if (dev->prepare(dev)<0)
 184                 return -EAGAIN;
 185         if (!(dev->resource[0].flags & IORESOURCE_IO))
 186                 return -ENODEV;
 187         if (!dev->ro) {
 188                 /* override resource */
 189                 if (user_port != USER_PORT_AUTO_VALUE)
 190                         isapnp_resource_change(&dev->resource[0], user_port, 1);
 191         }
 192         if (dev->activate(dev)<0) {
 193                 printk("isapnp configure failed (out of resources?)\n");
 194                 return -ENOMEM;
 195         }
 196         user_port = dev->resource[0].start;             /* get real port */
 197
 198 /*** deactivation ***/
 199
 200         /* to deactivate use: */
 201         if (dev)
 202                 dev->deactivate(dev);