=========================================Embedded Multicore Building Blocks (EMBB)=========================================Overview========The Embedded Multicore Building Blocks (EMBB) are an easy to use yet powerfuland efficient C/C++ library for the development of parallel applications. EMBBhas been specifically designed for embedded systems and the typicalrequirements that accompany them, such as real-time capability and constraintson memory consumption. As a major advantage, low-level operations are hiddenin the library which relieves software developers from the burden of threadmanagement and synchronization. This not only improves productivity ofparallel software development, but also results in increased reliability andperformance of the applications.EMBB is independent of the hardware architecture (x86, ARM, ...) and runs onvarious platforms, from small devices to large systems containing numerousprocessor cores. It builds on MTAPI, a standardized programming interface forleveraging task parallelism in embedded systems containing symmetric orasymmetric multicore processors. A core feature of MTAPI is low-overheadscheduling of fine-grained tasks among the available cores during runtime.Unlike existing libraries, EMBB supports task priorities, which allows thecreation of soft real-time systems. Additionally, the scheduling strategy canbe optimized for non-functional requirements such as minimal latency andfairness.Besides the task scheduler, EMBB provides basic parallel algorithms, concurrentdata structures, and skeletons for implementing stream processingapplications. These building blocks are largely implemented in a non-blockingfashion, thus preventing frequently encountered pitfalls like lock contention,deadlocks, and priority inversion. As another advantage in real-time systems,the algorithms and data structures give certain progress guarantees. Forexample, wait-free data structures guarantee system-wide progress which meansthat every operation completes within a finite number of steps independentlyof any other concurrent operations on the same data structure.Community and Contact=====================Project home:https://github.com/siemens/embbGit:https://github.com/siemens/embb.git                git@github.com:siemens/embb.gitMailing lists:  embb-announcements@googlegroups.com                embb-dev@googlegroups.com (development)Subscription:https://groups.google.com/forum/#!forum/embb-announcements/joinhttps://groups.google.com/forum/#!forum/embb-dev/joinContact:        embb.info@gmail.com or tobias.schuele@siemens.comLicense=======See the file "COPYING.txt" in the project's root directory.Requirements============This project is based on the standards C99 (for C code) and C++03 (for C++code) to be usable on a wide range of target systems. It has been tested onthe following OS/compiler/architecture combinations:  - Linux (Ubuntu 12.10) / GCC 4.8.1 / x86, x86_64  - Linux (Ubuntu 14.04) / GCC 4.8.2 / ARMv7  - Windows    * MSVC 12.0.21005.1 REL / x86, x86_64    * MSVC 11.0.50727.42 VSLRSTAGE / x86, x86_64Other compilers and operating systems may be supported without any changes tothe source code. The project includes unit tests that can be used to find outwhether a system not officially supported is suitable to run EMBB. If there isa requirement to support a system on which the unit tests do not pass, pleasecontact us: embb-dev@googlegroups.com.Directory Structure===================EMBB is a technology stack consisting of various building blocks. For some ofthem, there exist C and C++ versions, others are only implemented in C++. Thedirectory names are postfixed with either "_cpp" or "_c" for  the C++ and Cversions, respectively. Currently, EMBB contains the following components:  - base: base_c, base_cpp  - mtapi: mtapi_c, mtapi_cpp  - algorithms: algorithms_cpp  - dataflow: dataflow_cpp  - containers: containers_cppEach component consists of an include, a src, and a test subfolder that containthe header files, source files, and unit tests, respectively.Component base_c contains abstractions for threading, synchronization, atomicoperations, and other functionalities. As the name indicates, the code isimplemented in C. Component base_cpp is mainly a C++ wrapper around the base_cfunctionalities. Component mtapi_c is a task scheduler written in C andmtapi_cpp a C++ wrapper for the scheduler. Component algorithms_cpp provideshigh-level constructs for typical parallelization task in C++, anddataflow_cpp generic skeletons for the development of parallel stream-basedapplications. Finally, component containers_cpp provides containers, i.e.,data structures for storing object in an organized and thread-safe way.Build and Installation======================EMBB is built using CMake (version 2.8.9 or higher). CMake is a build filegenerator which allows to abstract from the concrete build tools. To generateand invoke the platform-specific build files, open a shell (on Windows, usethe Visual Studio developer shell to have the correct environment variables)and change to the project's root directory. Create a subdirectory, where youwant to build the library, e.g., "build". Change to that subdirectory. It isassumed that the project's root directory is now the parent directory.1. Generation of native build files-----------------------------------Choose an appropriate build file generator for your system.  - For Linux, GCC, x86/x86_64/ARM:       "Unix Makefiles"  - For Windows, MSVC of VS 2013, x86:    "Visual Studio 12"  - For Windows, MSVC of VS 2013, x86_64: "Visual Studio 12 Win64"  - For Windows, MSVC of VS 2012, x86:    "Visual Studio 11"  - For Windows, MSVC of VS 2012, x86_64: "Visual Studio 11 Win64"A list of all available generators can be displayed by typing "cmake" withoutany options. The build files can be generated using the following command:  cmake -G <generator> .. [OPTIONS]Note that on Linux, the architecture (32/64 bit) cannot be selected by thegenerator. However, the build mode (Release/Debug) can be specified using theoption -DCMAKE_BUILD_TYPE=[Release|Debug]. If no build mode is given on Linux,the default (Release) is used. The Visual Studio generators create build filesfor both modes (the selection is done at build time).EMBB can be built with and without C++ exception handling, which has to bespecified on build file generation. When exceptions are turned off, an errormessage is emitted and the program aborts in case of an exception within EMBB.To disable exceptions, add the option -DUSE_EXCEPTIONS=OFF.The tutorial of EMBB comes with example source files in doc/examples/. Thesecan be built with the other source files using CMake option -DBUILD_EXAMPLES=ONin the generation step. Note, however, that the examples use C++11 features andrequire a corresponding compiler.Now you can generate the build files as shown by the following examples.For a Linux Debug build with exception handling, type  cmake -G "Unix Makefiles" .. -DCMAKE_BUILD_TYPE=DebugFor a Windows build (VS 2013, x86) without exception handling, type  cmake -G "Visual Studio 12" .. -DUSE_EXCEPTIONS=OFFNote that "Visual Studio 12" refers to the version number of Visual Studio andnot to the year in which it was released (2013).2. Compiling and linking------------------------As the next step, you can compile the library using the generated build files.On Linux, the build mode (Release|Debug) is already given in the build files,whereas on Windows, it has to be specified now.For a Linux build, type  cmake --build .For a Windows Release build, type  cmake --build . --config Release3. Running the tests--------------------To check whether EMBB was compiled correctly, run the tests. The testexecutables are contained in the subfolder "binaries".On Linux, type  binaries/run_tests.shOn Windows, type  binaries\run_tests.batIf no error message occurs, EMBB is working fine.4. Installation---------------The default installation path on Linux is  /usr/local/and on Windows  C:\Program Files\embb-X.Y.Z\ or C:\Program Files (x86)\embb-X.Y.Zdepending on the target architecture.If you want a different installation path, you can change it now by typing  cmake -DINSTALL_PREFIX=YourCustomPath ..The option "-DINSTALL_PREFIX=YourCustomPath" can also be given in Step 1.To install the files, use the command  cmake --build . --target installwhich copies the contents of the "install" folder to the "bin", "lib", and"include" folders in the installation path. For the default paths, theinstallation has to be run with administrator / root privileges.Using the Library=================To use EMBB, the include files have to be made available during compilation ofyour application and the libraries have to be added during linking.1. Using C++------------If you want to use the C++ functionalities of EMBB, you have to link thefollowing libraries (names will be different on Windows and on Linux) in thegiven order:  embb_base, embb_base_cpp, embb_mtapi_c, embb_mtapi_cpp, embb_containers_cpp,  embb_algorithms_cpp, embb_dataflow_cppThe C++ header files can be included as follows:  #include<embb/mtapi/mtapi.h>  #include<embb/base/base.h>  #include<embb/containers/containers.h>  #include<embb/dataflow/dataflow.h>2. Using C----------The following libraries have to be linked in the given order:  embb_base_c, mtapi_cThe C header files can be included as follows:  #include<embb/mtapi/c/mtapi.h>  or  #include<mtapi.h>  #include<embb/base/c/base.h>Documentation=============EMBB comes with a tutorial, example programs, and an HTML referencedocumentation describing the APIs, which can be found in the "doc" folder.The root document of the HTML reference is "doc/reference/index.html".Code Quality============For the C++ parts of EMBB, we respect most rules of the "Google C++ StyleGuide" which are checked using the cpplint tool. However, we ignore somerules, as they are not applicable or yield false results for this project.For example, we respect the include order of the Google Style Guide, but use<> instead of "" for project includes, which confuses the cpplint tool.Moreover, we do not tolerate compiler warnings and regularly check the sourcecode using Cppcheck, a static analysis tool for C++.Known Bugs and Limitations==========================  - The usage of EMBB atomic operations with types of size 1 or 2 bytes such    as 'bool' does not work on ARMv7. This is an alignment issue which can    cause stack corruption.  Links=====  - Multicore Association:http://www.multicore-association.org  - MTAPI:http://www.multicore-association.org/workgroup/mtapi.php  - CMake:http://www.cmake.org/  - Google C++ Style Guidehttp://google-styleguide.googlecode.com/svn/trunk/cppguide.html  - cpplint:http://google-styleguide.googlecode.com/svn/trunk/cpplint/  - Cppcheck:http://cppcheck.sourceforge.net/