Hardware Platform Interface - Backward Compatibility

Backward Compatibility

It is a goal of the SA Forum that new versions of its specifications be kept backward compatible with previous versions. In the case of the HPI specification, this means that user programs written to work with HPI implementations of a certain version should continue to work without change with HPI implementations that support a later version of the specification. This goal has been met with HPI specifications published since the SAI-HPI-B.01.01 specification. The “B” series of HPI specifications are not backward compatible with the SAI-HPI-A.01.01 specification.

To achieve backward compatibility of HPI specifications, several strategies are employed:
a) Functions defined in earlier versions of the HPI specification are included in later versions, with no change to the function prototype. Obsolete functions are retained, but advice is included in the specification that they should not be used by new user programs.
b) New functions may be added in new versions of the HPI specification, as long as their use is not required by existing programs.
c) Various enumerations that report data like hardware Entity types, Sensor types, etc. are declared in the HPI specification as being open-ended. The list of error return codes that HPI functions may return is also declared as open-ended. New versions of the HPI specification do not remove or change any existing enumerated values, but may add new values to an open-ended enumeration. User programs should accept values that are not currently defined and treat them as “valid but undefined.” By doing so, the program can continue to work when it is used with an implementation that is built to a newer version of the HPI specification, which may have defined new values for the enumeration.
d) Data structures passed from HPI functions to the user may not grow in length in new versions of the HPI specification or change the format of the data that was defined in previous versions. However, previously undefined bits in bit-fields may be defined in new versions of the HPI specification, and unused space in unions may be used, as long as programs that do not recognize the new bits or new use of unused space will continue to operate correctly.
e) Data structures passed to HPI functions from the user may change in new versions of the HPI specification, as long as the change is made in a way such that an existing program passing the earlier defined structure will continue to operate correctly.