<!-- ...................................................................... -->
<!-- $Id: openhpi_highlevel.sgml,v 1.10 2009/01/19 07:36:20 subrata_modak Exp $ ........................................ -->
<!-- 
        (C) Copyright Intel Corp
        (C) Copyright IBM Corp
 
        Authors:
            Rusty Lynch
            Sean Dague

        This material may be distributed only subject to the terms and 
        conditions set forth in the Open Publication License, v1.0 or later 
        (the latest version is currently available at 
        http://www.opencontent.org/openpub/).  Distribution of substantively 
        modified version of this document is prohibited without the explicit 
        permission of the copyright holder.

        Other company, product, or service names may be trademarks or service 
        marks of others.
-->

  <chapter>
  <title>OpenHPI 10,000 foot view</title>
  <para>
    This chapter attempts to give an overview of the current OpenHPI
    implementation.  It will always lag behind the actually source
    code base, so interested parties are best served by retrieving
    OpenHPI from our CVS repository, and joining the OpenHPI mailing
    lists.
  </para>
  <sect1>
    <title>Theory</title>
    <sect2>
      <title>Guiding Principles</title>
      <para>
        The goal of OpenHPI is to become the reference implemention
        for HPI.  HPI is an emerging specification, of great
        importance to those wishing to have a standardized mechanism
        for Platform Management.  By producing a reliable Open Source
        implementation of HPI, the OpenHPI team will help to turn HPI
        from an emerging specification to an industry standard.
      </para>
      <para>
        There are a few guiding principals behind 
        the design and implementation of the OpenHPI project. To succeed, 
        the project must be: 
      </para>
      <itemizedlist mark='opencircle'>
        <listitem>
          <para>
            <emphasis>Simple</emphasis> - the easier the code is to
            follow, the easier it is to find and fix bugs.
          </para>
        </listitem>
        <listitem>
          <para>
            <emphasis>Reliable</emphasis> - OpenHPI will be used in very
            dynamic environments, and will need to be as robust as
            possible.  To this end, the reliance on well known, well
            debugged external libraries is perfered to writing our own
            implementations of the same functions.
          </para>
        </listitem>
        <listitem>
          <para>
            <emphasis>Efficient</emphasis> - this is both in terms of
            performance as well as code re-use.         
            For performance, the reasons are obvious; you don't want your management layers 
            to bring down the performance of your system. In regard to code re-use--the more 
            that pieces of code can be re-used the faster that others can develop hardware 
            specific components to sit within the OpenHPI domain. 
          </para>
        </listitem>
      </itemizedlist>
    </sect2>
    <sect2>
      <title>Requirements / Expectations</title>
      <sect3>
        <title>Compliance</title>
        <para>
          OpenHPI will be a fully compliant
          implementation of the HPI specification.  The OpenHPI team
          is committed to providing a 100% compliant implementation HPI,
          and to that end has produced a compliance test suite as part
          of the OpenHPI project.  It is expected that many vendors may
          wish to reuse or contribute to the compliance test suite
          separate from the OpenHPI library itself.  
        </para>
        <para>
          As of the writing of this document, there has only be one
          official release of HPI (1.0, released October 2002).  Due
          to the nature of HPI specification design, the OpenHPI team
          can only have access to officially released material.  The
          OpenHPI team is committed to supporting future versions of
          HPI after they are released.  However, given OpenHPI is an
          Open Source project, and the requirements that any HPI
          branded product be fully compliant to and major release
          verion of the HPI spec, no formal commitment to the timing
          of future specification support can be made.
        </para>
      </sect3>
      <sect3>
        <title>Commercialization</title>
        <para>
          It is expected that many vendors may wish to offer a version
          of HPI for their users, but do not wish to incur the cost of
          developing an HPI solution from scratch.  OpenHPI wishes to
          be a reference implementation for these vendors.  For this
          reason OpenHPI is licensed under a BSD style license, that
          allows this commercialization.  Contributions by these
          entities back to the OpenHPI base are always welcomed and
          encouraged, but not required.
        </para>
        <para>
          To a similar end, it is expected the plugin interface will
          be standardized so that vendors may produce object code only
          enablement for their hardware when appropriate.  OpenHPI
          still encourages those vendors to contribute their sources
          back to OpenHPI whenever possible, but understands that this
          will not always be the case.
        </para>
      </sect3>
      <sect3>
        <title>External Requirements</title>
        <para>
          HPI is a new specification.  As of the writing of this
          document the OpenHPI team is unaware of any externally
          available HPI based applications or implementations.  Given
          that fact, the OpenHPI team is getting most of its
          requirements from the OpenHPI participants directly.  As
          available HPI applications become prevelant, OpenHPI expects
          to work with those application vendors to gather further
          external requirements which 
        </para>
      </sect3>
    </sect2>
  </sect1>
  <sect1>
    <title>Implementation</title>
    <para>
      To meet the above requirements the design is broken down into four major areas. 
      Each of these areas will eventually be defined in detail on subsequent pages. Brief 
      descriptions are provided below.
    </para>
    <sect2>
      <title>Application Interface Stubs</title>
      <para>This portion deals with the code that provides the entry points into 
        the libhpi.so. Initially this will literally just contain stubs that provide 
        API compliance without any features. Stub APIs will output to the stderr a 
        TODO: Implement _api_ message. As the api is implemented, these output messages 
        will be removed.
      </para>
    </sect2>
    <sect2>
      <title>Infrastructure</title>
      <para>The core library is considered infrastructure.  This is the
        section of code which provides and internal representation of
        resources and events, and exposes them as HPI data structures.
      </para>
    </sect2>
    <sect2>
      <title>Utility Functions</title>
      <para>
        The utility functions need by OpenHPI are provided by the
        glib utility library, this includes linked list and hash
        implementations.  This is a well tested library used by
        many open source projects (including gtk, gnome, and linux-ha).
        It is thread safe, so proper utilization of the library for
        OpenHPI data structures will ensure that OpenHPI is thread safe
        as well.
      </para>
    </sect2>
    <sect2>
      <title>OpenHPI Plugin Interface</title>
      <para>The OpenHPI plugin interface is the method of communication
        between the OpenHPI infrastructure and real hardware.  It is
        designed to be abstract enough to allow communication to any
        type of hardware over any sane interface (be that a device
        driver or network protocol).
      </para>
    </sect2>
    <sect2>
      <title>OpenHPI Plugins</title>
      <para>There exist a number of plugins in the OpenHPI source tree
        to enable different types of hardware and other interfaces.  The
        current ones are listed below:
      </para>
      <itemizedlist mark='opencircle'>
        <listitem>
        <para>
          <emphasis>Dummy</emphasis> - a static plugin which provides
            a number or resources statically to test the infrastructure.
          </para>
        </listitem>
        <listitem>
          <para>
            <emphasis>IPMI</emphasis> - an IPMI interface module based
            on the libOpenIPMI library developed by Correy Minyard.
          </para>
        </listitem>
        <listitem>
          <para>
            <emphasis>Watchdog</emphasis> - an interface to the Linux
            watchdog device.  Softdog can be used in place of a real
            hardware watchdog.
          </para>
        </listitem>
        <listitem>
          <para>
            <emphasis>Text_remote</emphasis> - a remoting plugin which
            talks to the openhpi daemon on a remote machine.  This
            allows multiple instances of hpi to be seen together in a
            single domain.
          </para>
        </listitem>
      </itemizedlist>
    </sect2>
  </sect1>
  </chapter>
