|
|
| Line 1: |
Line 1: |
| {{DISPLAYTITLE:Building Guide (liblfds)}} | | {{DISPLAYTITLE:function libbenchmark_misc_pal_helper_new_topology_node}} |
| ==Introducton== | | ==Source Files== |
| The ''liblfds'' library uses a porting abstraction layer to mask platform differences. Building ''liblfds'' requires build files (makefile, etc) for your toolchain (GCC, gnumake, etc) and a port of the abstraction layer to your platform.
| | └───test_and_benchmark |
| | └───libbenchmark |
| | ├───inc |
| | │ └───libbenchmark |
| | │ libbenchmark_porting_abstraction_layer.h |
| | └───src |
| | └───libbenchmark_misc |
| | libbenchmark_misc_pal_helpers.c |
|
| |
|
| A small number of popular toolchains are supported out-of-the-box, and all supported toolchains have a porting abtraction layer provided.
| | ==Opaque Structures== |
| | struct [[r7.1.1:struct libbenchmark_topology_state|libbenchmark_topology_state]]; |
|
| |
|
| ==Supported Toolchains== | | ==Prototype== |
| The supported toolchains are;
| | 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 ); |
|
| |
|
| * GCC and gnumake
| | ==Parameters== |
| * GCC, kbuild and gnumake (Linux kernel toolchain)
| | ''struct libbenchmark_topology_state *ts'' |
| * MSVC and gnumake (Windows user-mode toolchain - and, yup, gnumake, not nmake) | | : A pointer a ''struct libbenchmark_topology'' obtained from ''libbenchmark_pal_populate_topology''. |
| * WDK 7.1 (Windows XP/Vista/7 kernel toolchain)
| |
|
| |
|
| 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.
| | ''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''. |
|
| |
|
| Mac support is not available due to lack of access to a Mac.
| | ''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). |
|
| |
|
| ==Directory Structure==
| | ''lfds711_pal_uint_t windows_processor_group_number'' |
| └───liblfds711 : liblfds library
| | : 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. |
| ├───bin : output directory - the library file ends up here
| |
| ├───build : build configuration directory - contains one directory per platform
| |
| │ ├───gcc_gnumake : GCC and gnumake
| |
| │ ├───gcc_gnumake_kbuild : GCC, gnumake, and kbuild
| |
| │ ├───msvc_gnumake : Microsoft Visual C (command line compiler) and gnumake
| |
| │ └───wdk_7.1 : WDK 7.1
| |
| ├───inc : the public header files
| |
| │ └───liblfds711
| |
| ├───obj : temporary directory for object files
| |
| └───src : the data structures
| |
| ├───lfds711_btree_addonly_unbalanced : btree (add-only, unbalanced)
| |
| ├───lfds711_freelist : freelist
| |
| ├───lfds711_hash_addonly : hash (add-only)
| |
| ├───lfds711_list_addonly_singlylinked_ordered : singly-linked list (add-only, singly-linked, ordered)
| |
| ├───lfds711_list_addonly_singlylinked_unordered : singly-linked list (add-only, singly-linked, unordered)
| |
| ├───lfds711_misc : misc library functions
| |
| ├───lfds711_prng : PRNG library functions
| |
| ├───lfds711_queue_bounded_singleproducer_singleconsumer : queue (bounded, single-producer, single-consumer)
| |
| ├───lfds711_queue_bounded_manyproducer_manyconsumer : queue (bounded, many-producer, many-consumer)
| |
| ├───lfds711_unqueue_bounded_manyproducer_manyconsumer : queue (unbounded, many-producer, many-consumer)
| |
| ├───lfds711_ringbuffer : ringbuffer
| |
| └───lfds711_stack : stack
| |
|
| |
|
| ==Building== | | ==Return Value== |
| The library directory tree contains at its top level directory called ''build''.
| | No return value. |
|
| |
|
| 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.
| | ==Example== |
|
| |
|
| The resultant library file will be placed in the top level directory ''liblfds711/bin/'', with the root filename ''liblfds711.*'', where the suffix varies by build type (static or dynamic) and by operating system (''.a'', ''.lib'', etc).
| | ==Notes== |
| | | This helper function is used by ''libbenchmark_pal_populate_topology'' to add a logical processor node to the topology tree. |
| The header files are in the top level directory ''inc''. They are arranged a single master header file, ''liblfds711/inc/liblfds711.h'' together with a subdirectory, ''liblfds711/inc/liblfds711/'', which contains a set of header files, one per data structure, where these per-data structure header files are included by the master file.
| |
| | |
| To use the header files, include and only include the master header file, ''liblfds711/inc/liblfds711.h''.
| |
| | |
| 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===
| |
| └───liblfds711
| |
| └───build
| |
| └───gcc_gnumake
| |
| Makefile
| |
| | |
| To build, install GCC and gnumake, enter the build directory and type;
| |
| | |
| make
| |
| | |
| The following targets are available;
| |
| | |
| ar_cov : archive (.a), coverage
| |
| ar_dbg : archive (.a), debug
| |
| ar_prof : archive (.a), profiling
| |
| ar_rel : archive (.a), release
| |
| ar_tsan : archive (.a), thread sanitizer
| |
| ar_vanilla : archive (.a), no specific-build arguments
| |
| ar_install : install to /usr/local/include/ and /usr/local/lib/
| |
| ar_uninstall : uninstall
| |
|
| |
| so_cov : shared (.so), coverage
| |
| so_dbg : shared (.so), debug
| |
| so_prof : shared (.so), profiling
| |
| so_rel : shared (.so), release
| |
| so_tsan : shared (.so), thread sanitizer
| |
| so_vanilla : shared (.so), no specific-build arguments
| |
| so_install : install to /usr/local/include/ and /usr/local/lib/ (creates the necessary soft links for .so versioning)
| |
| so_uninstall : uninstall
| |
|
| |
| 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 kbuild===
| |
| └───liblfds711
| |
| └───build
| |
| └───gcc_gnumake_kbuild
| |
| Kbuild
| |
| Makefile
| |
| | |
| To build, install GCC, gnumake, kbuild (and the Linux kernel headers), enter the build directory and type;
| |
| | |
| make
| |
| | |
| The makefile is complimentory (mint-flavoured :-) and simply issues the necessary kbuild command.
| |
| | |
| There are three targets;
| |
| | |
| clean
| |
| help
| |
| modules
| |
| | |
| Note that ''modules'' is the default build (i.e. with no arguments).
| |
| | |
| I do not properly understand kbuild. I've read the documentation; I find for example examples which have switches in which are simply not present in the documentation, and in general I don't see how libraries are built to fit in with larger projects. The most I can say about this build is that it compiles without warnings or errors. I am pretty sure it's not something which can be used as it is in a kernel build or driver, but anyone who knows enough to be developing such a thing should be able to take what is here (since it compiles against the kernel) and easily fit it into their work.
| |
| | |
| Any feedback on making this build proper is greatly appreciated.
| |
| | |
| ===MSVC and gnumake===
| |
| └───liblfds711
| |
| └───build
| |
| └───msvc_and_gnumake
| |
| liblfds711.def
| |
| makefile
| |
| | |
| To build, install an MSVC command line compiler, enter the build directory and type;
| |
| | |
| make
| |
| | |
| The following targets are available;
| |
| | |
| libdbg : archive (.lib), debug
| |
| librel : archive (.lib), release
| |
|
| |
| dlldbg : shared (.dll), debug
| |
| dllrel : shared (.dll), release
| |
|
| |
| clean : what you'd expect
| |
| | |
| When switching from one target to another, clean must be made.
| |
| | |
| ===WDK 7.1===
| |
| └───liblfds711
| |
| └───build
| |
| └───wdk_7.1
| |
| dirs
| |
| driver_entry_renamed_to_avoid_compiler_warning.c
| |
| liblfds711.def
| |
| readme_before_win_kernel_build.txt
| |
| runme_before_win_kernel_dynamic_lib_build.bat
| |
| runme_before_win_kernel_static_lib_build.bat
| |
| sources.dynamic
| |
| sources.static
| |
| | |
| All processor types are supported (x86, IA64, x64).
| |
| | |
| The WDK 7.1 kernel build environment is primitive and has a number of severe limitations; in particular, all source files must be in one directory and it is not possible to choose the output binary type (static or dynamic library) from the build command line; rather, a string has to be modified in a text file used by the build (!)
| |
| | |
| To deal with these limitations, it is necessary for a Windows kernel build to run a batch file prior to building. There are two batch files, one for static library builds and the other for dynamic library builds. They are idempotent; you can run them as often as you like and switch between them as often as you want. It's all fine.
| |
| | |
| Both batch files copy all the sources file into a single directory, ''liblfds711/build/wdk7.1/single_dir_for_windows_kernel/''.
| |
| | |
| The static library batch file will then copy ''liblfds711/sources.static'' into ''liblfds711/build/wdk7.1/single_dir_for_windows_kernel/'', which will cause a static library to be built.
| |
| | |
| The dynamic library batch file will then copy ''liblfds711/sources.dynamic'' into ''liblfds711/build/wdk7.1/single_dir_for_windows_kernel/'', which will cause a dynamic library to be built. It will also copy ''driver_entry_renamed_to_avoid_compiler_warning.c'' to ''liblfds711/build/wdk7.1/single_dir_for_windows_kernel/driver_entry.c'' (note the renaming), since the linker requires the ''DriverEntry'' function to exist, even though it's not used.
| |
| | |
| To build, start a build command line as usual, indicating through the command line you select whether you are making a debug or release build. Then run the appropriate liblfds batch file to select a static or dynamic library. Then, finally, run ''build.exe'' in the ''liblfds711/build/wdk_7.1/'' directory, with whatever arguments you prefer.
| |
| | |
| Note that due to limitations in the build environment, object files appear in a subdirectory in ''liblfds711/build/wdk7.1/single_dir_for_windows_kernel/'', rather than in the usual ''liblfds711/obj/''. The final binary output however still appears almost as usual, in ''liblfds711/bin/[processor]/'', where processor might be ''i386''. (The usual is just ''liblfds711/bin/'', with no subdirectories).
| |
| | |
| Note that the ''sources'' file used to compile the library asserts the define ''KERNEL_MODE''. This appears to be necessary, due to the lack of a compiler-provided macro to differentiate in the code between a user-mode or kernel-mode build.
| |
|
| |
|
| ==See Also== | | ==See Also== |
| * [[r7.1.1:Release_7.1.1_Documentation|Release 7.1.1 Documentation]] | | * [[r7.1.1:Porting Guide (libbenchmark)|Porting Guide (libbenchmark)]] |
| | * ''[[r7.1.1:function libbenchmark_pal_populate_topology|libbenchmark_pal_populate_topology]]'' |