linux-kernel - [RFC PATCH 19/19] cpufreq: documentation: document locking scheme

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-Id: <1452533760-13787-20-git-send-email-juri.lelli@arm.com>
Date:	Mon, 11 Jan 2016 17:36:00 +0000
From:	Juri Lelli <juri.lelli@....com>
To:	linux-kernel@...r.kernel.org
Cc:	linux-pm@...r.kernel.org, peterz@...radead.org, rjw@...ysocki.net,
	viresh.kumar@...aro.org, mturquette@...libre.com,
	steve.muckle@...aro.org, vincent.guittot@...aro.org,
	morten.rasmussen@....com, dietmar.eggemann@....com,
	juri.lelli@....com, Jonathan Corbet <corbet@....net>,
	linux-doc@...r.kernel.org
Subject: [RFC PATCH 19/19] cpufreq: documentation: document locking scheme

CPUFreq locking scheme is quite complicated. Provide some initial
documentation for it.

Cc: Jonathan Corbet <corbet@....net>
Cc: "Rafael J. Wysocki" <rjw@...ysocki.net>
Cc: Viresh Kumar <viresh.kumar@...aro.org>
Cc: linux-doc@...r.kernel.org
Signed-off-by: Juri Lelli <juri.lelli@....com>
---
 Documentation/cpu-freq/core.txt | 44 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 44 insertions(+)

diff --git a/Documentation/cpu-freq/core.txt b/Documentation/cpu-freq/core.txt
index ba78e7c..1838976 100644
--- a/Documentation/cpu-freq/core.txt
+++ b/Documentation/cpu-freq/core.txt
@@ -21,6 +21,7 @@ Contents:
 1.  CPUFreq core and interfaces
 2.  CPUFreq notifiers
 3.  CPUFreq Table Generation with Operating Performance Point (OPP)
+4.  CPUFreq locking scheme for internal data structures
 
 1. General Information
 =======================
@@ -118,3 +119,46 @@ dev_pm_opp_init_cpufreq_table - cpufreq framework typically is initialized with
 	addition to CONFIG_PM_OPP.
 
 dev_pm_opp_free_cpufreq_table - Free up the table allocated by dev_pm_opp_init_cpufreq_table
+
+4. CPUFreq locking scheme for internal data structures
+======================================================
+CPUFreq locking scheme has to guarantee ordering and mutual exclusion on
+internal data structures while concurrent execution of CPU hotplug, OPP
+selection, governor changes and driver changes might happen.
+
+Data structures depicted in the following diagram (except policyX data
+structures, see below) are protected by cpufreq_ driver_lock RWLOCK (see
+beginning of cpufreq.c).
+
+ cpufreq_driver -> struct cpufreq_driver
+
+ cpufreq_cpu_data (per-CPU)
+
+                         +---+---+---+    +---+
+                         | 0 | 1 | 2 | .. |N-1|
+                         +-+-+-+-+-+-+    +-+-+
+                           |   |   |        |
+                           |---+   +--------+
+                           |                |
+                           |                |
+                           V                V
+ cpufreq_policy_list --> policy0 -- .. -> policy(N-1)-+
+                                                      |
+					              x
+
+Concurrent reads/updates of policyX data structures are guarded by policy->
+rwsem. The rules for this semaphore are (as also reported in include/linux/
+cpufreq.h):
+
+ - any routine that wants to read from the policy structure will
+   do a down_read on this semaphore;
+ - any routine that will write to the policy structure and/or may take away
+   the policy altogether (eg. CPU hotplug), will hold this lock in write
+   mode before doing so.
+
+We then have another list that keeps track of available governors and that is
+protected by cpufreq_governor_mutex MUTEX:
+
+ cpufreq_governor_list --> governor0 -- .. --> governor(N-1) -+
+                                                              |
+				                              x
-- 
2.2.2