PEP

Pegasus Enhancement Proposal (PEP)

PEP #: 318

PEP Type: Functional

Title: 32bit providers in 64bit OpenPegasus

Version: 1.0

Status: Approved.

Version History:

Version	Date	Author	Change Description
0.1	29 feb 2008	Marek Szermutzky	Discussion draft
0.2	22 Sep 2010	Venkat Puvvada/Surendra Kodali	Initial version based on Marek's proposal
1.0	28 sep 2010	Venkat Puvvada/Surendra Kodali	Added libcmpiCppImpl library for CMPI C++ Providers. Ballot version

Abstract: Introduce support to run 32-bit providers in a 64-bit OpenPegasus

Definition of the Problem

There is a high number of providers available which are build for 32-bit platforms. Switching to 64-bit addressing becomes an obstacle as all those providers have to be rebuild, retested and sometimes even recoded.

Proposed Solution

Support for 32-bit providers in a 64-bit OpenPegasus can be reached by using the Out-of-Process support build into OpenPegasus. A 32-bit Out-of-Process agent(cimprovagt) executable plus its necessary libraries can run the 32-bit providers. The data transfered between the Out-of-Process agent (cimprovagt) and the CIM Server does not rely on the addressing mode of either side as objects exchanged between the CIM Server and the ProviderAgent are encoded in XML or internal binary.

13 libraries and 1 executable will need to be build as 32-bit. For this purpose platforms who wish to build 32-bit provider support will have to provide the necessary platform definition. For some platforms it might be possible to reuse the already existing definitions for 32-bit builds. A new build time option PEGASUS_PLATFORM_FOR_32BIT_PROVIDER_SUPPORT is introduced to enable 32-bit provider support. If the this option is set, the value MUST contain valid 32-bit supported platform name supported by OpenPegasus.

Executable:

cimprovagt (renamed as cimprovagt32)

Direct dependent libraries :

libpegpmrouter
libpegprovidermanager
libDefaultProviderManager
libpegprovider
libpegconfig
libpegclient
libpegqueryexpression
libpegwql
libpegquerycommon
libpeggeneral
libpegcommon

Libraries dynamically loaded by the cimprovagt based on build time options:

libCMPIProviderManager
libpegcql (used by libCMPIProviderManager if CQL enabled)
libcmpiCppImpl (used by CMPI C++ providers)

32-bit libraries and executable is built using the new top-level Makefile called as Makefile.cimprovagt32 (exists under Pegasus ROOT directory) which contains the necessary directories to build 32-bit provider agent. If the build option PEGASUS_PLATFORM_FOR_32BIT_PROVIDER_SUPPORT is set to any valid 32-bit platform, Makefile.cimprovagt32 is called from the main Makefile to build 32-bit provider agent which sets the PEGASUS_PLATFORM value with the value of PEGASUS_PLATFORM_FOR_32BIT_PROVIDER_SUPPORT. All 32-bit libraries are created under $(PEGASUS_HOME)/lib32 directory. All object (obj) files are created under $(PEGASUS_HOME)/obj32 directory. If obj directory is specified using the ALT_OBJ_DIR option, obj files are created under $(ALT_OBJ_DIR)32 directory. Executable file (named as cimprovagt32) is created under $(PEGASUS_HOME)/bin directory. Note that other required(based on build options) 32-bit dependent libraries(ex. SSL, ICU etc..) MUST be present on the build machine to build 32-bit provider agent successfully. PEGASUS_DEST_LIB_DIR environment variable is set to lib32 if not already defined otherwise "32" is appended to the value.

32-bit providers are registered to the CIM Server with a new property in PG_ProviderModule marking them as 32-bit providers and will then be executed in the 32-bit Out-of-Process agent. The following property is added to the PG_ProviderModule class.

      [Description(
        " Uint16 value indicating the provider module bitness."
        " This option is useful when the CIMServer is compiled"
        " to support different types of (bitness) provider modules. For"
        " example: 64 bit CIMServer supporting the 32-bit provider"
        " modules. \"Default\" indicates both provider module and"
        " CIMServer have same bitness."
        " \"32-bit\" indicates that the provider module is 32-bit type."
        " \"64-bit\" indicates that the provider module is 64-bit type."
        " \"128-bit\" indicates that the provider module is 128-bit type."
        " If the specified bitness is different from CIMServer bitness,"
        " the provider module is always loaded into out of process"
        " irrespective of forceProviderProcesses option value."),
      ValueMap {"1", "2", "3", "4"},
      Values {"Default", "32", "64", "128"}]
   uint16 Bitness;

Existing provider registrations in the repository will continue to work without any modifications. By default NULL value is assumed for the Bitness property and means that both CIMServer and provider module have same bitness.

Executer::startProviderAgent() method is modified to spawn the appropriate provider agent process based on the Bitness property of the PG_ProviderModule instance. The 32-bit version of the cimprovagt program is named as cimprovagt32. 32-bit version of the provider manager path is also passed to the 32-bit provider agent to load the appropriate provider manager. For release builds the 32-bit provider manager locations are fixed (see below). For non release builds, it is expected that the 32-bit provider managers exists in the directory after appending the "32" to providerManagerDir config property value. For example if providerManagerDir config property value is set to "lib", 64-bit provider managers are expected in $(PEGASUS_HOME)/lib directory and 32-bit provider managers in the $(PEGASUS_HOME)/lib32 directory.

How 32-providers work in the 64-bit CIMServer?

Build Pegasus using the PEGASUS_PLATFORM_FOR_32BIT_PROVIDER_SUPPORT option with valid 32-bit provider platform set. Build system creates the 32-bit provider agent and places the libraries under $(PEGASUS_HOME)/lib32 (non RPM build, RPM build explained below) and executable under $(PEGASUS_HOME)/bin (non RPM build, RPM build explained below)directory. For example "make build" or "make" in Pegasus root directory causes both 32-bit agent to be built and normal 64-bit CIMServer to be built. This is one step process. If changes are made to the source files those are part of the 32-bit provider agent, 32-bit libraries and executable must be rebuilt using the top-level makefile (ex, make cimprovagt32).
Register the providers by setting the PG_ProviderModule.Bitness property value to "2" (means 32-bit provider module).
When request comes to the 32-bit provider module, provider module is always loaded into out-of-process irrespective of the forceProviderProcesses config option. OOPProviderManagerRouter (or Executor process in case of privilege separation) creates the appropriate (in this case 32-bit) agent process.
Communication between CIMServer and cimprovagt process happens through anonymous pipe and data is encoded either in CIM-XML or internal binary which is independent of the bitness.

Release build changes for Linux and HP-UX (RPM builds)

32-bit libraries and executable are installed in the following directories.

PEGASUS_PROD_DIR = /usr
PEGASUS_ARCH_LIB = lib

PEGASUS_DEST_LIB_DIR = $(PEGASUS_PROD_DIR)/$(PEGASUS_ARCH_LIB)                             -----> cimprovagt32 direct dependent libraries(see above)
PEGASUS_SBIN_DIR = $(PEGASUS_PROD_DIR)/sbin                                                                  -----> cimprovagt32 (executable)
PEGASUS_PROVIDER_DIR = $(PEGASUS_PROD_DIR)/$(PEGASUS_ARCH_LIB)/Pegasus
PEGASUS_PROVIDER_LIB_DIR = $(PEGASUS_PROVIDER_DIR)/providers                                   ------> 32-bit providers staging directory
PEGASUS_PROVIDER_MANAGER_LIB_DIR = $(PEGASUS_PROVIDER_DIR)/providerManagers    ------> libCMPIProviderManager

Update to BuildAndReleaseOptions.html

PEGASUS_PLATFORM_FOR_32BIT_PROVIDER_SUPPORT

Description: Builds the Pegasus with 32-bit provider support for the specified platform. If this option is set, the value MUST be one of the 32-bit supported platforms by Pegasus.
Default Value: Not set
Recommended Value (Development Build): Not set
Recommended Value (Release Build): Not set
Required: No
Considerations: This option is used to run the 32-bit providers under 64-bit CIMserver. To register the 32-bit providers, register the provider module by setting the Bitness property value to "2". 32-bit Providers are always loaded out of process irrespective of forceProviderProcesses config option.

Testcases

Testcases are added to run 32-bit Default C++ test providers and CMPI test providers as part of nightly builds if the option PEGASUS_PLATFORM_FOR_32BIT_PROVIDER_SUPPORT is set on 64-bit platforms.

Schedule

Available in 2.11

Discussion

There are two possible ways of structuring the build process. Either a single Makefile is used to build the one executable and 14 libraries, or the build of the 32bit support is integrated into the 16 Makefiles which build the 64bit version.

Keeping everything in one Makefile will make more visible what is necessary for the 32-bit support. Against this approach speaks that it would mean replicating a lot of the existing Makefiles, possibly later on making service for that Makefile a nightmare.

Integrating the necessary changes into the existing Makefile structure will spread the changes out, but has the advantage that existing structures can easily be reused and even some of the existing unit tests can probably be reused.

Should the property in PG_ProviderModule be required for the 32-bit or the 64bit providers ? While it seems logical to assume that "legacy" providers would need the special marking, it might be better for supporting existing providers to mark the 64bit providers as such.

Comments on version 0.1

(b_whiteley) Have you considered instead adding a property to PG_ProviderModule to simply specify the full path to the cimprovagt?
(venkat_puvvada) Yes, this can also be done. But allowing the full path for the cimprovagt has security problems. From the end user perspective its simple to specify the bitness of the provider module rather than specifying the cimprovagt path.

(r_kumpf) With some reorganization, I think this list can be reduced. For example, libpegprm and libpegrepository are only used by the ProviderManagerService on the cimserver side. The ProviderManagerService class is not used by cimprovagt.
(venkat_puvvada) Completed with bug 8843.

(r_kumpf) The new PG_ProviderModule property will need to have an affect on which providers run out of process, if forceProviderProcesses=false.
(Venkat_puvvada) Yes, included in the deign.

(r_kumpf) The PEGASUS_DEST_LIB_DIR environment variable will need to be defined differently for the 32- and 64-bit builds, to allow the BasicProviderManagerRouter to dynamically load provider manager libraries from the correct location.
(Venkat_puvvada) Yes, included in the deign.

(b_whiteley) Neither of these approaches are needed. Think of a higher level approach. For example, you could do set the 32bit PLATFORM env var, and run a complete build. Then, do a 'make install' to some staging area. Now clean up and set the 64bit env var and run a complete build. Do a 'make install' to a different staging area. Now, collect the built 64bit components, and the necessary subset of built 32bit components, and include these in your package. This could be optimized, of course, by not doing a complete build for 32bit. Instead, just go to the directories of the needed components, and run 'make' there one by one in the proper order, instead of running a top-level 'make'. This is the way that we accomplished support for 32bit providers under a 64bit OpenWBEM. The OpenWBEM Makefiles didn't change at all. The work was done entirely in the RPM SPEC file.
(Venkat_puvvada) Yes, a top-level make file is written to build the 32-bit provider agent. See the release build changes section for updates to the RPM spec file.

(b_whiteley) A new environment variable may not be needed at all. See my comment to the first discussion item.
(venkat_puvvada) Without new environment variable this feature cannot be made optional and it providers 32-bit platform name.

(b_whiteley) As part of this PEP, we should move cimprovagt from /usr/sbin to somewhere under /usr/%_lib/Pegasus (where %_lib is either 'lib' or 'lib64'). This is the more appropriate location for cimprovagt regardless, since it is not intended to be executed by a human, and doesn't need to be in the PATH.
(venkat_puvvada) This is also good option. To be consistent with the existing installations, currently 32-bit cimprovagt program has been renamed to the cimprovagt32. Moving the cimprovagt to lib directory will be taken as separate enhancement.

Copyright (c) 2006 Hewlett-Packard Development Company, L.P.; IBM Corp.;
EMC Corporation; Symantec Corporation; The Open Group.

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to
deal in the Software without restriction, including without limitation the
rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
sell copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

THE ABOVE COPYRIGHT NOTICE AND THIS PERMISSION NOTICE SHALL BE INCLUDED IN
ALL COPIES OR SUBSTANTIAL PORTIONS OF THE SOFTWARE. THE SOFTWARE IS PROVIDED
"AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Template last modified: March 26th 2006 by Martin Kirk
Template version: 1.11