<!-- ...................................................................... -->
<!-- $Id: sahpi_breakdown.sgml,v 1.10 2009/01/19 07:36:20 subrata_modak Exp $ ......................................... -->
<!-- 
        Copyright (C) IBM Corp 2003

        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>Overview of SA HPI - 10,000 foot view</title>
  <para>The following chapter is designed as a primer on the SA HPI
    specification.  It is meant to represent the OpenHPI teams
    interpretation and explaination of various portions of the spec as we
    see it, and to help new users and developers come up to speed quickly
    in understanding the specification.  This chapter does not claim
    to be a comprehensive interpretation of the specification.  For
    that, one would need far more than the 113 pages which comprise
    HPI 1.0.  When in doubt, refer directly to the HPI 1.0
    specification.
  </para>
  <para>
    This chapter should always be
    considered a work in progress, and any questions or comments on it
    should be sent to the openhpi-devel@lists.sf.net mailing list.
  </para>
  <sect1>
    <title>Resource Model</title>
    <sect2>
      <title>Resources</title>
      <para>
        HPI provides a platform management interface which is entirely
        based on resources.  The crux of the entire HPI model is the
        Resource Presence Table (RPT).  Everything which can exist
        physically is represented in the RPT.  Every domain (we'll
        address domains later) contains one, and only one RPT.
      </para>
      <para>
        The RPT is a concept in HPI, though it isn't actually a data
        structure.  It is expected that implementers will create the
        proper data structure to encapsulate it.  What is specified is 2
        types of information:
      </para>
      <itemizedlist mark='opencircle'>
        <listitem>
          <para><emphasis>SaHpiRptInfoT</emphasis> - a meta data structure that
            contains the update time and incremental counter for the RPT.
          </para>
        </listitem>
        <listitem>
          <para><emphasis>SaHpiRptEntryT</emphasis> - The actually Resource
            Presence Table entries. It is expected that there will be
            many of them.
          </para>
        </listitem>
      </itemizedlist>
      <para>
        From here on in the term Resource will be synonymous with an
        object of SaHpiRptEntryT type.
      </para>
    </sect2>
    <sect2>
      <title>Resource Capabilities</title>
      <para>
        Every Resource has one field dedicated to capabilities of the
        resource.  This field is a 32bit vector, each bit
        corresponding to a capability.  They include:
      </para>
      <itemizedlist mark='opencircle'>
        <listitem>
          <para><emphasis>SAHPI_CAPABILITY_DOMAIN</emphasis> - the
            resource is a domain.
          </para>
        </listitem>
        <listitem>
          <para><emphasis>SAHPI_CAPABILITY_SEL</emphasis> - the
            resource has a system event log associated with it.
          </para>
        </listitem>
        <listitem>
          <para><emphasis>SAHPI_CAPABILITY_RDR</emphasis> - the
            resource has a rdr entries associated with it.  This is
            mandatory with HPI 1.0.
          </para>
        </listitem>
        <listitem>
          <para><emphasis>SAHPI_CAPABILITY_FRU</emphasis> - the
            resource is a field replacable unit.
          </para>
        </listitem>
      </itemizedlist>
      <para>
        There are many more capabilities as well.  For a full list,
        see page 103 of the HPI 1.0 Specification.
      </para>
    </sect2>
    <sect2>
      <title>Entity Path</title>
      <para>
        Resources are the logic representation of physical things.
        They may be a rack, a chassis, or a cpu.  Internal to HPI all
        resources are identified by a ResourceId.  However, the
        enumeration of this value is very implementation specific, so
        may not always be the best way to refer to resources.
      </para>
      <para>
        All resources in HPI have an entity path.  This is a 16
        element array of SaHpiEntityT structures.  The structure
        defines an entity type, and an instance number.  For instance:
        <literal>SAHPI_ENT_DISK_BAY 0</literal>.  The entity paths
        provide the real world physical topology of the resources.  So
        it could be well understood that the resource with
        ResourceId=37 was a CPU contained in the chassis which is
        ResourceId=21.  Entity paths <emphasis>must be
          unique</emphasis> within the context of a single Resource
        Presence Table.
      </para>
      <para>
        HPI entity paths go from least significant to most
        significant (i.e. the element to the right in the array is the
        container for the element on its left).
      </para>
      <para>
        <emphasis>OpenHPI Note:</emphasis> for the purposes of
        portibility OpenHPI has created a canonical string
        representation of the entity path.  It involves removing the
        SAHPI_ENT_ prefix from the types, and creating tuples for the
        entity types.  Order of significance is inverted to make
        entity paths look more like Unix directory structure. It is
        also assumed that {ROOT,0} exists implicitly before all of
        these entries.  Examples look as follows:
      </para>
      <itemizedlist mark='opencircle'>
        <listitem>
          <para>{SYSTEM_CHASSIS,2}{PROCESSOR_BOARD,0}</para>
        </listitem>
        <listitem>
          <para>{COMPACTPCI_CHASSIS,1}{IO_BLADE,12}</para>
        </listitem>
      </itemizedlist>
   </sect2>
    <sect2>
      <title>Resource Data Records</title>
      <para>
        Associated with every Resource are Resource Data Records
        (RDRs).  <literal>SAHPI_CAPABILITY_RDR</literal> is required
        to be on for all resources in HPI 1.0 (this appears to be
        changing based on early errata released).  There is a many to
        one relationship between RDRs and Resources, and it is
        expected that all resources will have many RDRs.
      </para>
      <para>
        RDRs come in 4 types: Sensor, Control, Inventory, or
        Watchdog.  Where the Resources represent a physical object,
        the RDRs represent a quality of that object.  For instance a
        Motherboard (a Resource) may have many thermal sensors (Sendor
        RDRs), voltage sensors (Sensor RDRs), remote power control
        (Control RDR), programmable leds (Control RDRs), and inventory
        function (Inventory RDR).
      </para>
      <para>
        RDRs are basically the meta information describing a sensor
        (or other type).  There are a set of functions for accessing
        the actual hardware for each of the types defined in the HPI.
      </para>
      <para>
        The connecting element in the relationship between RDRs and
        Resources is the entity path.  Although entity path will
        uniquely identify a Resource, it will identify one or more
        RDRs that are associated with that Resource.
      </para>
    </sect2>
    <sect2>
      <title>Discovering Resources</title>
      <para>
        HPI specifies that resources should be discovered dynamically.
        It is expected that over the life of an HPI consuming
        application the resources represented to it will change.  This
        may come from a user action (i.e. adding a new blade to the
        chassis), or from a non user driven action (i.e. disk failure in
        a rack mount server).
    </para>
    <para>
      Given the dynamic nature of Resources, the first thing that must
      be done once an open session is created is a discovery of all
      resources.  The HPI call
      <literal>saHpiResourcesDiscover</literal> provides this
      mechanism.  This function is meant to be called any time the
      user wishes to ensure the RPT is a current reflection of the
      Resources that exist in their environment.  
    </para>
    <note>
      <para>
        It is unclear in the specification whether this is meant to be
        a blocking call or not.  However, given the tone of the
        section on resource discovery, and the assumption by the user
        that after <literal>saHpiResourcesDiscover</literal> is called
        the RPT table can be walked, the OpenHPI has decided that it
        must be implemented as a blocking call.
      </para>
    </note>
    <para>
      It is not specified that the RPT will only be updated by
      saHpiResourcesDiscover.  However, no guaruntees are provided by
      HPI as to how often the RPT will be updated.  This item is
      implementation specific, so all users are advised to refresh the
      RPT before assuming the Resources accurately reflect the state
      of the system.
    </para>
  </sect2>
  </sect1>
  <sect1>
    <title>Event Model</title>
    <para>
      If Resources are the nouns of HPI, Events are the verbs.
      Based on flags set on Resources, events will be generated by
      changes in RDR values.  This section attempts to clarify what
      events mean in an HPI context.
    </para>
    <para>
      There are 2 types of events in HPI, which are based solely on
      their level of persistence.  Normal HPI Events are transient
      objects that sit on an event queue until processed by the user, at
      which time they disappear entirely.  Some subset of these Events
      may be made persistent by inserting them into a System Event
      Log (SEL).  The logic for which events end up in a SEL is
      entirely determined by the implementation.
    </para>
    <sect2>
      <title>HPI Events</title>
      <para>
        HPI Events refer to the transient Events that are generated
        within the HPI infrastructure.  The reason for HPI event
        generation can be many.  The failure of a resource, the loss
        of redundancy of a resource, a sensor value exceeding a
        warning threshold, or many other reasons.
      </para>
      <sect3>
        <title>Sensor Events</title>
        <para>
          Sensor Events are easily quantifiable.  Event generation for
          a sensor is specified via
          <literal>saHpiSensorEventEnablesSet</literal>. This may
          include both assertion (crossing a threshold), and
          deassertion (returning to a "safe" value from the
          threshold).  For all sensors that have events enabled, on
          any RPT update those sensor value will be compared to the
          set threshold, and events will be generated if appropriate.
        </para>
      </sect3>
      <sect3>
        <title>Non Sensor Events</title>
        <para>
          Non sensor events a bit trickier.  What qualifies as
          "redundancy loss" requires extreme knowledge of the hardware
          being examined.  The exact manner of the generation of these
          events is not specified in HPI, and is left to the
          implementer to create them.
        </para>
      </sect3>
    </sect2>
    <sect2>
      <title>Accessing Events</title>
      <para>
        The method for accessing events is multi step process.  First,
        a user must subscribe to events within a domain.  When a
        subscription for events occurs, the user may specify whether
        they wish to see events that have already occured, or merely
        see events from the current time forward.
      </para>
      <para>
        Events are then fetched by a polling function call
        <literal>saHpiEventGet</literal>.  This function specifies a
        timeout that it is willing to wait for an event if one is not
        readily available.  This timeout can be specified as
        <literal>SAHPI_TIMEOUT_BLOCK</literal>, which will cause the
        function to block until such time as an event is available.
        If any other timeout value is specified, and no event exists
        in the event queue during the timeout period, the function
        will return NULL.
      </para>
      <note>
        <para>
          SLD: In a multiple tenant environment, how does one process
          events properly?  If events are transient, the first
          processing should purge them.  In OpenHPI's current model,
          this shouldn't be a problem, as events will all exist in
          all OpenHPI instances because they are in separate memory
          environments.  However, if a daemon model were chosen, this
          would be an issue.
        </para>
      </note>
    </sect2>
    <sect2>
      <title>System Event Logs</title>
      <para>
        If a Resource has the <literal>SAHPI_CAPABILITY_SEL</literal>
        bit set, there is a System Event Log (SEL) associated with that
        resource.  The SEL is a repository for events
        that can later be retrieved via HPI calls.  SELs come in 2 flavors, Domain Level,
        and Resource Level.
      </para>
      <para>
        A Domain Level SEL is implemented in software, and
        contains events associated with the domain.  There is
        exactly one Domain level SEL per domain.  These may
        have been generated because HPI has been told to monitor
        the temperature of a sensor, and on the latest polling for
        that data, the sensor exceeded the threshold.  The
        important part to remember is that the events in the
        Domain level SEL are HPI originated, based on rulesets in
        HPI.
      </para>
      <para>
        A Resource (which is not a domain) will have the
        <literal>SAHPI_CAPABILITY_DOMAIN</literal> bit turned on
        if that resource represents a piece of hardware which
        contains a hardware implemented SEL.  For instance, most
        server mother boards have an SEL that monitors what the
        hardware considers critical events.  This may include a
        fan failure, a boot failure, or other events.  Unlike
        Domain level SELs, the decision mechanism for what events
        get generated in a Resource SEL are not under the control
        of HPI.  They are hardcoded in the hardware directly.
      </para>
      <para>
        There may be mechanisms for changing what events get
        generated in an Resource SEL.  However, those controls are
        beyond the scope of HPI.
      </para>
      <warning>
        <para>SLD: Did I get this right?  Seems odd, perhaps it is
          too late on friday</para>
      </warning>
      <sect3>
        <title>Populating Event Logs</title>
        <para>
          Which events qualify for Domain SEL addition is an
          implementation specific question.
          For Resource level events, these are
          generated by hardware and stored in hardware, so the question
          of event population is <emphasis>extremely</emphasis> hardware
          specific.
        </para>
      </sect3>
      <sect3>
        <title>Manipulating Event Log Entries</title>
        <para>
          HPI provides a number of functions to add, delete, and get
          entries from SELs.  It also allows clearing of the SEL.
        </para>
        <warning>
          <para>
            Not all hardware allows adding of event log entries from
            user space.  How does one deal with this?
          </para>
        </warning>
      </sect3>
    </sect2>
  </sect1>
  <sect1>
    <title>Domain Model</title>
    <sect2>
      <title>Domains</title>
      <para>
        The concept of Domains has come up a number of times in the
        design spec.  On even cursory reading of the HPI
        specification, it can be seen that domains take up a large
        portion of the specification.  Domains are arbitrary logical
        groupings of resources.  They can be overlapping (i.e. the
        same resource can appear in multiple domains), and they need
        not be hierarchical.
      </para>
      <para>
        The intended use of Domains appears to be as a security
        mechanism.  Page 18 of the HPI 1.0 specification describes
        domains to be used by a "Lanlord" to get access to a set of
        resources by a "Tenant".  A problem that arises from this
        interpretation is the requirement in HPI 1.0 that the security
        pointer to saHpiSessionOpen be NULL.  Because of this fact,
        privilege separation can not be acheived through the HPI
        interface in its current incarnation.
      </para>
    </sect2>
    <sect2>
      <title>OpenHPI's take on Domains</title>
      <para>
        Because of this fact, the OpenHPI team has decided
        <emphasis>not to implement multiple domains</emphasis> at this
        time.  If there is no way to privilege separate users, then
        all users have access to all resources anyway.  Hence,
        security is not made any better.
      </para>
      <para>
        Of further note, OpenHPI is expected to be utilized and
        productized by many different organizations for different
        purposes.  Given this, it seems counter productive to have
        OpenHPI itself enforce policy about what qualifies as a
        Domain.  There are ideas about how multiple domains will be
        implemented in OpenHPI in the future, and how site admins will
        be able to configure the domain structure to fit their site
        policy.  If you wish to participate in this element of design,
        please join our mailing list and speak up.  We are more than
        happy to accept new volunteers.
      </para>
    </sect2>
    <sect2>
      <title>Sessions</title>
      <para>
        Closely associated with Domains are sessions.  The second call
        that any application must make when interfacing with HPI is
        <literal>saHpiOpenSession</literal>.  It takes a DomainId as
        an identifier, and provides a session handle which allows the
        user to access resources only within that Domain.
      </para>
      <note>
        <para>
          As OpenHPI only uses <literal>SAHPI_DEFAULT_DOMAIN</literal>
          applications using OpenHPI will only have to open a single
          session.
        </para>
      </note>
    </sect2>
  </sect1>
  <sect1>
    <title>SA HPI Data Structures</title>
    <sect2>
      <title>RPT Data Structures</title>
      <para>
        The following is an unrolling of SA HPI Data Structures
        surrounding the RPT.  For sake of sanity, it is unrolled only
        as far as the high level RDR types.  Those will be broken down later.
      </para>
      <mediaobject>
        <imageobject>
          <imagedata fileref="images/saf_hpi_rpt.png">
        </imageobject>
      </mediaobject>
    </sect2>
  </sect1>
</chapter>
