pm: EDP: added kernel documentation

This patch adds documentation about:

(1) dynamic EDP capping in general
(2) EDP framework design
(3) user guide with example for device driver authors
(4) EDP sysfs
(5) EDP policy governors

Change-Id: I63e7ac25d28e025e5faead276a091ceaaa3c64f0
Signed-off-by: Sivaram Nair <sivaramn@nvidia.com>
Reviewed-on: http://git-master/r/131065
Reviewed-by: Automatic_Commit_Validation_User
GVS: Gerrit_Virtual_Submit
Reviewed-by: Diwakar Tundlam <dtundlam@nvidia.com>
Reviewed-by: Matthew Longnecker <mlongnecker@nvidia.com>

5 files changed, 459 insertions, 0 deletions

diff --git a/Documentation/edp/design b/Documentation/edp/design
new file mode 100644
index 000000000000..eaafb4d45805
--- /dev/null
+++ b/Documentation/edp/design
@@ -0,0 +1,147 @@
+
+SYSTEM EDP CAPPING DESIGN
+
+1. Introduction
+
+This document uses a glossary of terms to explain the design of System
+EDP capping.
+
+2. System EDP manager
+
+The central piece of software which dynamically allocates
+current-sourcing capacity to EDP client drivers for use by their
+devices. A system may have more than one manager. Managers are
+distinguished by their unique names.
+
+3. EDP client driver
+
+The device driver associated with one particular power consuming device.
+EDP client drivers register with the System EDP manager to monitor and
+manage the current consumption of their associated device. A client can
+be registered with only one manager at any given time.
+
+4. E-state
+
+Electrical states which are defined per EDP client and numbered {...
+E-2, E-1, E0, E1, E2...}.  Each E-state for a given driver indicates a
+particular maximum current consumption.
+
+	[*] Higher E-state: an E-state closer to E-infinity. E-1 is
+	    higher than E0, E1 is higher than E2 etc.
+	[*] Lower E-state: an E-state closer to Einfinity. E-1 is lower
+	    than E-2, E1 is lower than E0 etc.
+	[*] Positive E-states: E0, E1, E2...
+	[*] Negative E-state: ...E-3, E-2, E-1.
+	[*] E0: the system EDP manager guarantees that it can provide
+	    E0 simultaneously for all devices.
+
+In practice, E-states are defined as an array of maximum current
+consumption for each state and are identified by their offset into this
+array.  The states should be sorted in descending order (highest E-state
+appearing first).
+
+E0 for each client must be specified explicitly by providing its id
+while registering the client with a manager.  Rest of the E-states are
+determined according to their relative position to E0. For example, E-1
+is the state at e0_index - 1, E2 is the state at e0_index + 2 etc.
+
+5. EDP client registration
+
+An EDP client calls into the EDP manager (roughly once per boot) to
+register itself as a client. During registration, the EDP client
+provides its list of E-states to the System EDP manager. If a client
+attempts to register with an intolerably high E0 current (i.e. a current
+which pushes the sum of all E0 currents too high), the EDP manager will
+raise a fatal error.
+
+6. E-state request
+
+An EDP client calls into the EDP manager (issues an E-state request)
+BEFORE going to a higher E-state and AFTER going to a lower E-state. The
+EDP manager will:
+
+	[*] always approve requests to dgo to a lower E-state
+	[*] always approve requests to go to a non-negative E-state and
+	[*] either approve or reject a request to go to a higher
+	    negative E-state.
+
+When the EDP manager rejects an E-state request, it returns a lower
+E-state to the client. The client then transitions to that E-state
+without needing to make a new request.
+
+7. Throttling
+
+A client is said to being throttled when its manager demands it to
+transition to a lower E-state in order to meet requests from other
+clients. A client is never asked to transition beyond E0 which means
+that throttling is done only to those clients that are running at a
+negative E-state. The EDP manager blocks until the client finishes
+transitioning to the lower E-state.
+
+8. E-state callback
+
+A function pointer provided during EDP client registration to the EDP
+manager by each EDP client which supports negative E-states.  The EDP
+manager maintains a record of each driver's most recently requested
+E-state (including rejected requests).  When any EDP client requests a
+lowering of its E-state, the EDP manager may call one or more of the
+E-state callbacks to accept a previously rejected request.
+
+Additionally, the EDP manager will invoke the callback whenever a
+client is being throttled.
+
+Since the callbacks are synchronous, the total time for an E-state
+request that involve throttling is affected by the callback processing.
+Therefore, it is important to reschedule any non-critical time-consuming
+processing on a different context.
+
+9. EDP lender
+
+Some current consuming devices have side-band mechanisms which lets them
+share a current consumption budget.  An EDP lender is an EDP client
+driver:
+
+	[*] whose device typically draws current less than some
+	    (dynamically varying) threshold
+	[*] whose occasionally draws more than its threshold but less
+	    than allowed by its current E-state
+	[*] which asserts (or whose device asserts) a side-band signal
+	    prior to exceeding the threshold
+
+10. EDP loan
+
+An EDP loan is a contract allowing an EDP borrower to borrow current
+consumption budget according to the difference between an EDP lender's
+E-state and its threshold when the side-band is deasserted.
+
+11. EDP borrower
+
+An EDP borrower is an EDP client driver which:
+
+	[*] gets its base current consumption budget by setting an
+	    E-state with the EDP manager
+	[*] enters into an EDP loan with an EDP lender
+	[*] borrows from the EDP lender's borrows additional current
+	    budget according to the difference between an EDP lender's
+	    E-state and its threshold when the side-band is deasserted.
+	[*] stops borrowing from the EDP lender's budget whenever the
+	    side-band is asserted
+
+12. EDP loan API
+
+An EDP lender and an EDP borrower register their loan with the EDP
+manager via the EDP loan API. Additionally the EDP lender manages its
+threshold via the EDP loan API. The EDP manager informs the borrower
+whenever the loan size changes (due to a change in the lender's E-state
+or threshold).
+
+For example, a modem's peak transmit state might require E0 but its
+typical transmit state requires only E2. The modem driver can loan the
+difference between typical and peak to the CPU as long as the CPU stops
+borrowing when it is told to do so (the loan size becomes 0).
+
+13. Policies
+
+Policies decide how to allocate the available power budget to clients.
+These are implemented by corresponding governors and is explained in a
+separate document.
diff --git a/Documentation/edp/dynamic-edp-capping b/Documentation/edp/dynamic-edp-capping
new file mode 100644
index 000000000000..091d4122ecaa
--- /dev/null
+++ b/Documentation/edp/dynamic-edp-capping
@@ -0,0 +1,36 @@
+
+DYNAMIC EDP CAPPING IN GENERAL
+
+The goal of dynamic EDP capping is to maximize performance of a system
+without violating the peak-current capacity of that system's power
+source.
+
+Dynamic EDP Capping makes sense in systems with:
+	[*] a power source of finite peak-current capacity
+	[*] one or more controllable variables which have a known
+	    effect on peak current consumption from the power source.
+	[*] One or more variables whose changes are:
+		- observable in	advance and
+		- which have a known effect on peak current consumption
+		  from the power source
+
+In a system with only one controllable variable, the control algorithm
+is extremely simple. When the observables change, the algorithm solves
+for the maximum permissible current associated with the controllable and
+then limits the controllable as necessary to keep its current under that
+limit.
+
+In a system with more than one controllables, the control algorithm
+needs to worry about a strategy which controls the sum of their current
+while maximizing performance. There may or may not be a provably correct
+algorithm for that. If not, the EDP capping needs to fall back on a
+heuristic-based policy for choosing how to spread the pain among the
+controllables.
+
+In practice, the selection of controllables and observables is
+debatable. The simpler the set, the lower the software &
+characterization overhead. However, the simpler the set, the less
+accuracy that the observables+controllables provide in estimating the
+peak current. The larger the worst-case estimation error, the more
+performance must be sacrificed from the controllables in order to avoid
+violating the power sources peak-current capacity.
diff --git a/Documentation/edp/governors b/Documentation/edp/governors
new file mode 100644
index 000000000000..7639bca1faa0
--- /dev/null
+++ b/Documentation/edp/governors
@@ -0,0 +1,38 @@
+
+EDP GOVERNORS
+
+1. Introduction
+
+EDP governors implements the policy for current budget allocation amoung
+clients. In general, the governor decides budget allocation in the
+following situations:
+
+	[*] When a client makes an E-state request. If the request can
+	    not be met with the remaining current, other clients may be
+	    throttled to recover extra current which can then be granted
+	    to the requester. If the request is unfarely high, a reduced
+	    E-state has to be decided according to the policy.
+
+	[*] When there is an increase in the manager's remaining cap,
+	    the governor will try to distribute the surplus amoung
+	    clients whose requests were previously rejected or who were
+	    throttled during the above step.
+
+	[] When a client has more than one borrower, the loan has to be
+	   distributed.
+
+Following sections provides a short description about available
+governors.
+
+2. Priority
+
+As the name indicates, this governor implements a priority based
+allocation in which higher priority clients are given preference. When a
+budget recovery takes place, lower priority clients are throttled before
+the higher priority ones. Similarly, during a promotion cycle or during
+a loan update, higher priority clients are served first.
+
+If the request can not be satisfied by throttling lower priority
+clients, the requested E-state may be lowered at most to E0. This
+ensures that higher priority clients are throttled only to provide
+minimum guarantee E-state.
diff --git a/Documentation/edp/howto b/Documentation/edp/howto
new file mode 100644
index 000000000000..da8384894558
--- /dev/null
+++ b/Documentation/edp/howto
@@ -0,0 +1,197 @@
+
+EDP API GUIDE
+
+1. Introduction
+
+This document explains how to setup an EDP framework for a system. It is
+assumed that you have read 'dynamic-edp-capping' and 'design' before
+getting here.
+
+2. Config flags
+
+EDP framework implementation depends on the CONFIG_EDP_FRAMEWORK flag.
+When this is disabled, all the APIs either return an error code or does
+nothing.
+
+3. Include files
+
+#include <linux/edp.h>
+
+4. EDP manager
+
+The manager represents the current source with its limited capacity that
+needs to be budgetted across various client drivers. A typical example
+is the battery. As this is the basic building block of the framework, it
+is necessary to create and register the manager object before the
+clients can make any request. Following is an example:
+
+	#include <linux/edp.h>
+
+	/* Define the battery EDP manager - imax indicates the cap */
+	struct edp_manager battery_edp_manager = {
+		.name = "battery",
+		.imax = 9800
+	};
+
+	...
+
+	/* Register the battery EDP manager */
+	static int __init board_init(void)
+	{
+		return edp_register_manager(&battery_edp_manager);
+	}
+	early_initcall(board_init);
+
+5. EDP client
+
+A client needs to be registered before it can make requests. Following
+examples show how the usual operations are performed.
+
+	Example 1:
+
+	/* E-state ids */
+	#define CPU_EDP_MAX	0
+	#define CPU_EDP_HIGH	1
+	#define CPU_EDP_NORMAL	2
+	#define CPU_EDP_LOW	3
+	#define CPU_EDP_MIN	4
+
+	/* E-state array */
+	static unsigned int cpu_edp_states[] = {
+		7500, 6000, 3000, 2000, 1000
+	};
+
+	/* throttle callback function */
+	static void throttle_cpu(unsigned int new_state)
+	{
+		/* lower the operating point */
+		...
+	}
+
+	/*
+	 * promotion call back - a previously rejected request is now
+	 * granted
+	 */
+	static void promote_cpu(unsigned int new_state)
+	{
+		/* increase the operating point */
+		...
+	}
+
+	/* loan size changed */
+	static unsigned int update_cpu_loan(unsigned int new_size,
+			struct edp_client *)
+	{
+		/* increase the operating point */
+		...
+
+		/* return the amount of loan consumed */
+		return new_size;
+	}
+
+	/* cpu client: see the include header for more info */
+	struct edp_client cpu_edp_client = {
+		.name = "cpu",
+		.states = cpu_edp_states,
+		.num_states = ARRAY_SIZE(cpu_edp_states),
+		.e0_index = CPU_EDP_NORMAL,
+		.priority = EDP_MIN_PRIO,
+		.throttle = throttle_cpu,
+		.notify_promotion = promote_cpu,
+		.notify_loan_update = update_cpu_loan
+	};
+
+	...
+
+	static int __init platform_cpu_dvfs_init(void)
+	{
+		...
+
+		/* register the EDP client */
+		if (edp_register_client(&battery_edp_manager,
+				&cpu_edp_client))
+			/* fatal error! */
+
+		/* request E0 - must succeed */
+		err = edp_update_client_request(&cpu_edp_client,
+				CPU_EDP_NORMAL, NULL);
+
+		/* get the modem client pointer */
+		modem_client = edp_get_client("modem");
+
+		/* borrow from modem */
+		err = edp_register_loan(modem, &cpu_edp_client);
+
+		...
+	}
+
+	static int cpu_target(struct cpufreq_policy *policy,
+			unsigned int target_freq,
+			unsigned int relation)
+	{
+		unsigned int req;
+		unsigned int approved;
+
+		...
+
+		/* Calculate E-state id for target_freq */
+		req = to_estateid(target_freq);
+		err = edp_update_client_request(&cpu_edp_client, req,
+				&approved);
+
+		if (approved != req)
+			/* got a lower E-state granted */
+
+		...
+	}
+
+	Example 2:
+
+	/* modem client */
+	struct edp_client modem_edp_client = {
+		.name = "modem",
+		.states = { 2500, 1500, 1000, 500, 0 },
+		.e0_index = MODEM_EDP_E0,
+		.priority = EDP_MAX_PRIO - 3,
+		.max_borrowers = 1,
+		...
+	};
+
+	static int __init modem_edp_init(void)
+	{
+		...
+
+		/* get the manager */
+		battery_manager = edp_get_manager("battery");
+		if (!battery)
+			/* fatal error! */
+
+		err = edp_register_client(battery_manager,
+			&modem_edp_client);
+
+		...
+	}
+
+	static void update_modem_state(int state)
+	{
+		...
+
+		if (state == MODEM_RELAX) {
+			...
+
+			/* calc loan threshold */
+			threshold = ...
+			err = edp_update_loan_threshold(
+					&modem_edp_client, threshold);
+			...
+		} else if (state == MODEM_RUNNING) {
+			err = edp_update_client_request(
+					&modem_edp_client,
+					MODEM_EDP_E2H, &approved);
+
+			/* freeze the loan */
+			err = edp_update_loan_threshold(
+					&modem_edp_client, 0);
+			...
+		}
+	}
diff --git a/Documentation/edp/sysfs b/Documentation/edp/sysfs
new file mode 100644
index 000000000000..4927086ba2ff
--- /dev/null
+++ b/Documentation/edp/sysfs
@@ -0,0 +1,41 @@
+
+EDP SYSFS
+
+1. Introduction
+
+EDP sysfs root is at /sys/power/edp. Manager and client objects appear
+as subfolders under the root forming a tree structure where clients
+appear under the managers to whom they are registered.
+
+Following sections describe the sysfs attributes. Unless explicitly
+mentioned, all files are read-only.
+
+2. EDP root level attributes
+
+	[1] governors: shows the name of available EDP policy governors.
+
+3. EDP manager
+
+Manager entries appear under the EDP root folder as subfolder with the
+same name. It contains the following attributes:
+
+	[1] cap: peak current capacity
+	[2] remaining: remaining current
+	[3] governor: current policy governor - writting to this will
+	    change the governor
+
+4. EDP clients
+
+Client objects appear under their manager folders as subfolder with the
+client name. Attributes:
+
+	[1] states: E-state values
+	[2] num_states: number of E-states
+	[3] E0: E0 state value
+	[4] max_borrowers: maximum number of borrowers allowed
+	[5] priority: client's priority
+	[6] request: current request value
+	[7] current: current state's value
+	[8] threshold: loan threshold
+	[9] borrowers: number of borrowers
+	[10] number of loans.