From mboxrd@z Thu Jan  1 00:00:00 1970
Return-Path: <linux-kernel-owner@vger.kernel.org>
Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand
	id S1752830AbbJYJTV (ORCPT <rfc822;w@1wt.eu>);
	Sun, 25 Oct 2015 05:19:21 -0400
Received: from mail-wi0-f182.google.com ([209.85.212.182]:32881 "EHLO
	mail-wi0-f182.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org
	with ESMTP id S1750802AbbJYJTT (ORCPT
	<rfc822;linux-kernel@vger.kernel.org>);
	Sun, 25 Oct 2015 05:19:19 -0400
Date: Sun, 25 Oct 2015 10:19:15 +0100
From: Ingo Molnar <mingo@kernel.org>
To: Namhyung Kim <namhyung@kernel.org>
Cc: Thomas Gleixner <tglx@linutronix.de>, "bp@suse.de" <bp@suse.de>,
        Wang Nan <wangnan0@huawei.com>, David Ahern <dsahern@gmail.com>,
        "H. Peter Anvin" <hpa@zytor.com>,
        "linux-kernel@vger.kernel.org" <linux-kernel@vger.kernel.org>,
        Arnaldo Carvalho de Melo <acme@redhat.com>,
        Jiri Olsa <jolsa@redhat.com>, Chandler Carruth <chandlerc@gmail.com>,
        Adrian Hunter <adrian.hunter@intel.com>,
        Peter Zijlstra <a.p.zijlstra@chello.nl>,
        Stephane Eranian <eranian@google.com>,
        Brendan Gregg <brendan.d.gregg@gmail.com>,
        =?iso-8859-1?Q?Fr=E9d=E9ric?= Weisbecker <fweisbec@gmail.com>,
        linux-tip-commits@vger.kernel.org
Subject: Re: [tip:perf/core] perf tools: Improve call graph documents and
 help messages
Message-ID: <20151025091915.GA4380@gmail.com>
References: <1445524112-5201-2-git-send-email-namhyung@kernel.org>
 <tip-76a26549eb367f683fbb394b7246bef5dc665f8c@git.kernel.org>
 <20151023090359.GA22437@gmail.com>
 <CAM9d7cijNsSWN5DpogJs8y-S4V9u2wJ4TFs7GGU010ZcCN80Og@mail.gmail.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <CAM9d7cijNsSWN5DpogJs8y-S4V9u2wJ4TFs7GGU010ZcCN80Og@mail.gmail.com>
User-Agent: Mutt/1.5.23 (2014-03-12)
Sender: linux-kernel-owner@vger.kernel.org
List-ID: <linux-kernel.vger.kernel.org>
X-Mailing-List: linux-kernel@vger.kernel.org


* Namhyung Kim <namhyung@kernel.org> wrote:

> Hi Ingo,
> 
> On Fri, Oct 23, 2015 at 6:03 PM, Ingo Molnar <mingo@kernel.org> wrote:
> >
> > * tip-bot for Namhyung Kim <tipbot@zytor.com> wrote:
> >
> >> Commit-ID:  76a26549eb367f683fbb394b7246bef5dc665f8c
> >> Gitweb:     http://git.kernel.org/tip/76a26549eb367f683fbb394b7246bef5dc665f8c
> >> Author:     Namhyung Kim <namhyung@kernel.org>
> >> AuthorDate: Thu, 22 Oct 2015 23:28:32 +0900
> >> Committer:  Arnaldo Carvalho de Melo <acme@redhat.com>
> >> CommitDate: Thu, 22 Oct 2015 16:23:19 -0300
> >>
> >> perf tools: Improve call graph documents and help messages
> >>
> >> The --call-graph option is complex so we should provide better guide for
> >> users.  Also change help message to be consistent with config option
> >> names.  Now perf top will show help like below:
> >>
> >>   $ perf top --call-graph
> >>     Error: option `call-graph' requires a value
> >>
> >>    Usage: perf top [<options>]
> >>
> >>       --call-graph <record_mode[,record_size],print_type,threshold[,print_limit],order,sort_key[,branch]>
> >>            setup and enables call-graph (stack chain/backtrace):
> >>
> >>               record_mode:    call graph recording mode (fp|dwarf|lbr)
> >>               record_size:    if record_mode is 'dwarf', max size of stack recording (<bytes>)
> >>                               default: 8192 (bytes)
> >>               print_type:     call graph printing style (graph|flat|fractal|none)
> >>               threshold:      minimum call graph inclusion threshold (<percent>)
> >>               print_limit:    maximum number of call graph entry (<number>)
> >>               order:          call graph order (caller|callee)
> >>               sort_key:       call graph sort key (function|address)
> >>               branch:         include last branch info to call graph (branch)
> >
> > Btw., how is the last line to be interpreted? Is the 'branch' value 0/1? If yes
> > then the text should probably say so? Or does the string 'branch' have to be used?
> 
> Yep, the string 'branch' should be used.

Yeah, so that wasn't very obvious, as there's a mixture of literal symbols with 
parameter names. For example:

       --call-graph <record_mode[,record_size],print_type,threshold[,print_limit],order,sort_key[,branch]>
            setup and enables call-graph (stack chain/backtrace):

so 'record_size' is obviously never to be written in a literal fashion - but 
'branch' is?

But I cannot think of a better solution, other than replacing:

                              default: 8192 (bytes)

with :
                              default: 8192 bytes

because in all other cases parantheses denote a specification of valid parameter 
values.

Thanks,

	Ingo