xref: /freebsd/sys/dev/bhnd/cores/pmu/bhnd_pmu_if.m (revision d0b2dbfa) 
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
30#include <sys/types.h>
31#include <sys/bus.h>
32
33#include <dev/bhnd/bhnd.h>
34
35INTERFACE bhnd_pmu;
36
37#
38# bhnd(4) PMU interface.
39#
40# Provides an interface to the PMU hardware found on modern bhnd(4) chipsets.
41#
42
43HEADER {
44	#include <dev/bhnd/cores/pmu/bhnd_pmu_types.h>
45
46	struct bhnd_core_pmu_info;
47}
48
49CODE {
50
51	static uint32_t
52	bhnd_pmu_null_read_chipctrl(device_t dev, uint32_t reg)
53	{
54		panic("bhnd_pmu_read_chipctrl unimplemented");
55	}
56
57	static void
58	bhnd_pmu_null_write_chipctrl(device_t dev, uint32_t reg, uint32_t value,
59	uint32_t mask)
60	{
61		panic("bhnd_pmu_write_chipctrl unimplemented");
62	}
63
64	static uint32_t
65	bhnd_pmu_null_read_regctrl(device_t dev, uint32_t reg)
66	{
67		panic("bhnd_pmu_read_regctrl unimplemented");
68	}
69
70	static void
71	bhnd_pmu_null_write_regctrl(device_t dev, uint32_t reg, uint32_t value,
72	uint32_t mask)
73	{
74		panic("bhnd_pmu_write_regctrl unimplemented");
75	}
76
77	static uint32_t
78	bhnd_pmu_null_read_pllctrl(device_t dev, uint32_t reg)
79	{
80		panic("bhnd_pmu_read_pllctrl unimplemented");
81	}
82
83	static void
84	bhnd_pmu_null_write_pllctrl(device_t dev, uint32_t reg, uint32_t value,
85	uint32_t mask)
86	{
87		panic("bhnd_pmu_write_pllctrl unimplemented");
88	}
89
90	static int
91	bhnd_pmu_null_request_spuravoid(device_t dev,
92	    bhnd_pmu_spuravoid spuravoid)
93	{
94		panic("bhnd_pmu_request_spuravoid unimplemented");
95	}
96
97	static int
98	bhnd_pmu_null_set_voltage_raw(device_t dev,
99	    bhnd_pmu_regulator regulator, uint32_t value)
100	{
101		panic("bhnd_pmu_set_voltage_raw unimplemented");
102	}
103
104	static int
105	bhnd_pmu_null_enable_regulator(device_t dev,
106	    bhnd_pmu_regulator regulator)
107	{
108		panic("bhnd_pmu_enable_regulator unimplemented");
109	}
110
111	static int
112	bhnd_pmu_null_disable_regulator(device_t dev,
113	    bhnd_pmu_regulator regulator)
114	{
115		panic("bhnd_pmu_disable_regulator unimplemented");
116	}
117
118	static int
119	bhnd_pmu_null_get_clock_latency(device_t dev, bhnd_clock clock,
120	    u_int *latency)
121	{
122		panic("bhnd_pmu_get_clock_latency unimplemented");
123	}
124
125	static int
126	bhnd_pmu_null_get_clock_freq(device_t dev, bhnd_clock clock,
127	    u_int *freq)
128	{
129		panic("bhnd_pmu_get_clock_freq unimplemented");
130	}
131}
132
133/**
134 * Return the current value of a PMU chipctrl register.
135 *
136 * @param dev A bhnd(4) PMU device.
137 * @param reg The PMU chipctrl register to be read.
138 *
139 * Drivers should only use function for functionality that is not
140 * available via another bhnd_chipc() function.
141 *
142 * @returns The chipctrl register value, or 0 if undefined by this hardware.
143 */
144METHOD uint32_t read_chipctrl {
145	device_t dev;
146	uint32_t reg;
147} DEFAULT bhnd_pmu_null_read_chipctrl;
148
149/**
150 * Write @p value with @p mask to a PMU chipctrl register.
151 *
152 * @param dev	A bhnd(4) PMU device.
153 * @param reg	The PMU chipctrl register to be written.
154 * @param value	The value to write.
155 * @param mask	The mask of bits to be written from @p value.
156 *
157 * Drivers should only use function for functionality that is not
158 * available via another bhnd_pmu() function.
159 */
160METHOD void write_chipctrl {
161	device_t dev;
162	uint32_t reg;
163	uint32_t value;
164	uint32_t mask;
165} DEFAULT bhnd_pmu_null_write_chipctrl;
166
167/**
168 * Return the current value of a PMU regulator control register.
169 *
170 * @param dev A bhnd(4) PMU device.
171 * @param reg The PMU regctrl register to be read.
172 *
173 * Drivers should only use function for functionality that is not
174 * available via another bhnd_chipc() function.
175 *
176 * @returns The regctrl register value, or 0 if undefined by this hardware.
177 */
178METHOD uint32_t read_regctrl {
179	device_t dev;
180	uint32_t reg;
181} DEFAULT bhnd_pmu_null_read_regctrl;
182
183/**
184 * Write @p value with @p mask to a PMU regulator control register.
185 *
186 * @param dev	A bhnd(4) PMU device.
187 * @param reg	The PMU regctrl register to be written.
188 * @param value	The value to write.
189 * @param mask	The mask of bits to be written from @p value.
190 *
191 * Drivers should only use function for functionality that is not
192 * available via another bhnd_pmu() function.
193 */
194METHOD void write_regctrl {
195	device_t dev;
196	uint32_t reg;
197	uint32_t value;
198	uint32_t mask;
199} DEFAULT bhnd_pmu_null_write_regctrl;
200
201/**
202 * Return the current value of a PMU PLL control register.
203 *
204 * @param dev A bhnd(4) PMU device.
205 * @param reg The PMU pllctrl register to be read.
206 *
207 * Drivers should only use function for functionality that is not
208 * available via another bhnd_chipc() function.
209 *
210 * @returns The pllctrl register value, or 0 if undefined by this hardware.
211 */
212METHOD uint32_t read_pllctrl {
213	device_t dev;
214	uint32_t reg;
215} DEFAULT bhnd_pmu_null_read_pllctrl;
216
217/**
218 * Write @p value with @p mask to a PMU PLL control register.
219 *
220 * @param dev	A bhnd(4) PMU device.
221 * @param reg	The PMU pllctrl register to be written.
222 * @param value	The value to write.
223 * @param mask	The mask of bits to be written from @p value.
224 *
225 * Drivers should only use function for functionality that is not
226 * available via another bhnd_pmu() function.
227 */
228METHOD void write_pllctrl {
229	device_t dev;
230	uint32_t reg;
231	uint32_t value;
232	uint32_t mask;
233} DEFAULT bhnd_pmu_null_write_pllctrl;
234
235/**
236 * Set a hardware-specific output voltage register value for @p regulator.
237 *
238 * @param dev		PMU device.
239 * @param regulator	Regulator to be configured.
240 * @param value		The raw voltage register value.
241 *
242 * @retval 0		success
243 * @retval ENODEV	If @p regulator is not supported by this driver.
244 */
245METHOD int set_voltage_raw {
246	 device_t		dev;
247	 bhnd_pmu_regulator	regulator;
248	 uint32_t		value;
249} DEFAULT bhnd_pmu_null_set_voltage_raw;
250
251/**
252 * Enable the given @p regulator.
253 *
254 * @param dev		PMU device.
255 * @param regulator	Regulator to be enabled.
256 *
257 * @retval 0		success
258 * @retval ENODEV	If @p regulator is not supported by this driver.
259 */
260METHOD int enable_regulator {
261	device_t		dev;
262	bhnd_pmu_regulator	regulator;
263} DEFAULT bhnd_pmu_null_enable_regulator;
264
265/**
266 * Disable the given @p regulator.
267 *
268 * @param dev		PMU device.
269 * @param regulator	Regulator to be disabled.
270 *
271 * @retval 0		success
272 * @retval ENODEV	If @p regulator is not supported by this driver.
273 */
274METHOD int disable_regulator {
275	device_t		dev;
276	bhnd_pmu_regulator	regulator;
277} DEFAULT bhnd_pmu_null_disable_regulator;
278
279/**
280 * Return the transition latency required for @p clock in microseconds, if
281 * known.
282 *
283 * The BHND_CLOCK_HT latency value is suitable for use as the D11 core's
284 * 'fastpwrup_dly' value.
285 *
286 * @param	dev	PMU device.
287 * @param	clock	The clock to be queried for transition latency.
288 * @param[out]	latency	On success, the transition latency of @p clock in
289 *			microseconds.
290 *
291 * @retval 0		success
292 * @retval ENODEV	If the transition latency for @p clock is not available.
293 */
294METHOD int get_clock_latency {
295	device_t	 dev;
296	bhnd_clock	 clock;
297	u_int		*latency;
298} DEFAULT bhnd_pmu_null_get_clock_latency;
299
300/**
301 * Return the frequency for @p clock in Hz, if known.
302 *
303 * @param	dev	PMU device.
304 * @param	clock	The clock to be queried.
305 * @param[out]	freq	On success, the frequency of @p clock in Hz.
306 *
307 * @retval 0		success
308 * @retval ENODEV	If the frequency for @p clock is not available.
309 */
310METHOD int get_clock_freq {
311	device_t	 dev;
312	bhnd_clock	 clock;
313	u_int		*freq;
314} DEFAULT bhnd_pmu_null_get_clock_freq;
315
316/**
317 * Request that the PMU configure itself for a given hardware-specific
318 * spuravoid mode.
319 *
320 * @param dev		PMU device.
321 * @param spuravoid	The requested mode.
322 *
323 * @retval 0		success
324 * @retval ENODEV	If @p regulator is not supported by this driver.
325 */
326METHOD int request_spuravoid {
327	 device_t		dev;
328	 bhnd_pmu_spuravoid	spuravoid;
329} DEFAULT bhnd_pmu_null_request_spuravoid;
330
331/**
332 * Return the PMU's maximum state transition latency in microseconds.
333 *
334 * This upper bound may be used to busy-wait on PMU clock and resource state
335 * transitions.
336 *
337 * @param dev PMU device.
338 *
339 * @returns maximum PMU transition latency, in microseconds.
340 */
341METHOD u_int get_max_transition_latency {
342	device_t dev;
343};
344