diff options
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/edp/design | 147 | ||||
| -rw-r--r-- | Documentation/edp/dynamic-edp-capping | 36 | ||||
| -rw-r--r-- | Documentation/edp/governors | 38 | ||||
| -rw-r--r-- | Documentation/edp/howto | 197 | ||||
| -rw-r--r-- | Documentation/edp/sysfs | 41 |
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. |