// vim:expandtab:autoindent:tabstop=4:shiftwidth=4:filetype=txt:textwidth=80:
/** \page presentation Libsmbios Concept/Design Review Presentation

    <H2>Why libsmbios?</H2>

    <p>Many systems management applications require access to data stored in the
    system SMBIOS table. Some sort of uniform mechanism is needed by diverse
    groups across Dell to access SMBIOS information. Currently there are
    numerous disjoint libraries within Dell used by various groups to get this
    information. This is not acceptable because we are collectively duplicating
    work instead of solving the underlying problem.

    <p>In this presentation, I have attempted to list all of the various reasons
    I have seen for the existing lack of code reuse and sharing in Dell in this
    specific area. I have then listed the specific ways in which libsmbios has
    sought to address each of these problems. Most of the existing 
    implementations of code to obtain information from SMBIOS present one or 
    more of the following difficulties:

    \li Dependency Management
    \li Changing Requirements
    \li Rigidity
    \li Fragility
    \li Immobility
    \li Viscosity of Design
    \li Viscosity of Environment

    Here is a brief description of each of the above problems, an example of the
    problem, and the ways in which libsmbios sets out to help with this problem.

<hr>
    <H3>Dependency Management</H3>
        <b>Problem:</b> Bringing in one small piece of code necessitates bringing in a pile of
        supporting code just to use the one component you want. Developers
        become hesitant to bring in code due to this. Some projects have tight
        space/depencency requirements that others may not have. Libs that do not
        target lowest common denominator are likely to be shunned.

        <b>Example:</b> DUP/SVM: managing compatibility against N prior versions of
        Disney because they have to work with existing installed version of
        Disney.

        How libsmbios helps: 
            - The open nature of libsmbios means users can 
              "have it their way"(TM) Users/clients can statically link 
              libsmbios for 'embedded, zero-install' use. Others can depend on a
              normal system library compiled. 

            - The driverless nature of libsmbios means users/clients need not
              manage driver dependencies for existing installs.

            - Open source means we can get this accepted into the Base OS and
              depend on there being a current version installed all the time.

<hr>
    <H3>Changing Requirements</H3>
        <b>Problem:</b> Code originally written for one project may not be suitable for another
        project due to differences in requirements between the projects. For
        example, one project might assume a static install on a target system,
        while another assumes that it must run with zero-install footprint.
        Obviously the latter will have great difficulty using the former,
        depending on the assumptions made by the former.

        <b>Example:</b> Autry/SVM cannot rely on existing, installed version of Disney
        to gather data, neither can they rely on Disney _not_ being installed
        and use their own because Disney lacks a contention resolution
        mechanism.  Catch-22 results.

        How libsmbios helps:
            - Libsmbios was designed to be 'splittable', ie. the core smbios
              parsing code has no external dependencies, and should be able to
              be used in any environment.

            - Libsmbios is open. Users can submit code to help libsmbios fit
              into places the original designers never thought to put it.

            - Libsmbios is based upon best-practice design with a solid unit
              testing framework. The development team can make changes to the
              framework and be confident that the design still works because of
              the depth of testing.

<hr>
    <H3>Rigidity</H3>
        <b>Problem:</b> "Tendency for software to be difficult to change, even in simple ways."
        For example, if the software does not have a clear and concise way of
        extending the code to support future systems, then people will be
        confused about how to add this support when it is needed. They may
        attempt to do it the "wrong" way, degrading the design.

        <b>Example:</b> Existing code for SMBIOS parsing from almost everywhere has no
        automated unit test framework to back up changes to the code. Every
        change to the code must undergo an extensive, manual unit test phase to
        ensure that problems are caught on every system, from legacy to
        yet-to-be released systems. If there are holes in the manual unit test 
        plan, then there are potential "test escapes".

        How libsmbios helps:
            - Extensive, in-depth, thorough, and automated unit test suite.
              Every change that a developer makes to the core library can
              immediately be tested to ensure that it works on every system,
              from legacy to development machines. There are over 20 platforms
              in the unit test database, with a clear, easy-to-use way to add
              new systems to the database. Over 1000 tests are run every time
              you run the unit test framework.

            - Built-in code coverage analysis. Every time you add code, you can
              inspect the code coverage analysis to ensure that the unit test
              framework is actually hitting the code that has been changed or
              added.

            - Built-in leak-detection analysis. Built-in leak detection when
              automated unit tests are run ensure that no memory leaks are added
              to the codebase.

            - To sum up: you can make changes to the codebase with confidence
              that you will not break working code.

<hr>
    <H3>Fragility</H3>
        <b>Problem:</b> "Tendency of software to break in many places each time it is changed."
        Closely related to Rigidity. This describes that aspect of software
        engineering where adding a new feature breaks previously-working
        features, or fixing a bug in one configuration breaks another
        configuration.

        <b>Example:</b> Everybody can supply their own example here where a change in
        one spot of the code broke a completely unrelated module. :-)

        How libsmbios helps:
            - see above under "Rigidity".

<hr>
    <H3>Immobility</H3>
        <b>Problem:</b> "Inability to reuse software from other projects or from parts of the 
        same project."

        <b>Example:</b>

        How libsmbios helps:
            - Open nature of libsmbios encourages everybody do both do their own
              thing and also contribute back their findings or new code. 

            - Portable design. Libsmbios is designed from the ground up to be
              portable to different OSs with minimal work and with little to no
              impact on existing platforms.

            - Existing projects within Dell cannot do things like support a
              completely new OS, for example SuSE, Debian, FreeBSD, Solaris, or
              BeOS without official support by the development team. Few 
              development teams would go out of their way to support non-Tier-1
              OSs. The Open nature of libsmbios, combined with a design that
              keeps an eye open for portability helps. People like Custom
              Engineering can maintain support for these platforms without
              impacting the mainline code. This means that Custom Engineering
              can benefit from the design and bugfixes in the mainline version
              without having to keep their own complete standalone version
              around and in-sync.

<hr>
    <H3>Viscosity of Design</H3>
        <b>Problem:</b> When "design preserving" methods of change are harder to employ than 
        design-destroying methods of change. 

        <b>Example:</b> Disney code to get System ID. One 300-line C function that
        covers all platforms. Developers adding a new system to this
        function are faced with the daunting task of figuring out _how_ to do
        this with no concrete way of knowing that their change broke no legacy
        platforms.

        How libsmbios helps: 
            - All functions where it is anticipated that there will be a
              different way of doing things in the future have been made
              extensible from the start. This makes it easy for engineers to
              come in later and do the "right" thing to add new support.
              For example: 
                - "Workarounds" framework to deal with BIOS bugs.
                - Clear, extensible system for getting System ID 
                - Clear, extensible system for getting System Name

<hr>
    <H3>Viscosity of Environment</H3>
        <b>Problem:</b> When development environment is slow and inefficient. Long compile
        times, long checkin times, etc.

        <b>Example:</b> ClearCase

        How libsmbios helps:
            - Come on guys, libsmbios can't fix <i>everything</i> :-)


<hr>
<hr>
    <H2>Design Principles</H2>

    <H3>The Open Closed Principle (OCP)</H3>
    We should write our modules so that they can be extended, without
    requiring them to be modified.

    We want to be able to change what the modules do without changing the source
    code of the modules.

    How this is applied to libsmbios:
        - All user/client visible interfaces are expressed in terms of abstract
        interfaces. All object creation is done by abstract factories, so
        people who want to extend libsmbios can supply their own factory to make
        new, user-defined types.

    <H3>The Dependency Inversion Principle (DIP)</H3>
    Always depend on abstractions rather than concrete implementations.

    How this is applied to libsmbios:
        - All user/client interfaces are abstract.

    <H3>Package Architecture</H3>
    The Release Equivalency Principle (REP)
        "The granule of reuse is the granule of release"

    The Common Closure Principle (CCP)
        "Classes that change together, belong together"

    The Common Reuse Principle (CRP)
        "Classes that are not reused together should not be grouped together."

    <H3>Package Coupling</H3>
    The Acyclic Dependencies Principle (ADP)
        "The dependencies between packages must not form cycles." 

    The Stable Dependencies Principle (SDP)
        "Depend in the direction of stability." 

        How this is applied to libsmbios:
            - Libsmbios is meant to be "stable". The base smbios parsing code
              has no external dependencies that would drive libsmbios to
              unexpectedly change. 

<hr>
<hr>

Statistics:
    \li Total .cpp size: ~5200 Raw LOC
        <p>~1300 Raw LOC for SMBIOS table parsing
        <p> ~800 Raw LOC for SMBIOS CMOS Token parsing/manipulation
        <p> ~700 Raw LOC for XML-Enhanced SMBIOS Parsing
        <p> ~400 Raw LOC for common 
        <p> ~450 Raw LOC for Memory access (Linux/Windows)
        <p> ~500 Raw LOC for CMOS access (Linux/Windows)

    \li Interface size (public .h files, incl docs): ~1600 LOC
    \li Implementation headers (private .h, incl docs): ~1200 LOC
    \li Portability headers: ~1500 LOC

    \li Total code size: ~9500 Raw LOC 
        - all headers and code files, not including generated headers.

<hr>
<hr>

credits:
    \li Material and descriptions shamelessly pulled from:
    http://www.objectmentor.com/publications/Principles%20and%20Patterns.PDF

<hr>
<p>
<p><small>there isn't anything else here. go back to the main page and look at the
pretty pictures. :-)</small>
<p>
*/