new file mode 100644
@@ -0,0 +1,229 @@
+/* Copyright (c) 2015, Linaro Limited
+ * All rights reserved.
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+
+
+/**
+ * @file
+ *
+ * ODP Message bus API
+ */
+
+#ifndef ODP_API_MBUS_H_
+#define ODP_API_MBUS_H_
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/** @defgroup odp_mbus ODP MBUS
+ * @{
+ */
+
+/**
+ * @typedef odp_mbus_t
+ * ODP message bus handle
+ */
+
+/**
+ * @def ODP_MBUS_ADDR_SIZE
+ * Size of the address of a message bus endpoint
+ */
+
+/**
+ * @typedef odp_mbus_prio_t
+ * ODP MBUS message priority
+ */
+
+/**
+ * @def ODP_MBUS_PRIO_HIGHEST
+ * Highest MBUS message priority
+ */
+
+/**
+ * @def ODP_MBUS_PRIO_NORMAL
+ * Normal MBUS message priority
+ */
+
+/**
+ * @def ODP_MBUS_PRIO_LOWEST
+ * Lowest MBUS message priority
+ */
+
+/**
+ * @def ODP_MBUS_PRIO_DEFAULT
+ * Default MBUS message priority
+ */
+
+
+/**
+ * Create message bus endpoint
+ *
+ * Create an endpoint on the message bus. The scope of the message bus is
+ * not defined but it is expected that it encompasses the OS instance but
+ * no more.
+ *
+ * A unique address for the endpoint is created.
+ *
+ * @param name Name of our endpoint
+ * @param pool Pool (of type ODP_EVENT_MESSAGE) for incoming messages
+ * @param queue Handle for default input queue
+ *
+ * @return Message bus handle on success
+ * @retval ODP_MBUS_INVALID on failure and errno set
+ */
+odp_mbus_t odp_mbus_create(const char *name,
+ odp_pool_t pool,
+ odp_queue_t queue);
+
+/**
+ * Destroy message bus endpoint
+ *
+ * @param mbus Message bus handle
+ *
+ * @retval 0 on success
+ * @retval <0 on failure
+ */
+int odp_mbus_destroy(odp_mbus_t mbus);
+
+/**
+ * Set the default input queue for a message bus endpoint
+ *
+ * @param mbus Message bus handle
+ * @param queue Queue handle
+ *
+ * @retval 0 on success
+ * @retval <0 on failure
+ */
+int odp_mbus_inq_setdef(odp_mbus_t mbus, odp_queue_t queue);
+
+/**
+ * Set the input queue for a specific message priority
+ *
+ * @param mbus Message bus handle
+ * @param prio Message priority
+ * @param queue Queue handle
+ *
+ * @retval 0 on success
+ * @retval <0 on failure
+ */
+int odp_mbus_inq_set(odp_mbus_t mbus, odp_mbus_prio_t prio, odp_queue_t queue);
+
+/**
+ * Remove the default input queue
+ *
+ * Remove (disassociate) the default input queue from a message bus endpoint.
+ * The queue itself is not touched.
+ *
+ * @param mbus Message bus handle
+ *
+ * @retval 0 on success
+ * @retval <0 on failure
+ */
+int odp_mbus_inq_remdef(odp_mbus_t mbus);
+
+/**
+ * Remove the input queue for a specific message priority
+ *
+ * Remove (disassociate) the matching input queue from a message bus endpoint.
+ * The queue itself is not touched.
+ *
+ * @param mbus Message bus handle
+ * @param prio Message priority
+ *
+ * @retval 0 on success
+ * @retval <0 on failure
+ */
+int odp_mbus_inq_rem(odp_mbus_t mbus, odp_mbus_prio_t prio);
+
+/**
+ * Lookup endpoint by name
+ *
+ * Look up a current or future endpoint by name.
+ * When the endpoint exists, return the specified message with the endpoint
+ * as the sender.
+ *
+ * @param mbus Message bus handle
+ * @param name Name to look up
+ * @param msg Message to return
+ */
+void odp_mbus_lookup(odp_mbus_t mbus,
+ const char *name,
+ odp_message_t msg);
+
+/**
+ * Monitor endpoint
+ *
+ * Monitor an endpoint (which may already have disappeared).
+ * When the endpoint disappears, return the specified message with the endpoint
+ * as the sender.
+ *
+ * Unrecognized or invalid endpoint addresses are treated as non-existing
+ * endpoints.
+ *
+ * @param mbus Message bus handle
+ * @param addr Address of monitored endpoint
+ * @param msg Message to return
+ */
+void odp_mbus_monitor(odp_mbus_t mbus,
+ const uint8_t addr[ODP_MBUS_ADDR_SIZE],
+ odp_message_t msg);
+
+/**
+ * Send message
+ *
+ * Send a message to an endpoint (which may no longer exist).
+ *
+ * Message delivery into the recipient address space is ordered (per priority)
+ * and reliable. Delivery of message N implies delivery of all messages <N
+ * (of the same priority).
+ * All messages (accepted by MBUS) will be delivered up to the point of
+ * endpoint termination or lost connection where no more messages will be
+ * delivered.
+ *
+ * Actual reception (dequeueing) and processing by the recipient is not
+ * guaranteed (use end-to-end acknowledgements for that).
+ *
+ * Monitor the remote endpoint to detect the disappearance or disconnect of
+ * the endpoint.
+ *
+ * A message may temporarily not be accepted for transmission (e.g. due
+ * to out of buffer space), -1 will be returned and ODP errno set to EAGAIN.
+ *
+ * @param mbus Message bus handle
+ * @param msg Message to send
+ * @param prio Priority of message
+ * @param addr Address of recipient endpoint
+ *
+ * @retval 0 on success
+ * @retval <0 on error
+ */
+int odp_mbus_send(odp_mbus_t mbus,
+ odp_message_t msg,
+ odp_mbus_prio_t prio,
+ const uint8_t addr[ODP_MBUS_ADDR_SIZE]);
+
+/**
+ * Get printable value for an odp_mbus_t
+ *
+ * @param mbus Message bus 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 odp_mbus_t handle.
+ */
+uint64_t odp_mbus_to_u64(odp_mbus_t mbus);
+
+/**
+ * @}
+ */
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif
new file mode 100644
@@ -0,0 +1,141 @@
+/* Copyright (c) 2015, Linaro Limited
+ * All rights reserved.
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+
+
+/**
+ * @file
+ *
+ * ODP Message event type
+ */
+
+#ifndef ODP_API_MESSAGE_H_
+#define ODP_API_MESSAGE_H_
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/** @defgroup odp_message ODP MESSAGE
+ * @{
+ */
+
+/**
+ * @typedef odp_message_t
+ * ODP message handle
+ */
+
+
+/**
+ * Get address of sender (source) of message
+ *
+ * @param msg Message handle
+ * @param addr Address of sender endpoint
+ */
+void odp_message_sender(odp_message_t msg,
+ uint8_t addr[ODP_MBUS_ADDR_SIZE]);
+
+/**
+ * Message data pointer
+ *
+ * Return a pointer to the message data
+ *
+ * @param msg Message handle
+ *
+ * @return Pointer to the message data
+ */
+void *odp_message_data(odp_message_t msg);
+
+/**
+ * Message data length
+ *
+ * Return length of the message data.
+ *
+ * @param msg Message handle
+ *
+ * @return Message length
+ */
+uint32_t odp_message_length(const odp_message_t msg);
+
+/**
+ * Set message length
+ *
+ * Set length of the message data.
+ * The actual message data is not modified.
+ *
+ * @param msg Message handle
+ * @param len New length
+ *
+ * @retval 0 on success
+ * @retval <0 on error
+ */
+int odp_message_length_set(const odp_message_t msg, uint32_t len);
+
+/**
+ * Allocate message
+ *
+ * Allocate a message of a specific length.
+ *
+ * @param pool Message pool to allocate message from
+ * @param len Length of the allocated message
+ *
+ * @return Message handle on success
+ * @retval ODP_MESSAGE_INVALID on failure and errno set
+ */
+odp_message_t odp_message_alloc(odp_pool_t pool, uint32_t len);
+
+/**
+ * Free message
+ *
+ * Free message back to the message pool it was allocated from.
+ *
+ * @param msg Handle of message to free
+ */
+void odp_message_free(odp_message_t msg);
+
+/**
+ * Get message handle from event
+ *
+ * Converts an ODP_EVENT_MESSAGE type event to a message.
+ *
+ * @param ev Event handle representing a message.
+ *
+ * @return Message handle
+ *
+ * @see odp_event_type()
+ */
+odp_message_t odp_message_from_event(odp_event_t ev);
+
+/**
+ * Convert message handle to event
+ *
+ * @param msg Message handle
+ *
+ * @return Event handle
+ */
+odp_event_t odp_message_to_event(odp_message_t msg);
+
+/**
+ * Get printable value for an odp_message_t
+ *
+ * @param msg Message 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 odp_message_t handle.
+ */
+uint64_t odp_message_to_u64(odp_message_t msg);
+
+/**
+ * @}
+ */
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif
new file mode 100644
@@ -0,0 +1,40 @@
+/* Copyright (c) 2013, Linaro Limited
+ * All rights reserved.
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+
+/**
+ * @file
+ *
+ * ODP Message Bus
+ */
+
+#ifndef ODP_PLAT_MBUS_H_
+#define ODP_PLAT_MBUS_H_
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#include <odp/std_types.h>
+#include <odp/plat/pool_types.h>
+#include <odp/plat/mbus_types.h>
+#include <odp/plat/message_types.h>
+#include <odp/plat/queue_types.h>
+
+/** @ingroup odp_mbus
+ * @{
+ */
+
+/**
+ * @}
+ */
+
+#include <odp/api/mbus.h>
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif
new file mode 100644
@@ -0,0 +1,39 @@
+/* Copyright (c) 2013, Linaro Limited
+ * All rights reserved.
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+
+/**
+ * @file
+ *
+ * ODP Message Bus
+ */
+
+#ifndef ODP_PLAT_MESSAGE_H_
+#define ODP_PLAT_MESSAGE_H_
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#include <odp/std_types.h>
+#include <odp/plat/pool_types.h>
+#include <odp/plat/message_types.h>
+#include <odp/plat/queue_types.h>
+
+/** @ingroup odp_message
+ * @{
+ */
+
+/**
+ * @}
+ */
+
+#include <odp/api/message.h>
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif
new file mode 100644
@@ -0,0 +1,59 @@
+/* Copyright (c) 2015, Linaro Limited
+ * All rights reserved.
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+
+
+/**
+ * @file
+ *
+ * ODP Message bus types
+ */
+
+#ifndef ODP_MBUS_TYPES_H_
+#define ODP_MBUS_TYPES_H_
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#include <odp/std_types.h>
+#include <odp/plat/strong_types.h>
+
+/** @addtogroup odp_mbus ODP message bus
+ * Operations on a message bus.
+ * @{
+ */
+
+typedef int odp_mbus_prio_t;
+
+#define ODP_MBUS_PRIO_HIGHEST 0
+
+#define ODP_MBUS_PRIO_NORMAL 1
+
+#define ODP_MBUS_PRIO_LOWEST 3
+
+#define ODP_MBUS_PRIO_DEFAULT ODP_MBUS_PRIO_NORMAL
+
+typedef ODP_HANDLE_T(odp_mbus_t);
+
+#define ODP_MBUS_INVALID _odp_cast_scalar(odp_mbus_t, 0xffffffff)
+
+#define ODP_MBUS_ADDR_SIZE 6
+
+/** Get printable format of odp_mbus_t */
+static inline uint64_t odp_mbus_to_u64(odp_mbus_t hdl)
+{
+ return _odp_pri(hdl);
+}
+
+/**
+ * @}
+ */
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif
new file mode 100644
@@ -0,0 +1,47 @@
+/* Copyright (c) 2015, Linaro Limited
+ * All rights reserved.
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+
+
+/**
+ * @file
+ *
+ * ODP Message message type
+ */
+
+#ifndef ODP_MESSAGE_TYPES_H_
+#define ODP_MESSAGE_TYPES_H_
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#include <odp/std_types.h>
+#include <odp/plat/strong_types.h>
+
+/** @addtogroup odp_message ODP message
+ * Operations on a message.
+ * @{
+ */
+
+typedef ODP_HANDLE_T(odp_message_t);
+
+#define ODP_MESSAGE_INVALID _odp_cast_scalar(odp_message_t, 0xffffffff)
+
+/** Get printable format of odp_message_t */
+static inline uint64_t odp_message_to_u64(odp_message_t hdl)
+{
+ return _odp_pri(hdl);
+}
+
+/**
+ * @}
+ */
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif
Here is my second attempt at a standalone API for MBUS - message passing based IPC for a shared nothing architecture. The semantics of message passing is that sending a message to an endpoint will always look like it succeeds. The appearance of endpoints is explicitly notified through user-defined messages specified in the odp_mbus_lookup() call. Similarly, the disappearance (e.g. death or otherwise lost connection) is also explicitly notified through user-defined messages specified in the odp_mbus_monitor() call. The send call does not fail because the addressed endpoints has disappeared. Message delivery into the recipient address space is ordered (per priority) and reliable. Delivery of message N implies delivery of all messages <N (of the same priority). All messages (accepted by MBUS) will be delivered up to the point of endpoint termination or lost connection where no more messages will be delivered. Actual reception (dequeueing) and processing by the recipient is not guaranteed (use end-to-end acknowledgements for that). MBUS endpoints can be seen as interfaces (taps) to an internal reliable multidrop network where each endpoint has a unique address which is only valid for the lifetime of the endpoint. I.e. if an endpoint is destroyed and then recreated (with the same name), the new endpoint will have a new address (eventually endpoints addresses will have to be recycled but not for a very long time). Endpoints names do not necessarily have to be unique. v2: Split off all message definitions in a separate file message.h Renamed Inter Process Communication (IPC) to Message Bus (MBUS). Changed all definitions to use "mbus" instead of "ipc" prefix/infix. Renamed odp_ipc_msg_t to odp_message_t. odp_mbus_create(): Added parameter for default input queue. Explicitly state that the pool must be use type ODP_EVENT_MESSAGE. Renamed odp_ipc_resolve() to odp_mbus_lookup(). odp_mbus_send(): Added priority parameter. Renamed odp_ipc_sender() to odp_message_sender(). Renamed odp_ipc_data() to odp_message_data(). Renamed odp_ipc_length() to odp_message_length(). Renamed odp_ipc_reset() to odp_message_length_set(). Renamed odp_ipc_alloc() to odp_message_alloc(). Renamed odp_ipc_free() to odp_message_free(). odp_message_alloc(): Corrected name of invalid message handle. Added message priorities and calls to set and remove input queues for specific priorities: odp_mbus_inq_set(), odp_mbus_inq_rem(). Signed-off-by: Ola Liljedahl <ola.liljedahl@linaro.org> --- (This document/code contribution attached is provided under the terms of agreement LES-LTM-21309) include/odp/api/mbus.h | 229 +++++++++++++++++++++ include/odp/api/message.h | 141 +++++++++++++ platform/linux-generic/include/odp/mbus.h | 40 ++++ platform/linux-generic/include/odp/message.h | 39 ++++ .../linux-generic/include/odp/plat/mbus_types.h | 59 ++++++ .../linux-generic/include/odp/plat/message_types.h | 47 +++++ 6 files changed, 555 insertions(+) create mode 100644 include/odp/api/mbus.h create mode 100644 include/odp/api/message.h create mode 100644 platform/linux-generic/include/odp/mbus.h create mode 100644 platform/linux-generic/include/odp/message.h create mode 100644 platform/linux-generic/include/odp/plat/mbus_types.h create mode 100644 platform/linux-generic/include/odp/plat/message_types.h