diff options
Diffstat (limited to 'documentation')
| -rw-r--r-- | documentation/vsomeipProtocol | 372 | ||||
| -rw-r--r-- | documentation/vsomeipUserGuide | 132 |
2 files changed, 463 insertions, 41 deletions
diff --git a/documentation/vsomeipProtocol b/documentation/vsomeipProtocol new file mode 100644 index 0000000..2fc905e --- /dev/null +++ b/documentation/vsomeipProtocol @@ -0,0 +1,372 @@ +vSomeIP command documentation +============================= + +VSOMEIP_ASSIGN_CLIENT (0x00) + +Command 00 +Version xx xx +Client xx xx +Size xx xx xx xx +Name xx ... xx ;#xx = Size + + +VSOMEIP_ASSIGN_CLIENT_ACK (0x01) + +Command 01 +Version xx xx +Client xx xx +Size 02 00 00 00 +Assigned xx xx + + +VSOMEIP_REGISTER_APPLICATION (0x02) + +Command 02 +Version xx xx +Client xx xx +Size 00 00 00 00 + + +VSOMEIP_DEREGISTER_APPLICATION (0x03) + +Command 03 +Version xx xx +Client xx xx +Size 00 00 00 00 + + +VSOMEIP_APPLICATION_LOST (0x04) + +<unused> + + +VSOMEIP_ROUTING_INFO (0x05) + +Command 05 +Version xx xx +Client xx xx +Size xx xx xx xx +Entries + SubCommand xx ; RIE_ADD_CLIENT (0x0) or RIE_DEL_CLIENT (0x1) + Size xx xx xx xx + Client xx xx + [Address] xx .. xx ; Size - sizeof(Client) - sizeof(Port) + [Port] xx + + SubCommand xx ; RIE_ADD_SERVICE_INSTANCE (0x2) or RIE_DEL_SERVICE_INSTANCE (0x3) + Size xx xx xx xx ; Command size + Size xx xx xx xx ; Client info size + Client xx xx + [Address] xx .. xx ; Client info size - sizeof(Client) - sizeof(Port) + [Port] xx + Size xx xx xx xx ; Services size + Service xx xx + Instance xx xx + Major xx + Minor xx xx xx xx + + +VSOMEIP_REGISTERED_ACK (0x06) + +Command 06 +Version xx xx +Client xx xx +Size 00 00 00 00 + + +VSOMEIP_PING (0x07) + +Command 07 +Version xx xx +Client 00 00 +Size 00 00 00 00 + + +VSOMEIP_PONG (0x08) + +Command 08 +Version xx xx +Client xx xx +Size 00 00 00 00 + + +VSOMEIP_OFFER_SERVICE (0x10) + +Command 10 +Version xx xx +Client xx xx +Size 09 00 00 00 +Service xx xx +Instance xx xx +Major xx +Minor xx xx xx xx + + +VSOMEIP_STOP_OFFER_SERVICE (0x11) + +Command 11 +Version xx xx +Client xx xx +Size 09 00 00 00 +Service xx xx +Instance xx xx +Major xx +Minor xx xx xx xx + + +VSOMEIP_SUBSCRIBE (0x12) + +Command 12 +Version xx xx +Client xx xx +Size xx xx xx xx +Service xx xx +Instance xx xx +Eventgroup xx xx +Major xx +Event xx xx +Pending ID xx xx +Filter + OnChange xx + OnChangeResetsInterval xx + Interval xx xx xx xx xx xx xx xx + Ignore (per entry) + Key xx xx xx xx xx xx xx xx + Value xx + + +VSOMEIP_UNSUBSCRIBE (0x13) +VSOMEIP_EXPIRE (0x2A) + +Command 13/2A +Version xx xx +Client xx xx +Size 0a 00 00 00 +Service xx xx +Instance xx xx +Eventgroup xx xx +Event xx xx +Pending ID xx xx + + +VSOMEIP_REQUEST_SERVICE (0x14) + +Command 14 +Version xx xx +Client xx xx +Size xx xx xx xx +Entries + Service xx xx + Instance xx xx + Major xx + Minor xx xx xx xx + + +VSOMEIP_RELEASE_SERVICE (0x15) + +Command 15 +Version xx xx +Client xx xx +Size 04 00 00 00 +Service xx xx +Instance xx xx + + +VSOMEIP_SUBSCRIBE_NACK (0x16) + +Command 16 +Version xx xx +Client xx xx +Size 0c 00 00 00 +Service xx xx +Instance xx xx +Eventgroup xx xx +Subscriber xx xx +Event xx xx +ID xx xx + + +VSOMEIP_SUBSCRIBE_ACK (0x17) + +Command 17 +Version xx xx +Client xx xx +Size 0c 00 00 00 +Service xx xx +Instance xx xx +Eventgroup xx xx +Subscriber xx xx +Event xx xx +ID xx xx + + +VSOMEIP_SEND (0x18) +VSOMEIP_NOTIFY (0x19) +VSOMEIP_NOTIFY_ONE (0x1A) + +Command 18|19|1a +Version xx xx +Client xx xx +Size xx xx xx xx +Instance xx xx +Reliable xx ; UDP (00) or TCP (01) +Status xx ; CRC of E2E - protected messages +Destination xx xx ; Client ID of the receiver +Payload xx ... xx + + +VSOMEIP_REGISTER_EVENT (0x1B) + +Command 1b +Version xx xx +Client xx xx +Size xx xx xx xx ; 10 + #eventgroups * 2 +Entries + Service xx xx + Instance xx xx + Notifier xx xx + Type xx ; ET_EVENT (00), ET_SELECTIVE_EVENT(01) or ET_FIELD(02) + Provided xx ; False (00) or True (01) + Reliability xx ; UDP (00) or TCP (01) + IsCyclic xx + Num Eventgroups xx xx + Entries + Eventgroup xx xx + + +VSOMEIP_UNREGISTER_EVENT (0x1C) + +Command 1c +Version xx xx +Client xx xx +Size 07 00 00 00 +Service xx xx +Instance xx xx +Notifier xx xx +Provided xx + + +VSOMEIP_ID_RESPONSE (0x1D) + +<unused> + + +VSOMEIP_ID_REQUEST (0x1E) + +<unused> + + +VSOMEIP_OFFERED_SERVICES_REQUEST (0x1F) + +Command 1f +Version xx xx +Client xx xx +Size 01 00 00 00 +OfferType xx (00 = LOCAL, 01 = REMOTE, 02 = ALL) + + +VSOMEIP_OFFERED_SERVICES_RESPONSE (0x20) + +Command 20 +Version xx xx +Client xx xx +Size xx xx xx xx +OfferedServices + Subcommand xx (00 = ADD CLIENT, 01 = ADD SERVICE INSTANCE, 02 = DELETE SERVICE INSTANCE, 03 = DELETE CLIENT) + Size xx xx xx xx + ServiceInstances + Service xx xx + Instance xx xx + Major xx xx + Minor xx xx + + +VSOMEIP_UNSUBSCRIBE_ACK (0x21) + +Command 21 +Version xx xx +Client xx xx +Size 08 00 00 00 +Service xx xx +Instance xx xx +Eventgroup xx xx +Id xx xx + + +VSOMEIP_RESEND_PROVIDED_EVENTS (0x22) + +Command 22 +Version xx xx +Client xx xx +Size 04 00 00 00 +PendingOfferId xx xx xx xx + + +VSOMEIP_UPDATE_SECURITY_POLICY (0x23) +VSOMEIP_UPDATE_SECURITY_POLICY_INT (0x29) + +Command 23/29 +Version xx xx +Client xx xx +Size xx xx xx xx +UpdateId xx xx xx xx +Policy xx ... xx + + +VSOMEIP_UPDATE_SECURITY_POLICY_RESPONSE (0x24) + +Command 24 +Version xx xx +Client xx xx +Size 04 00 00 00 +UpdateId xx xx xx xx + + +VSOMEIP_REMOVE_SECURITY_POLICY (0x25) + +Command 25 +Version xx xx +Client xx xx +Size 0c 00 00 00 +UpdateId xx xx xx xx +Uid xx xx xx xx +Gid xx xx xx xx + + +VSOMEIP_REMOVE_SECURITY_POLICY_RESPONSE (0x26) + +Command 26 +Version xx xx +Client xx xx +Size 04 00 00 00 +UpdateId xx xx xx xx + + +VSOMEIP_UPDATE_SECURITY_CREDENTIALS (0x27) + +Command 27 +Version xx xx +Client xx xx +Size xx xx xx xx +Credentials + Uid xx xx xx xx + Gid xx xx xx xx + + +VSOMEIP_DISTRIBUTE_SECURITY_POLICIES (0x28) + +Command 28 +Version xx xx +Client xx xx xx xx +Size xx xx xx xx +PoliciesCount xx xx xx xx +Policies + Size xx xx xx xx + Data xx ... xx + + +VSOMEIP_SUSPEND (0x30) + +Command 30 +Version xx xx +Size xx xx xx xx
\ No newline at end of file diff --git a/documentation/vsomeipUserGuide b/documentation/vsomeipUserGuide index dd4f13d..b98183a 100644 --- a/documentation/vsomeipUserGuide +++ b/documentation/vsomeipUserGuide @@ -15,7 +15,7 @@ vsomeip Copyright +++++++ -Copyright (C) 2015-2019, Bayerische Motoren Werke Aktiengesellschaft (BMW AG) +Copyright (C) 2015-2022, Bayerische Motoren Werke Aktiengesellschaft (BMW AG) License +++++++ @@ -42,7 +42,7 @@ Build Instructions ------------------ Dependencies ~~~~~~~~~~~~ -* A C++11 enabled compiler like gcc >= 5.2 is needed. +* A C++14 enabled compiler is needed (default for gcc >= v6.1) * vsomeip uses cmake as buildsystem. * vsomeip uses Boost >= 1.55: ** Ubuntu 14.04: @@ -144,15 +144,6 @@ to be ready to send/receive messages, call cmake like: cmake -DROUTING_READY_MESSAGE=<YOUR MESSAGE> .. ---- -Compilation with configuration overlays -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -To compile vsomeip with configuration overlays enabled, call cmake -like: -[source,bash] ----- -cmake -DENABLE_CONFIGURATION_OVERLAYS=1 .. ----- - Compilation with vSomeIP 2 compatibility layer ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ To compile vsomeip with enabled vSomeIP 2 compatibility layer, call @@ -272,6 +263,8 @@ On startup the following environment variables are read out: 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). +* `VSOMEIP_CONFIGURATION_<application>`: Application-specific version of `VSOMEIP_CONFIGURATION`. + Please note that <application> must be valid as part of an environment variable. * `VSOMEIP_MANDATORY_CONFIGURATION_FILES`: vsomeip allows to specify mandatory configuration files to speed-up application startup. While mandatory configuration files are read by all applications, all other configuration files are only read by the application that is @@ -551,14 +544,6 @@ An application plug-in extends the functionality on application level. It gets i by vsomeip over the basic application states (INIT/START/STOP) and can, based on these notifications, access the standard "application"-API via the runtime. + -** 'overlay' (optional) -+ -Contains the path to a configuration that overwrites specific configuration elements -(unicast, netmask, device, network, diagnosis address & mask, service discovery) for the -application. This allows to manage different network addresses from a single process. -+ -NOTE: This feature is only available if vsomeip was compiled with ENABLE_CONFIGURATION_OVERLAYS. -+ * `services` (array) + Contains the services of the service provider. @@ -951,14 +936,15 @@ Event ID. *** `on_change` + -Specifies whether the event is only forwared on -paylaod change or not. (valid values: _true_, _false_). +Specifies whether the event is forwarded on +payload change or not. (valid values: _true_, _false_). +Default is _false_. *** `ignore` + Array of payload indexes with given bit mask (optional) to be ignored in payload change evaluation. -Instead of specifying an index / bitmask pair, one can only define the paylaod index +Instead of specifying an index / bitmask pair, one can only define the payload index which shall be ignored in the evaluation. **** `index` @@ -973,17 +959,64 @@ Example mask: 0x0f ignores payload changes in low nibble of the byte at given in *** `interval` + Specifies if the event shall be debounced based on elapsed time interval. -(valid values: _time in ms_, _never_). +(valid values: _time in ms_, _never_). Default is _never_. -*** `on_change_resets_interval_` (optional) +*** `on_change_resets_interval` (optional) Specifies if interval timer is reset when payload change was detected. -(valid values: _false_, _true_). +(valid values: _false_, _true_). Defaults to _false_. + +* `routing` (optional) ++ +Specifies the properties of the routing. Either a string that specifies the application that hosts the +routing component or a structure that specifies all properties of the routing. If the routing is not +specified, the first started application will host the routing component. + +** `host` ++ +Properties of the routing manager. + +*** `name` ++ +Name if the application that hosts the routing component. + +*** `uid` ++ +User identifier of the process that runs the routing component. Must be specified if credential checks +are enabled by _check_credentials_ set to true. + +*** `gid` ++ +Group identifier of the process that runs the routing component. Must be specified if credential checks +are enabled by _check_credentials_ set to true. + +*** `unicast` (optional) ++ +The unicast address that shall be used by the routing manager, if the internal communication shall be done +by using TCP connections. -* `routing` +*** `port` (optional) + -The name of the application that is responsible for the routing. +The port that shall be used by the routing manager, if the internal communication shall be done +by using TCP connections. -* `routing-credentials` +** `guests` (optional) ++ +Properties of all applications that do not host the routing component, if the internal communication shall be +done using TCP connections. + +*** `unicast` ++ +The unicast address that shall be used by the applications to connect to the routing manager. + +*** `ports` ++ +A set of port ranges that shall be used to connect to the routing manager. Each client application requires +two ports, one for receiving messages from other applications and one to send messages to other applications. +Notes: Each configured port range must contain an even number of ports. If an even port number is configured +to be the routing host port, the first port in the range must also be even. If an uneven port number is +configured to be the routing host port, the first port in the range must also be uneven. + +* `routing-credentials` (deprecated) + The UID / GID of the application acting as routing manager. (Must be specified if credentials checks are enabled using _check_credentials_ set to _true_ in order to successfully check the routing managers credentials passed on connect) @@ -1113,14 +1146,6 @@ Time which the stack collects new service offers before they enter the repetition phase. This can be used to reduce the number of sent messages during startup. The default setting is _500ms_. + - -** `max_remote_subscribers` -+ -Limit the number of possible remote subscribers from same remote IP address -to an eventgroup provided by a service/instance if the remote subscriber uses -different ports for its subscriptions. The default setting is _3_. -+ - //Watchdog * anchor:config-watchdog[]`watchdog` (optional) + @@ -1408,6 +1433,31 @@ They give a basic overview how to use the security related configuration tags de in this chapter to run a simple request/response or subscribe/notify example locally or remotely. + +Security policy extensions +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +vsomeip policy extension configuration supports the definition of paths that contain additional +security policies to be loaded whenever a client with a yet unknown hostname connects to a local server endpoint. +The following configuration parameters are available and can be defined in a file named `vsomeip_policy_extensions.json`. + +// Security policy extension +* anchor:config-policy-extension[]`container_policies` (optional array) ++ +Specifies the additional configuration folders to be loaded for each container hostname / filesystem path pair. + +** `container` ++ +Specifies the linux hostname. + +** `path` ++ +Specifies a filesystem path (relative to vsomeip_policy_extensions.json or absolute) which contains +$UID_$GID subfolders that hold a `vsomeip_security.json` file. +Note: ($UID / $GID is the UID /GID of the vsomeip client application +to which a client from hostname defined with `container`connetcs to. + + Audit Mode ~~~~~~~~~~ vsomeip's security implementation can be put in a so called 'Audit Mode' where @@ -1551,7 +1601,7 @@ Service [source, bash] ---- -include::../examples/hello_world/hello_world_service.cpp[] +include::../examples/hello_world/hello_world_service_main.cpp[] ---- The service example results in the following program execution: @@ -1634,7 +1684,7 @@ Client ~~~~~~ [source, bash] ---- -include::../examples/hello_world/hello_world_client.cpp[] +include::../examples/hello_world/hello_world_client_main.cpp[] ---- The client example results in the following program execution: @@ -1829,17 +1879,17 @@ Example: ---- // get trace connector std::shared_ptr<vsomeip::trace::connector> its_connector - = vsomeip::trace::connector::get(); + = vsomeip::trace::connector::get(); // add channel std::shared_ptr<vsomeip::trace::channel> its_channel - = its_connector->create_channel("MC", "My channel"); + = its_connector->create_channel("MC", "My channel"); // add filter rule vsomeip::trace::match_t its_match = std::make_tuple(0x1234, 0xffff, 0x80e8); vsomeip::trace::filter_id_t its_filter_id - = its_channel->add_filter(its_match, true); + = its_channel->add_filter(its_match, true); // init trace connector its_connector->init(); |