From patchwork Fri Aug 5 15:27:11 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mike Holmes X-Patchwork-Id: 73369 Delivered-To: patch@linaro.org Received: by 10.140.29.52 with SMTP id a49csp1995632qga; Fri, 5 Aug 2016 08:27:23 -0700 (PDT) X-Received: by 10.55.75.79 with SMTP id y76mr14014498qka.9.1470410843273; Fri, 05 Aug 2016 08:27:23 -0700 (PDT) Return-Path: Received: from lists.linaro.org (lists.linaro.org. [54.225.227.206]) by mx.google.com with ESMTP id z101si9307634qkg.25.2016.08.05.08.27.22; Fri, 05 Aug 2016 08:27:23 -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; 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; dmarc=pass (p=NONE dis=NONE) header.from=linaro.org Received: by lists.linaro.org (Postfix, from userid 109) id 628BB6097F; Fri, 5 Aug 2016 15:27:22 +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 1C75960977; Fri, 5 Aug 2016 15:27:18 +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 79D9E60979; Fri, 5 Aug 2016 15:27:15 +0000 (UTC) Received: from mail-qk0-f170.google.com (mail-qk0-f170.google.com [209.85.220.170]) by lists.linaro.org (Postfix) with ESMTPS id B218460975 for ; Fri, 5 Aug 2016 15:27:14 +0000 (UTC) Received: by mail-qk0-f170.google.com with SMTP id v123so133454260qkh.3 for ; Fri, 05 Aug 2016 08:27:14 -0700 (PDT) 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; bh=ylxvdSbATAMXWge1rGrrpYsgKfQ1W6lrVJ0qko00ceU=; b=FFPHEYhpPcvA4qdCQSG8Q3ysxR6cM33yP0B1rpe6EQOz8S9/Q/FoarHfZzudiQZ3HI YnXUp6c1oYEyofismjhL3PTriTbmH179vvOdh/ng+79fY8N2ZE0VdFANyqwdf5Xoape2 5oavt6Wc+vh4kcRoA/6ehtiIBnBRdRYiRxdcTnO0mhlWNxT+bR6ugZyhf6kOnQOdvT2k joAgdZ1C6U/+TPfqA60/PeOPntDVTX0xbNAu5cdUF7bTVW+Vk70X1F6kFAv1EYZZhaWJ 5dSm9Hjm53UIyX6KCF2OD0Yyeu6/Bq3GMMObfOTCGN4WTieo+q7RC8BYNXNWUofXde+N p++Q== X-Gm-Message-State: AEkoouurGavnC3ZNX48CXGCPaiWJGSwopqLLn4a3WmAkGSsqhx2iEj6MWmpQ4g6/yuOvayYKE5s= X-Received: by 10.55.5.17 with SMTP id 17mr12931120qkf.280.1470410834215; Fri, 05 Aug 2016 08:27:14 -0700 (PDT) Received: from localhost (c-98-221-136-245.hsd1.nj.comcast.net. [98.221.136.245]) by smtp.gmail.com with ESMTPSA id n20sm9844356qtn.40.2016.08.05.08.27.13 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Fri, 05 Aug 2016 08:27:13 -0700 (PDT) From: Mike Holmes To: lng-odp@lists.linaro.org Date: Fri, 5 Aug 2016 11:27:11 -0400 Message-Id: <1470410831-21571-1-git-send-email-mike.holmes@linaro.org> X-Mailer: git-send-email 2.7.4 X-Topics: patch Subject: [lng-odp] [PATCH v2] linux-gen: doc: defining the ODP thread 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: , Errors-To: lng-odp-bounces@lists.linaro.org Sender: "lng-odp" From: Christophe Milard Signed-off-by: Christophe Milard Signed-off-by: Mike Holmes --- v2 Added the new file to the distribution in a generic way (maxim) Do we want to put additional documentation in the DOC dir or in with the platform specific header files as Christophe has done initially in this patch ? I see pros to both. In the include dir is where a coder who does not look at docs will find it, however generally we put dox files in the DOC dir I am leaning towards case one as the most helpful to a common case where docs are not consulted. doc/platform-api-guide/Makefile.am | 7 +++- .../include/odp/api/platform_specific.dox | 46 ++++++++++++++++++++++ 2 files changed, 52 insertions(+), 1 deletion(-) create mode 100644 platform/linux-generic/include/odp/api/platform_specific.dox -- 2.7.4 diff --git a/doc/platform-api-guide/Makefile.am b/doc/platform-api-guide/Makefile.am index a04c254..a3c7f14 100644 --- a/doc/platform-api-guide/Makefile.am +++ b/doc/platform-api-guide/Makefile.am @@ -1,5 +1,10 @@ +#If additional documentation is added in the platform include directory but it is +#not in a .h file, it must be included here as an extra part of the distribution + EXTRA_DIST = \ - Doxyfile + Doxyfile \ + $(top_srcdir)/platform/${with_platform}/include/odp/api/*.dox + clean-local: rm -rf output diff --git a/platform/linux-generic/include/odp/api/platform_specific.dox b/platform/linux-generic/include/odp/api/platform_specific.dox new file mode 100644 index 0000000..e116ec6 --- /dev/null +++ b/platform/linux-generic/include/odp/api/platform_specific.dox @@ -0,0 +1,46 @@ +/* Copyright (c) 2016, Linaro Limited + * All rights reserved + * + * SPDX-License-Identifier: BSD-3-Clause + */ + +/** +* @file platform_specific.dox +* extra linux-generic documentation +*/ + +/** @addtogroup odp_thread + * @par ODP thread + * In this ODP implementation an odp thread is either: + * - a linux process descendant (or same as) the odp instantiation process. + * - a pthread 'member' of a linux process descendant (or same as) the odp + * instantiation process. + */ + +/** + * @fn odp_init_local(odp_instance_t instance, odp_thread_type_t thr_type) + * @note In this ODP implementation odpthreads have to be + * processes descendant of (or same as) the ODP + * instantiation process, or pthreads 'member' of such + * processes. + * @note As ODP instantiation processes cannot be descendants + * of each others, the instance parameter provided + * to odp_init_local() is actually fully defined by these + * requirements: It has to be the value returned by the + * unique call to odp_init_global() made by one single + * acsendant of the current process. + */ + +/** + * @fn odp_init_global(odp_instance_t *instance, + * const odp_init_t *params, + * const odp_platform_init_t *platform_params) + * @note This ODP implementation supports mupliple instances of ODP + * (i.e. multiple call to odp_init_global()) with the following + * restrictions: + * @note -Different ODP instances cannot share the same instantiation + * process. In other words, a single process may + * only call odp_init_global() once. + * @note -Different ODP instantiation processes cannot be descendant of + * each other. + */