1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97
|
// vim:expandtab:autoindent:tabstop=4:shiftwidth=4:filetype=c:
//
//Do not use "\section", "\subsection", or other page-related commands here as
//this file is inlined in the ISmbios.h file.
//
/** \page workaround_theory Implementation of Workarounds and Exceptions
*
* <b>Overview</b>
*
* <p>A sad fact of life is that software has bugs. The system BIOS is no
* exception, and facilities must be designed in from the ground up to deal
* with exceptions in SMBIOS table where important and critical data in the
* SMBIOS table is wrong. If the design does not take this fact into
* account, then over time the design will be compromised as workaround
* after workaround are inserted into the code to fixup problems.
*
* It is with this in mind that a standard way to fixup buggy and broken
* tables was designed. A few points were kept in mind when doing the
* design:
* \li Client code outside of libsmbios should never see bad data.
* \li All workarounds should be "Data-driven" and not "Code-driven". We
* should be able to come up with a grammar to describe the bugs, their
* symptoms, and their fixups that is generic. No source code should need
* to change to add a new workaround.
* \li All fixups should be performed as close to the data source as possible to
* limit "leaking" of workaounds all over the code.
* \li No code inside the ISmbiosTable or ISmbiosItem heirarchy should ever
* have to take into account workarounds.
* \li Workarounds should have the smallest possible effect on the speed of
* normal operations on a table.
* \li Design of the workaround code should not force private data into the
* public namespace just so that workarounds can be applied.
*
* <b>Prevention is the best medicine</b>
*
* <p>One outcome of the libsmbios project is a tool that can be used to
* validate BIOS conformance to all of the relevant specifications. This
* tool, validateBios (on Linux) and validateBios.exe (on Windows) can be
* used to verify that all BIOS properly implements all specifications.
*
* <p>The validateBios executable is a natural outgrowth of the unit test
* suite. When first written, the purpose of the unit test suite was to find
* bugs in the libsmbios code and prevent them from progressing beyond an
* individual developer workstation. This approach was highly successfull,
* but after a certain point, the unit test suite went beyond finding bugs
* in libsmbios code and started finding bugs in the BIOS test data sets
* that were used.
*
* <p> At this point, it was easy to just paste in the failing functions
* into a separate executable that can be distributed to the BIOS team. This
* has been done, and work to add more tests to this executable are ongoing.
* We hope that the BIOS team adopts the libsmbios validateBios executable
* as part of their standard testing methodology for testing all potential
* BIOS releases.
*
* <b>Theory of Operation</b>
*
* The fundamental point upon which the workaround concept is based is that
* the ISmbiosTable object will normally have a buffer of the pristine
* SMBIOS table, as read from memory. The ISmbiosItem class gets its own
* copy of its individual data buffer when it is instantiated from the table.
* The workaround framework takes advantage of this fact to fixup the raw
* ISmbiosItem data after it is instantiated, but before the client code has
* a chance to ever look at potentially wrong data in the Item.
*
* This insertion into the instantiation, and fixup of the item's raw data
* meets most of the design objectives for the workaround design.
*
* <b>Implementation</b>
*
* The ISmbiosTable object contains a Workaround object. This workaround
* object is initialized at the same time that the table is created. The
* workaround initialization process uses the raw table data to initialize
* enough of itself to select the appropriate set of workarounds for the
* system it is running on. After the workaround object has been
* initialized, workarounds are active.
*
* Creation of ISmbiosItem objects is centrally controlled by the
* ISmbiosTable::makeItem() function. It is here where the workaround fixups
* are applied. First, the item is created normally. Next, the item's
* ->fixup() method is called with the table's workaround instance as a
* parameter.
*
* The next step is the ISmbiosItem calls the workaround object's
* ->fixupItem() function call. The parameters are the item's "this"
* pointer, a pointer to the item's raw buffer, and the size of the raw
* buffer.
*
* The purpose of this circuitous chain of function calls is to ensure the
* following:
* \li ISmbiosItem never needs to know about the containing table's workaround
* object
* \li Workaround never needs to access non-public data and/or methods in
* the ISmbiosItem.
*
*
*/
|