1Some notes on IODC, its general brokenness, and how to work around it.
2
3Short Version
4
5IODC is HP's pre-PCI standard for device identification (a la PCI vendor,
6device IDs), detection, configuration, initialization and so on.
7
8It also can provide firmware function to do the actual IO, which are slow,
9not really defined for runtime usage and generally not desirable.  (There
10are other firmware standards, such as STI, to do real IO).
11
12Usually, there are two parts to IODC.  The actual ROMs, which are laid out,
13detected aso in a bus-specific manner (IO_DC_ADDRESS / IO_DC_DATA on
14GSC/Runway, PCI spec - compliant ROMs for PCI, God-only-knows how on EISA),
15and the slightly cooked data read by PDC_IODC.
16
17The ROM layout is generally icky (only one byte out of every 4-byte-word
18might be valid, and many devices don't implement required options), so
19using PDC_IODC is highly recommended.  (In fact, you should use the device
20lists set up by the kernel proper instead of calling PDC_IODC yourself).
21
22Now, let's have a look at what the cooked ROM looks like (see iodc.pdf for
23the details, this is the simplified version).
24
25Basically, the first 8 bytes of IODC contain two 32-bit ids called HVERSION
26and SVERSION.  Those are further split up into bit fields, and
27unfortunately just ignoring this split up isn't an option.
28
29SVERSION consists of a 4-bit revision field, a 20-bit model field and a
308-bit opt field.  Now, forget the revision and opt fields exist.  Basically,
31the model field is equivalent to a PCI device id (there is no vendor id.
32this is proprietary hardware we're talking about).  That is, all your
33driver cares for, in 90 % of the cases, is to find all devices that match
34the model field.
35
36The rev field is - you guessed it - roughly equivalent to the revision
37byte for PCI, with the exception that higher revisions should be strict
38supersets of lower revisions.
39
40The last byte of HVERSION, "type", and the last byte of SVERSION, "opt",
41belong together;  type gives a very rough indication of what the device
42is supposed to do, and opt contains some type-specific information. (For
43example, the "bus converter" (ie bus bridge) type encodes the kind of
44bus behind the bridge in the opt field.
45
46The rest of HVERSION contains, in most cases, a number identifying the
47machine the chip was used in, or a revision indicator that just fixed
48bugs and didn't add any features (or was done in a shrinked process or
49whatever).
50
51So, here's the interface you actually should use to find your devices:
52
53
54/* Find a device, matching the model field of sversion only (from=NULL
55 * for the first call */
56struct iodc_dev *iodc_find_device(u32 sversion, struct iodc_dev *from);
57
58
59Here's a function you should use if you have special requirements, such
60as finding devices by type rather than by model.  Generally, if you're
61using this, you should be me).
62
63/* Find a device, masking out bits as specified */
64struct iodc_dev *iodc_find_device_mask(u32 hversion, u32 sversion,
65	u32 hversion_mask, u32 sversion_mask, struct iodc_dev *from);
66
67
68	Philipp Rumpf <prumpf@tux.org>
69