From patchwork Mon Feb 22 17:02:56 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Christophe Milard X-Patchwork-Id: 62607 Delivered-To: patch@linaro.org Received: by 10.112.43.199 with SMTP id y7csp1325266lbl; Mon, 22 Feb 2016 08:05:24 -0800 (PST) X-Received: by 10.50.50.201 with SMTP id e9mr12818566igo.10.1456157121970; Mon, 22 Feb 2016 08:05:21 -0800 (PST) Return-Path: Received: from lists.linaro.org (lists.linaro.org. [54.225.227.206]) by mx.google.com with ESMTP id z18si33716703igq.63.2016.02.22.08.05.21; Mon, 22 Feb 2016 08:05:21 -0800 (PST) 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; Authentication-Results: mx.google.com; spf=pass (google.com: domain of lng-odp-bounces@lists.linaro.org designates 54.225.227.206 as permitted sender) smtp.mailfrom=lng-odp-bounces@lists.linaro.org Received: by lists.linaro.org (Postfix, from userid 109) id 642C3617EF; Mon, 22 Feb 2016 16:05:21 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on ip-10-142-244-252 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 [127.0.0.1] (localhost [127.0.0.1]) by lists.linaro.org (Postfix) with ESMTP id 5FAAE6177C; Mon, 22 Feb 2016 16:04:25 +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 53717617E9; Mon, 22 Feb 2016 16:04:04 +0000 (UTC) Received: from mail-lb0-f173.google.com (mail-lb0-f173.google.com [209.85.217.173]) by lists.linaro.org (Postfix) with ESMTPS id 8FC446177C for ; Mon, 22 Feb 2016 16:04:01 +0000 (UTC) Received: by mail-lb0-f173.google.com with SMTP id of3so84617386lbc.1 for ; Mon, 22 Feb 2016 08:04:01 -0800 (PST) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references; bh=Vd5g72K1LERGVDxxjGgBta7XF/XvsoGp2jVFYKTArFI=; b=JZbIo6uXv9AOIEtUUOOxF/E/MloHtI8wBY8kfvx8BNkFq5dPomSHIPr5c7hiwCsxHb UcIi6xovczgi4M57f42HaN7iezirFwolnJBkr9cnY7dQ0kt3l5tVAlDwtoBQ9SGZKNPM qTB1+mPK2SzIjOY3yAuSlIEbTi9WXtHpQnTdb7iZyxkFKMkmZkCEDsx8+uwNcWaRG1xT UXvwTpLTVrToEO1KRKns+WLvt0v/L8WtucK3AFbYkXSJ5HTICXGYSwNN+f3NvQRDefof Xe1tQ/EuJo45VaV4kFQLKXvw3TaTD0kqtKdY8tuoSRuA6Zb6xqSv/rfrVrdJzk4a3nfa CJMg== X-Gm-Message-State: AG10YOR9beog+uazpfsTD3KDMFMGjKOU+cqwyoeBG/iwUdPGEHyit681RHvoQKfA6Y29YHTl5t4= X-Received: by 10.112.151.134 with SMTP id uq6mr8531688lbb.18.1456157040530; Mon, 22 Feb 2016 08:04:00 -0800 (PST) Received: from erachmi-ericsson.ki.sw.ericsson.se (c-83-233-90-46.cust.bredband2.com. [83.233.90.46]) by smtp.gmail.com with ESMTPSA id f184sm3470959lfe.6.2016.02.22.08.03.59 (version=TLS1_2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Mon, 22 Feb 2016 08:03:59 -0800 (PST) From: Christophe Milard To: mike.holmes@linaro.org, bill.fischofer@linaro.org, petri.savolainen@linaro.org Date: Mon, 22 Feb 2016 18:02:56 +0100 Message-Id: <1456160578-8312-3-git-send-email-christophe.milard@linaro.org> X-Mailer: git-send-email 2.1.4 In-Reply-To: <1456160578-8312-1-git-send-email-christophe.milard@linaro.org> References: <1456160578-8312-1-git-send-email-christophe.milard@linaro.org> X-Topics: patch Cc: lng-odp@lists.linaro.org Subject: [lng-odp] [PATCHv3 2/4] doc: user-guide: shmem X-BeenThere: lng-odp@lists.linaro.org X-Mailman-Version: 2.1.16 Precedence: list List-Id: "The OpenDataPlane \(ODP\) List" 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" section regarding shared memo added. Signed-off-by: Christophe Milard Reviewed-and-tested-by: Bill Fischofer --- doc/users-guide/users-guide.adoc | 130 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 130 insertions(+) diff --git a/doc/users-guide/users-guide.adoc b/doc/users-guide/users-guide.adoc index bbb53a7..494c8ab 100644 --- a/doc/users-guide/users-guide.adoc +++ b/doc/users-guide/users-guide.adoc @@ -543,6 +543,136 @@ lookup. The lookup function is particularly useful to allow an ODP application that is divided into multiple processes to obtain the handle for the common resource. +== Shared memory +=== Allocating shared memory +Blocks of shared memory can be created using the +odp_shm_reserve()+ API +call. The call expects a shared memory block name, a block size, an alignment +requirement, and optional flags as parameters. It returns a +odp_shm_t+ +handle. The size and alignment requirement are given in bytes. + +.creating a block of shared memory +[source,c] +---- +#define ALIGNMENT 128 +#define BLKNAME "shared_items" + +odp_shm_t shm; +uint32_t shm_flags = 0; + +typedef struct { +... +} shared_data_t; + +shm = odp_shm_reserve(BLKNAME, sizeof(shared_data_t), ALIGNMENT, shm_flags); +---- + +=== Getting the shared memory block address +The returned odp_shm_t handle can then be used to retrieve the actual +address (in the caller's ODP thread virtual address space) of the created +shared memory block. + +.getting the address of a shared memory block +[source,c] +---- +shared_data_t *shared_data; +shared_data = odp_shm_addr(shm); +---- + +The address returned by +odp_shm_addr()+ is valid only in the calling ODP +thread space: odp_shm_t handles can be shared between ODP threads and remain +valid within any threads, whereas the address returned by +odp_shm_addr(shm)+ +may differ from ODP threads to ODP threads (for the same 'shm' block), and +should therefore not be shared between ODP threads. +For instance, it would be correct to send a shm handle using IPC between two +ODP threads and let each of these thread do their own +odp_shm_addr()+ to +get the block address. Directly sending the address returned by ++odp_shm_addr()+ from one ODP thread to another would however possibly fail +(the address may have no sense in the receiver address space). + +The address returned by +odp_shm_addr()+ is nevertheless guaranteed to be +aligned according to the alignment requirements provided at block creation +time, even if the call to +odp_shm_addr()+ is performed by a different ODP +thread than the one which originally called +odp_shm_reserve()+. + +All shared memory blocks are contiguous in any ODP thread addressing space: +'address' to 'address'\+'size' (where 'size' is the shared memory block size, +as provided in the +odp_shm_reserve()+ call) is read and writeable and +mapping the shared memory block. There is no fragmentation. + +=== Memory behaviour +By default ODP threads are assumed to behave as cache coherent systems: +Any change performed on a shared memory block is guaranteed to eventually +become visible to other ODP threads sharing this memory block. +(this behaviour may be altered by flags to +odp_shm_reserve()+ in the future). +Nevertheless, there is no implicit memory barrier associated with any action +on shared memories: *When* a change performed by an ODP thread becomes visible +to another ODP thread is not known: An application using shared memory +blocks has to use some memory barrier provided by ODP to guarantee shared data +validity between ODP threads. + +=== Lookup by name +As mentioned, shared memory handles can be sent from ODP threads to ODP +threads using any IPC mechanism, and then the block address retrieved. +A simpler approach to get the shared memory block handle of an already created +block is to use the +odp_shm_lookup()+ API function call. +This nevertheless requires the calling ODP thread to provide the name of the +shared memory block: ++odp_shm_lookup()+ will return +ODP_SHM_INVALID+ if no shared memory block +with the provided name is known by ODP. + +.retrieving a block handle and address from another ODP task +[source,c] +---- +#define BLKNAME "shared_items" + +odp_shm_t shm; +shared_data_t *shared_data; + +shm = odp_shm_lookup(BLKNAME); +if (shm != ODP_SHM_INVALID) { + shared_data = odp_shm_addr(shm); + ... +} +---- + +=== Freeing memory +Freeing shared memory is performed using the +odp_shm_free()+ API call. ++odp_shm_free()+ takes one single argument, the shared memory block handle. +Any ODP thread is allowed to perform a +odp_shm_free()+ on a shared memory +block (i.e. the thread performing the +odp_shm_free()+ may be different +from the thread which did the +odp_shm_reserve()+). Shared memory blocks should +be freed only once, and once freed, a shared memory block should no longer +be referenced by any ODP threads. + +.freeing a shared memory block +[source,c] +---- +if (odp_shm_free(shm) != 0) { + ...//handle error +} +---- + +=== Memory creation flags +The last argument to odp_shm_reserve() is a set of ORed flags. +Two flags are supported: + +==== ODP_SHM_PROC +When this flag is given, the allocated shared memory will become visible +outside ODP. Non ODP threads (e.g. usual linux process or linux threads) +will be able to access the memory using native (non ODP) OS calls such as +'shm_open()' and 'mmap' (for linux). +Each ODP implementation should provide a description on exactly how +this mapping should be done on that specific platform. + +==== ODP_SHM_SW_ONLY +This flag tells ODP that the shared memory will be used by the ODP application +software only: no HW (such as DMA, or other accelerator) will ever +try to access the memory. No other ODP call will be involved on this memory +(as ODP calls could implicitly involve HW, depending on the ODP +implementation), except for +odp_shm_lookup()+ and +odp_shm_free()+. +ODP implementations may use this flag as a hint for performance optimization, +or may as well ignore this flag. + == Queues Queues are the fundamental event sequencing mechanism provided by ODP and all ODP applications make use of them either explicitly or implicitly. Queues are