From patchwork Wed May 27 08:08:07 2015 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Ola Liljedahl X-Patchwork-Id: 48996 Return-Path: X-Original-To: linaro@patches.linaro.org Delivered-To: linaro@patches.linaro.org Received: from mail-la0-f71.google.com (mail-la0-f71.google.com [209.85.215.71]) by ip-10-151-82-157.ec2.internal (Postfix) with ESMTPS id 02D38202A3 for ; Wed, 27 May 2015 08:08:31 +0000 (UTC) Received: by lalw1 with SMTP id w1sf722216lal.0 for ; Wed, 27 May 2015 01:08:29 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:delivered-to:delivered-to:from:to:date :message-id:subject:precedence:list-id:list-unsubscribe:list-archive :list-post:list-help:list-subscribe:mime-version:content-type :content-transfer-encoding:errors-to:sender:x-original-sender :x-original-authentication-results:mailing-list; bh=luldm8AkSAD21v/JsxhwweOMV6zDyFmswn6zNMEt00M=; b=CmJWyTHRTEp2UIhu662ceeoK6C+0/l4UPXafx2kvHblIRo44OzW3WmZzocJp/WG02w MCmfQAob1RfU+/zlNAKqT4u7CNdR6uSMES1S7DvStzC40l18F/5dNEXFwR1z9SX4U+sd KOQXgW74InQq/JqT0xSStGU0VzkXRWFWWq70tWYa4gzc/0vFGpW0tu/1kFJgHK60Oq+B zmr6rmkqI2e0OaUArS1aDPjsf5s70N/rLfAT16Mz9u4ZHMGYvDKWwJV7tphNFWuIdg/n UywPqHHfw4qAhwe28DpQmAAY0fsNydpcejSpkov/NzAB1fzG5dZ3Pyk7yXmih7sr4MmM B+CQ== X-Gm-Message-State: ALoCoQkEXMr5aC9OK2zwzY+bmsmWq0PtSdmz4aSb4vFpmTaBRr+Ruy70OIPtHBVaGYQZaMFoWVQE X-Received: by 10.112.162.228 with SMTP id yd4mr31072322lbb.8.1432714109930; Wed, 27 May 2015 01:08:29 -0700 (PDT) X-BeenThere: patchwork-forward@linaro.org Received: by 10.152.29.66 with SMTP id i2ls11892lah.19.gmail; Wed, 27 May 2015 01:08:29 -0700 (PDT) X-Received: by 10.152.3.161 with SMTP id d1mr26500742lad.70.1432714109627; Wed, 27 May 2015 01:08:29 -0700 (PDT) Received: from mail-la0-f53.google.com (mail-la0-f53.google.com. [209.85.215.53]) by mx.google.com with ESMTPS id r10si13075128lal.5.2015.05.27.01.08.29 for (version=TLSv1.2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Wed, 27 May 2015 01:08:29 -0700 (PDT) Received-SPF: pass (google.com: domain of patch+caf_=patchwork-forward=linaro.org@linaro.org designates 209.85.215.53 as permitted sender) client-ip=209.85.215.53; Received: by laat2 with SMTP id t2so1692003laa.1 for ; Wed, 27 May 2015 01:08:29 -0700 (PDT) X-Received: by 10.152.6.69 with SMTP id y5mr26227273lay.72.1432714109509; Wed, 27 May 2015 01:08:29 -0700 (PDT) X-Forwarded-To: patchwork-forward@linaro.org X-Forwarded-For: patch@linaro.org patchwork-forward@linaro.org Delivered-To: patch@linaro.org Received: by 10.112.108.230 with SMTP id hn6csp167960lbb; Wed, 27 May 2015 01:08:28 -0700 (PDT) X-Received: by 10.140.92.120 with SMTP id a111mr38005641qge.30.1432714107846; Wed, 27 May 2015 01:08:27 -0700 (PDT) Received: from lists.linaro.org (lists.linaro.org. [54.225.227.206]) by mx.google.com with ESMTP id d191si17239448qka.74.2015.05.27.01.08.26; Wed, 27 May 2015 01:08:27 -0700 (PDT) Received-SPF: pass (google.com: domain of lng-odp-bounces@lists.linaro.org designates 54.225.227.206 as permitted sender) client-ip=54.225.227.206; Received: by lists.linaro.org (Postfix, from userid 109) id 7F4A161E0E; Wed, 27 May 2015 08:08:26 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on ip-10-142-244-252.ec2.internal X-Spam-Level: X-Spam-Status: No, score=-2.6 required=5.0 tests=BAYES_00, RCVD_IN_DNSWL_LOW, RCVD_IN_MSPIKE_H3, RCVD_IN_MSPIKE_WL, URIBL_BLOCKED autolearn=disabled version=3.4.0 Received: from ip-10-142-244-252.ec2.internal (localhost [127.0.0.1]) by lists.linaro.org (Postfix) with ESMTP id 711B361D02; Wed, 27 May 2015 08:08:15 +0000 (UTC) X-Original-To: lng-odp@lists.linaro.org Delivered-To: lng-odp@lists.linaro.org Received: by lists.linaro.org (Postfix, from userid 109) id A1F3661D2C; Wed, 27 May 2015 08:08:08 +0000 (UTC) Received: from mail-la0-f44.google.com (mail-la0-f44.google.com [209.85.215.44]) by lists.linaro.org (Postfix) with ESMTPS id 6686B61D02 for ; Wed, 27 May 2015 08:08:05 +0000 (UTC) Received: by labbd9 with SMTP id bd9so1666549lab.2 for ; Wed, 27 May 2015 01:08:03 -0700 (PDT) X-Received: by 10.152.7.239 with SMTP id m15mr25729504laa.95.1432714083834; Wed, 27 May 2015 01:08:03 -0700 (PDT) Received: from localhost.localdomain (78-82-119-245.tn.glocalnet.net. [78.82.119.245]) by mx.google.com with ESMTPSA id lf12sm3630520lac.38.2015.05.27.01.08.02 (version=TLSv1.2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Wed, 27 May 2015 01:08:03 -0700 (PDT) From: Ola Liljedahl To: lng-odp@lists.linaro.org Date: Wed, 27 May 2015 10:08:07 +0200 Message-Id: <1432714087-2191-1-git-send-email-ola.liljedahl@linaro.org> X-Mailer: git-send-email 1.9.1 Subject: [lng-odp] [RFCv3] Add message I/O (MSGIO) API's X-BeenThere: lng-odp@lists.linaro.org X-Mailman-Version: 2.1.16 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: , List-Help: , List-Subscribe: , MIME-Version: 1.0 Errors-To: lng-odp-bounces@lists.linaro.org Sender: "lng-odp" X-Removed-Original-Auth: Dkim didn't pass. X-Original-Sender: ola.liljedahl@linaro.org X-Original-Authentication-Results: mx.google.com; spf=pass (google.com: domain of patch+caf_=patchwork-forward=linaro.org@linaro.org designates 209.85.215.53 as permitted sender) smtp.mail=patch+caf_=patchwork-forward=linaro.org@linaro.org Mailing-list: list patchwork-forward@linaro.org; contact patchwork-forward+owners@linaro.org X-Google-Group-Id: 836684582541 Here is my third attempt at a ODP API for MSGIO - asynchronous message passing based IPC for a shared nothing architecture. IPC/message passing can be separated into a number of different layers. 1) Message formats and protocols (as seen by the user). 2) API - defines syntax and semantics of MSGIO operations. 3) Transport interface - defines a binary packet format used by MSGIO endpoints/implementations. Cf. OSI network layer. 4) Transport layer - implements the transport of message packet between different endpoints. Cf. OSI link layer. #1 is application specific and there are many different standards (e.g. Linux Netlink, NETCONF, OpenFlow, YouNameIt) intended for different use cases. #3 may be implementation specific but is important for interoperatibility (binary compatibility). If the user message (payload), operation and parameters are encoded in a well-defined way (e.g. some kind of packet format which includes operation, sender and receiver addresses, payload etc), inter-operatibility between different ODP/MSGIO implementations may be achieved or simplified. #4 is implementation (platform) specific. This proposal focuses on the API which is fundamental for source code compatibility between different platforms (ODP implementations) - this being the primary purpose of ODP. A packet format for messages will be specified as part of the reference implementation and may be seen as a proposal for a standard packet format for binary compatibility between different ODP/MSGIO implementations. All MSGIO calls are non-blocking (with the possible exception of odp_msgio_create, odp_msgio_activate and odp_msgio_destroy). Message transfer is asynchronous so it is not possible to return any status operation concerning the eventual (or remote) result of an operation. The semantics of MSGIO 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_msgio_lookup() call. Similarly, the disappearance (e.g. death of or otherwise lost connection to endpoint) is also explicitly notified through user-defined messages specified in the odp_msgio_monitor() call. The send call does not fail because the addressed endpoint has disappeared, the message is just silently discarded. Message delivery into the recipient address space is ordered (per priority) and reliable. Delivery of message N implies delivery of all messages --- (This document/code contribution attached is provided under the terms of agreement LES-LTM-21309) include/odp/api/message.h | 199 ++++++++++++++++++ include/odp/api/msgio.h | 222 +++++++++++++++++++++ platform/linux-generic/include/odp/message.h | 39 ++++ platform/linux-generic/include/odp/msgio.h | 40 ++++ .../linux-generic/include/odp/plat/message_types.h | 47 +++++ .../linux-generic/include/odp/plat/msgio_types.h | 59 ++++++ 6 files changed, 606 insertions(+) create mode 100644 include/odp/api/message.h create mode 100644 include/odp/api/msgio.h create mode 100644 platform/linux-generic/include/odp/message.h create mode 100644 platform/linux-generic/include/odp/msgio.h create mode 100644 platform/linux-generic/include/odp/plat/message_types.h create mode 100644 platform/linux-generic/include/odp/plat/msgio_types.h diff --git a/include/odp/api/message.h b/include/odp/api/message.h new file mode 100644 index 0000000..76697fb --- /dev/null +++ b/include/odp/api/message.h @@ -0,0 +1,199 @@ +/* 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[out] addr Buffer to hold sender address + */ +void odp_message_sender(odp_message_t msg, + uint8_t addr[ODP_MSGIO_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. + * Increase message data length by moving message tail into message tailroom. + * The actual message data is not modified. + * + * @param msg Message handle + * @param len New length + * + * @retval 0 on success + * @retval <0 on error (e.g. no enough tailroom) + */ +int odp_message_length_set(const odp_message_t msg, uint32_t len); + +/** + * Message headroom length + * + * Return length of the message headroom + * + * @param msg Message handle + * + * @return Headroom length + */ +uint32_t odp_message_headroom(const odp_message_t msg); + +/** + * Push out message head + * + * Increase message data length by moving message head into message headroom. + * Message headroom is decreased with the same amount. The message head may be + * pushed out up to 'headroom' bytes. Message is not modified if there's not + * enough headroom space. + * + * odp_message_xxx: + * length += len + * headroom -= len + * data -= len + * + * @param msg Message handle + * @param len Number of bytes to push the head (0 ... headroom) + * + * @return The new data pointer + * @retval NULL Requested offset exceeds available headroom + * + * @see odp_message_headroom(), odp_message_pull_head() + */ +void *odp_message_push_head(odp_message_t msg, uint32_t len); + +/** + * Pull in message head + * + * Decrease message data length by moving message head into message data. + * Message headroom is increased with the same amount. The message head may be + * pulled in up to 'length' bytes. Message is not modified if there's not + * enough data. + * + * odp_message_xxx: + * length -= len + * headroom += len + * data += len + * + * @param msg Message handle + * @param len Number of bytes to pull the head (0 ... length) + * + * @return The new data pointer + * @retval NULL Requested offset exceeds available data + * + * @see odp_message_headroom(), odp_message_push_head() + */ +void *odp_message_pull_head(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 diff --git a/include/odp/api/msgio.h b/include/odp/api/msgio.h new file mode 100644 index 0000000..8d73021 --- /dev/null +++ b/include/odp/api/msgio.h @@ -0,0 +1,222 @@ +/* Copyright (c) 2015, Linaro Limited + * All rights reserved. + * + * SPDX-License-Identifier: BSD-3-Clause + */ + + +/** + * @file + * + * ODP Message I/O API + */ + +#ifndef ODP_API_MSGIO_H_ +#define ODP_API_MSGIO_H_ + +#ifdef __cplusplus +extern "C" { +#endif + +/** @defgroup odp_msgio ODP MSGIO + * @{ + */ + +/** + * @typedef odp_msgio_t + * ODP message I/O handle + */ + +/** + * @def ODP_MSGIO_ADDR_SIZE + * Size of the address of a message I/O endpoint + */ + +/** + * @typedef odp_msgio_prio_t + * ODP MSGIO message priority + */ + +/** + * @def ODP_MSGIO_PRIO_HIGHEST + * Highest MSGIO message priority + */ + +/** + * @def ODP_MSGIO_PRIO_NORMAL + * Normal MSGIO message priority + */ + +/** + * @def ODP_MSGIO_PRIO_LOWEST + * Lowest MSGIO message priority + */ + +/** + * @def ODP_MSGIO_PRIO_DEFAULT + * Default MSGIO message priority + */ + + +/** + * Create message I/O endpoint + * + * Create an message I/O endpoint. The scope of the message bus is + * not defined but it is expected that it by default encompasses the OS + * instance but no more. + * + * A unique address for the endpoint is created. The addresses for other + * endpoints can be obtained using the odp_msgio_lookup() call and specified + * in the odp_msgio_send() call. + * + * @param name Name of our endpoint + * @param pool Pool (of type ODP_EVENT_MESSAGE) for incoming messages + * + * @return Message I/O handle on success + * @retval ODP_MSGIO_INVALID on failure and errno set + */ +odp_msgio_t odp_msgio_create(const char *name, + odp_pool_t pool); + +/** + * Set the input queue for a specific message priority + * + * @param msgio Message I/O handle + * @param prio Message priority + * @param queue Queue handle + * + * @retval 0 on success + * @retval <0 on failure + */ +int odp_msgio_inq_set(odp_msgio_t msgio, + odp_msgio_prio_t prio, + odp_queue_t queue); + +/** + * Activate message I/O endpoint + * + * Make this endpoint visible (odp_msgio_lookup() messages will be returned). + * Enable transmission and reception of messages through the endpoint. + * + * @param msgio Message I/O handle + * + * @retval 0 on success + * @retval <0 on failure + */ +int odp_msgio_activate(odp_msgio_t msgio); + +/** + * Destroy message I/O endpoint + * + * @param msgio Message I/O handle + * + * @retval 0 on success + * @retval <0 on failure + */ +int odp_msgio_destroy(odp_msgio_t msgio); + +/** + * Remove the input queue for a specific message priority + * + * Remove (disassociate) the matching input queue from a message I/O endpoint. + * The queue itself is not touched. + * + * @param msgio Message I/O handle + * @param prio Message priority + * + * @retval 0 on success + * @retval <0 on failure + */ +int odp_msgio_inq_rem(odp_msgio_t msgio, + odp_msgio_prio_t prio); + +/** + * Lookup endpoint by name + * + * Look up a current or future endpoint by name. + * When the endpoint exists, return the specified message (not necessarily the + * same message handle) with the endpoint as the sender. + * + * @param msgio Message I/O handle + * @param name Name to look up + * @param msg Message to return + */ +void odp_msgio_lookup(odp_msgio_t msgio, + 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 (not necessarily + * the same message handle) with the endpoint as the sender. + * + * Unrecognized or invalid endpoint addresses are treated as non-existing + * endpoints. + * + * @param msgio Message I/O handle + * @param[in] addr Address of monitored endpoint + * @param msg Message to return + */ +void odp_msgio_monitor(odp_msgio_t msgio, + const uint8_t addr[ODP_MSGIO_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 +#include +#include +#include + +/** @ingroup odp_message + * @{ + */ + +/** + * @} + */ + +#include + +#ifdef __cplusplus +} +#endif + +#endif diff --git a/platform/linux-generic/include/odp/msgio.h b/platform/linux-generic/include/odp/msgio.h new file mode 100644 index 0000000..f45b3a2 --- /dev/null +++ b/platform/linux-generic/include/odp/msgio.h @@ -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_MSGIO_H_ +#define ODP_PLAT_MSGIO_H_ + +#ifdef __cplusplus +extern "C" { +#endif + +#include +#include +#include +#include +#include + +/** @ingroup odp_msgio + * @{ + */ + +/** + * @} + */ + +#include + +#ifdef __cplusplus +} +#endif + +#endif diff --git a/platform/linux-generic/include/odp/plat/message_types.h b/platform/linux-generic/include/odp/plat/message_types.h new file mode 100644 index 0000000..3a42064 --- /dev/null +++ b/platform/linux-generic/include/odp/plat/message_types.h @@ -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 +#include + +/** @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 diff --git a/platform/linux-generic/include/odp/plat/msgio_types.h b/platform/linux-generic/include/odp/plat/msgio_types.h new file mode 100644 index 0000000..9d9f9da --- /dev/null +++ b/platform/linux-generic/include/odp/plat/msgio_types.h @@ -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_MSGIO_TYPES_H_ +#define ODP_MSGIO_TYPES_H_ + +#ifdef __cplusplus +extern "C" { +#endif + +#include +#include + +/** @addtogroup odp_msgio ODP message bus + * Operations on a message bus. + * @{ + */ + +typedef int odp_msgio_prio_t; + +#define ODP_MSGIO_PRIO_HIGHEST 0 + +#define ODP_MSGIO_PRIO_NORMAL 2 + +#define ODP_MSGIO_PRIO_LOWEST 3 + +#define ODP_MSGIO_PRIO_DEFAULT ODP_MSGIO_PRIO_NORMAL + +typedef ODP_HANDLE_T(odp_msgio_t); + +#define ODP_MSGIO_INVALID _odp_cast_scalar(odp_msgio_t, 0xffffffff) + +#define ODP_MSGIO_ADDR_SIZE 6 + +/** Get printable format of odp_msgio_t */ +static inline uint64_t odp_msgio_to_u64(odp_msgio_t hdl) +{ + return _odp_pri(hdl); +} + +/** + * @} + */ + +#ifdef __cplusplus +} +#endif + +#endif