Chapter 3. Overview of SA HPI - 10,000 foot view

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.

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.

3.1. Resource Model

3.1.1. Resources

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.

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:

  • SaHpiRptInfoT - a meta data structure that contains the update time and incremental counter for the RPT.

  • SaHpiRptEntryT - The actually Resource Presence Table entries. It is expected that there will be many of them.

From here on in the term Resource will be synonymous with an object of SaHpiRptEntryT type.

3.1.2. Resource Capabilities

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:

  • SAHPI_CAPABILITY_DOMAIN - the resource is a domain.

  • SAHPI_CAPABILITY_SEL - the resource has a system event log associated with it.

  • SAHPI_CAPABILITY_RDR - the resource has a rdr entries associated with it. This is mandatory with HPI 1.0.

  • SAHPI_CAPABILITY_FRU - the resource is a field replacable unit.

There are many more capabilities as well. For a full list, see page 103 of the HPI 1.0 Specification.

3.1.3. Entity Path

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.

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: SAHPI_ENT_DISK_BAY 0. 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 must be unique within the context of a single Resource Presence Table.

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).

OpenHPI Note: 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:

  • {SYSTEM_CHASSIS,2}{PROCESSOR_BOARD,0}

  • {COMPACTPCI_CHASSIS,1}{IO_BLADE,12}

3.1.4. Resource Data Records

Associated with every Resource are Resource Data Records (RDRs). SAHPI_CAPABILITY_RDR 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.

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).

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.

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.

3.1.5. Discovering Resources

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).

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 saHpiResourcesDiscover 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.

Note

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 saHpiResourcesDiscover is called the RPT table can be walked, the OpenHPI has decided that it must be implemented as a blocking call.

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.