[PATCH v2 08/26] robust-futex-ABI.txt: standardize document format

Path	csiph.com!eternal-september.org!feeder.eternal-september.org!news.mixmin.net!aioe.org!bofh.it!news.nic.it!robomod
From	Mauro Carvalho Chehab <mchehab@s-opensource.com>
Newsgroups	linux.kernel
Subject	[PATCH v2 08/26] robust-futex-ABI.txt: standardize document format
Date	Sat, 17 Jun 2017 17:40:02 +0200
Message-ID	<tTnZo-Cs-29@gated-at.bofh.it> (permalink)
References	<tTnPI-y3-25@gated-at.bofh.it>
X-Original-To	Linux Doc Mailing List <linux-doc@vger.kernel.org>
X-Amavis-Alert	BAD HEADER SECTION, Duplicate header field: "References"
X-Mailer	git-send-email 2.9.4
Sender	robomod@news.nic.it
List-ID	<linux-kernel.vger.kernel.org>
X-Mailing-List	linux-kernel@vger.kernel.org
Approved	robomod@news.nic.it
Lines	69
Organization	linux.* mail to news gateway
X-Original-Cc	Mauro Carvalho Chehab <mchehab@s-opensource.com>, Mauro Carvalho Chehab <mchehab@infradead.org>, linux-kernel@vger.kernel.org, Jonathan Corbet <corbet@lwn.net>, Thomas Gleixner <tglx@linutronix.de>, Ingo Molnar <mingo@redhat.com>, Peter Zijlstra <peterz@infradead.org>, Darren Hart <dvhart@infradead.org>
X-Original-Date	Sat, 17 Jun 2017 12:26:48 -0300
X-Original-Message-ID	<14a19b89bc2ca613d5bc2436722e02d4e92de33d.1497713221.git.mchehab@s-opensource.com>
X-Original-References	<1a82f2bf2de4b016964cb71ff92dc3a472044f40.1497713221.git.mchehab@s-opensource.com>
X-Original-Sender	linux-kernel-owner@vger.kernel.org
Xref	csiph.com linux.kernel:1668300

Show key headers only | View raw

Each text file under Documentation follows a different
format. Some doesn't even have titles!

Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx:

- promote document title;
- use :Author: for authorship;
- mark literal blocks;
- add blank lines.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/robust-futex-ABI.txt | 14 +++++++++-----
 1 file changed, 9 insertions(+), 5 deletions(-)

diff --git a/Documentation/robust-futex-ABI.txt b/Documentation/robust-futex-ABI.txt
index 16eb314f56cc..8a5d34abf726 100644
--- a/Documentation/robust-futex-ABI.txt
+++ b/Documentation/robust-futex-ABI.txt
@@ -1,7 +1,9 @@
-Started by Paul Jackson <pj@sgi.com>
-
+====================
 The robust futex ABI
---------------------
+====================
+
+:Author: Started by Paul Jackson <pj@sgi.com>
+
 
 Robust_futexes provide a mechanism that is used in addition to normal
 futexes, for kernel assist of cleanup of held locks on task exit.
@@ -32,7 +34,7 @@ probably causing deadlock or other such failure of the other threads
 waiting on the same locks.
 
 A thread that anticipates possibly using robust_futexes should first
-issue the system call:
+issue the system call::
 
     asmlinkage long
     sys_set_robust_list(struct robust_list_head __user *head, size_t len);
@@ -91,7 +93,7 @@ that lock using the futex mechanism.
 When a thread has invoked the above system call to indicate it
 anticipates using robust_futexes, the kernel stores the passed in 'head'
 pointer for that task.  The task may retrieve that value later on by
-using the system call:
+using the system call::
 
     asmlinkage long
     sys_get_robust_list(int pid, struct robust_list_head __user **head_ptr,
@@ -135,6 +137,7 @@ manipulating this list), the user code must observe the following
 protocol on 'lock entry' insertion and removal:
 
 On insertion:
+
  1) set the 'list_op_pending' word to the address of the 'lock entry'
     to be inserted,
  2) acquire the futex lock,
@@ -143,6 +146,7 @@ On insertion:
  4) clear the 'list_op_pending' word.
 
 On removal:
+
  1) set the 'list_op_pending' word to the address of the 'lock entry'
     to be removed,
  2) remove the lock entry for this lock from the 'head' list,
-- 
2.9.4

Back to linux.kernel | Previous | Next | Find similar | Unroll thread

Thread

[PATCH v2 08/26] robust-futex-ABI.txt: standardize document format Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-06-17 17:40 +0200

csiph-web