diff options
-rw-r--r-- | README.md | 751 |
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: |