[API-NEXT,PATCHv3,05/13] drv: adding shared memory

Message ID 1471679163-17240-6-git-send-email-christophe.milard@linaro.org
State New
Headers show

Commit Message

Christophe Milard Aug. 20, 2016, 7:45 a.m.
The public definition of the shared memory allocator
for the driver interface is added.

Signed-off-by: Christophe Milard <christophe.milard@linaro.org>

---
 include/odp/drv/spec/shm.h | 231 +++++++++++++++++++++++++++++++++++++++++++++
 platform/Makefile.inc      |   1 +
 2 files changed, 232 insertions(+)
 create mode 100644 include/odp/drv/spec/shm.h

-- 
2.7.4

Patch

diff --git a/include/odp/drv/spec/shm.h b/include/odp/drv/spec/shm.h
new file mode 100644
index 0000000..ef64f5d
--- /dev/null
+++ b/include/odp/drv/spec/shm.h
@@ -0,0 +1,231 @@ 
+/* Copyright (c) 2016, Linaro Limited
+ * All rights reserved.
+ *
+ * SPDX-License-Identifier:     BSD-3-Clause
+ */
+
+/**
+ * @file
+ *
+ * ODPRDV shared memory (shm)
+ */
+
+#ifndef ODPDRV_SHM_H_
+#define ODPDRV_SHM_H_
+#include <odp/visibility_begin.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/** @addtogroup odpdrv_shm ODPDRV SHARED MEMORY
+ *  Operations on driver shared memory.
+ *  @{
+ */
+
+/**
+ * @typedef odpdrv_shm_t
+ * odpdrv shared memory block
+ */
+
+/**
+ * @def ODPDRV_SHM_INVALID
+ * Invalid odpdrv shared memory block
+ */
+
+/** Maximum shared memory block name length in chars */
+#define ODPDRV_SHM_NAME_LEN 32
+
+/*
+ * Shared memory flags
+ */
+#define ODPDRV_SHM_SINGLE_VA	0x01 /**< Memory shall be mapped at same VA */
+#define ODPDRV_SHM_LOCK		0x02 /**< Memory shall be locked (no swap) */
+
+/**
+ * Shared memory block info
+ */
+typedef struct odpdrv_shm_info_t {
+	const char *name;      /**< Block name */
+	void       *addr;      /**< Block address */
+	uint64_t    size;      /**< Block size in bytes */
+	uint64_t    page_size; /**< Memory page size */
+	uint32_t    flags;     /**< ODPDRV_SHM_* flags */
+} odpdrv_shm_info_t;
+
+/**
+ * Shared memory capabilities
+ */
+typedef struct odpdrv_shm_capability_t {
+	/** Maximum number of shared memory blocks
+	 *
+	 * This number of separate shared memory blocks can be
+	 * reserved concurrently. */
+	unsigned max_blocks;
+
+	/** Maximum memory block size in bytes
+	 *
+	 * The value of zero means that size is limited only by the available
+	 * memory size. */
+	uint64_t max_size;
+
+	/** Maximum memory block alignment in bytes
+	 *
+	 * The value of zero means that alignment is limited only by the
+	 * available memory size. */
+	uint64_t max_align;
+
+} odpdrv_shm_capability_t;
+
+/**
+ * Query shared memory capabilities
+ *
+ * Outputs shared memory capabilities on success.
+ *
+ * @param[out] capa   Pointer to capability structure for output
+ *
+ * @retval 0 on success
+ * @retval <0 on failure
+ */
+int odpdrv_shm_capability(odpdrv_shm_capability_t *capa);
+
+/**
+ * Reserve a contiguous block of shared memory
+ *
+ * @param[in] name   Name of the block (maximum ODPDRV_SHM_NAME_LEN - 1 chars)
+ * @param[in] size   Block size in bytes
+ * @param[in] align  Block alignment in bytes
+ * @param[in] flags  Shared memory parameter flags (ODPDRV_SHM_*).
+ *                   Default value is 0.
+ *
+ * @return Handle of the reserved block
+ * @retval ODPDRV_SHM_INVALID on failure
+ */
+odpdrv_shm_t odpdrv_shm_reserve(const char *name, uint64_t size, uint64_t align,
+				uint32_t flags);
+
+/**
+ * Free a contiguous block of shared memory
+ *
+ * Frees a previously reserved block of shared memory (found by its handle).
+ * @note Freeing memory that is in use will result in UNDEFINED behavior
+ *
+ * @param[in] shm	odpdrv_shm Block handle
+ *
+ * @retval 0 on success
+ * @retval <0 on failure
+ */
+int odpdrv_shm_free_by_handle(odpdrv_shm_t shm);
+
+/**
+ * Free a contiguous block of shared memory (found from its name)
+ *
+ * Frees a previously reserved block of shared memory.
+ * @note Freeing memory that is in use will result in UNDEFINED behavior
+ *
+ * @param[in] name	odpdrv_shm Block name
+ *
+ * @retval 0 on success
+ * @retval <0 on failure
+ */
+int odpdrv_shm_free_by_name(const char *name);
+
+/**
+ * Free a contiguous block of shared memory (found from its address)
+ *
+ * Frees a previously reserved block of shared memory.
+ * @note Freeing memory that is in use will result in UNDEFINED behavior
+ *
+ * @param[in] address	odpdrv_shm Block address
+ *
+ * @retval 0 on success
+ * @retval <0 on failure
+ */
+int odpdrv_shm_free_by_address(void *address);
+
+/**
+ * Lookup and map a block of shared memory (identified by its handle)
+ *
+ * @param[in] shm	odpdrv_shm Block handle
+ *
+ * @return The address of the newly mapped block.
+ * @retval NULL on failure
+ */
+void *odpdrv_shm_lookup_by_handle(odpdrv_shm_t shm);
+
+/**
+ * Lookup and map a block of shared memory (identified by its name)
+ *
+ * @param[in] name	odpdrv_shm Block name
+ *
+ * @return The handle of the newly mapped block.
+ * @retval ODPDRV_SHM_INVALID on failure
+ */
+odpdrv_shm_t odpdrv_shm_lookup_by_name(const char *name);
+
+/**
+ * Lookup and map a block of shared memory (identified by its address)
+ *
+ * @note This only works when the flag ODPDRV_SHM_SINGLE_VA was set,
+ * as otherwise addresses are odp-thread local and hence meaningless to
+ * identify the block between odp-threads.
+ *
+ * @param[in] address	odpdrv_shm Block address
+ *
+ * @return The handle of the newly mapped block.
+ * @retval ODPDRV_SHM_INVALID on failure
+ */
+odpdrv_shm_t odpdrv_shm_lookup_by_address(void *address);
+
+/**
+ * Get a Shared memory block address
+ *
+ * @param[in] shm	odpdrv_shm Block handle
+ *
+ * @return Memory block address
+ * @retval NULL on failure
+ */
+void *odpdrv_shm_addr(odpdrv_shm_t shm);
+
+/**
+ * Shared memory block info
+ *
+ * @param[in]  shm	Odpdrv_shm block handle
+ * @param[out] info	Block info pointer for output
+ *
+ * @retval 0 on success
+ * @retval <0 on failure
+ */
+int odpdrv_shm_info(odpdrv_shm_t shm, odpdrv_shm_info_t *info);
+
+/**
+ * Print all shared memory blocks and returns the number of allocated blocks.
+ * This function is meant for debug.
+ * @param title  A string to be printed before the shared memory status
+ * @return       The total number of allocated blocks
+ */
+int odpdrv_shm_print_all(const char *title);
+
+/**
+ * Get printable value for an odpdrv_shm_t
+ *
+ * @param hdl  odpdrv_shm_t handle to be printed
+ * @return     uint64_t value that can be used to print/display this
+ *             handle
+ *
+ * @note This routine is intended to be used for diagnostic purposes
+ * to enable applications to generate a printable value that represents
+ * an odpdrv_shm_t handle.
+ */
+uint64_t odpdrv_shm_to_u64(odpdrv_shm_t hdl);
+
+/**
+ * @}
+ */
+
+#ifdef __cplusplus
+}
+#endif
+
+#include <odp/visibility_end.h>
+#endif
diff --git a/platform/Makefile.inc b/platform/Makefile.inc
index 6ade6df..7c53d1d 100644
--- a/platform/Makefile.inc
+++ b/platform/Makefile.inc
@@ -68,6 +68,7 @@  odpdrvspecinclude_HEADERS = \
 		  $(top_srcdir)/include/odp/drv/spec/barrier.h \
 		  $(top_srcdir)/include/odp/drv/spec/byteorder.h \
 		  $(top_srcdir)/include/odp/drv/spec/compiler.h \
+		  $(top_srcdir)/include/odp/drv/spec/shm.h \
 		  $(top_srcdir)/include/odp/drv/spec/spinlock.h \
 		  $(top_srcdir)/include/odp/drv/spec/std_types.h \
 		  $(top_srcdir)/include/odp/drv/spec/sync.h