include/linux/clk-provider.h

1 /* SPDX-License-Identifier: GPL-2.0 */
3  *  Copyright (c) 2010-2011 Jeremy Kerr <jeremy.kerr@canonical.com>
4  *  Copyright (C) 2011-2012 Linaro Ltd <mturquette@linaro.org>
14  * top-level framework.  custom flags for dealing with hardware specifics
20 #define CLK_SET_PARENT_GATE	BIT(1) /* must be gated across re-parent */
26 #define CLK_SET_RATE_NO_REPARENT BIT(7) /* don't re-parent on rate change */
27 #define CLK_GET_ACCURACY_NOCACHE BIT(8) /* do not use the cached clk accuracy */
29 #define CLK_SET_RATE_UNGATE	BIT(10) /* clock needs to run to set rate */
31 /* parents need enable during gate/ungate, set rate and re-parent */
33 /* duty cycle call may be forwarded to the parent clock */
43  * struct clk_rate_request - Structure encoding the clk constraints that
44  * a clock user might require.
46  * @rate:		Requested clock rate. This field will be adjusted by
47  *			clock drivers according to hardware capabilities.
52  * @best_parent_hw:	The most appropriate parent clock that fulfills the
65  * struct clk_duty - Struture encoding the duty cycle ratio of a clock
76  * struct clk_ops -  Callback operations for hardware clocks; these are to
77  * be provided by the clock implementation, and will be called by drivers
80  * @prepare:	Prepare the clock for enabling. This must not return until
81  *		the clock is fully prepared, and it's safe to call clk_enable.
82  *		This callback is intended to allow clock implementations to
86  * @unprepare:	Release the clock from its prepared state. This will typically
90  * @is_prepared: Queries the hardware to determine if the clock is prepared.
94  * @unprepare_unused: Unprepare the clock atomically.  Only called from
98  * @enable:	Enable the clock atomically. This must not return until the
99  *		clock is generating a valid clock signal, usable by consumer
103  * @disable:	Disable the clock atomically. Called with enable_lock held.
106  * @is_enabled:	Queries the hardware to determine if the clock is enabled.
110  * @disable_unused: Disable the clock atomically.  Only called from
115  * @save_context: Save the context of the clock in prepration for poweroff.
117  * @restore_context: Restore the context of the clock after a restoration
120  * @recalc_rate	Recalculate the rate of this clock, by querying hardware. The
123  *		Returns the calculated rate.  Optional, but recommended - if
124  *		this op is not set then clock rate will be initialized to 0.
127  *		supported by the clock. The parent rate is an input/output
131  *		actually supported by the clock, and optionally the parent clock
132  *		that should be used to provide the clock rate.
134  * @set_parent:	Change the input source of this clock; for clocks with multiple
139  *		Returns 0 on success, -EERROR otherwise.
141  * @get_parent:	Queries the hardware to determine the parent of a clock.  The
143  *		the parent clock.  This index can be applied to either the
146  *		index.  Currently only called when the clock is initialized by
151  * @set_rate:	Change the rate of this clock. The requested rate is specified
155  *		Returns 0 on success, -EERROR otherwise.
157  * @set_rate_and_parent: Change the rate and the parent of this clock. The
166  *		Returns 0 on success, -EERROR otherwise.
168  * @recalc_accuracy: Recalculate the accuracy of this clock. The clock accuracy
169  *		is expressed in ppb (parts per billion). The parent accuracy is
171  *		Returns the calculated accuracy.  Optional - if	this op is not
172  *		set then clock accuracy will be initialized to parent accuracy
173  *		or 0 (perfect clock) if clock has no parent.
175  * @get_phase:	Queries the hardware to get the current phase of a clock.
176  *		Returned values are 0-359 degrees on success, negative
179  * @set_phase:	Shift the phase this clock signal in degrees specified
181  *		0-359. Return 0 on success, otherwise -EERROR.
184  *              of a clock. Returned values denominator cannot be 0 and must be
187  * @set_duty_cycle: Apply the duty cycle ratio to this clock signal specified by
190  *              and >= numerator) Return 0 on success, otherwise -EERROR.
192  * @init:	Perform platform-specific initialization magic.
193  *		This is not used by any of the basic clock types.
196  *		clock. It may also be used dynamic resource allocation is
197  *		required. It shall not used to deal with clock parameters,
199  *		Returns 0 on success, -EERROR otherwise.
203  * @debug_init:	Set up type-specific debugfs entries for this clock.  This
205  *		clock has been created.  The dentry pointer representing that
207  *		prepare_lock held.  Returns 0 on success, -EERROR otherwise.
209  * @pre_rate_change: Optional callback for a clock to fulfill its rate
211  *		its clock tree. Returns 0 on success, -EERROR otherwise.
213  * @post_rate_change: Optional callback for a clock to clean up any
214  *		requirements that were needed while the clock and its tree
215  *		was changing states. Returns 0 on success, -EERROR otherwise.
219  * (prepare) contexts.  If enabling a clock requires code that might sleep,
220  * this must be done in clk_prepare.  Clock enable code that will never be
223  * Typically, drivers will call clk_prepare when a clock may be needed later
224  * (eg. when a device is opened), and clk_enable when the clock is actually
272  * struct clk_parent_data - clk parent information
286  * struct clk_init_data - holds init data that's common to all clocks and is
287  * shared between the clock provider and the common clock framework.
289  * @name: clock name
290  * @ops: operations this clock supports
297  * @flags: framework-level hints and quirks
311  * struct clk_hw - handle for traversing from a struct clk to its corresponding
312  * hardware-specific structure.  struct clk_hw should be declared within struct
319  * @clk: pointer to the per-user struct clk instance that can be used to call
323  * with the common clock framework. This pointer will be set to NULL once
333  * DOC: Basic clock implementations common to many platforms
335  * Each basic clock hardware type is comprised of a structure describing the
336  * clock hardware, implementations of the relevant callbacks in struct clk_ops,
342  * struct clk_fixed_rate - fixed-rate clock
343  * @hw:		handle between common and hardware-specific interfaces
344  * @fixed_rate:	constant frequency of clock
345  * @fixed_accuracy: constant accuracy of clock in ppb (parts per billion)
349  * * CLK_FIXED_RATE_PARENT_ACCURACY - Use the accuracy of the parent clk
372  * clk_hw_register_fixed_rate - register fixed-rate clock with the clock
374  * @dev: device that is registering this clock
375  * @name: name of this clock
376  * @parent_name: name of clock's parent
377  * @flags: framework-specific flags
378  * @fixed_rate: non-adjustable clock rate
384  * clk_hw_register_fixed_rate_parent_hw - register fixed-rate clock with
385  * the clock framework
386  * @dev: device that is registering this clock
387  * @name: name of this clock
389  * @flags: framework-specific flags
390  * @fixed_rate: non-adjustable clock rate
397  * clk_hw_register_fixed_rate_parent_data - register fixed-rate clock with
398  * the clock framework
399  * @dev: device that is registering this clock
400  * @name: name of this clock
402  * @flags: framework-specific flags
403  * @fixed_rate: non-adjustable clock rate
411  * clk_hw_register_fixed_rate_with_accuracy - register fixed-rate clock with
412  * the clock framework
413  * @dev: device that is registering this clock
414  * @name: name of this clock
415  * @parent_name: name of clock's parent
416  * @flags: framework-specific flags
417  * @fixed_rate: non-adjustable clock rate
418  * @fixed_accuracy: non-adjustable clock accuracy
427  * clk_hw_register_fixed_rate_with_accuracy_parent_hw - register fixed-rate
428  * clock with the clock framework
429  * @dev: device that is registering this clock
430  * @name: name of this clock
432  * @flags: framework-specific flags
433  * @fixed_rate: non-adjustable clock rate
434  * @fixed_accuracy: non-adjustable clock accuracy
442  * clk_hw_register_fixed_rate_with_accuracy_parent_data - register fixed-rate
443  * clock with the clock framework
444  * @dev: device that is registering this clock
445  * @name: name of this clock
446  * @parent_name: name of clock's parent
447  * @flags: framework-specific flags
448  * @fixed_rate: non-adjustable clock rate
449  * @fixed_accuracy: non-adjustable clock accuracy
463  * struct clk_gate - gating clock
465  * @hw:		handle between common and hardware-specific interfaces
468  * @flags:	hardware-specific flags
471  * Clock which can gate its output.  Implements .enable & .disable
474  * CLK_GATE_SET_TO_DISABLE - by default this clock sets the bit at bit_idx to
475  *	enable the clock.  Setting this flag does the opposite: setting the bit
476  *	disable the clock and clearing it enables the clock
477  * CLK_GATE_HIWORD_MASK - The gate settings are only in lower 16-bit
478  *	of this register, and mask of gate bits are in higher 16-bit of this
479  *	register.  While setting the gate bits, higher 16-bit should also be
481  * CLK_GATE_BIG_ENDIAN - by default little endian register accesses are used for
512  * clk_hw_register_gate - register a gate clock with the clock framework
513  * @dev: device that is registering this clock
514  * @name: name of this clock
515  * @parent_name: name of this clock's parent
516  * @flags: framework-specific flags for this clock
517  * @reg: register address to control gating of this clock
518  * @bit_idx: which bit in the register controls gating of this clock
519  * @clk_gate_flags: gate-specific flags for this clock
520  * @lock: shared register lock for this clock
528  * clk_hw_register_gate_parent_hw - register a gate clock with the clock
530  * @dev: device that is registering this clock
531  * @name: name of this clock
533  * @flags: framework-specific flags for this clock
534  * @reg: register address to control gating of this clock
535  * @bit_idx: which bit in the register controls gating of this clock
536  * @clk_gate_flags: gate-specific flags for this clock
537  * @lock: shared register lock for this clock
545  * clk_hw_register_gate_parent_data - register a gate clock with the clock
547  * @dev: device that is registering this clock
548  * @name: name of this clock
550  * @flags: framework-specific flags for this clock
551  * @reg: register address to control gating of this clock
552  * @bit_idx: which bit in the register controls gating of this clock
553  * @clk_gate_flags: gate-specific flags for this clock
554  * @lock: shared register lock for this clock
571  * struct clk_divider - adjustable divider clock
573  * @hw:		handle between common and hardware-specific interfaces
580  * Clock with an adjustable divider affecting its output frequency.  Implements
584  * CLK_DIVIDER_ONE_BASED - by default the divisor is the value read from the
588  * CLK_DIVIDER_POWER_OF_TWO - clock divisor is 2 raised to the value read from
590  * CLK_DIVIDER_ALLOW_ZERO - Allow zero divisors.  For dividers which have
593  *	zero divisor by not modifying their input clock
595  * CLK_DIVIDER_HIWORD_MASK - The divider settings are only in lower 16-bit
596  *	of this register, and mask of divider bits are in higher 16-bit of this
597  *	register.  While setting the divider bits, higher 16-bit should also be
599  * CLK_DIVIDER_ROUND_CLOSEST - Makes the best calculated divider to be rounded
601  * CLK_DIVIDER_READ_ONLY - The divider settings are preconfigured and should
602  *	not be changed by the clock framework.
603  * CLK_DIVIDER_MAX_AT_ZERO - For dividers which are like CLK_DIVIDER_ONE_BASED
606  * CLK_DIVIDER_BIG_ENDIAN - By default little endian register accesses are used
620 #define clk_div_mask(width)	((1 << (width)) - 1)
662  * clk_register_divider - register a divider clock with the clock framework
663  * @dev: device registering this clock
664  * @name: name of this clock
665  * @parent_name: name of clock's parent
666  * @flags: framework-specific flags
670  * @clk_divider_flags: divider-specific flags for this clock
671  * @lock: shared register lock for this clock
679  * clk_hw_register_divider - register a divider clock with the clock framework
680  * @dev: device registering this clock
681  * @name: name of this clock
682  * @parent_name: name of clock's parent
683  * @flags: framework-specific flags
687  * @clk_divider_flags: divider-specific flags for this clock
688  * @lock: shared register lock for this clock
696  * clk_hw_register_divider_parent_hw - register a divider clock with the clock
698  * @dev: device registering this clock
699  * @name: name of this clock
701  * @flags: framework-specific flags
705  * @clk_divider_flags: divider-specific flags for this clock
706  * @lock: shared register lock for this clock
715  * clk_hw_register_divider_parent_data - register a divider clock with the clock
717  * @dev: device registering this clock
718  * @name: name of this clock
720  * @flags: framework-specific flags
724  * @clk_divider_flags: divider-specific flags for this clock
725  * @lock: shared register lock for this clock
734  * clk_hw_register_divider_table - register a table based divider clock with
735  * the clock framework
736  * @dev: device registering this clock
737  * @name: name of this clock
738  * @parent_name: name of clock's parent
739  * @flags: framework-specific flags
743  * @clk_divider_flags: divider-specific flags for this clock
745  * @lock: shared register lock for this clock
754  * clk_hw_register_divider_table_parent_hw - register a table based divider
755  * clock with the clock framework
756  * @dev: device registering this clock
757  * @name: name of this clock
759  * @flags: framework-specific flags
763  * @clk_divider_flags: divider-specific flags for this clock
765  * @lock: shared register lock for this clock
775  * clk_hw_register_divider_table_parent_data - register a table based divider
776  * clock with the clock framework
777  * @dev: device registering this clock
778  * @name: name of this clock
780  * @flags: framework-specific flags
784  * @clk_divider_flags: divider-specific flags for this clock
786  * @lock: shared register lock for this clock
801  * struct clk_mux - multiplexer clock
803  * @hw:		handle between common and hardware-specific interfaces
808  * @flags:	hardware-specific flags
811  * Clock with multiple selectable parents.  Implements .get_parent, .set_parent
815  * CLK_MUX_INDEX_ONE - register index starts at 1, not 0
816  * CLK_MUX_INDEX_BIT - register index is a single bit (power of two)
817  * CLK_MUX_HIWORD_MASK - The mux settings are only in lower 16-bit of this
818  *	register, and mask of mux bits are in higher 16-bit of this register.
819  *	While setting the mux bits, higher 16-bit should also be updated to
821  * CLK_MUX_READ_ONLY - The mux registers can't be written, only read in the
823  * CLK_MUX_ROUND_CLOSEST - Use the parent rate that is closest to the desired
825  * CLK_MUX_BIG_ENDIAN - By default little endian register accesses are used for
866 			       (flags), (reg), (shift), BIT((width)) - 1,     \
879 			      (shift), BIT((width)) - 1, (clk_mux_flags),     \
885 			      BIT((width)) - 1, (clk_mux_flags), NULL, (lock))
891 			      BIT((width)) - 1, (clk_mux_flags), NULL, (lock))
903  * struct clk_fixed_factor - fixed multiplier and divider clock
905  * @hw:		handle between common and hardware-specific interfaces
909  * Clock with a fixed multiplier and divider. The output frequency is the
910  * parent clock rate divided by div and multiplied by mult.
933  * struct clk_fractional_divider - adjustable fractional divider clock
935  * @hw:		handle between common and hardware-specific interfaces
943  * Clock with adjustable fractional divider affecting its output frequency.
946  * CLK_FRAC_DIVIDER_ZERO_BASED - by default the numerator and denominator
950  * CLK_FRAC_DIVIDER_BIG_ENDIAN - By default little endian register accesses are
953  * CLK_FRAC_DIVIDER_NO_LIMIT - not need to follow the 20 times limit on
990  * struct clk_multiplier - adjustable multiplier clock
992  * @hw:		handle between common and hardware-specific interfaces
998  * Clock with an adjustable multiplier affecting its output frequency.
1002  * CLK_MULTIPLIER_ZERO_BYPASS - By default, the multiplier is the value read
1004  *	zeroing the output clock rate. If CLK_MULTIPLIER_ZERO_BYPASS is
1007  * CLK_MULTIPLIER_ROUND_CLOSEST - Makes the best calculated divider to be
1009  * CLK_MULTIPLIER_BIG_ENDIAN - By default little endian register accesses are
1031  * struct clk_composite - aggregate clock of mux, divider and gate clocks
1033  * @hw:		handle between common and hardware-specific interfaces
1034  * @mux_hw:	handle between composite and hardware-specific mux clock
1035  * @rate_hw:	handle between composite and hardware-specific rate clock
1036  * @gate_hw:	handle between composite and hardware-specific gate clock
1037  * @mux_ops:	clock ops for mux
1038  * @rate_ops:	clock ops for rate
1039  * @gate_ops:	clock ops for gate
1142 	dst->clk = src->clk;  in __clk_hw_set_clk()
1143 	dst->core = src->core;  in __clk_hw_set_clk()
1167  * FIXME clock api without lock protection
1377 	return ERR_PTR(-ENOENT);  in of_clk_src_simple_get()
1382 	return ERR_PTR(-ENOENT);  in of_clk_hw_simple_get()
1387 	return ERR_PTR(-ENOENT);  in of_clk_src_onecell_get()
1392 	return ERR_PTR(-ENOENT);  in of_clk_hw_onecell_get()