Shared Memory Plug-in¶
The Share Memory plug-in is used to exchange data between this plug-in and any other application with a shared memory interface.
Attention
This plug-in assigns CPU affinity and requires elevated permissions to run correctly. Make sure that you have elevated permissions to execute the EC Protocol Bridge.
Note
Any unknown parameters in a configuration file will simply be ignored.
Table of Contents
Shared Memory - Plug-in Level Configuration Parameters¶
Three configuration parameters are currently available at the plug-in level: RT thread core affinity, schedule priority, and sharedmem group parameter.
sharedmem: dx-core-affinity¶
This optional parameter defines the core to which the publisher, subscriber, or both real-time threads will be assigned.
By default, this value is set to 0.
Example:
dx-core-affinity: 1
sharedmem: dx-sched-priority¶
This optional parameter defines the core real-time thread priority assigned to the publisher, subscriber, or both.
By default, this value is set to 60.
Example:
dx-sched-priority: 60
sharedmem: sharedmem¶
This parameter defines a Posix or SystemV region of the shared memory in the Linux OS. Using shared memory allows two or more separate applications to quickly share data, which would be faster than using a network or socket. The limitation is that both applications need to be running in the same kernel instance. Example:
sharedmem:
sharedmem: datasets¶
Each dataset refers to a region of shared memory. One or more datasets can be defined. A dataset can be for reading or writing, but not for both at the same time as this could cause circular references. However, the same shared memory could be defined in one dataset for reading and another dataset for writing. This is possible because the datasets are processed sequentially.
Example:
datasets:
shared-ds: type¶
This parameter indicates whether the shared memory reader and writer are using Posix functions or SystemV functions. To use Posix functions, define type as Posix. To use SystemV functions, define type as SystemV. If type is not defined, Posix will be used. Posix functions are recommended for best performance.
Example:
type: Posix
shared-ds: name¶
This parameter applies to Posix shared memory and is also used for the name of the semaphore that is used to synchronize the shared memory between the applications. It is the first parameter passed to the shm_open function. The name defined here must match the name parameter used in the other application using the same shared memory.
Example:
name: "/motion_controller_test2"
shared-ds: key¶
This parameter only applies to the SystemV shared memory. It is the first parameter passed to the shmget function. The key defined here must match the key parameter used in the other application using the same shared memory.
Example:
key: 87654321
shared-ds: direction¶
This parameter indicates whether the dataset is to be read from shared memory or written to shared memory. It must be either “read” or “write”.
Example:
direction: write
shared-ds: datasize¶
This parameter is a positive integer number that defines the total size of the shared memory, which the system has allocated for the dataset. For Posix shared memory, this is the data size that is passed to the mmap function. For SystemV shared memory, this is the data size that is passed to the shmget function.
Shared memory synchronization is where a semaphore is used to synchronize the access to the shared memory between applications. Before reading from or writing to shared memory, the gateway tries to open a semaphore. If the semaphore can be opened, the read or write operation is performed. If the semaphore cannot be opened, indicating that another process is acting on the memory, the read or write operation will not be performed, and will be retried in the next gateway process cycle. The semaphore name passed to the sem_open function is the name concatenated with -sem. For the semaphore to work, each application should use the same semaphore name.
Example:
datasize: 4096
shared-ds: datafields¶
This parameter indicates one or more sequence of bytes in the shared memory, from the total bytes, which will either be read from the shared memory and broadcasted to the EC Protocol Bridge, if the dataset is set to “read”, or written to the shared memory from a EC Protocol Bridge listener, if the dataset is set to write.
share-fld: datatype¶
This parameter determines how the byte data will be interpreted after the bytes are read or the type of data that will be written to the bytes. This can be ‘int8’, ‘uint8’, ‘int16’, ‘uint16’, ‘int32’, ‘uint32’, ‘int64’, ‘uint64, ‘float’, ‘double’, or ‘string’.
Example:
datatype: int8
share-fld: startposition¶
This parameter indicates the position of the data field bytes in the total set of bytes. The starting index is zero.
Example:
startposition: 2
share-fld: datasize¶
The datasize is the number of bytes that is the data field. For int16, the size is 2. For int32, the size is 4. For int64, the size is 8. For string, the size is the maximum size of a null terminated string that includes the null terminator. For example, if the size is 4, “abc” will fit in the space, but “abcd” will not. If the size is 4 and the string is “ab”, the last third byte should and will contain a 0 as the null terminator.
Example:
datasize: 1
Shared Memory - Putting it all together¶
This section provides a sample configuration snippet. This section also provides the list of example configuration files, in the GitLab repo, which can be used for testing.
Shared Memory - Configuration Example¶
The following is a sample configuration snippet:
configuration:
sharedmem:
datasets:
-
name: "/motion_controller_test2"
key: 87654321
type: Posix
direction: write
datasize: 4096
interval: 1000000
dataset-id: shmemreadds
datafields:
-
datatype: int8
startposition: 0
datasize: 1
name: an_int8
datafld-id: an_int8
-
datatype: uint8
startposition: 1
datasize: 1
name: a_uint8
datafld-id: a_uint8
-
datatype: int16
startposition: 2
datasize: 2
name: an_int16
datafld-id: an_int16