From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mga03.intel.com (mga03.intel.com [134.134.136.65]) by dpdk.org (Postfix) with ESMTP id 165C02BD5 for ; Mon, 19 Nov 2018 11:15:24 +0100 (CET) X-Amp-Result: SKIPPED(no attachment in message) X-Amp-File-Uploaded: False Received: from orsmga008.jf.intel.com ([10.7.209.65]) by orsmga103.jf.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 19 Nov 2018 02:15:24 -0800 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.56,252,1539673200"; d="scan'208";a="93170256" Received: from aburakov-mobl1.ger.corp.intel.com (HELO [10.237.220.124]) ([10.237.220.124]) by orsmga008.jf.intel.com with ESMTP; 19 Nov 2018 02:15:21 -0800 To: dev@dpdk.org Cc: John McNamara , Marko Kovacevic , Bruce Richardson , Wenzhuo Lu , Jingjing Wu , Bernard Iremonger , thomas@monjalon.net, ferruh.yigit@intel.com, keith.wiles@intel.com References: <6c5eddbb2339d917a9b67666499ae11ca8aa344b.1542386956.git.anatoly.burakov@intel.com> From: "Burakov, Anatoly" Message-ID: <553833b2-1920-1240-1deb-26693ac01b8c@intel.com> Date: Mon, 19 Nov 2018 10:15:21 +0000 User-Agent: Mozilla/5.0 (Windows NT 10.0; WOW64; rv:52.0) Gecko/20100101 Thunderbird/52.9.1 MIME-Version: 1.0 In-Reply-To: <6c5eddbb2339d917a9b67666499ae11ca8aa344b.1542386956.git.anatoly.burakov@intel.com> Content-Type: text/plain; charset=utf-8; format=flowed Content-Language: en-US Content-Transfer-Encoding: 7bit Subject: Re: [dpdk-dev] [PATCH] doc: document all EAL parameters in one place X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 19 Nov 2018 10:15:25 -0000 On 16-Nov-18 4:52 PM, Anatoly Burakov wrote: > Currently, the most complete (but still incomplete) user guide for > EAL command-line parameters resides in user guide for testpmd. > This is wrong on multiple levels, and should not be the case. > > To fix it, we have to create a document that lists all supported > EAL command-line arguments. However, because different platforms > support different subsets of available EAL parameters, instead of > creating a single file, we will create a common file in > doc/guides/common containing documentation for EAL parameters > that are supported on all of our supported platforms (Linux and > FreeBSD at the time of this writing). > > We will then include this document in the Getting Started guides > for all supported platforms, so that any changes made to > documentation for commonly supported EAL parameters will be > reflected in Getting Started guides for all platforms. > > This patch also removes EAL parameters documentation from the > testpmd user guide, and instead adds references to the newly > created documents in both testpmd user guides and in sample > applications guide. > > Signed-off-by: Anatoly Burakov > --- > > Notes: > Here, "supported" is defined not as "doesn't produce error > on a particular platform, but rather is defined as "actually > works according to current codebase". All command-line > options have been traced through code to determine whether > they actually do anything. > > As a result, even though some command-line options (such as > "--vmware-tsc-map") are handled in eal_common_options (and > thus are supposed to be supported on all platforms), they > are nevertheless marked as Linux-specific. I believe this > is a good standard to follow. > > It would also be good to include links to relevant PG > sections for each parameters, but that can be done in > the future. This is a good enough start, i think. > > Also, currently, this breaks our pdf doc build because > i've added a "common" directory, and our PDF generator > expects an index.rst to be in there, even though this > directory is not supposed to be an actual document. I > would kindly request community's advice on how to best > resolve this situation. > > Things that i can think of myself: > - Put the common EAL flags somewhere in the existing > directories (we don't have anything appropriate for > that, but the last resolt would be something like > Linux GSG directory) > - Hack our build system to not create a "common" PDF > file and skip this directory altogether > - Put this file outside of doc/guides (doc/common?) > The above problem with pdf doc build still exists and needs to be solved before this patch is integrated. Unfortunately, my LaTeX-fu is lacking, so i'd really like some help here :) -- Thanks, Anatoly