About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / power / regulator / consumer.txt




Custom Search

Based on kernel version 3.16. Page generated on 2014-08-06 21:40 EST.

1	Regulator Consumer Driver Interface
2	===================================
3	
4	This text describes the regulator interface for consumer device drivers.
5	Please see overview.txt for a description of the terms used in this text.
6	
7	
8	1. Consumer Regulator Access (static & dynamic drivers)
9	=======================================================
10	
11	A consumer driver can get access to its supply regulator by calling :-
12	
13	regulator = regulator_get(dev, "Vcc");
14	
15	The consumer passes in its struct device pointer and power supply ID. The core
16	then finds the correct regulator by consulting a machine specific lookup table.
17	If the lookup is successful then this call will return a pointer to the struct
18	regulator that supplies this consumer.
19	
20	To release the regulator the consumer driver should call :-
21	
22	regulator_put(regulator);
23	
24	Consumers can be supplied by more than one regulator e.g. codec consumer with
25	analog and digital supplies :-
26	
27	digital = regulator_get(dev, "Vcc");  /* digital core */
28	analog = regulator_get(dev, "Avdd");  /* analog */
29	
30	The regulator access functions regulator_get() and regulator_put() will
31	usually be called in your device drivers probe() and remove() respectively.
32	
33	
34	2. Regulator Output Enable & Disable (static & dynamic drivers)
35	====================================================================
36	
37	A consumer can enable its power supply by calling:-
38	
39	int regulator_enable(regulator);
40	
41	NOTE: The supply may already be enabled before regulator_enabled() is called.
42	This may happen if the consumer shares the regulator or the regulator has been
43	previously enabled by bootloader or kernel board initialization code.
44	
45	A consumer can determine if a regulator is enabled by calling :-
46	
47	int regulator_is_enabled(regulator);
48	
49	This will return > zero when the regulator is enabled.
50	
51	
52	A consumer can disable its supply when no longer needed by calling :-
53	
54	int regulator_disable(regulator);
55	
56	NOTE: This may not disable the supply if it's shared with other consumers. The
57	regulator will only be disabled when the enabled reference count is zero.
58	
59	Finally, a regulator can be forcefully disabled in the case of an emergency :-
60	
61	int regulator_force_disable(regulator);
62	
63	NOTE: this will immediately and forcefully shutdown the regulator output. All
64	consumers will be powered off.
65	
66	
67	3. Regulator Voltage Control & Status (dynamic drivers)
68	======================================================
69	
70	Some consumer drivers need to be able to dynamically change their supply
71	voltage to match system operating points. e.g. CPUfreq drivers can scale
72	voltage along with frequency to save power, SD drivers may need to select the
73	correct card voltage, etc.
74	
75	Consumers can control their supply voltage by calling :-
76	
77	int regulator_set_voltage(regulator, min_uV, max_uV);
78	
79	Where min_uV and max_uV are the minimum and maximum acceptable voltages in
80	microvolts.
81	
82	NOTE: this can be called when the regulator is enabled or disabled. If called
83	when enabled, then the voltage changes instantly, otherwise the voltage
84	configuration changes and the voltage is physically set when the regulator is
85	next enabled.
86	
87	The regulators configured voltage output can be found by calling :-
88	
89	int regulator_get_voltage(regulator);
90	
91	NOTE: get_voltage() will return the configured output voltage whether the
92	regulator is enabled or disabled and should NOT be used to determine regulator
93	output state. However this can be used in conjunction with is_enabled() to
94	determine the regulator physical output voltage.
95	
96	
97	4. Regulator Current Limit Control & Status (dynamic drivers)
98	===========================================================
99	
100	Some consumer drivers need to be able to dynamically change their supply
101	current limit to match system operating points. e.g. LCD backlight driver can
102	change the current limit to vary the backlight brightness, USB drivers may want
103	to set the limit to 500mA when supplying power.
104	
105	Consumers can control their supply current limit by calling :-
106	
107	int regulator_set_current_limit(regulator, min_uA, max_uA);
108	
109	Where min_uA and max_uA are the minimum and maximum acceptable current limit in
110	microamps.
111	
112	NOTE: this can be called when the regulator is enabled or disabled. If called
113	when enabled, then the current limit changes instantly, otherwise the current
114	limit configuration changes and the current limit is physically set when the
115	regulator is next enabled.
116	
117	A regulators current limit can be found by calling :-
118	
119	int regulator_get_current_limit(regulator);
120	
121	NOTE: get_current_limit() will return the current limit whether the regulator
122	is enabled or disabled and should not be used to determine regulator current
123	load.
124	
125	
126	5. Regulator Operating Mode Control & Status (dynamic drivers)
127	=============================================================
128	
129	Some consumers can further save system power by changing the operating mode of
130	their supply regulator to be more efficient when the consumers operating state
131	changes. e.g. consumer driver is idle and subsequently draws less current
132	
133	Regulator operating mode can be changed indirectly or directly.
134	
135	Indirect operating mode control.
136	--------------------------------
137	Consumer drivers can request a change in their supply regulator operating mode
138	by calling :-
139	
140	int regulator_set_optimum_mode(struct regulator *regulator, int load_uA);
141	
142	This will cause the core to recalculate the total load on the regulator (based
143	on all its consumers) and change operating mode (if necessary and permitted)
144	to best match the current operating load.
145	
146	The load_uA value can be determined from the consumers datasheet. e.g.most
147	datasheets have tables showing the max current consumed in certain situations.
148	
149	Most consumers will use indirect operating mode control since they have no
150	knowledge of the regulator or whether the regulator is shared with other
151	consumers.
152	
153	Direct operating mode control.
154	------------------------------
155	Bespoke or tightly coupled drivers may want to directly control regulator
156	operating mode depending on their operating point. This can be achieved by
157	calling :-
158	
159	int regulator_set_mode(struct regulator *regulator, unsigned int mode);
160	unsigned int regulator_get_mode(struct regulator *regulator);
161	
162	Direct mode will only be used by consumers that *know* about the regulator and
163	are not sharing the regulator with other consumers.
164	
165	
166	6. Regulator Events
167	===================
168	Regulators can notify consumers of external events. Events could be received by
169	consumers under regulator stress or failure conditions.
170	
171	Consumers can register interest in regulator events by calling :-
172	
173	int regulator_register_notifier(struct regulator *regulator,
174				      struct notifier_block *nb);
175	
176	Consumers can uregister interest by calling :-
177	
178	int regulator_unregister_notifier(struct regulator *regulator,
179					struct notifier_block *nb);
180	
181	Regulators use the kernel notifier framework to send event to their interested
182	consumers.
Hide Line Numbers
About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.