From mboxrd@z Thu Jan 1 00:00:00 1970 From: "Burakov, Anatoly" Subject: Re: [PATCH] doc: document all EAL parameters in one place Date: Mon, 19 Nov 2018 10:15:21 +0000 Message-ID: <553833b2-1920-1240-1deb-26693ac01b8c@intel.com> References: <6c5eddbb2339d917a9b67666499ae11ca8aa344b.1542386956.git.anatoly.burakov@intel.com> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8; format=flowed Content-Transfer-Encoding: 7bit Cc: John McNamara , Marko Kovacevic , Bruce Richardson , Wenzhuo Lu , Jingjing Wu , Bernard Iremonger , thomas@monjalon.net, ferruh.yigit@intel.com, keith.wiles@intel.com To: dev@dpdk.org 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) In-Reply-To: <6c5eddbb2339d917a9b67666499ae11ca8aa344b.1542386956.git.anatoly.burakov@intel.com> Content-Language: en-US List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org Sender: "dev" 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