README.md 14.8 KB
Newer Older
1
Embedded Multicore Building Blocks (EMB²)
2 3 4 5
=========================================


Overview
6
--------
7

Tobias Schuele committed
8 9
The Embedded Multicore Building Blocks (EMB²) are an easy to use yet powerful
and efficient C/C++ library for the development of parallel applications. EMB²
10 11 12 13 14 15 16 17
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.

Tobias Schuele committed
18
EMB² is independent of the hardware architecture (x86, ARM, ...) and runs on
19 20 21 22 23
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.
24 25 26 27
Unlike existing libraries, EMB² supports task priorities and affinities, 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.
28

Tobias Schuele committed
29
Besides the task scheduler, EMB² provides basic parallel algorithms, concurrent
30 31 32 33 34 35 36 37 38 39
data structures, and skeletons for implementing stream processing applications
(see figure below). 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.

40
<img src="doc/images/embb.png" alt="Building blocks of EMB²" width="500"/>
41 42

Community and Contact
43
---------------------
44

Tobias Schuele committed
45 46
Project home:
  - https://github.com/siemens/embb
47

Tobias Schuele committed
48 49 50
Git:
  - https://github.com/siemens/embb.git (HTTP)
  - git@github.com:siemens/embb.git (SSH)
51

Tobias Schuele committed
52 53 54
Mailing lists:
  - embb-announcements@googlegroups.com (announcements)
  - embb-dev@googlegroups.com (development)
55

Tobias Schuele committed
56 57 58
Subscription:
  - https://groups.google.com/forum/#!forum/embb-announcements/join
  - https://groups.google.com/forum/#!forum/embb-dev/join
59

Tobias Schuele committed
60 61
Contact:
  - embb.info@gmail.com or
Tobias Schuele committed
62
  - tobias.schuele@siemens.com, sebnem.rusitschka@siemens.com
63 64 65


License
66
-------
67

Tobias Schuele committed
68
See the file "COPYING.md" in the project's root directory.
69 70 71


Requirements
72
------------
73 74 75 76 77

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:

78
  - Linux (Ubuntu 12.04) / GCC 4.8.1 / x86, x86_64
79
  - Linux (Ubuntu 12.04) / Clang 3.0.0 / x86_64
80 81
  - Linux (Ubuntu 14.04) / GCC 4.8.2 / ARMv7
  - Windows
Tobias Schuele committed
82
    * MSVC 12.0.21005.1 REL / x86, x86_64
83 84 85 86
    * 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
Tobias Schuele committed
87
whether a system not officially supported is suitable to run EMB². If there is
88 89 90 91 92
a requirement to support a system on which the unit tests do not pass, please
contact us: embb-dev@googlegroups.com.


Directory Structure
93
-------------------
94

Tobias Schuele committed
95 96 97 98
EMB² consists 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, EMB² contains the following components:
99 100

  - base: base_c, base_cpp
101 102
  - mtapi: mtapi_c, mtapi_cpp and
    mtapi_plugins_c (mtapi_network_c and mtapi_opencl_c)
103 104 105 106 107 108 109 110 111 112
  - 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
Tobias Schuele committed
113 114 115
functions. Component mtapi_c is a task scheduler written in C and mtapi_cpp a
C++ wrapper for the scheduler (mtapi_network_c and mtapi_opencl_c are scheduler
plugins for distributed and OpenCL-based heterogeneous systems, respectively).
116 117 118
Component algorithms_cpp provides high-level constructs for typical
parallelization tasks in C++, and dataflow_cpp generic skeletons for the
development of parallel stream-based applications. Finally, containers_cpp
Tobias Schuele committed
119
provides data structures for storing objects in a thread-safe way.
120 121 122


Build and Installation
123
----------------------
124

125 126 127
Note: It is recommended to build from a release file and not from a repository
snapshot in order to get the documentation and the examples out-of-the box.
The release files can be found at https://github.com/siemens/embb/releases.
128

Tobias Schuele committed
129
EMB² is built using CMake (version 2.8.9 or higher). CMake is a build file
130 131 132 133 134 135 136
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.

137
### 1. Generation of native build files
138 139 140

Choose an appropriate build file generator for your system.

141
  - For Linux, GCC/Clang, x86/x86_64/ARM: "Unix Makefiles"
142 143 144 145 146 147 148 149
  - 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
150
    cmake -G <generator> .. [OPTIONS]
151 152 153 154 155 156 157

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).

158
You may choose a custom compiler instead the default one by defining
159 160
CMAKE_CXX_COMPILER and/or CMAKE_C_COMPILER. For example, to use Clang on Linux
use:
161 162 163

    cmake .. -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_C_COMPILER=clang

164
In the same way you may cross compile to another platform. For example, to cross
165 166
compile to ARM Linux using GCC, you need to specify the cross compiler itself and
the target architecture as an argument to the compiler:
167 168 169 170 171 172

    cmake .. -DCMAKE_CXX_COMPILER=arm-linux-gnueabi-gcc++
             -DCMAKE_CXX_FLAGS=-march=armv7-a
             -DCMAKE_C_COMPILER=arm-linux-gnueabi-gcc
             -DCMAKE_C_FLAGS=-march=armv7-a

Tobias Schuele committed
173
EMB² can be built with and without C++ exception handling, which has to be
174
specified on build file generation. When exceptions are turned off, an error
Tobias Schuele committed
175
message is emitted and the program aborts in case of an exception within EMB².
176
To disable exceptions, add the option -DUSE_EXCEPTIONS=OFF.
177

178 179 180
Similarly, automatic initialization of the task scheduler by the MTAPI C++
interface can be disabled with -DUSE_AUTOMATIC_INITIALIZATION=OFF. This way,
unexpected delays after startup can be avoided, e.g. for timing measurements.
181

182 183 184 185 186
Furthermore, EMB² can be built to work with threading analysis tools such as
Helgrind or ThreadSanitizer.
To enable support for them use -DTHREADING_ANALYSIS_MODE=ON. This uses mutexes
around atomics to avoid false positives and degrades performance significantly.

Tobias Schuele committed
187
The tutorial of EMB² comes with example source files in doc/examples/. These
188 189 190 191 192 193 194 195
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
196
    cmake -G "Unix Makefiles" .. -DCMAKE_BUILD_TYPE=Debug
197

198 199 200 201
For a default Linux build without automatic MTAPI C++ initialization, type

    cmake .. -DUSE_AUTOMATIC_INITIALIZATION=OFF

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

Roger Meier committed
204
    cmake -G "Visual Studio 12" .. -DUSE_EXCEPTIONS=OFF
205 206 207 208

Note that "Visual Studio 12" refers to the version number of Visual Studio and
not to the year in which it was released (2013).

209
### 2. Compiling and linking
210 211 212 213 214 215 216

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
217
    cmake --build .
218 219 220

For a Windows Release build, type

Roger Meier committed
221
    cmake --build . --config Release
222

223
### 3. Running the tests
224

Tobias Schuele committed
225
To check whether EMB² was compiled correctly, run the tests. The test
226 227 228 229
executables are contained in the subfolder "binaries".

On Linux, type

Roger Meier committed
230
    binaries/run_tests.sh
231 232 233

On Windows, type

Roger Meier committed
234
    binaries\run_tests.bat
235

Tobias Schuele committed
236
If no error message occurs, EMB² is working fine.
237

238
### 4. Installation
239 240 241

The default installation path on Linux is

Roger Meier committed
242
    /usr/local/
243 244 245

and on Windows

Roger Meier committed
246
    C:\Program Files\embb-X.Y.Z\ or C:\Program Files (x86)\embb-X.Y.Z
247 248 249 250 251

depending on the target architecture.

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

Roger Meier committed
252
    cmake -DINSTALL_PREFIX=YourCustomPath ..
253 254 255 256 257

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

To install the files, use the command

Roger Meier committed
258
    cmake --build . --target install
259 260 261 262 263 264 265

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
266
-----------------
267

Tobias Schuele committed
268
To use EMB², the include files have to be made available during compilation of
269 270
your application and the libraries have to be added during linking.

271
### 1. Using C++
272

Tobias Schuele committed
273
If you want to use the C++ functionalities of EMB², you have to link the
274 275 276
following libraries (names will be different on Windows and on Linux) in the
given order:

277 278
    embb_dataflow_cpp, embb_algorithms_cpp, embb_containers_cpp,
    embb_mtapi_cpp, embb_mtapi_c, embb_base_cpp, embb_base_c
279 280 281

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

Roger Meier committed
282 283 284 285
    #include<embb/mtapi/mtapi.h>
    #include<embb/base/base.h>
    #include<embb/containers/containers.h>
    #include<embb/dataflow/dataflow.h>
286

287
### 2. Using C
288 289 290

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

291
    embb_mtapi_c, embb_base_c
292 293 294

The C header files can be included as follows:

Roger Meier committed
295 296
    #include<embb/mtapi/c/mtapi.h>  or  #include<mtapi.h>
    #include<embb/base/c/base.h>
297 298 299


Documentation
300
-------------
301

302 303 304 305 306 307 308
The release files of EMB² come with a tutorial, example programs, and a
reference manual (HTML) describing the APIs. All documentation is contained in
the "doc" folder. The root document of the HTML reference is
"doc/reference/index.html". Note that generated documentation files are not
under version control and hence not contained in the repository. As mentioned
above, it is therefore recommended to download one of the packaged release
files in order to have ready-to-use documentation.
309 310 311


Code Quality
312
------------
313

Tobias Schuele committed
314
For the C++ parts of EMB², we respect most rules of the "Google C++ Style
315 316 317 318 319 320 321 322 323
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
324
--------------------------
325

Tobias Schuele committed
326
- For memory management reasons, the number of threads EMB² can deal with
Tobias Schuele committed
327 328 329
  is bounded by a predefined but modifiable constant (see functions
  embb_thread_get_max_count() / embb_thread_set_max_count() and class
  embb::base::Thread).
330 331
- While MTAPI fully supports heterogeneous systems, the algorithms and
  dataflow components are currently limited to homogeneous systems.
Tobias Schuele committed
332

333

334
Development and Contribution
335
----------------------------
336 337 338 339 340

The EMB² team welcomes all kinds of contributions, preferably as pull requests
or patches via the development mailing lists (see above). If possible, please
refer to a current snapshot of the development branch.

341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366
EMB² is supposed to be easily portable to platforms unsupported so far. Almost
all platform specific code is located in the base_c and base_cpp modules. All
existing platform specific code is fenced by EMBB_PLATFORM_* defines.

To distinguish between compilers, EMB² currently uses the following defines:

  - EMBB_PLATFORM_COMPILER_GNUC
  - EMBB_PLATFORM_COMPILER_MSVC
  - EMBB_PLATFORM_COMPILER_UNKNOWN

Different architectures are distinguished using:

  - EMBB_PLATFORM_ARCH_X86
  - EMBB_PLATFORM_ARCH_X86_32
  - EMBB_PLATFORM_ARCH_X86_64
  - EMBB_PLATFORM_ARCH_ARM
  - EMBB_PLATFORM_ARCH_UNKNOWN

Threading APIs are switched by:

  - EMBB_PLATFORM_THREADING_WINTHREADS
  - EMBB_PLATFORM_THREADING_POSIXTHREADS

Please use these defines for new platform specific code. If additional defines
are needed, they can be defined in the config.h or cmake_config.h.in files.

367

368 369 370 371
Important Notes
---------------

- The MTAPI C++ interface supports automatic initialization, which allows for
Marcus Winter committed
372
  easy usage of the MTAPI C++, Algorithms, and Dataflow components. For
373 374 375
  performance measurements, explicit initialization is strongly recommended
  since the measurements will otherwise include the initialization time of
  MTAPI.
376 377 378 379
- When using ThreadSanitizer there is a bug that causes the built-in CMake type
  size determination to fail which in turn leads to a broken configuration.
  Therefore, you have to do a normal build first and then rerun CMake with
  flags and libs configured for ThreadSanitizer.
380 381


382
Links
383
-----
384 385 386 387 388 389 390

  - Multicore Association:
    http://www.multicore-association.org
  - MTAPI:
    http://www.multicore-association.org/workgroup/mtapi.php
  - CMake:
    http://www.cmake.org/
Tobias Schuele committed
391
  - Google C++ Style Guide:
392 393 394 395 396
    http://google-styleguide.googlecode.com/svn/trunk/cppguide.html
  - cpplint:
    http://google-styleguide.googlecode.com/svn/trunk/cpplint/
  - Cppcheck:
    http://cppcheck.sourceforge.net/