Date: Fri, 18 Dec 2015 19:37:32 +0000 (UTC)
From: Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
To: Davidlohr Bueso <dave@stgolabs.net>
Cc: Michael Kerrisk <mtk.manpages@gmail.com>, linux-kernel@vger.kernel.org,
        "Paul E. McKenney" <paulmck@linux.vnet.ibm.com>,
        Josh Triplett <josh@joshtriplett.org>,
        KOSAKI Motohiro <kosaki.motohiro@jp.fujitsu.com>,
        rostedt <rostedt@goodmis.org>, Nicholas Miell <nmiell@comcast.net>,
        Ingo Molnar <mingo@redhat.com>,
        One Thousand Gnomes <gnomes@lxorguk.ukuu.org.uk>,
        Lai Jiangshan <laijs@cn.fujitsu.com>,
        Stephen Hemminger <stephen@networkplumber.org>,
        Thomas Gleixner <tglx@linutronix.de>,
        Peter Zijlstra <peterz@infradead.org>,
        David Howells <dhowells@redhat.com>,
        Pranith Kumar <bobby.prani@gmail.com>,
        Shuah Khan <shuahkh@osg.samsung.com>,
        Andrew Morton <akpm@linux-foundation.org>,
        Linus Torvalds <torvalds@linux-foundation.org>,
        linux-api <linux-api@vger.kernel.org>
Message-ID: <1370012029.264035.1450467452427.JavaMail.zimbra@efficios.com>
In-Reply-To: <20151218184035.GF17386@linux-uzut.site>
References: <1450012663-16173-1-git-send-email-mathieu.desnoyers@efficios.com> <20151218184035.GF17386@linux-uzut.site>
Subject: Re: [RFC PATCH man-pages] Add membarrier system call man page
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: 7bit
Thread-Topic: Add membarrier system call man page
Thread-Index: EEjs+KLW86znQPXvBFhsqeLXX7uPiA==
Sender: linux-kernel-owner@vger.kernel.org
Content-Length: 1826
Lines: 49

----- On Dec 18, 2015, at 1:40 PM, Davidlohr Bueso dave@stgolabs.net wrote:

> On Sun, 13 Dec 2015, Mathieu Desnoyers wrote:
>>+.SH RETURN VALUE
>>+On success, this system call returns zero.  On error, \-1 is returned,
>>+and
> 
> For the zero return, would it make sense to specify that it is also the case
> for MEMBARRIER_CMD_SHARED under UP? Its pretty obvious it should be a no-op,
> but wouldn't hurt to make it explicit.

My understanding is that man pages should not document the internal behavior
of the system call. What matters here from a user-space perspective, independently
of UP vs SMP, is that membarrier with MEMBARRIER_CMD_SHARED command either
succeeds (0) or fails (e.g. -1, with ENOSYS or EINVAL errno).

By the way, the updated man page text now has this for MEMBARRIER_CMD_SHARED
description:

"      MEMBARRIER_CMD_SHARED
              Ensure that all threads from all processes on  the  system  pass
              through   a  state  where  all  memory  accesses  to  user-space
              addresses match program order between entry to and  return  from
              the  membarrier()  system  call.   All threads on the system are
              targeted by this command."

The text above is true both on UP and SMP.

I fear that calling out details about UP vs SMP in the man page might confuse
users, leading them to think they need to do special handling of UP, even
though this is something about which they really should not have to worry.

Thanks,

Mathieu

> 
> Thanks,
> Davidlohr

-- 
Mathieu Desnoyers
EfficiOS Inc.
http://www.efficios.com
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/