<!-- ...................................................................... -->
<!-- $Id: openhpi_structure.sgml,v 1.10 2009/01/19 07:36:20 subrata_modak Exp $ ........................................ -->
<!-- 
        (C) Copyright IBM Corp
 
        Authors:
            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 Structure</title>
  <para>
    This chapter is the first that gets into the nitty gritty of the
    basic mechanisms used by OpenHPI.  It will come slower than the
    rest, but will be updated constantly.
  </para>
  <sect1>
    <title>OpenHPI Plugins</title>
    <para>
      OpenHPI has two major parts, the core library (infrastructure),
      and the plugins.  The plugin mechanism allows OpenHPI to support
      numerous hardware types without requiring any core changes to
      the library.
    </para>
    <sect2>
      <title>Plugin ABI</title>
      <para>
        Every plugin is a libtool dynamic library.  The
        <literal>lt_dlopenext</literal> call is used to open and load
        the symbols from the plugin.
      </para>
      <para>
        Every plugin must include a <literal>get_interface</literal>
        function which populates an oh_abi_v2 structure.  This
        structure contains 35 function pointers, and is loaded only
        once per plugin.  Many of the functions in the plugin ABI map
        very closely to those in the SA HPI, however they are named
        with more Linux friendly naming convention (i.e. add_sel_entry
        vs. saHpiEventLogEntryAdd).
      </para>
      <para>
        The plugin ABI should not yet be considered stabalized, as
        there haven't been enough fully functional plugins to ensure
        that it can fulfill every possible type of plugin for the HPI
        1.0 interface.
      </para>
      <para>
        Once Plugins are loaded, their abi functions are stored in a
        global linked list.  This allows multiple instances of the
        same plugin to share the same function pointers.
      </para>
      <note>
        <para>
          SLD: We should probably change this to a hash for faster
          access
        </para>
      </note>
    </sect2>
    <sect2>
      <title>Handlers</title>
      <para>
        OpenHPI plugins are shared objects that are loaded by the
        plugin loader.  Handlers are instances of those objects
        created by the oh_abi_v2.open function included in the plugin.
      </para>
      <para>
        The handler open call is made during the saHpiSessionOpen
        function to generate a list of open handlers (stored in a
        global linked list).  The handles include pointers to the
        function table for the handler, and a <literal>void
          *</literal> generated by the handler during its open call.
        This is the location for the handler to store persistent data,
        as this pointer is passed to every plugin abi call except for
        <literal>open</literal>.  The contents of the pointer are
        currently not specified, however in future it may make sense
        to standardize the state struct which the handlers get during
        their processing.
      </para>
      <para>
        In many ways the use of the function pointer table, and
        persistent instance data is a rudimentary OO design.
      </para>
    </sect2>
  </sect1>
  
  </chapter>
