Adding README in markdown format for GitHub

1 files changed, 751 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..8864fec
--- /dev/null
+++ b/README.md
@@ -0,0 +1,751 @@
+# vSOMEIP
+
+Copyright
++++++++++
+Copyright (C) 2015, Bayerische Motoren Werke Aktiengesellschaft (BMW AG)
+
+License
++++++++
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+Version
++++++++
+// set the version to the one we get from cmake
+// or pass it via -a version=$VSOMEIP_VERSION to asciidoc
+This documentation was generated for version {version} of vsomeip.
+
+vsomeip Overview
+----------------
+The vsomeip stack implements the http://some-ip.com/[Scalable service-Oriented
+MiddlewarE over IP (SOME/IP)] protocol. The stack consists out of:
+
+* a shared library for SOME/IP (`libvsomeip.so`)
+* a second shared library for SOME/IP's service discovery (`libvsomeip-sd.so`)
+  which is loaded during runtime if the service discovery is enabled.
+
+Build Instructions
+------------------
+Dependencies
+~~~~~~~~~~~~
+* A C++11 enabled compiler like gcc >= 4.8 is needed.
+* vsomeip uses cmake as buildsystem.
+* vsomeip uses Boost >= 1.54:
+** Ubuntu 14.04:
+*** `sudo apt-get install libboost-system1.54-dev libboost-thread1.54-dev
+    libboost-log1.54-dev`
+** Ubuntu 12.04: a PPA is necessary to use version 1.54 of Boost:
+*** URL: https://launchpad.net/~boost-latest/+archive/ubuntu/ppa
+*** `sudo add-apt-repository ppa:boost-latest/ppa`
+*** `sudo apt-get install libboost-system1.54-dev libboost-thread1.54-dev
+    libboost-log1.54-dev`
+* For the tests Google's test framework
+  https://code.google.com/p/googletest/[gtest] in version 1.7.0 is needed
+** URL: https://googletest.googlecode.com/files/gtest-1.7.0.zip[direct link,
+   version 1.7.0]
+* To build the documentation asciidoc, source-highlight, doxygen and graphviz is needed:
+** `sudo apt-get install asciidoc source-highlight doxygen graphviz`
+
+Compilation
+~~~~~~~~~~~
+anchor:Compilation[]
+For compilation call:
+[source, bash]
+----
+mkdir build
+cd build
+cmake ..
+make
+----
+
+To specify a installation directory (like `--prefix=` if you're used to
+autotools) call cmake like:
+[source, bash]
+----
+cmake -DCMAKE_INSTALL_PREFIX:PATH=$YOUR_PATH ..
+make
+make install
+----
+
+Compilation of examples
+^^^^^^^^^^^^^^^^^^^^^^^
+For compilation of the examples call:
+[source, bash]
+----
+mkdir build
+cd build
+cmake ..
+make examples
+----
+
+Compilation of tests
+^^^^^^^^^^^^^^^^^^^^
+To compile the tests, first unzip gtest to location of your desire.
+Some of the tests require a second node on the same network. There are two cmake
+variables which are used to automatically adapt the json files to the used
+network setup:
+
+* `TEST_IP_MASTER`: The IP address of the interface which will act as test
+  master.
+* `TEST_IP_SLAVE`: The IP address of the interface of the second node which will
+  act as test slave.
+
+If one of this variables isn't specified, only the tests using local
+communication exclusively will be runnable.
+
+Example, compilation of tests:
+[source, bash]
+----
+mkdir build
+cd build
+export GTEST_ROOT=$PATH_TO_GTEST/gtest-1.7.0/
+cmake -DTEST_IP_MASTER=10.0.3.1 -DTEST_IP_SLAVE=10.0.3.125 ..
+make check
+----
+
+Additional make targets for the tests:
+
+* Call `make build_tests` to only compile the tests
+* Call `ctest` in the build directory to execute the tests without a verbose
+  output
+* To run single tests call `ctest --verbose --tests-regex $TESTNAME` short
+  form: `ctest -V -R $TESTNAME`
+* To list all available tests run `ctest -N`.
+* For further information about the tests please have a look at the
+  `readme.txt` in the `test` subdirectory.
+
+For development purposes two cmake variables exist which control if the
+json files and test scripts are copied (default) or symlinked into the build
+directory. These settings are ignored on Windows.
+
+* `TEST_SYMLINK_CONFIG_FILES`: Controls if the json and scripts needed
+  to run the tests are copied or symlinked into the build directory. (Default:
+  OFF, ignored on Windows)
+* `TEST_SYMLINK_CONFIG_FILES_RELATIVE`: Controls if the json and scripts needed
+  to run the tests are symlinked relatively into the build directory.
+  (Default: OFF, ignored on Windows)
+
+Example cmake call:
+[source, bash]
+----
+cmake  -DTEST_SYMLINK_CONFIG_FILES=ON -DTEST_SYMLINK_CONFIG_FILES_RELATIVE=ON ..
+----
+
+For compilation of only a subset of tests (for a quick
+functionality check) the cmake variable `TESTS_BAT` has
+to be set:
+
+Example cmake call:
+[source, bash]
+----
+cmake  -DTESTS_BAT=ON ..
+----
+
+Generating the documentation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+To generate the documentation call cmake as described in <<Compilation>> and
+then call `make doc`.
+This will generate:
+
+* The README file in html: `$BUILDDIR/documentation/README.html`
+* A doxygen documentation in `$BUILDDIR/documentation/html/index.html`
+
+Starting vsomeip Applications / Used environment variables
+----------------------------------------------------------
+On startup the following environment variables are read out:
+
+* `VSOMEIP_APPLICATION_NAME`: This environment variable is used to specify the
+  name of the application. This name is later used to map a client id to the
+  application in the configuration file. It is independent from the
+  application's binary name.
+* `VSOMEIP_CONFIGURATION`: vsomeip uses the default configuration file `/etc/vsomeip.json`
+   and/or the default configuration folder `/etc/vsomeip`. This can be overridden by a
+   local configuration file `./vsomeip.json` and/or a local configuration folder `./vsomeip`.
+   If `VSOMEIP_CONFIGURATION` is set to a valid file or directory path, this is used instead
+   of the standard configuration (thus neither default nor local file/folder will be parsed).
+
+NOTE: If the file/folder that is configured by `VSOMEIP_CONFIGURATION` does _not_ exist,
+the default configuration locations will be used.
+
+NOTE: vsomeip will parse and use the configuration from all files in a configuration folder
+but will _not_ consider directories within the configuration folder.
+
+In the following example the application `my_vsomeip_application` is started.
+The settings are read from the file `my_settings.json` in the current working
+directory. The client id for the application can be found under the name
+`my_vsomeip_client` in the configuration file.
+
+[source, bash]
+----
+#!/bin/bash
+export VSOMEIP_APPLICATION_NAME=my_vsomeip_client
+export VSOMEIP_CONFIGURATION=my_settings.json
+./my_vsomeip_application
+----
+
+Configuration File Structure
+----------------------------
+The configuration files for vsomeip are http://www.json.org/[JSON]-Files and are
+composed out of multiple key value pairs and arrays.
+
+[quote, , json.org]
+____
+* An object is an unordered set of name/value pairs. An object begins with `{
+(left brace)` and ends with `} (right brace)`. Each name is followed by `:
+(colon)` and the name/value pairs are separated by `, (comma)`.
+
+* An array is an ordered collection of values. An array begins with `[ (left
+bracket)` and ends with `] (right bracket)`. Values are separated by `,
+(comma)`.
+
+* A value can be a _string_ in double quotes, or a _number_, or `true` or `false`
+or `null`, or an _object_ or an _array_. These structures can be nested.
+____
+
+Configuration file element explanation:
+
+
+* 'unicast'
++
+The IP address of the host system.
++
+* 'netmask'
++
+The netmask to specify the subnet of the host system.
++
+//Logging
+* 'logging'
++
+** 'level'
++
+Specifies the log level (valid values: _trace_, _debug_, _info_, _warning_,
+_error_, _fatal_).
++
+** 'console'
++
+Specifies whether logging via console is enabled (valid values: _true, false_).
++
+** 'file'
++
+*** 'enable'
++
+Specifies whether a log file should be created (valid values: _true, false_).
++
+*** 'path'
++
+The absolute path of the log file.
++
+** 'dlt'
++
+Specifies whether Diagnostic Log and Trace (DLT) is enabled (valid values:
+_true, false_).
++
+//Applications
+* 'applications (array)'
++
+Contains the applications of the host system that use this config file.
++
+** 'name'
++
+The name of the application.
++
+** 'id'
++
+The id of the application.
++
+** 'num_dispatchers'
++
+The number of threads that shall be used to execute the callbacks to the application.
+If 'num_dispatchers' is set to '0', the callbacks will be executed within the 
+application thread. If an application wants/must do time consuming work directly
+within event, availability or message callbacks, 'num_dispatchers' should be set
+to '2' or higher.
++
+** `services` (array)
++
+Contains the services of the service provider.
+
+*** `service`
++
+The id of the service.
+
+*** `instance`
++
+The id of the service instance.
+
+*** `protocol` (optional)
++
+The protocol that is used to implement the service instance. The default setting
+is _someip_. If a different setting is provided, vsomeip does not open the specified
+port (server side) or does not connect to the specified port (client side). Thus,
+this option can be used to let the service discovery announce a service that is
+externally implemented. 
+
+*** `unicast` (optional)
++
+The unicast that hosts the service instance.
++
+NOTE: The unicast address is needed if external service instances shall be used,
+but service discovery is disabled. In this case, the provided unicast address
+is used to access the service instance. 
+
+*** `reliable`
++
+Specifies that the communication with the service is reliable respectively the
+TCP protocol is used for communication.
+
+**** `port`
++
+The port of the TCP endpoint.
+
+**** `enable-magic-cookies`
++
+Specifies whether magic cookies are enabled (valid values: _true_, _false_).
+
+*** `unreliable`
++
+Specifies that the communication with the service is unreliable respectively the
+UDP protocol is used for communication (valid values: the _port_ of the UDP
+endpoint).
+
+*** `multicast`
++
+A service can be offered to a specific group of clients via multicast.
+
+**** `address`
++
+The specific multicast address.
+
+**** `port`
++
+The specific port.
+
+*** `events` (array)
++
+Contains the events of the service.
+
+**** `event`
++
+The id of the event.
+
+***** `is_field`
++
+Specifies whether the event is of type field.
++
+NOTE: A field is a combination of getter, setter and notification event. It
+contains at least a getter, a setter, or a notifier. The notifier sends an event
+message that transports the current value of a field on change.
+
+***** `is_reliable`
++
+Specifies whether the communication is reliable respectively whether the event
+is sent with the TCP protocol (valid values: _true_,_false_).
++
+If the value is _false_ the UDP protocol will be used.
+
+*** `eventgroups` (array)
++
+Events can be grouped together into on event group. For a client it is thus
+possible to subscribe for an event group and to receive the appropriate events
+within the group.
+
+**** `eventgroup`
++
+The id of the event group.
+
+**** `events` (array)
++
+Contains the ids of the appropriate events.
+
+**** `is_multicast`
++
+Specifies whether the events should be sent via multicast (valid values:
+_true_,_false_).
+
+**** `multicast`
++
+The multicast address which the events are sent to.
+
+* `payload-sizes` (array)
++
+Array to specify the maximum allowed payload sizes per IP and port. If not
+specified, or a smaller value than the default values is specified, the default
+values are used. The settings in this array only affect communication over TCP
+and local communication over UNIX domain sockets.
+
+** `unicast`
++
+On client side: the IP of the remote service to which the oversized messages
+should be sent.
+On service side: the IP of the offered service which should receive the
+oversized messages and is allowed to respond with oversized messages.
+If client and service only communicate locally, any IP can be entered here as
+for local communication only the maximum specified payload size is relevant.
+
+** `ports` (array)
++
+Array which holds pairs of port and payload-size statements.
+
+*** `port`
++
+On client side: the port of the remote service to which the oversized messages
+should be sent.
+On service side: the port of the offered service which should receive the
+oversized messages and is allowed to respond with oversized messages.
+If client and service only communicate locally, any port number can be entered.
+
+*** `max-payload-size`
++
+On client side: the maximum payload size in bytes of a message sent to the
+remote service hosted on beforehand specified IP and port.
+On service side: the maximum payload size in bytes of messages received by the
+service offered on previously specified IP and port. If multiple services are
+hosted on the same port all of them are allowed to receive oversized messages
+and send oversized responses.
+
+* `routing`
++
+The name of the application that is responsible for the routing.
+
+* `service-discovery`
++
+Contains settings related to the Service Discovery of the host application.
+
+** `enable`
++
+Specifies whether the Service Discovery is enabled (valid values: _true_,
+_false_). The default value is _true_.
+
+** `multicast`
++
+The multicast address which the messages of the Service Discovery will be sent
+to. The default value is "224.0.0.1".
+
+** `port`
++
+The port of the Service Discovery. The default setting is 30490.
+
+** `protocol`
++
+The protocol that is used for sending the Service Discovery messages (valid
+values: _tcp_, _udp_). The default setting is _udp_.
+
+** `initial_delay_min`
++
+Minimum delay before first offer message.
+
+** `initial_delay_max`
++
+Maximum delay before first offer message.
+
+** `repetitions_base_delay`
++
+Base delay sending offer messages within the repetition phase.
+ 
+** `repetitions_max`
++
+Maximum number of repetitions for provided services within the 
+repetition phase.
+ 
+** `ttl`
++
+Lifetime of entries for provided services as well as consumed services and eventgroups.
+
+** `cyclic_offer_delay`
++
+Cycle of the OfferService messages in the main phase.
+
+** `request_response_delay`
++
+Minimum delay of a unicast message to a multicast message for
+provided services and eventgroups.
+
+Autoconfiguration
+-----------------
+vsomeip supports the automatic configuration of client identifiers and the routing.
+The first application that starts using vsomeip will automatically become the
+routing manager if it is _not_ explicitly configured. The client identifiers
+are generated from the diagnosis address that can be specified by defining
+DIAGNOSIS_ADDRESS when compiling vsomeip. vsomeip will use the diagnosis address
+as the high byte and enumerate the connecting applications within the low byte
+of the client identifier.
+
+vsomeipd
+--------
+The vsomeipd is a minimal vsomeip application intended to offer routing manager
+functionality on a node where one system wide configuration file is present.
+
+The vsomeipd uses the application name `vsomeipd` by default. This name can be
+overridden by specifying `-DROUTING=$DESIRED_NAME` during the cmake call.
+
+Example: Starting the daemon on a system where the system wide configuration is
+stored under `/etc/vsomeip.json`:
+[source, bash]
+----
+VSOMEIP_CONFIGURATION=/etc/vsomeip.json ./vsomeipd
+----
+
+When using the daemon it should be ensured that:
+
+* In the system wide configuration file the vsomeipd is defined as
+  routing manager, meaning it contains the line `"routing" : "vsomeipd"`.
+  If the default name is overridden the entry has to be adapted accordingly.
+  The system wide configuration file should contain the information about all
+  other offered services on the system as well.
+* There's no other vsomeip configuration file used on the system which contains
+  a `"routing"` entry. As there can only be one routing manager per system.
+
+
+vsomeip Hello World
+-------------------
+In this paragraph a Hello World program consisting out of a client and a service
+is developed. The client sends a message containing a string to the service.
+The service appends the received string to the string `Hello` and sends it back
+to the client.
+Upon receiving a response from the service the client prints the payload of the
+response ("Hello World").
+This example is intended to be run on the same host.
+
+All files listed here are contained in the `examples\hello_world` subdirectory.
+
+Build instructions
+~~~~~~~~~~~~~~~~~~
+The example can build with its own CMakeFile, please compile the vsomeip stack
+before hand as described in <<Compilation>>. Then compile the example starting
+from the repository root directory as followed:
+[source, bash]
+----
+cd examples/hello_world
+mkdir build
+cd build
+cmake ..
+make
+----
+
+Starting and expected output
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Starting and expected output of service
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+[source, bash]
+----
+$ VSOMEIP_CONFIGURATION=../helloworld-local.json \
+  VSOMEIP_APPLICATION_NAME=hello_world_service \
+  ./hello_world_service
+2015-04-01 11:31:13.248437 [info] Using configuration file: ../helloworld-local.json
+2015-04-01 11:31:13.248766 [debug] Routing endpoint at /tmp/vsomeip-0
+2015-04-01 11:31:13.248913 [info] Service Discovery disabled. Using static routing information.
+2015-04-01 11:31:13.248979 [debug] Application(hello_world_service, 4444) is initialized.
+2015-04-01 11:31:22.705010 [debug] Application/Client 5555 got registered!
+----
+
+Starting and expected output of client
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+[source, bash]
+----
+$ VSOMEIP_CONFIGURATION=../helloworld-local.json \
+  VSOMEIP_APPLICATION_NAME=hello_world_client \
+  ./hello_world_client
+2015-04-01 11:31:22.704166 [info] Using configuration file: ../helloworld-local.json
+2015-04-01 11:31:22.704417 [debug] Connecting to [0] at /tmp/vsomeip-0
+2015-04-01 11:31:22.704630 [debug] Listening at /tmp/vsomeip-5555
+2015-04-01 11:31:22.704680 [debug] Application(hello_world_client, 5555) is initialized.
+Sending: World
+Received: Hello World
+----
+
+CMakeFile
+~~~~~~~~~
+
+[source, bash]
+----
+include::examples/hello_world/CMakeLists.txt[]
+----
+
+Configuration File For Client and Service
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+[source, bash]
+----
+include::examples/hello_world/helloworld-local.json[]
+----
+
+Service
+~~~~~~~
+
+[source, bash]
+----
+include::examples/hello_world/hello_world_service.cpp[]
+----
+
+The service example results in the following program execution:
+
+:numbered!:
+
+[float]
+
+Main
+^^^^^
+
+. __main()__
++
+First the application is initialized. After the initialization is
+finished the application is started.
+
+[float]
+Initialization
+^^^^^^^^^^^^^^
+
+[start=2]
+. __init()__
++
+The initialization contains the registration of a message
+handler and an event handler.
++
+The message handler declares a callback (__on_message_cbk__) for messages that
+are sent to the specific service (specifying the service id, the service
+instance id and the service method id).
++
+The event handler declares a callback (__on_event_cbk__) for events that occur.
+One event can be the successful registration of the application at the runtime.
+
+[float]
+Start
+^^^^^
+
+[start=3]
+. __start()__
++
+The application will be started. This function only returns when the application
+will be stopped.
+
+[float]
+Callbacks
+^^^^^^^^^
+
+[start=4]
+. __on_state_cbk()__
++
+This function is called by the application when an state change occurred. If
+the application was successfully registered at the runtime then the specific
+service is offered.
+
+. __on_message_cbk()__
++
+This function is called when a message/request from a client for the specified
+service was received.
++
+First a response based upon the request is created.
+Afterwards the string 'Hello' will be concatenated with the payload of the
+client's request.
+After that the payload of the response is created. The payload data is set with
+the previously concatenated string.
+Finally the response is sent back to the client and the application is stopped.
+
+[float]
+Stop
+^^^^
+
+[start=6]
+. __stop()__
++
+This function stops offering the service, unregister the message and the event
+handler and shuts down the application.
+
+:numbered:
+
+Client
+~~~~~~
+[source, bash]
+----
+include::examples/hello_world/hello_world_client.cpp[]
+----
+
+The client example results in the following program execution:
+
+:numbered!:
+
+[float]
+Main
+^^^^^
+
+. __main()__
++
+First the application is initialized. After the initialization is finished the
+application is started.
+
+[float]
+Initialization
+^^^^^^^^^^^^^^
+
+[start=2]
+. __init()__
++
+The initialization contains the registration of a message handler, an event
+handler and an availability handler.
++
+The event handler declares again a callback (__on_state_cbk__) for state changes
+that occur.
++
+The message handler declares a callback (__on_message_cbk__) for messages that
+are received from any service, any service instance and any method.
++
+The availability handler declares a callback (__on_availability_cbk__) which is
+called when the specific service is available (specifying the service id and the
+service instance id).
+
+[float]
+Start
+^^^^^
+
+[start=3]
+. __start()__
++
+The application will be started. This function only returns when the application
+will be stopped.
+
+[float]
+Callbacks
+^^^^^^^^^
+
+[start=4]
+. __on_state_cbk()__
++
+
+This function is called by the application when an state change occurred. If the
+application was successfully registered at the runtime then the specific service
+is requested.
+
+. __on_availability_cbk()__
++
+This function is called when the requested service is available or no longer
+available.
++
+First there is a check if the change of the availability is related to the
+'hello world service' and the availability changed to true.
+If the check is successful a service request is created and the appropriate
+service information are set (service id, service instance id, service method
+id).
+After that the payload of the request is created. The data of the payload is
+'World' and will be set afterwards.
+Finally the request is sent to the service.
+
+. __on_message_cbk()__
++
+This function is called when a message/response was received.
+If the response is from the requested service, of type 'RESPONSE' and the return
+code is 'OK' then the payload of the response is printed. Finally the
+application is stopped.
+
+[float]
+Stop
+^^^^
+
+[start=7]
+. __stop()__
++
+This function unregister the event and the message handler and shuts down the
+application.
+
+:numbered: