From patchwork Mon May 18 22:03:47 2015 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Ola Liljedahl X-Patchwork-Id: 48724 Return-Path: X-Original-To: linaro@patches.linaro.org Delivered-To: linaro@patches.linaro.org Received: from mail-wi0-f200.google.com (mail-wi0-f200.google.com [209.85.212.200]) by ip-10-151-82-157.ec2.internal (Postfix) with ESMTPS id 49E2321411 for ; Mon, 18 May 2015 22:04:04 +0000 (UTC) Received: by wizk4 with SMTP id k4sf28010098wiz.2 for ; Mon, 18 May 2015 15:04:03 -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=9o2vahTyH2IQ5FIYxqwNwdf+BHDTPc2CY2JWKzgCobQ=; b=C4BdrnkYZMWpHwaTItHFC+UsjMypThjZDDlv14WSM/HgmxtP3RoEN5I7actHp74zob 6GRNq7r3t3jGBDqEha4hLNo0mpCYvXHTbN/5kZ7eOqQ9sN2VotIU5gH9RLlHujwjSUi3 21LV2IRBurH5HZfsZcn4pA4yt8Gq3GMhedv4gxJHefJYyWUKADtYkqjd48yx+s1VGFiL ofzX4jxeOrmRjAu8/OurZ1j09W9VZ/yQPh2JZbpyZEYHwWkagz/JveQEk+auudT2KAt1 /RCnPH7n9B90dDNtpcZdHt5a0qWOz8ItaU6GvHB7136w9PDhb9KsGsXyMY4yWNMhLLNS w4qA== X-Gm-Message-State: ALoCoQklml0WFa86pf45pyex1bAalMDa025Ew8B6NyOyvbYagI6fzQF0ezuhQ/4VNiO35SZlHiGT X-Received: by 10.112.83.172 with SMTP id r12mr8172369lby.23.1431986643553; Mon, 18 May 2015 15:04:03 -0700 (PDT) X-BeenThere: patchwork-forward@linaro.org Received: by 10.152.7.101 with SMTP id i5ls672430laa.58.gmail; Mon, 18 May 2015 15:04:03 -0700 (PDT) X-Received: by 10.152.234.139 with SMTP id ue11mr19099059lac.28.1431986643406; Mon, 18 May 2015 15:04:03 -0700 (PDT) Received: from mail-la0-f49.google.com (mail-la0-f49.google.com. [209.85.215.49]) by mx.google.com with ESMTPS id s10si7509929laj.84.2015.05.18.15.04.03 for (version=TLSv1.2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Mon, 18 May 2015 15:04:03 -0700 (PDT) Received-SPF: pass (google.com: domain of patch+caf_=patchwork-forward=linaro.org@linaro.org designates 209.85.215.49 as permitted sender) client-ip=209.85.215.49; Received: by labbd9 with SMTP id bd9so240310427lab.2 for ; Mon, 18 May 2015 15:04:03 -0700 (PDT) X-Received: by 10.112.29.36 with SMTP id g4mr19376625lbh.56.1431986643269; Mon, 18 May 2015 15:04:03 -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 hn6csp360549lbb; Mon, 18 May 2015 15:04:01 -0700 (PDT) X-Received: by 10.55.26.29 with SMTP id a29mr27462684qka.0.1431986641212; Mon, 18 May 2015 15:04:01 -0700 (PDT) Received: from lists.linaro.org (lists.linaro.org. [54.225.227.206]) by mx.google.com with ESMTP id o5si7985071qko.11.2015.05.18.15.04.00; Mon, 18 May 2015 15:04:01 -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 D198C61D4F; Mon, 18 May 2015 22:03:59 +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 71E3861B35; Mon, 18 May 2015 22:03:57 +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 7B80561D3C; Mon, 18 May 2015 22:03:55 +0000 (UTC) Received: from mail-la0-f53.google.com (mail-la0-f53.google.com [209.85.215.53]) by lists.linaro.org (Postfix) with ESMTPS id 0CD8A61B35 for ; Mon, 18 May 2015 22:03:54 +0000 (UTC) Received: by lagv1 with SMTP id v1so240036892lag.3 for ; Mon, 18 May 2015 15:03:53 -0700 (PDT) X-Received: by 10.112.50.236 with SMTP id f12mr907994lbo.89.1431986632977; Mon, 18 May 2015 15:03:52 -0700 (PDT) Received: from localhost.localdomain (78-82-118-124.tn.glocalnet.net. [78.82.118.124]) by mx.google.com with ESMTPSA id x2sm3027450laj.8.2015.05.18.15.03.51 (version=TLSv1.2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Mon, 18 May 2015 15:03:52 -0700 (PDT) From: Ola Liljedahl To: lng-odp@lists.linaro.org Date: Tue, 19 May 2015 00:03:47 +0200 Message-Id: <1431986627-16629-1-git-send-email-ola.liljedahl@linaro.org> X-Mailer: git-send-email 1.9.1 Subject: [lng-odp] [RFC] Add ipc.h 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.49 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 As promised, here is my first attempt at a standalone API for IPC - inter process communication in a shared nothing architecture (message passing between processes which do not share memory). Currently all definitions are in the file ipc.h but it is possible to break out some message/event related definitions (everything from odp_ipc_sender) in a separate file message.h. This would mimic the packet_io.h/packet.h separation. 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_ipc_resolve() call. Similarly, the disappearance (e.g. death or otherwise lost connection) is also explicitly notified through user-defined messages specified in the odp_ipc_monitor() call. The send call does not fail because the addressed endpoints has disappeared. Messages (from endpoint A to endpoint B) are delivered in order. If message N sent to an endpoint is delivered, then all messages --- (This document/code contribution attached is provided under the terms of agreement LES-LTM-21309) include/odp/api/ipc.h | 261 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 261 insertions(+) create mode 100644 include/odp/api/ipc.h diff --git a/include/odp/api/ipc.h b/include/odp/api/ipc.h new file mode 100644 index 0000000..3395a34 --- /dev/null +++ b/include/odp/api/ipc.h @@ -0,0 +1,261 @@ +/* Copyright (c) 2015, Linaro Limited + * All rights reserved. + * + * SPDX-License-Identifier: BSD-3-Clause + */ + + +/** + * @file + * + * ODP IPC API + */ + +#ifndef ODP_API_IPC_H_ +#define ODP_API_IPC_H_ + +#ifdef __cplusplus +extern "C" { +#endif + +/** @defgroup odp_ipc ODP IPC + * @{ + */ + +/** + * @typedef odp_ipc_t + * ODP IPC handle + */ + +/** + * @typedef odp_ipc_msg_t + * ODP IPC message handle + */ + + +/** + * @def ODP_IPC_ADDR_SIZE + * Size of the address of an IPC endpoint + */ + +/** + * Create IPC endpoint + * + * @param name Name of local IPC endpoint + * @param pool Pool for incoming messages + * + * @return IPC handle on success + * @retval ODP_IPC_INVALID on failure and errno set + */ +odp_ipc_t odp_ipc_create(const char *name, odp_pool_t pool); + +/** + * Destroy IPC endpoint + * + * @param ipc IPC handle + * + * @retval 0 on success + * @retval <0 on failure + */ +int odp_ipc_destroy(odp_ipc_t ipc); + +/** + * Set the default input queue for an IPC endpoint + * + * @param ipc IPC handle + * @param queue Queue handle + * + * @retval 0 on success + * @retval <0 on failure + */ +int odp_ipc_inq_setdef(odp_ipc_t ipc, odp_queue_t queue); + +/** + * Remove the default input queue + * + * Remove (disassociate) the default input queue from an IPC endpoint. + * The queue itself is not touched. + * + * @param ipc IPC handle + * + * @retval 0 on success + * @retval <0 on failure + */ +int odp_ipc_inq_remdef(odp_ipc_t ipc); + +/** + * Resolve endpoint by name + * + * Look up an existing or future endpoint by name. + * When the endpoint exists, return the specified message with the endpoint + * as the sender. + * + * @param ipc IPC handle + * @param name Name to resolve + * @param msg Message to return + */ +void odp_ipc_resolve(odp_ipc_t ipc, + const char *name, + odp_ipc_msg_t msg); + +/** + * Monitor endpoint + * + * Monitor an existing (potentially already dead) endpoint. + * When the endpoint is dead, return the specified message with the endpoint + * as the sender. + * + * Unrecognized or invalid endpoint addresses are treated as dead endpoints. + * + * @param ipc IPC handle + * @param addr Address of monitored endpoint + * @param msg Message to return + */ +void odp_ipc_monitor(odp_ipc_t ipc, + const uint8_t addr[ODP_IPC_ADDR_SIZE], + odp_ipc_msg_t msg); + +/** + * Send message + * + * Send a message to an endpoint (which may already be dead). + * Message delivery is ordered and reliable. All (accepted) messages will be + * delivered up to the point of endpoint death or lost connection. + * Actual reception and processing is not guaranteed (use end-to-end + * acknowledgements for that). + * Monitor the remote endpoint to detect death or lost connection. + * + * @param ipc IPC handle + * @param msg Message to send + * @param addr Address of remote endpoint + * + * @retval 0 on success + * @retval <0 on error + */ +int odp_ipc_send(odp_ipc_t ipc, + odp_ipc_msg_t msg, + const uint8_t addr[ODP_IPC_ADDR_SIZE]); + +/** + * Get address of sender (source) of message + * + * @param msg Message handle + * @param addr Address of sender endpoint + */ +void odp_ipc_sender(odp_ipc_msg_t msg, + uint8_t addr[ODP_IPC_ADDR_SIZE]); + +/** + * Message data pointer + * + * Return a pointer to the message data + * + * @param msg Message handle + * + * @return Pointer to the message data + */ +void *odp_ipc_data(odp_ipc_msg_t msg); + +/** + * Message data length + * + * Return length of the message data. + * + * @param msg Message handle + * + * @return Message length + */ +uint32_t odp_ipc_length(const odp_ipc_msg_t msg); + +/** + * Set message length + * + * Set length of the message data. + * + * @param msg Message handle + * @param len New length + * + * @retval 0 on success + * @retval <0 on error + */ +int odp_ipc_reset(const odp_ipc_msg_t msg, uint32_t len); + +/** + * Allocate message + * + * Allocate a message of a specific size. + * + * @param pool Message pool to allocate message from + * @param len Length of the allocated message + * + * @return IPC message handle on success + * @retval ODP_IPC_MSG_INVALID on failure and errno set + */ +odp_ipc_msg_t odp_ipc_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_ipc_free(odp_ipc_msg_t msg); + +/** + * Get message handle from event + * + * Converts an ODP_EVENT_MESSAGE type event to a message. + * + * @param ev Event handle + * + * @return Message handle + * + * @see odp_event_type() + */ +odp_ipc_msg_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_ipc_msg_t msg); + +/** + * Get printable value for an odp_ipc_t + * + * @param ipc IPC 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_ipc_t handle. + */ +uint64_t odp_ipc_to_u64(odp_ipc_t ipc); + +/** + * Get printable value for an odp_ipc_msg_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_ipc_msg_t handle. + */ +uint64_t odp_ipc_msg_to_u64(odp_ipc_msg_t msg); + +/** + * @} + */ + +#ifdef __cplusplus +} +#endif + +#endif