Re: [RFC PATCH man-pages] Add membarrier system call man page

[Mathieu Desnoyers <mathieu.desnoyers@efficios.com>]

----- 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