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 don't
  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 form 'PNP0000'
  37         - <logdev> is in form '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 Information for developers
  58 ==========================
  59
  60 Finding appropriate device
  61 --------------------------
  62
  63 extern struct pci_bus *isapnp_find_card(unsigned short vendor,
  64                                         unsigned short device,
  65                                         struct pci_bus *from);
  66
  67 This function finds a ISA PnP card. For the vendor device should
  68 be used ISAPNP_VENDOR(a,b,c) where a,b,c are characters or integers.
  69 For the device number should be used ISAPNP_DEVICE(x) macro where x is
  70 integer value. Both vendor and device numbers can be taken from contents
  71 of the /proc/isapnp file.
  72
  73 extern struct pci_dev *isapnp_find_dev(struct pci_bus *card,
  74                                        unsigned short vendor,
  75                                        unsigned short function,
  76                                        struct pci_dev *from);
  77
  78 This function finds the ISA PnP device. If card is NULL, then
  79 the global search mode is used (all devices are used for the searching).
  80 Otherwise only devices which belongs to the specified card are verified.
  81 For the function number can be used ISAPNP_FUNCTION(x) macro which works
  82 similarly as the ISAPNP_DEVICE(x) macro.
  83
  84 extern int isapnp_probe_cards(const struct isapnp_card_id *ids,
  85                               int (*probe)(struct pci_bus *card,
  86                                            const struct isapnp_card_id *id));
  87
  88
  89 This function is a helper for drivers which requires to use more than
  90 one device from an ISA PnP card. For each cards is called the probe
  91 callback with appropriate information.
  92
  93 Example for ids parameter initialization:
  94
  95 static struct isapnp_card_id ids[] __devinitdata = {
  96         {
  97                 ISAPNP_CARD_ID('A','D','V', 0x550a),
  98                 devs: {
  99                         ISAPNP_DEVICE_ID('A', 'D', 'V', 0x0010),
 100                         ISAPNP_DEVICE_ID('A', 'D', 'V', 0x0011)
 101                 },
 102                 driver_data: 0x1234,
 103         },
 104         {
 105                 ISAPNP_CARD_END,
 106         }
 107 };
 108
 109 ISA PnP configuration
 110 =====================
 111
 112 There are two ways how can be ISA PnP interface used.
 113
 114 First way is lowlevel
 115 ---------------------
 116
 117 All ISA PNP configuration registers are accessible via lowlevel
 118 isapnp_(read|write)_(byte|word|dword) functions.
 119
 120 The function isapnp_cfg_begin() must be called before any lowlevel function.
 121 The function isapnp_cfg_end() must be always called after configuration
 122 otherwise the access to the ISA PnP configuration functions will be blocked.
 123
 124 Second way is auto-configuration
 125 --------------------------------
 126
 127 This feature gives to the driver the real power of the ISA PnP code.
 128 Function dev->prepare() initializes the resource members in the device
 129 structure. This structure contains all resources set to auto configuration
 130 values after the initialization. The device driver may modify some resources
 131 to skip the auto configuration for a given resource.
 132
 133 Once the device structure contains all requested resource values, the function
 134 dev->activate() must be called to assign free resources to resource members
 135 with the auto configuration value.
 136
 137 Function dev->activate() does:
 138         - resources with the auto configuration value are configured
 139         - the auto configuration is created using ISA PnP resource map
 140         - the function writes configuration to ISA PnP configuration registers
 141         - the function returns to the caller actual used resources
 142
 143 When the device driver is removing, function dev->deactivate() has to be
 144 called to free all assigned resources.
 145
 146 Example (game port initialization)
 147 ==================================
 148
 149 /*** initialization ***/
 150
 151         struct pci_dev *dev;
 152
 153         /* find the first game port, use standard PnP IDs */
 154         dev = isapnp_find_dev(NULL,
 155                               ISAPNP_VENDOR('P','N','P'),
 156                               ISAPNP_FUNCTION(0xb02f),
 157                               NULL);
 158         if (!dev)
 159                 return -ENODEV;
 160         if (dev->prepare(dev)<0)
 161                 return -EAGAIN;
 162         if (!(dev->resource[0].flags & IORESOURCE_IO))
 163                 return -ENODEV;
 164         if (!dev->ro) {
 165                 /* override resource */
 166                 if (user_port != USER_PORT_AUTO_VALUE)
 167                         isapnp_resource_change(&dev->resource[0], user_port, 1);
 168         }
 169         if (dev->activate(dev)<0) {
 170                 printk("isapnp configure failed (out of resources?)\n");
 171                 return -ENOMEM;
 172         }
 173         user_port = dev->resource[0].start;             /* get real port */
 174
 175 /*** deactivation ***/
 176
 177         /* to deactivate use: */
 178         if (dev)
 179                 dev->deactivate(dev);