arm: tegra: tegratab: Set PULL_DOWN for KB_COL4
[linux-2.6.git] / Documentation / edp / design
1
2 SYSTEM EDP CAPPING DESIGN
3
4 1. Introduction
5
6 This document uses a glossary of terms to explain the design of System
7 EDP capping.
8
9 2. System EDP manager
10
11 The central piece of software which dynamically allocates
12 current-sourcing capacity to EDP client drivers for use by their
13 devices. A system may have more than one manager. Managers are
14 distinguished by their unique names.
15
16 3. EDP client driver
17
18 The device driver associated with one particular power consuming device.
19 EDP client drivers register with the System EDP manager to monitor and
20 manage the current consumption of their associated device. A client can
21 be registered with only one manager at any given time.
22
23 4. E-state
24
25 Electrical states which are defined per EDP client and numbered {...
26 E-2, E-1, E0, E1, E2...}.  Each E-state for a given driver indicates a
27 particular maximum current consumption.
28
29         [*] Higher E-state: an E-state closer to E-infinity. E-1 is
30             higher than E0, E1 is higher than E2 etc.
31         [*] Lower E-state: an E-state closer to Einfinity. E-1 is lower
32             than E-2, E1 is lower than E0 etc.
33         [*] Positive E-states: E0, E1, E2...
34         [*] Negative E-state: ...E-3, E-2, E-1.
35         [*] E0: the system EDP manager guarantees that it can provide
36             E0 simultaneously for all devices.
37
38 In practice, E-states are defined as an array of maximum current
39 consumption for each state and are identified by their offset into this
40 array.  The states should be sorted in descending order (highest E-state
41 appearing first).
42
43 E0 for each client must be specified explicitly by providing its id
44 while registering the client with a manager.  Rest of the E-states are
45 determined according to their relative position to E0. For example, E-1
46 is the state at e0_index - 1, E2 is the state at e0_index + 2 etc.
47
48 5. EDP client registration
49
50 An EDP client calls into the EDP manager (roughly once per boot) to
51 register itself as a client. During registration, the EDP client
52 provides its list of E-states to the System EDP manager. If a client
53 attempts to register with an intolerably high E0 current (i.e. a current
54 which pushes the sum of all E0 currents too high), the EDP manager will
55 raise a fatal error.
56
57 6. E-state request
58
59 An EDP client calls into the EDP manager (issues an E-state request)
60 BEFORE going to a higher E-state and AFTER going to a lower E-state. The
61 EDP manager will:
62
63         [*] always approve requests to dgo to a lower E-state
64         [*] always approve requests to go to a non-negative E-state and
65         [*] either approve or reject a request to go to a higher
66             negative E-state.
67
68 When the EDP manager rejects an E-state request, it returns a lower
69 E-state to the client. The client then transitions to that E-state
70 without needing to make a new request.
71
72 7. Throttling
73
74 A client is said to being throttled when its manager demands it to
75 transition to a lower E-state in order to meet requests from other
76 clients. A client is never asked to transition beyond E0 which means
77 that throttling is done only to those clients that are running at a
78 negative E-state. The EDP manager blocks until the client finishes
79 transitioning to the lower E-state.
80
81 8. Callbacks
82
83 An EDP client may provide the following callbacks which are invoked by
84 the manager at various stages.
85
86         [*] throttle: invoked when the client is being throttled;
87             mandatory for those clients that support negative E-states
88         [*] promotion notification (optional): to inform the client
89             that a previously rejected request is granted now.
90         [*] loan update notification: to inform the client that a loan
91             amount is changed; mandatory for clients that are engaged
92             in a loan agreement.
93         [*] loan closure: to inform the client that a loan is now
94             closed; mandatory for clients that are engaged in a loan
95             agreement.
96
97 All callbacks are synchronous which means that the total time for an
98 operation is affected by client processing. Therefore, it is important
99 to reschedule any non-critical time consuming steps on a different
100 context.
101
102 IMPORTANT: Callbacks are invoked by the EDP manager while holding its
103 lock.  Thefore, clients should never call into the EDP framework from
104 the callback path. Not doing so shall result in a deadlock.
105
106 9. EDP lender
107
108 Some current consuming devices have side-band mechanisms which lets them
109 share a current consumption budget.  An EDP lender is an EDP client
110 driver:
111
112         [*] whose device typically draws current less than some
113             (dynamically varying) threshold
114         [*] whose occasionally draws more than its threshold but less
115             than allowed by its current E-state
116         [*] which asserts (or whose device asserts) a side-band signal
117             prior to exceeding the threshold
118
119 10. EDP loan
120
121 An EDP loan is a contract allowing an EDP borrower to borrow current
122 consumption budget according to the difference between an EDP lender's
123 E-state and its threshold when the side-band is deasserted.
124
125 11. EDP borrower
126
127 An EDP borrower is an EDP client driver which:
128
129         [*] gets its base current consumption budget by setting an
130             E-state with the EDP manager
131         [*] enters into an EDP loan with an EDP lender
132         [*] borrows from the EDP lender's borrows additional current
133             budget according to the difference between an EDP lender's
134             E-state and its threshold when the side-band is deasserted.
135         [*] stops borrowing from the EDP lender's budget whenever the
136             side-band is asserted
137
138 12. EDP loan API
139
140 An EDP lender and an EDP borrower register their loan with the EDP
141 manager via the EDP loan API. Additionally the EDP lender manages its
142 threshold via the EDP loan API. The EDP manager informs the borrower
143 whenever the loan size changes (due to a change in the lender's E-state
144 or threshold).
145
146 For example, a modem's peak transmit state might require E0 but its
147 typical transmit state requires only E2. The modem driver can loan the
148 difference between typical and peak to the CPU as long as the CPU stops
149 borrowing when it is told to do so (the loan size becomes 0).
150
151 13. Policies
152
153 Policies decide how to allocate the available power budget to clients.
154 These are implemented by corresponding governors and is explained in a
155 separate document.