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