Difference between pages "r7.1.1:Building Guide (benchmark)" and "r7.1.1:Function libbenchmark misc pal helper add logical processor node to topology tree"

From liblfds.org
(Difference between pages)
Jump to navigation Jump to search
m (1 revision imported)
 
m (1 revision imported)
 
Line 1: Line 1:
{{DISPLAYTITLE:Building Guide (benchmark)}}
{{DISPLAYTITLE:function libbenchmark_misc_pal_helper_new_topology_node}}
==Introducton==
==Source Files==
The ''benchmark'' binary is a thin command line veneer which provides convenient access to the benchmark functionality in ''libbenchmark''. The binary depends on ''liblfds711'', ''liblfds700'', ''libbenchmark'' and ''libshared''.
└───test_and_benchmark
    └───libbenchmark
        ├───inc
        │  └───libbenchmark
        │          libbenchmark_porting_abstraction_layer.h
        └───src
            └───libbenchmark_misc
                    libbenchmark_misc_pal_helpers.c


The ''benchmark'' library uses a porting abstraction layer to mask platform differences. Building ''benchmark'' requires build files (makefile, etc) for your toolchain (GCC, gnumake, etc) and a port of the abstraction layer to your platform.
==Opaque Structures==
struct [[r7.1.1:struct libbenchmark_topology_state|libbenchmark_topology_state]];


A small number of popular toolchains are supported out-of-the-box, along with porting abstraction layers which cover Windows (user-mode) and Linux (user-mode).
==Prototype==
void libbenchmark_misc_pal_helper_add_logical_processor_node_to_topology_tree( struct libbenchmark_topology_state *ts,
                                                                                lfds711_pal_uint_t logical_processor_number,
                                                                                enum flag windows_processor_group_inuse_flag,
                                                                                lfds711_pal_uint_t windows_processor_group_number );


==Supported Toolchains==
==Parameters==
The supported toolchains are;
''struct libbenchmark_topology_state *ts''
: A pointer a ''struct libbenchmark_topology'' obtained from ''libbenchmark_pal_populate_topology''.


* GCC and gnumake
''lfds711_pal_uint_t logical_processor_number''
* MSVC and gnumake (yes, gnumake, not nmake)
: The logical processor number of the logical processor to add to the topology tree pointed to by ''ts''.


Additionally, there is a second variant of the GCC and gnumake toolchain, which adds NUMA support in the form of ''libnuma''.  All builds depend on releases 7.1.1 and 7.0.0 of ''liblfds''.  This is because the benchmark application benchmarks previous versions, as well as the current version, of ''liblfds'' data structures.  Releases 7.1.1 and 7.0.0 offer exactly the same platform support, so if 7.1.1 can compile, so can 7.0.0.
''enum flag windows_processor_group_inuse_flag''
: An ''enum flag'' which indicates whether or not the ''windows_processor_group_number'' argument contains a valid value (for that field is only meaningful on Windows 7 and greater).


The ''libnuma'' library is necessary under Linux to access NUMA functionality.  However, the library is an installed package and as such may or may not be installed.  It is not possible in C to optionally include header files, or to detect whether or not they are present; as such either something must detect the presence of absence of the libnuma library and its header file and then construct the makefile (the route taken with ''configure'') or the makefile must indicate to the build (through, say, a define passed to the compiler command line) whether or not libnuma is present.  The makefiles are intended to be platform indepedent, to support for example arbitrary embedded platforms, and so the presence of ''ldconfig'' cannot be assumed.  As such, there is no obvious way to determine the presence of absence of ''libnuma'' - so as such, there is a seperate "toolchain" which is the normal GCC and gnumake makefile but with linking to ''libnuma'' and a define passed to the compiler.
''lfds711_pal_uint_t windows_processor_group_number''
: The Windows processor group number of the logical processor to add to the topology tree pointed to by ''ts''.  This value is only meaningful on Windows 7 and greater.  It will only be used if the ''windows_processor_group_inuse_flag'' is set to ''RAISED'', and so if not used, can be set to any value.  Zero is as good a choice as any other.


Note that in 7.1.1, Visual Studio solution files are not provided.  This is because there are over ''liblfds'' and the ''benchmark'' and ''benchmark'' libraries and programmes (seven projects in all) in the end due to the multple build variants (debug, release, library, DLL, kernel library, kernel DLL, and repeated twice, once for VS2012 and once for VS2013) what comes to something like ten thousand settings, all of which have to be set using a mouse and a GUI, which is not only extraordinarily time-consuming and error-prone, but emotionally agonizing.
==Return Value==
No return value.


In all cases, the build files know where the various ''liblfds'' header and library files are, and so nothing needs to be installed for ''benchmark'' to build.
==Example==


Mac support is not available due to lack of access to a Mac.
==Notes==
 
This helper function is used by ''libbenchmark_pal_populate_topology'' to add a logical processor node to the topology tree.
==Directory Structure==
└── test_and_benchmark
    └── benchmark                                                : benchmark command line veneer
         ├── bin                                                  : output directory - the binary ends up here
         ├── build                                                : build configuration directory - contains one directory per platform
         │   ├── gcc_gnumake_hosted_liblfds711_liblfds700          : GCC, gnumake, hosted implementation, liblfds 7.1.1 and liblfds 7.0.0
         │   ├── gcc_gnumake_hosted_liblfds711_liblfds700_libnuma  : GCC, gnumake, hosted implementation, liblfds 7.1.1, liblfds 7.0.0 and libnuma
         │   └── msvc_gnumake_liblfds711_liblfds700                : Microsoft Visual C (command line compiler), gnumake, liblfds 7.1.1 and liblfds 7.0.0
         ├── obj                                                  : temporary directory for object files
         └── src                                                  : the source files
 
==Building==
The ''benchmark'' directory tree contains at its top level directory called ''build''.
 
This directory contains one directory per supported toolchain, where each such directory contains the files necessary to build for that toolchain.  Detailed descriptions of how to build for each toolchain are given below, with one heading per toolchain.
 
The ''benchmark'' binary depends on ''liblfds711'', ''liblfds700'', ''libbenchmark'' and ''libshared''.  The ''benchmark'' build files are hardcoded with relative paths to find the output from these libraries, so these libraries do not need to be installed.
 
On all platforms, you need to clean between changing build types (debug, release, static, dynamic, profiled, etc), as there is only one directory used to hold object files.
 
==Per-Toolchain Build Instructions==
 
===GCC and gnumake===
└── test_and_benchmark
    └── benchmark
        └── build
            └── gcc_gnumake_hosted_liblfds711_liblfds700
                    Makefile
 
To build, install GCC and gnumake, enter the build directory and type;
 
make
 
The following targets are available;
 
cov    : coverage
dbg    : debug
prof    : profiling
rel    : release
tsan    : thread sanitizer
vanilla : no specific-build arguments
clean  : what you'd expect
 
When switching from one target to another, ''clean'' must be made.
 
If building ''*_ar_tsan'', ''libtsan'' must be installed.  This is not necessary if building ''*_so_tsan''.
 
===GCC, gnumake and libnuma===
└── test_and_benchmark
    └── benchmark
        └── build
            └── gcc_gnumake_hosted_liblfds711_liblfds700_libnuma
                    Makefile
 
To build, install GCC, gnumake and libnuma (package name is usually "numctl-dev" or "numactl-devel"), enter the build directory and type;
 
make
 
The following targets are available;
 
cov    : coverage
dbg    : debug
prof    : profiling
rel    : release
tsan    : thread sanitizer
vanilla : no specific-build arguments
clean  : what you'd expect
 
When switching from one target to another, ''clean'' must be made.
 
If building ''*_ar_tsan'', ''libtsan'' must be installed.  This is not necessary if building ''*_so_tsan''.
 
If building for ARM32 with shared object versions of the ''liblfds'' libraries, linking will fail, with the error ''"/usr/bin/ld: ../../bin/benchmark: hidden symbol `__aeabi_uidiv' in /usr/lib/gcc/arm-linux-gnueabihf/4.9/libgcc.a(_udivsi3.o) is referenced by DSO"''.  This means something has attempted to divide a 64 bit value by a 64 bit value, an operation which apparently is costly and usually unnecessary, a 32 bit divisor apparently is normally adequate, and as such is intentionally caught in a link-breaking way.
 
Unfortunately, as far as can be determined, ''liblfds'' itself is not performing this operation - and as such, it is not obvious how to fix it.
 
===MSVC and gnumake===
└── test_and_benchmark
    └── benchmark
        └── build
            └── msvc_gnumake_liblfds711_liblfds700
                    makefile
 
To build, install an MSVC command line compiler, enter the build directory and type;
 
make
 
The following targets are available;
 
dlldbg  : debug  (with ''liblfds'' libs built as DLLs)
dllrel  : release (with ''liblfds'' libs built as DLLs)
libdbg  : debug  (with ''liblfds'' libs built as libs)
librel  : release (with ''liblfds'' libs built as libs)
clean  : what you'd expect
 
When switching from one target to another, clean must be made.


==See Also==
==See Also==
* [[r7.1.1:Building Guide (benchmarking)|Building Guide (benchmarking)]]
* [[r7.1.1:Porting Guide (libbenchmark)|Porting Guide (libbenchmark)]]
* ''[[r7.1.1:function libbenchmark_pal_populate_topology|libbenchmark_pal_populate_topology]]''

Latest revision as of 20:16, 17 February 2017

Source Files

└───test_and_benchmark
    └───libbenchmark
        ├───inc
        │   └───libbenchmark
        │           libbenchmark_porting_abstraction_layer.h
        └───src
            └───libbenchmark_misc
                    libbenchmark_misc_pal_helpers.c

Opaque Structures

struct libbenchmark_topology_state;

Prototype

void libbenchmark_misc_pal_helper_add_logical_processor_node_to_topology_tree( struct libbenchmark_topology_state *ts,
                                                                               lfds711_pal_uint_t logical_processor_number,
                                                                               enum flag windows_processor_group_inuse_flag,
                                                                               lfds711_pal_uint_t windows_processor_group_number );

Parameters

struct libbenchmark_topology_state *ts

A pointer a struct libbenchmark_topology obtained from libbenchmark_pal_populate_topology.

lfds711_pal_uint_t logical_processor_number

The logical processor number of the logical processor to add to the topology tree pointed to by ts.

enum flag windows_processor_group_inuse_flag

An enum flag which indicates whether or not the windows_processor_group_number argument contains a valid value (for that field is only meaningful on Windows 7 and greater).

lfds711_pal_uint_t windows_processor_group_number

The Windows processor group number of the logical processor to add to the topology tree pointed to by ts. This value is only meaningful on Windows 7 and greater. It will only be used if the windows_processor_group_inuse_flag is set to RAISED, and so if not used, can be set to any value. Zero is as good a choice as any other.

Return Value

No return value.

Example

Notes

This helper function is used by libbenchmark_pal_populate_topology to add a logical processor node to the topology tree.

See Also

Retrieved from ‘https://www.liblfds.org/mediawiki/index.php?title=r7.1.1:Building_Guide_(benchmark)&oldid=1113’