xref: /freebsd/sys/dev/bhnd/cores/pmu/bhnd_pmu_if.m (revision dad64f0e) 
1#-
2# Copyright (c) 2016 Landon Fuller <landon@landonf.org>
3# Copyright (c) 2017 The FreeBSD Foundation
4# All rights reserved.
5#
6# Portions of this software were developed by Landon Fuller
7# under sponsorship from the FreeBSD Foundation.
8#
9# Redistribution and use in source and binary forms, with or without
10# modification, are permitted provided that the following conditions
11# are met:
12# 1. Redistributions of source code must retain the above copyright
13#    notice, this list of conditions and the following disclaimer.
14# 2. Redistributions in binary form must reproduce the above copyright
15#    notice, this list of conditions and the following disclaimer in the
16#    documentation and/or other materials provided with the distribution.
17#
18# THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
19# IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
20# OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
21# IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
22# INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
23# (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
24# SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
25# CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
26# OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
27# USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
28#
29# $FreeBSD$
30
31#include <sys/types.h>
32#include <sys/bus.h>
33
34#include <dev/bhnd/bhnd.h>
35
36INTERFACE bhnd_pmu;
37
38#
39# bhnd(4) PMU interface.
40#
41# Provides an interface to the PMU hardware found on modern bhnd(4) chipsets.
42#
43
44HEADER {
45	#include <dev/bhnd/cores/pmu/bhnd_pmu_types.h>
46
47	struct bhnd_core_pmu_info;
48}
49
50CODE {
51
52	static uint32_t
53	bhnd_pmu_null_read_chipctrl(device_t dev, uint32_t reg)
54	{
55		panic("bhnd_pmu_read_chipctrl unimplemented");
56	}
57
58	static void
59	bhnd_pmu_null_write_chipctrl(device_t dev, uint32_t reg, uint32_t value,
60	uint32_t mask)
61	{
62		panic("bhnd_pmu_write_chipctrl unimplemented");
63	}
64
65	static uint32_t
66	bhnd_pmu_null_read_regctrl(device_t dev, uint32_t reg)
67	{
68		panic("bhnd_pmu_read_regctrl unimplemented");
69	}
70
71	static void
72	bhnd_pmu_null_write_regctrl(device_t dev, uint32_t reg, uint32_t value,
73	uint32_t mask)
74	{
75		panic("bhnd_pmu_write_regctrl unimplemented");
76	}
77
78	static uint32_t
79	bhnd_pmu_null_read_pllctrl(device_t dev, uint32_t reg)
80	{
81		panic("bhnd_pmu_read_pllctrl unimplemented");
82	}
83
84	static void
85	bhnd_pmu_null_write_pllctrl(device_t dev, uint32_t reg, uint32_t value,
86	uint32_t mask)
87	{
88		panic("bhnd_pmu_write_pllctrl unimplemented");
89	}
90
91	static int
92	bhnd_pmu_null_request_spuravoid(device_t dev,
93	    bhnd_pmu_spuravoid spuravoid)
94	{
95		panic("bhnd_pmu_request_spuravoid unimplemented");
96	}
97
98	static int
99	bhnd_pmu_null_set_voltage_raw(device_t dev,
100	    bhnd_pmu_regulator regulator, uint32_t value)
101	{
102		panic("bhnd_pmu_set_voltage_raw unimplemented");
103	}
104
105	static int
106	bhnd_pmu_null_enable_regulator(device_t dev,
107	    bhnd_pmu_regulator regulator)
108	{
109		panic("bhnd_pmu_enable_regulator unimplemented");
110	}
111
112	static int
113	bhnd_pmu_null_disable_regulator(device_t dev,
114	    bhnd_pmu_regulator regulator)
115	{
116		panic("bhnd_pmu_disable_regulator unimplemented");
117	}
118
119	static int
120	bhnd_pmu_null_get_clock_latency(device_t dev, bhnd_clock clock,
121	    u_int *latency)
122	{
123		panic("bhnd_pmu_get_clock_latency unimplemented");
124	}
125
126	static int
127	bhnd_pmu_null_get_clock_freq(device_t dev, bhnd_clock clock,
128	    u_int *freq)
129	{
130		panic("bhnd_pmu_get_clock_freq unimplemented");
131	}
132}
133
134/**
135 * Return the current value of a PMU chipctrl register.
136 *
137 * @param dev A bhnd(4) PMU device.
138 * @param reg The PMU chipctrl register to be read.
139 *
140 * Drivers should only use function for functionality that is not
141 * available via another bhnd_chipc() function.
142 *
143 * @returns The chipctrl register value, or 0 if undefined by this hardware.
144 */
145METHOD uint32_t read_chipctrl {
146	device_t dev;
147	uint32_t reg;
148} DEFAULT bhnd_pmu_null_read_chipctrl;
149
150/**
151 * Write @p value with @p mask to a PMU chipctrl register.
152 *
153 * @param dev	A bhnd(4) PMU device.
154 * @param reg	The PMU chipctrl register to be written.
155 * @param value	The value to write.
156 * @param mask	The mask of bits to be written from @p value.
157 *
158 * Drivers should only use function for functionality that is not
159 * available via another bhnd_pmu() function.
160 */
161METHOD void write_chipctrl {
162	device_t dev;
163	uint32_t reg;
164	uint32_t value;
165	uint32_t mask;
166} DEFAULT bhnd_pmu_null_write_chipctrl;
167
168/**
169 * Return the current value of a PMU regulator control register.
170 *
171 * @param dev A bhnd(4) PMU device.
172 * @param reg The PMU regctrl register to be read.
173 *
174 * Drivers should only use function for functionality that is not
175 * available via another bhnd_chipc() function.
176 *
177 * @returns The regctrl register value, or 0 if undefined by this hardware.
178 */
179METHOD uint32_t read_regctrl {
180	device_t dev;
181	uint32_t reg;
182} DEFAULT bhnd_pmu_null_read_regctrl;
183
184/**
185 * Write @p value with @p mask to a PMU regulator control register.
186 *
187 * @param dev	A bhnd(4) PMU device.
188 * @param reg	The PMU regctrl register to be written.
189 * @param value	The value to write.
190 * @param mask	The mask of bits to be written from @p value.
191 *
192 * Drivers should only use function for functionality that is not
193 * available via another bhnd_pmu() function.
194 */
195METHOD void write_regctrl {
196	device_t dev;
197	uint32_t reg;
198	uint32_t value;
199	uint32_t mask;
200} DEFAULT bhnd_pmu_null_write_regctrl;
201
202/**
203 * Return the current value of a PMU PLL control register.
204 *
205 * @param dev A bhnd(4) PMU device.
206 * @param reg The PMU pllctrl register to be read.
207 *
208 * Drivers should only use function for functionality that is not
209 * available via another bhnd_chipc() function.
210 *
211 * @returns The pllctrl register value, or 0 if undefined by this hardware.
212 */
213METHOD uint32_t read_pllctrl {
214	device_t dev;
215	uint32_t reg;
216} DEFAULT bhnd_pmu_null_read_pllctrl;
217
218/**
219 * Write @p value with @p mask to a PMU PLL control register.
220 *
221 * @param dev	A bhnd(4) PMU device.
222 * @param reg	The PMU pllctrl register to be written.
223 * @param value	The value to write.
224 * @param mask	The mask of bits to be written from @p value.
225 *
226 * Drivers should only use function for functionality that is not
227 * available via another bhnd_pmu() function.
228 */
229METHOD void write_pllctrl {
230	device_t dev;
231	uint32_t reg;
232	uint32_t value;
233	uint32_t mask;
234} DEFAULT bhnd_pmu_null_write_pllctrl;
235
236/**
237 * Set a hardware-specific output voltage register value for @p regulator.
238 *
239 * @param dev		PMU device.
240 * @param regulator	Regulator to be configured.
241 * @param value		The raw voltage register value.
242 *
243 * @retval 0		success
244 * @retval ENODEV	If @p regulator is not supported by this driver.
245 */
246METHOD int set_voltage_raw {
247	 device_t		dev;
248	 bhnd_pmu_regulator	regulator;
249	 uint32_t		value;
250} DEFAULT bhnd_pmu_null_set_voltage_raw;
251
252/**
253 * Enable the given @p regulator.
254 *
255 * @param dev		PMU device.
256 * @param regulator	Regulator to be enabled.
257 *
258 * @retval 0		success
259 * @retval ENODEV	If @p regulator is not supported by this driver.
260 */
261METHOD int enable_regulator {
262	device_t		dev;
263	bhnd_pmu_regulator	regulator;
264} DEFAULT bhnd_pmu_null_enable_regulator;
265
266/**
267 * Disable the given @p regulator.
268 *
269 * @param dev		PMU device.
270 * @param regulator	Regulator to be disabled.
271 *
272 * @retval 0		success
273 * @retval ENODEV	If @p regulator is not supported by this driver.
274 */
275METHOD int disable_regulator {
276	device_t		dev;
277	bhnd_pmu_regulator	regulator;
278} DEFAULT bhnd_pmu_null_disable_regulator;
279
280/**
281 * Return the transition latency required for @p clock in microseconds, if
282 * known.
283 *
284 * The BHND_CLOCK_HT latency value is suitable for use as the D11 core's
285 * 'fastpwrup_dly' value.
286 *
287 * @param	dev	PMU device.
288 * @param	clock	The clock to be queried for transition latency.
289 * @param[out]	latency	On success, the transition latency of @p clock in
290 *			microseconds.
291 *
292 * @retval 0		success
293 * @retval ENODEV	If the transition latency for @p clock is not available.
294 */
295METHOD int get_clock_latency {
296	device_t	 dev;
297	bhnd_clock	 clock;
298	u_int		*latency;
299} DEFAULT bhnd_pmu_null_get_clock_latency;
300
301/**
302 * Return the frequency for @p clock in Hz, if known.
303 *
304 * @param	dev	PMU device.
305 * @param	clock	The clock to be queried.
306 * @param[out]	freq	On success, the frequency of @p clock in Hz.
307 *
308 * @retval 0		success
309 * @retval ENODEV	If the frequency for @p clock is not available.
310 */
311METHOD int get_clock_freq {
312	device_t	 dev;
313	bhnd_clock	 clock;
314	u_int		*freq;
315} DEFAULT bhnd_pmu_null_get_clock_freq;
316
317/**
318 * Request that the PMU configure itself for a given hardware-specific
319 * spuravoid mode.
320 *
321 * @param dev		PMU device.
322 * @param spuravoid	The requested mode.
323 *
324 * @retval 0		success
325 * @retval ENODEV	If @p regulator is not supported by this driver.
326 */
327METHOD int request_spuravoid {
328	 device_t		dev;
329	 bhnd_pmu_spuravoid	spuravoid;
330} DEFAULT bhnd_pmu_null_request_spuravoid;
331
332/**
333 * Return the PMU's maximum state transition latency in microseconds.
334 *
335 * This upper bound may be used to busy-wait on PMU clock and resource state
336 * transitions.
337 *
338 * @param dev PMU device.
339 *
340 * @returns maximum PMU transition latency, in microseconds.
341 */
342METHOD u_int get_max_transition_latency {
343	device_t dev;
344};
345