Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1752747AbdFQP0E (ORCPT ); Sat, 17 Jun 2017 11:26:04 -0400 Received: from ec2-52-27-115-49.us-west-2.compute.amazonaws.com ([52.27.115.49]:38514 "EHLO osg.samsung.com" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org with ESMTP id S1752633AbdFQPZ7 (ORCPT ); Sat, 17 Jun 2017 11:25:59 -0400 X-Amavis-Alert: BAD HEADER SECTION, Duplicate header field: "References" From: Mauro Carvalho Chehab To: Linux Doc Mailing List Cc: Mauro Carvalho Chehab , Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Jonathan Corbet , Thomas Gleixner , Ingo Molnar , Peter Zijlstra , Darren Hart Subject: [PATCH v2 21/31] futex-requeue-pi.txt: standardize document format Date: Sat, 17 Jun 2017 12:25:40 -0300 Message-Id: X-Mailer: git-send-email 2.9.4 In-Reply-To: References: In-Reply-To: References: Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Length: 3672 Lines: 127 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 level for the document title; - mark literal blocks. Signed-off-by: Mauro Carvalho Chehab --- Documentation/futex-requeue-pi.txt | 83 +++++++++++++++++++------------------- 1 file changed, 42 insertions(+), 41 deletions(-) diff --git a/Documentation/futex-requeue-pi.txt b/Documentation/futex-requeue-pi.txt index 77b36f59d16b..14ab5787b9a7 100644 --- a/Documentation/futex-requeue-pi.txt +++ b/Documentation/futex-requeue-pi.txt @@ -1,5 +1,6 @@ +================ Futex Requeue PI ----------------- +================ Requeueing of tasks from a non-PI futex to a PI futex requires special handling in order to ensure the underlying rt_mutex is never @@ -20,28 +21,28 @@ implementation would wake the highest-priority waiter, and leave the rest to the natural wakeup inherent in unlocking the mutex associated with the condvar. -Consider the simplified glibc calls: +Consider the simplified glibc calls:: -/* caller must lock mutex */ -pthread_cond_wait(cond, mutex) -{ - lock(cond->__data.__lock); - unlock(mutex); - do { - unlock(cond->__data.__lock); - futex_wait(cond->__data.__futex); - lock(cond->__data.__lock); - } while(...) - unlock(cond->__data.__lock); - lock(mutex); -} + /* caller must lock mutex */ + pthread_cond_wait(cond, mutex) + { + lock(cond->__data.__lock); + unlock(mutex); + do { + unlock(cond->__data.__lock); + futex_wait(cond->__data.__futex); + lock(cond->__data.__lock); + } while(...) + unlock(cond->__data.__lock); + lock(mutex); + } -pthread_cond_broadcast(cond) -{ - lock(cond->__data.__lock); - unlock(cond->__data.__lock); - futex_requeue(cond->data.__futex, cond->mutex); -} + pthread_cond_broadcast(cond) + { + lock(cond->__data.__lock); + unlock(cond->__data.__lock); + futex_requeue(cond->data.__futex, cond->mutex); + } Once pthread_cond_broadcast() requeues the tasks, the cond->mutex has waiters. Note that pthread_cond_wait() attempts to lock the @@ -53,29 +54,29 @@ In order to support PI-aware pthread_condvar's, the kernel needs to be able to requeue tasks to PI futexes. This support implies that upon a successful futex_wait system call, the caller would return to user space already holding the PI futex. The glibc implementation -would be modified as follows: +would be modified as follows:: -/* caller must lock mutex */ -pthread_cond_wait_pi(cond, mutex) -{ - lock(cond->__data.__lock); - unlock(mutex); - do { - unlock(cond->__data.__lock); - futex_wait_requeue_pi(cond->__data.__futex); - lock(cond->__data.__lock); - } while(...) - unlock(cond->__data.__lock); - /* the kernel acquired the mutex for us */ -} + /* caller must lock mutex */ + pthread_cond_wait_pi(cond, mutex) + { + lock(cond->__data.__lock); + unlock(mutex); + do { + unlock(cond->__data.__lock); + futex_wait_requeue_pi(cond->__data.__futex); + lock(cond->__data.__lock); + } while(...) + unlock(cond->__data.__lock); + /* the kernel acquired the mutex for us */ + } -pthread_cond_broadcast_pi(cond) -{ - lock(cond->__data.__lock); - unlock(cond->__data.__lock); - futex_requeue_pi(cond->data.__futex, cond->mutex); -} + pthread_cond_broadcast_pi(cond) + { + lock(cond->__data.__lock); + unlock(cond->__data.__lock); + futex_requeue_pi(cond->data.__futex, cond->mutex); + } The actual glibc implementation will likely test for PI and make the necessary changes inside the existing calls rather than creating new -- 2.9.4