Perl interface to liblgrp (3LIB). Alexander Kolbasov 1. Summary The PSARC cases 2003/034 (Lgroup APIs), 2004/777 (lgrp_latency Extension) and 2004/836 (Lgroup Resource Interface) introduce a number of library calls as well as constants. These library calls provide the caller with extensive information about NUMA topology of the system. In order to make access to the contents possible from a scripting language rather than C, we propose a perl extension (XSUB) to provide a wrapper around the existing C liblgrp(3LIB) library. 2. Discussion. At present, the only way to access the information about the system topology is via the C API provided by liblgrp. This requires both a C compiler and a knowledge of C. By writing a perl wrapper to the liblgrp library, the interface can be simplified, for example, by hiding the details of the memory management that is required if the C API is used. Providing access to the liblgrp API from a scripting language facilitates creating customized reporting and extraction scripts (in perl rather than C). This fast track is intended to provide a perl interface to the underlying liblgrp(3LIB) API. The goal is to provide a perl interface that is functionally equivalent to the underlying C API. As much as possible, the data obtained from the underlying C API is presented as perl data types. However, the return value of all functions in case of error has been changed from -1 to the perl 'undef' value. The perl wrapper module is used by the lgrpinfo(1) utility for displaying the lgroup hierarchy and its contents and characteristics. It is also used by various tests. 3. Interface The module Sun::Solaris::Lgrp provides the following functions which are direct wrappers over their C equivalents: lgrp_init(3LGRP) lgrp_fini(3LGRP) lgrp_version(3LGRP) lgrp_affinity_get(3LGRP) lgrp_affinity_set(3LGRP) lgrp_children(3LGRP) lgrp_cookie_stale(3LGRP) lgrp_cpus(3LGRP) lgrp_home(3LGRP) lgrp_latency(3LGRP) lgrp_latency_cookie(3LGRP) lgrp_mem_size(3LGRP) lgrp_nlgrps(3LGRP) lgrp_parents(3LGRP) lgrp_root(3LGRP) lgrp_view(3LGRP) lgrp_resources(3LGRP) In addition, the module provides the following functions which are not present in liblgrp(3LIB): lgrp_lgrps() - Returns list of all lgroups in the system lgrp_leaves() - Returns list of all leaf lgroups in the system lgrp_isleaf() - Returns 1 for leaf nodes, 0 otherwise. The module also provides class-based interface to all the functions above with the following object methods: new() DESTROY() version() affinity_get() affinity_set() children() cookie_stale() cpus() home() latency() mem_size() nlgrps() parents() root() view() resources() lgrps() leaves() is_leaf() It also provides the following constants: LGRP_AFF_NONE LGRP_AFF_STRONG LGRP_AFF_WEAK LGRP_CONTENT_DIRECT LGRP_CONTENT_HIERARCHY LGRP_MEM_SZ_FREE LGRP_MEM_SZ_INSTALLED LGRP_VER_CURRENT LGRP_VER_NONE LGRP_VIEW_CALLER LGRP_VIEW_OS LGRP_NONE LGRP_RSRC_CPU LGRP_RSRC_MEM LGRP_CONTENT_ALL LGRP_LAT_CPU_TO_MEM The functions behave generally exactly like their "C" counterparts, but have been "perlized" in some cases. For example, they return "undef" or a result instead of "-1" and return list of values instead of C arrays. The stability level is Unstable. Requested release binding is Patch (since we should be able to provide this module for updates back as far as Solaris 9 Update 5). 4. Compatibility. Currently, there are two versions of the liblgrp library available on different versions of Solaris. Solaris 9 Update 5 and above and Solaris 10 support version 1 of the liblgrp API as described in PSARC 2003/034 (Lgroup APIs). Solaris 10 Update 1 and above and Solaris 11 support both version 1 and version 2 which includes additional functions and constants defined in PSARC cases 2004/836 (Lgroup Resource Interface) and 2004/777 (lgrp_latency Extension). The following functions are only present in the version 2 of the liblgrp: lgrp_resources(3LGRP) lgrp_latency_cookie(3LGRP) The following constants are only present in version 2 of the file: LGRP_RSRC_CPU LGRP_RSRC_MEM LGRP_CONTENT_ALL LGRP_LAT_CPU_TO_MEM The Sun::Solaris::Lgrp module automatically determines the version of the library used on the system where the module is installed. If it detects version 1, the following happens: - The call to lgrp_resources() returns undef. - The lgrp_latency_cookie() ignores the cookie value and returns the result of lgrp_latency() instead. The module still provides all of the version 2 constants. As a result, the Sun::Solaris::Lgrp module can be installed on systems running either version 1 or version 2 of the liblgrp library. 5. References. PSARC 2003/034 lgroup APIs PSARC 2004/777 lgrp_latency Extension PSARC 2004/836 Lgroup Resource Interface Project Web Page, including online documentation http://www.opensolaris.org/os/community/performance/numa/observability/tools/perl_lgrp 6. New manual pages Lgrp(3PERL) See Lgrp.txt