[flashrom] Tightening up the board enable table.

[Luc Verhaegen]

We have had board enable routines and our board enable table for more 
than two years now. And thanks to the good work of carldani and uwe 
and the release(s) (one done, one pending) this list is growing fast.

We have 47 boards in our board enable table today.

Board enables have the following format today:
<pci id set 1> <pci id set 2> <coreboot name> <pretty print name>
<board enable callback>

one pci id set is the following:

<vendor> <device> <card/subsystem vendor> <card/subsystem device>

While most of the time, the vendor and device ids are fixed, the 
subsystem pair is set by the bios. It can be write-once or it can be 
locked by some other bit in the device config space. Because subsystem 
ids are relatively new to the pci spec (second half of the 90s iirc), 
not all vendors have been using them. Most last-millenium boards will 
not have them filled in. Or often vendor bioses just copy main ids over. 
Many consumer board makers today do their job really well while embedded 
board makers tend to ignore subsystem ids.

Because of what i saw in my unichrome graphics driver (where i started 
using subsystem ids in 2004 to see which outputs were wired up), i knew 
that matching a single device was never going to work. So two were added 
here, but we only require a single set to be filled in.

There is a situation with some gigabyte boards for which carldani 
suggested to add a third set, which is imho a good solution, but we are 
trying to hold this one off until we really need it.

After the pair of pci ids, there are the board names.

The coreboot name is used two-fold. On a coreboot rom, this name is 
matched to the coreboot info. On a legacy bios, the user can provide the 
board name on the command line and therefor force flashrom to use a 
specific board enable. In both cases, the device and vendor ids of pci 
devices are matched as well as a safeguard.

So, three ways of matching boards:
* main ids + subsystem ids.
* legacy bios + command line name + main ids (ignoring subsystem ids).
* coreboot + coreboot name + main ids (ignoring subsystem ids).

Now that we have a more sizable table and a bigger and quickly growing 
userbase, i believe that we should look into tightening this up.

We are no longer part of the main coreboot project and are reaching a 
changed public now with the exposure we are getting. Average Joe User 
might end up abusing our board enable table and land himself in trouble 
and then will blame us. While we of course are not liable, it is still 
bad publicity and something we should try to avoid.

We also can see how board matches have been written over time, and i 
believe that we should be stricter about them. Quite a few people have 
just added a single main pci id, and then added a coreboot name to the 
table as this was the absolute minimal effort required to make it work 
for them. This is how humans are, and how humans will continue to 
be, so we should make it harder for this to happen.

So in order to make it safer for Average Joe User, and in order to 
force developers to be less lazy here, i propose some changes;

* require 2 sets of pci-ids.

Can anyone name a motherboard which has only a single pci device that 
even comes close to our target hardware (in as far as we have target 
hardware). By requiring 2 sets, we improve safety and we force 
developers to be less lazy.

* if one value of any of the 4 subsystem ids is filled in, assume that 
the rest should be matched as is.

When subsystem ids are not filled in correctly, they sometimes remain 
null. Null values should not mean "match anything" they should mean null 
when even one of the value is valid.

I am a bit weary of adding a #define for 0xFFFF (the pciid "match 
anything"). I do not wish to encourage people to create an entry like:

blah, blah, 0xFFFF, 0xFFFF, blah, blah, 0xFFFF, 0xFFFF

and get away with it.

Multiple similar boards should be matched separately. And, since we 
usually have more than just a few pci devices in our device tree, 
chances are extremely good that at least two of them can be matched in 
some way or another, without a catchall.

* on legacy bioses, do not allow both pci subsystem ids and a name.

The most efficient way to do this seems the following:

If a name is provided, we should go over the table, checking for devices 
with both subsystem id sets nulled, and try to match the name. If the 
name matches, try to match main pci ids.

* Add separate logic for coreboot name matching.

This to still allow subsystem ids to be present, and thus to offset the
previous point. We really will end up with three different ways of 
matching boards.

Apart from actual code changes, we should apply the following:

* Be extremely weary of patches.
  * We need at least an lspci -vvnnxxxx.
    We have started to do this anyway now, collecting info for our 
    current table, while retaining info for future table alteration.
  * Do not accept missing subsystem ids for recent boards.
    Motherboards of this millenium tend to have subsystem ids filled in.
  * Usage of a coreboot name when coreboot is supported.
    Why would a coreboot developer set a separate write protect on the
    rom? The board enable could be valid though, but not for flash write 
    protection. If developers want to bring up a board, and have this 
    write protection disabling as a todo, then they can hack their own 
    code into flashrom.

Even if we only apply some of the above, we still need to clean up our 
board enable table.

Here is a list of boards with questionable matching, as a quick list. I 
will be digging each of them out properly and try to contact the 
original authors for more information. If you are the original author 
and happen to be reading this, then by all means, feel free to contact 
us right away.

Acorp 6A815EPD
agami Aruma
Artec Group DBE61
Artec Group DBE62
GIGABYTE GA-2761GXDK
GIGABYTE GA-M57SLI-S4
GIGABYTE GA-M61P-S3
GIGABYTE GA-MA790FX-DQ6
HP DL145 G3
IBM x3455
IWILL DK8-HTX
Kontron 986LCD-M
Kontron 986LCD-M 	(yes, twice)
MSI MS-6590 (KT4 Ultra)
MSI MS-6712 (KT4V)
MSI MS-7135 (K8N Neo3)
VIA EPIA-N/NL
VIA PC3500G

The following two devices are known to be valid, as they predate pci 
subsystem ids: the ASUS P5A (which i own) and the EPoX EP-BX3.

Luc Verhaegen.