From b01822bc59b6a3cf5a4962eca69f980d4f554af2 Mon Sep 17 00:00:00 2001 From: Christian Eltzschig Date: Wed, 9 Mar 2022 20:46:35 +0100 Subject: [PATCH 1/2] iox-#743 Review configuration guide Signed-off-by: Christian Eltzschig --- doc/website/advanced/configuration-guide.md | 98 ++++++++++++++------- 1 file changed, 66 insertions(+), 32 deletions(-) diff --git a/doc/website/advanced/configuration-guide.md b/doc/website/advanced/configuration-guide.md index ed2ec267c6..d1bbc049a0 100644 --- a/doc/website/advanced/configuration-guide.md +++ b/doc/website/advanced/configuration-guide.md @@ -2,23 +2,30 @@ ## :material-cog: CMake switches for configuring iceoryx_posh build -When building iceoryx_posh, there are several configuration options set by default. -These options adjust the limits of Publisher and Subscriber Ports for resource management. These limits are used to create management structures in the shared memory segment called `iceoryx_mgmt` when starting up RouDi. +There are several configuration options set by default when iceoryx_posh is build. +These options adjust the global maximum amount of resources like Publisher and +Subscriber Ports which can have a huge impact on the memory footprint of iceoryx +since the define the size of the management structures +in the shared memory segment called `iceoryx_mgmt` when RouDi is started. | switch | description | |:---------|:-------------| - | `IOX_MAX_PUBLISHERS` | Maximum number of publishers which can be managed by one `RouDi` instance | - | `IOX_MAX_SUBSCRIBERS_PER_PUBLISHER` | Maximum number of connected subscriber ports per publisher port | - | `IOX_MAX_PUBLISHER_HISTORY` | Maximum number of chunks available for the publisher history | - | `IOX_MAX_CHUNKS_ALLOCATED_PER_PUBLISHER_SIMULTANEOUSLY` | Maximum number of chunks a publisher can allocate at a given time | - | `IOX_MAX_SUBSCRIBERS` | Maximum number of subscribers which can be managed by one `RouDi` instance | - | `IOX_MAX_CHUNKS_HELD_PER_SUBSCRIBER_SIMULTANEOUSLY` | Maximum number of chunks a subscriber can hold at a given time (subscriber history size)| - | `IOX_MAX_INTERFACE_NUMBER` | Maximum number of interface ports which are used for gateways | - -Have a look at [IceoryxPoshDeployment.cmake](https://github.com/eclipse-iceoryx/iceoryx/blob/master/iceoryx_posh/cmake/IceoryxPoshDeployment.cmake) for the default values of the constants. + | `IOX_MAX_PUBLISHERS` | Maximum number of publishers in one iceoryx system | + | `IOX_MAX_SUBSCRIBERS_PER_PUBLISHER` | Maximum number of connections one publisher port can handle | + | `IOX_MAX_PUBLISHER_HISTORY` | Maximum size of a publishers history | + | `IOX_MAX_CHUNKS_ALLOCATED_PER_PUBLISHER_SIMULTANEOUSLY` | Maximum number of chunks a publisher can allocate in parallel | + | `IOX_MAX_SUBSCRIBERS` | Maximum number of subscribers in one iceoryx system | + | `IOX_MAX_CHUNKS_HELD_PER_SUBSCRIBER_SIMULTANEOUSLY` | Maximum number of chunks a subscriber can take in parallel| + | `IOX_MAX_INTERFACE_NUMBER` | Maximum number of interface ports which are used by gateways | + +Have a look at +[IceoryxPoshDeployment.cmake](https://github.com/eclipse-iceoryx/iceoryx/blob/master/iceoryx_posh/cmake/IceoryxPoshDeployment.cmake) +for the default values of the constants. !!! hint - With the default values set, the size of `iceoryx_mgmt` is ~64.5 MByte. You can reduce the size by decreasing the values from the table via the CMake options. The current values are printed in the CMake stage when building iceoryx. + With the default values set, the size of `iceoryx_mgmt` is ~64.5 MByte. You + can reduce the size by decreasing the values from the table via the CMake + options. The current values are printed in the CMake stage when building iceoryx. Example: @@ -26,20 +33,33 @@ Example: cmake -Bbuild -Hiceoryx_meta -DIOX_MAX_CHUNKS_HELD_PER_SUBSCRIBER_SIMULTANEOUSLY=64 ``` -With that change, the footprint of the management segment is reduced to ~52.7 MBytes. For larger use cases you can increase the value to avoid that samples are dropped on the subscriber side (see also [#615](https://github.com/eclipse-iceoryx/iceoryx/issues/615)). +With that change, the footprint of the management segment is reduced to ~52.7 MBytes. +For larger use cases you can increase the value to avoid that samples are dropped +on the subscriber side (see also [#615](https://github.com/eclipse-iceoryx/iceoryx/issues/615)). ## :material-memory: Configuring Mempools for RouDi -RouDi supports several shared memory segments with different access rights, to limit the read and write access between different applications. Inside of these segments reside mempools where the user payload data for transfer is stored. +RouDi supports several shared memory segments with different access rights, to +limit the read and write access between different applications. Memory pools are +then managing the those segments and organizing the user payload data required +for communication. !!! note - Actually only the chunk-payload size is configured and the size of the `ChunkHeader` will be added to the configured size. If a user-header or a user-payload alignment larger than 8 is used, the available size for the user-payload will be smaller than the configured chunk-payload since some space is needed for the other functionality. - Please have a look at the `chunk_header.md` design document for a formula how to determine the necessary chunk-payload size with user-header and extended user-payload alignment. - -For building RouDi, iceoryx ships a library named `iceoryx_posh_roudi`. This lib gives you an API for compiling your own RouDi application and is part of `iceoryx_posh`. + Actually only the chunk-payload size is configured and the size of the + `ChunkHeader` will be added to the configured size. If a user-header or a + user-payload alignment larger than 8 is used, the available size for the + user-payload will be smaller than the configured chunk-payload since some + space is needed for the other functionality. + Please have a look at the + [chunk_header.md](https://github.com/eclipse-iceoryx/iceoryx/blob/master/doc/design/chunk_header.md) + design document for a formula how to determine the necessary chunk-payload + size with user-header and extended user-payload alignment. + +For building RouDi, iceoryx ships a library named `iceoryx_posh_roudi`. This lib +provides you an API for compiling your own RouDi application and is part of `iceoryx_posh`. !!! note - The chunk size for the mempool needs to follow these restrictions: + The chunk size for the memory pools needs to comply with the following restrictions: 1. Chunksize needs to be greater than the alignment 2. Chunksize needs to be a multiple of the alignment @@ -48,11 +68,14 @@ The value for the alignment is set to 8. ### :material-file-cog: Dynamic configuration -One way is to read a configuration dynamically at RouDi runtime (startup). -Using TOML Config in RouDi is not mandatory for configuring segments and mempools, but a comfortable alternative. +One way is to read a configuration dynamically during the startup of RouDi. +Using the TOML Config in RouDi is not mandatory for configuring segments and +mempools, but a comfortable alternative. -To enable the TOML config in iceoryx, the CMake option `-DTOML_CONFIG=ON` must be used (enabled by default). -The `iox-roudi` provided by iceoryx is with TOML support and can be used out of the box. +To enable the TOML config in iceoryx, the CMake option `-DTOML_CONFIG=ON` must +be enabled (this is the default setting). +The `iox-roudi` application provided by iceoryx is compiled with TOML support and +can be used out of the box. If you create your own RouDi application you need to link against `iceoryx_posh_config`: @@ -70,7 +93,7 @@ The TOML config file can be passed to RouDi with the `-c` command-line option. ./iox-roudi -c /absolute/path/to/config/file.toml ``` -This is a common config file with format version 1: +This is an examplary config file with format version 1: ```TOML [general] @@ -91,8 +114,11 @@ size = 1024 count = 1000 ``` -With this configuration, one payload segment will be created. The access rights are set to the RouDi group id. -There are three mempools within this segment. One with 10000 chunks of 32 byte payload size, one with 10000 chunks of 128 bytes, and one with 1000 chunks of 1024 bytes. +With this configuration, one payload segment will be created. The access rights +are set to the RouDi group id as default. +There are three mempools within this segment. One with 10000 chunks of 32 byte +payload size, one with 10000 chunks of 128 bytes, and one with 1000 chunks of +1024 bytes. To restrict the access, a reader and writer group can be set: @@ -117,7 +143,8 @@ size = 1024 count = 1000 ``` -With this configuration, only applications from the `bar` group have write access and can allocate chunks. Applications from the `foo` group have only read access. +With this configuration, only applications from the `bar` group have write access +and can allocate chunks. Applications from the `foo` group have only read access. This is an example with multiple segments: @@ -142,12 +169,19 @@ size = 1024 count = 100 ``` -When no config file is specified, a hard-coded version similar to the [default config](https://github.com/eclipse-iceoryx/iceoryx/blob/master/iceoryx_posh/etc/iceoryx/roudi_config_example.toml) will be used. +When no configuration file is specified a hard-coded version similar to the +[default config](https://github.com/eclipse-iceoryx/iceoryx/blob/master/iceoryx_posh/etc/iceoryx/roudi_config_example.toml) +will be used. ### Static configuration -Another way is to have a static config that is compile-time dependent, this means that you have to recompile your RouDi application if you want to change your config (not the iceoryx_posh_roudi lib). -You can have your source file with `main()` method where you can create your custom configuration and pass it to a RouDi instantiation. -In your CMake file for your custom RouDi you need to ensure that it is **not** linking against `iceoryx_posh_config` to have a static config. +Another way is to have a static configuration that is compiled into the roudi application. +As a consequence you have to recompile your RouDi application if you want to change +your config (not the `iceoryx_posh_roudi` lib). +You can create your custom configuration in the `main()` function where you then pass +it as constructor argument to the RouDi instance. +In the cmake file entry of the custom RouDi executable you need to ensure that it +is **not** linking against `iceoryx_posh_config` to ensure using the static configuration. -A good example of a static config can be found [here](https://github.com/eclipse-iceoryx/iceoryx/blob/master/iceoryx_examples/iceperf/roudi_main_static_config.cpp). +An example of a static config can be found +[here](https://github.com/eclipse-iceoryx/iceoryx/blob/master/iceoryx_examples/iceperf/roudi_main_static_config.cpp). From 8b8638481c0c57be216d8c098bb0f77b964b9bab Mon Sep 17 00:00:00 2001 From: Christian Eltzschig Date: Mon, 14 Mar 2022 11:15:40 +0100 Subject: [PATCH 2/2] iox-#743 Fix typos and rephrase some sentence Signed-off-by: Christian Eltzschig --- doc/website/advanced/configuration-guide.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/doc/website/advanced/configuration-guide.md b/doc/website/advanced/configuration-guide.md index d1bbc049a0..957485fa75 100644 --- a/doc/website/advanced/configuration-guide.md +++ b/doc/website/advanced/configuration-guide.md @@ -5,7 +5,7 @@ There are several configuration options set by default when iceoryx_posh is build. These options adjust the global maximum amount of resources like Publisher and Subscriber Ports which can have a huge impact on the memory footprint of iceoryx -since the define the size of the management structures +since they define the size of the management structures in the shared memory segment called `iceoryx_mgmt` when RouDi is started. | switch | description | @@ -40,8 +40,8 @@ on the subscriber side (see also [#615](https://github.com/eclipse-iceoryx/iceor ## :material-memory: Configuring Mempools for RouDi RouDi supports several shared memory segments with different access rights, to -limit the read and write access between different applications. Memory pools are -then managing the those segments and organizing the user payload data required +limit the read and write access between different applications. Memory pools +manage those segments and organize the user payload data required for communication. !!! note @@ -72,8 +72,8 @@ One way is to read a configuration dynamically during the startup of RouDi. Using the TOML Config in RouDi is not mandatory for configuring segments and mempools, but a comfortable alternative. -To enable the TOML config in iceoryx, the CMake option `-DTOML_CONFIG=ON` must -be enabled (this is the default setting). +The CMake option `-DTOML_CONFIG`, which is `ON` by default, enables the TOML config +for iceoryx. The `iox-roudi` application provided by iceoryx is compiled with TOML support and can be used out of the box.