README.md 10.9 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136
=========================================
Embedded Multicore Building Blocks (EMBB)
=========================================


Overview
========

The Embedded Multicore Building Blocks (EMBB) are an easy to use yet powerful
and efficient C/C++ library for the development of parallel applications. EMBB
has been specifically designed for embedded systems and the typical
requirements that accompany them, such as real-time capability and constraints
on memory consumption. As a major advantage, low-level operations are hidden
in the library which relieves software developers from the burden of thread
management and synchronization. This not only improves productivity of
parallel software development, but also results in increased reliability and
performance of the applications.

EMBB is independent of the hardware architecture (x86, ARM, ...) and runs on
various platforms, from small devices to large systems containing numerous
processor cores. It builds on MTAPI, a standardized programming interface for
leveraging task parallelism in embedded systems containing symmetric or
asymmetric multicore processors. A core feature of MTAPI is low-overhead
scheduling of fine-grained tasks among the available cores during runtime.
Unlike existing libraries, EMBB supports task priorities, which allows the
creation of soft real-time systems. Additionally, the scheduling strategy can
be optimized for non-functional requirements such as minimal latency and
fairness.

Besides the task scheduler, EMBB provides basic parallel algorithms, concurrent
data structures, and skeletons for implementing stream processing
applications. These building blocks are largely implemented in a non-blocking
fashion, 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. For
example, wait-free data structures guarantee system-wide progress which means
that every operation completes within a finite number of steps independently
of any other concurrent operations on the same data structure.


Community and Contact
=====================

Project home:   https://github.com/siemens/embb

Git:            https://github.com/siemens/embb.git
                git@github.com:siemens/embb.git

Mailing lists:  embb-announcements@googlegroups.com
                embb-dev@googlegroups.com (development)

Subscription:   https://groups.google.com/forum/#!forum/embb-announcements/join
                https://groups.google.com/forum/#!forum/embb-dev/join

Contact:        embb.info@gmail.com or tobias.schuele@siemens.com


License
=======

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 on
the 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_64

Other compilers and operating systems may be supported without any changes to
the source code. The project includes unit tests that can be used to find out
whether a system not officially supported is suitable to run EMBB. If there is
a requirement to support a system on which the unit tests do not pass, please
contact us: embb-dev@googlegroups.com.


Directory Structure
===================

EMBB is a technology stack consisting of various building blocks. For some of
them, there exist C and C++ versions, others are only implemented in C++. The
directory names are postfixed with either "_cpp" or "_c" for  the C++ and C
versions, 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_cpp

Each component consists of an include, a src, and a test subfolder that contain
the header files, source files, and unit tests, respectively.

Component base_c contains abstractions for threading, synchronization, atomic
operations, and other functionalities. As the name indicates, the code is
implemented in C. Component base_cpp is mainly a C++ wrapper around the base_c
functionalities. Component mtapi_c is a task scheduler written in C and
mtapi_cpp a C++ wrapper for the scheduler. Component algorithms_cpp provides
high-level constructs for typical parallelization task in C++, and
dataflow_cpp generic skeletons for the development of parallel stream-based
applications. 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 file
generator which allows to abstract from the concrete build tools. To generate
and invoke the platform-specific build files, open a shell (on Windows, use
the Visual Studio developer shell to have the correct environment variables)
and change to the project's root directory. Create a subdirectory, where you
want to build the library, e.g., "build". Change to that subdirectory. It is
assumed 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" without
any options. The build files can be generated using the following command:

Roger Meier committed
137
    cmake -G <generator> .. [OPTIONS]
138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158

Note that on Linux, the architecture (32/64 bit) cannot be selected by the
generator. However, the build mode (Release/Debug) can be specified using the
option -DCMAKE_BUILD_TYPE=[Release|Debug]. If no build mode is given on Linux,
the default (Release) is used. The Visual Studio generators create build files
for both modes (the selection is done at build time).

EMBB can be built with and without C++ exception handling, which has to be
specified on build file generation. When exceptions are turned off, an error
message 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/. These
can be built with the other source files using CMake option -DBUILD_EXAMPLES=ON
in the generation step. Note, however, that the examples use C++11 features and
require 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

Roger Meier committed
159
    cmake -G "Unix Makefiles" .. -DCMAKE_BUILD_TYPE=Debug
160 161 162

For a Windows build (VS 2013, x86) without exception handling, type

Roger Meier committed
163
    cmake -G "Visual Studio 12" .. -DUSE_EXCEPTIONS=OFF
164 165 166 167 168 169 170 171 172 173 174 175 176

Note that "Visual Studio 12" refers to the version number of Visual Studio and
not 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

Roger Meier committed
177
    cmake --build .
178 179 180

For a Windows Release build, type

Roger Meier committed
181
    cmake --build . --config Release
182 183 184 185 186 187 188 189 190

3. Running the tests
--------------------

To check whether EMBB was compiled correctly, run the tests. The test
executables are contained in the subfolder "binaries".

On Linux, type

Roger Meier committed
191
    binaries/run_tests.sh
192 193 194

On Windows, type

Roger Meier committed
195
    binaries\run_tests.bat
196 197 198 199 200 201 202 203

If no error message occurs, EMBB is working fine.

4. Installation
---------------

The default installation path on Linux is

Roger Meier committed
204
    /usr/local/
205 206 207

and on Windows

Roger Meier committed
208
    C:\Program Files\embb-X.Y.Z\ or C:\Program Files (x86)\embb-X.Y.Z
209 210 211 212 213

depending on the target architecture.

If you want a different installation path, you can change it now by typing

Roger Meier committed
214
    cmake -DINSTALL_PREFIX=YourCustomPath ..
215 216 217 218 219

The option "-DINSTALL_PREFIX=YourCustomPath" can also be given in Step 1.

To install the files, use the command

Roger Meier committed
220
    cmake --build . --target install
221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239

which copies the contents of the "install" folder to the "bin", "lib", and
"include" folders in the installation path. For the default paths, the
installation has to be run with administrator / root privileges.


Using the Library
=================

To use EMBB, the include files have to be made available during compilation of
your 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 the
following libraries (names will be different on Windows and on Linux) in the
given order:

Roger Meier committed
240 241
    embb_base, embb_base_cpp, embb_mtapi_c, embb_mtapi_cpp, embb_containers_cpp,
    embb_algorithms_cpp, embb_dataflow_cpp
242 243 244

The C++ header files can be included as follows:

Roger Meier committed
245 246 247 248
    #include<embb/mtapi/mtapi.h>
    #include<embb/base/base.h>
    #include<embb/containers/containers.h>
    #include<embb/dataflow/dataflow.h>
249 250 251 252 253 254

2. Using C
----------

The following libraries have to be linked in the given order:

Roger Meier committed
255
    embb_base_c, mtapi_c
256 257 258

The C header files can be included as follows:

Roger Meier committed
259 260
    #include<embb/mtapi/c/mtapi.h>  or  #include<mtapi.h>
    #include<embb/base/c/base.h>
261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305


Documentation
=============

EMBB comes with a tutorial, example programs, and an HTML reference
documentation 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++ Style
Guide" which are checked using the cpplint tool. However, we ignore some
rules, 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 source
code 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 Guide
    http://google-styleguide.googlecode.com/svn/trunk/cppguide.html
  - cpplint:
    http://google-styleguide.googlecode.com/svn/trunk/cpplint/
  - Cppcheck:
    http://cppcheck.sourceforge.net/