2017-04-15 21:22:19 +02:00
|
|
|
/** Shared-memory interface: The interface functions that the external program should use.
|
|
|
|
*
|
|
|
|
* @file
|
|
|
|
* @author Georg Martin Reinke <georg.reinke@rwth-aachen.de>
|
|
|
|
* @copyright 2017, Institute for Automation of Complex Power Systems, EONERC
|
2017-04-27 12:56:43 +02:00
|
|
|
* @license GNU General Public License (version 3)
|
|
|
|
*
|
|
|
|
* VILLASnode
|
|
|
|
*
|
|
|
|
* This program is free software: you can redistribute it and/or modify
|
|
|
|
* it under the terms of the GNU General Public License as published by
|
|
|
|
* the Free Software Foundation, either version 3 of the License, or
|
|
|
|
* any later version.
|
2017-05-05 19:24:16 +00:00
|
|
|
*
|
2017-04-27 12:56:43 +02:00
|
|
|
* This program is distributed in the hope that it will be useful,
|
|
|
|
* but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
|
|
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
|
|
* GNU General Public License for more details.
|
2017-05-05 19:24:16 +00:00
|
|
|
*
|
2017-04-27 12:56:43 +02:00
|
|
|
* You should have received a copy of the GNU General Public License
|
|
|
|
* along with this program. If not, see <http://www.gnu.org/licenses/>.
|
2017-04-15 21:22:19 +02:00
|
|
|
*********************************************************************************/
|
2017-04-07 12:57:40 +02:00
|
|
|
|
2017-04-17 18:50:43 +02:00
|
|
|
/** Interface to the shared memory node for external programs.
|
|
|
|
*
|
|
|
|
* @addtogroup shmem Shared memory interface
|
|
|
|
* @{
|
|
|
|
*/
|
|
|
|
|
2017-04-15 18:59:22 +02:00
|
|
|
#pragma once
|
2017-04-07 12:57:40 +02:00
|
|
|
|
2017-04-26 11:48:58 +02:00
|
|
|
#ifdef __cplusplus
|
|
|
|
extern "C" {
|
|
|
|
#endif
|
|
|
|
|
2017-04-07 12:57:40 +02:00
|
|
|
#include "pool.h"
|
|
|
|
#include "queue.h"
|
|
|
|
#include "queue_signalled.h"
|
2017-06-08 12:43:24 +02:00
|
|
|
#include "sample.h"
|
|
|
|
|
|
|
|
#define DEFAULT_SHMEM_QUEUELEN 512
|
2017-06-08 13:53:07 +02:00
|
|
|
#define DEFAULT_SHMEM_SAMPLELEN 64
|
2017-04-07 12:57:40 +02:00
|
|
|
|
2017-04-16 23:00:30 +02:00
|
|
|
/** A signalled queue or a regular (polling) queue, depending on the polling setting. */
|
2017-04-07 12:57:40 +02:00
|
|
|
union shmem_queue {
|
|
|
|
struct queue q;
|
|
|
|
struct queue_signalled qs;
|
|
|
|
};
|
|
|
|
|
2017-06-08 12:43:24 +02:00
|
|
|
#define SHMEM_MIN_SIZE (sizeof(struct memtype) + sizeof(struct memblock) + sizeof(pthread_barrier_t) + sizeof(pthread_barrierattr_t))
|
|
|
|
|
|
|
|
/** Struct containing all parameters that need to be known when creating a new
|
|
|
|
* shared memory object. */
|
|
|
|
struct shmem_conf {
|
2017-06-15 15:07:19 +02:00
|
|
|
int polling; /**< Whether to use polling instead of POSIX CVs */
|
|
|
|
int queuelen; /**< Size of the queues (in elements) */
|
|
|
|
int samplelen; /**< Maximum number of data entries in a single sample */
|
2017-06-08 12:43:24 +02:00
|
|
|
};
|
|
|
|
|
2017-04-07 13:27:10 +02:00
|
|
|
/** The structure that actually resides in the shared memory. */
|
2017-04-07 12:57:40 +02:00
|
|
|
struct shmem_shared {
|
2017-06-15 15:07:19 +02:00
|
|
|
int polling; /**< Whether to use a pthread_cond_t to signal if new samples are written to incoming queue. */
|
|
|
|
union shmem_queue queue; /**< Queues for samples passed in both directions. */
|
|
|
|
struct pool pool; /**< Pool for the samples in the queues. */
|
2017-06-14 13:00:43 +02:00
|
|
|
};
|
2017-04-15 18:59:22 +02:00
|
|
|
|
2017-06-14 13:32:44 +02:00
|
|
|
/** Relevant information for one direction of the interface. */
|
2017-06-14 13:00:43 +02:00
|
|
|
struct shmem_dir {
|
2017-06-15 15:07:19 +02:00
|
|
|
void *base; /**< Base address of the region. */
|
|
|
|
const char *name; /**< Name of the shmem object. */
|
|
|
|
size_t len; /**< Total size of the region. */
|
|
|
|
struct shmem_shared *shared; /**< Actually shared datastructure */
|
2017-06-08 12:43:24 +02:00
|
|
|
};
|
2017-04-15 18:59:22 +02:00
|
|
|
|
2017-06-08 13:01:23 +02:00
|
|
|
/** Main structure representing the shared memory interface. */
|
2017-06-08 12:43:24 +02:00
|
|
|
struct shmem_int {
|
2017-06-14 13:00:43 +02:00
|
|
|
struct shmem_dir read, write;
|
2017-04-07 12:57:40 +02:00
|
|
|
};
|
|
|
|
|
2017-06-14 13:00:43 +02:00
|
|
|
/** Open the shared memory objects and retrieve / initialize the shared data structures.
|
2017-06-14 13:32:44 +02:00
|
|
|
* Blocks until another process connects by opening the same objects.
|
2017-06-15 15:07:19 +02:00
|
|
|
*
|
2017-06-14 13:00:43 +02:00
|
|
|
* @param[in] wname Name of the POSIX shared memory object containing the output queue.
|
|
|
|
* @param[in] rname Name of the POSIX shared memory object containing the input queue.
|
2017-06-08 12:43:24 +02:00
|
|
|
* @param[inout] shm The shmem_int structure that should be used for following
|
|
|
|
* calls will be written to this pointer.
|
2017-06-14 13:00:43 +02:00
|
|
|
* @param[in] conf Configuration parameters for the output queue.
|
|
|
|
* @retval 0 The objects were opened and initialized successfully.
|
2017-06-08 12:43:24 +02:00
|
|
|
* @retval <0 An error occured; errno is set accordingly.
|
2017-04-16 23:00:30 +02:00
|
|
|
*/
|
2017-06-14 13:00:43 +02:00
|
|
|
int shmem_int_open(const char* wname, const char* rname, struct shmem_int* shm, struct shmem_conf* conf);
|
2017-04-12 14:38:18 +02:00
|
|
|
|
2017-06-08 12:43:24 +02:00
|
|
|
/** Close and destroy the shared memory interface and related structures.
|
2017-06-15 15:07:19 +02:00
|
|
|
*
|
2017-06-08 12:43:24 +02:00
|
|
|
* @param shm The shared memory interface.
|
2017-04-17 18:50:43 +02:00
|
|
|
* @retval 0 Closing successfull.
|
|
|
|
* @retval <0 An error occurred; errno is set appropiately.
|
2017-04-16 23:00:30 +02:00
|
|
|
*/
|
2017-06-08 12:43:24 +02:00
|
|
|
int shmem_int_close(struct shmem_int *shm);
|
2017-04-07 13:27:10 +02:00
|
|
|
|
2017-06-08 12:43:24 +02:00
|
|
|
/** Read samples from the interface.
|
2017-06-15 15:07:19 +02:00
|
|
|
*
|
2017-06-08 12:43:24 +02:00
|
|
|
* @param shm The shared memory interface.
|
2017-04-17 18:50:43 +02:00
|
|
|
* @param smps An array where the pointers to the samples will be written. The samples
|
2017-04-16 23:00:30 +02:00
|
|
|
* must be freed with sample_put after use.
|
2017-04-17 18:50:43 +02:00
|
|
|
* @param cnt Number of samples to be read.
|
|
|
|
* @retval >=0 Number of samples that were read. Can be less than cnt (including 0) in case not enough samples were available.
|
2017-06-08 12:43:24 +02:00
|
|
|
* @retval -1 The other process closed the interface; no samples can be read anymore.
|
2017-04-16 23:00:30 +02:00
|
|
|
*/
|
2017-06-08 12:43:24 +02:00
|
|
|
int shmem_int_read(struct shmem_int *shm, struct sample *smps[], unsigned cnt);
|
2017-04-07 13:27:10 +02:00
|
|
|
|
2017-06-08 12:43:24 +02:00
|
|
|
/** Write samples to the interface.
|
2017-06-15 15:07:19 +02:00
|
|
|
*
|
2017-06-08 12:43:24 +02:00
|
|
|
* @param shm The shared memory interface.
|
2017-06-14 13:31:59 +02:00
|
|
|
* @param smps The samples to be written. Must be allocated from shm_int_alloc.
|
2017-04-17 18:50:43 +02:00
|
|
|
* @param cnt Number of samples to write.
|
|
|
|
* @retval >=0 Number of samples that were successfully written. Can be less than cnt (including 0) in case of a full queue.
|
2017-06-08 12:43:24 +02:00
|
|
|
* @retval -1 The write failed for some reason; no more samples can be written.
|
2017-04-16 23:00:30 +02:00
|
|
|
*/
|
2017-06-08 12:43:24 +02:00
|
|
|
int shmem_int_write(struct shmem_int *shm, struct sample *smps[], unsigned cnt);
|
2017-04-07 12:57:40 +02:00
|
|
|
|
2017-06-17 03:15:35 +02:00
|
|
|
/** Allocate samples to be written to the interface.
|
2017-06-15 15:07:19 +02:00
|
|
|
*
|
2017-06-17 03:15:35 +02:00
|
|
|
* The writing process must not free the samples; only the receiving process should free them using sample_put after use.
|
2017-06-14 13:31:59 +02:00
|
|
|
* @param shm The shared memory interface.
|
|
|
|
* @param smps Array where pointers to newly allocated samples will be returned.
|
|
|
|
* @param cnt Number of samples to allocate.
|
2017-06-17 03:15:35 +02:00
|
|
|
* @return Number of samples that were successfully allocated (may be less then cnt).
|
2017-06-14 13:31:59 +02:00
|
|
|
*/
|
2017-06-17 03:15:35 +02:00
|
|
|
int shmem_int_alloc(struct shmem_int *shm, struct sample *smps[], unsigned cnt);
|
2017-06-14 13:31:59 +02:00
|
|
|
|
2017-04-16 23:00:30 +02:00
|
|
|
/** Returns the total size of the shared memory region with the given size of
|
|
|
|
* the input/output queues (in elements) and the given number of data elements
|
|
|
|
* per struct sample. */
|
2017-04-07 12:57:40 +02:00
|
|
|
size_t shmem_total_size(int insize, int outsize, int sample_size);
|
2017-04-17 18:50:43 +02:00
|
|
|
|
|
|
|
/** @} */
|
2017-04-26 11:48:58 +02:00
|
|
|
|
|
|
|
#ifdef __cplusplus
|
|
|
|
}
|
|
|
|
#endif
|