1 /* SPDX-License-Identifier: GPL-2.0 */
2 /*  linux/include/linux/clockchips.h
3  *
4  *  This file contains the structure definitions for clockchips.
5  *
6  *  If you are not a clockchip, or the time of day code, you should
7  *  not be including this file!
8  */
9 #ifndef _LINUX_CLOCKCHIPS_H
10 #define _LINUX_CLOCKCHIPS_H
11 
12 #ifdef CONFIG_GENERIC_CLOCKEVENTS
13 
14 # include <linux/clocksource.h>
15 # include <linux/cpumask.h>
16 # include <linux/ktime.h>
17 # include <linux/notifier.h>
18 
19 struct clock_event_device;
20 struct module;
21 
22 /*
23  * Possible states of a clock event device.
24  *
25  * DETACHED:	Device is not used by clockevents core. Initial state or can be
26  *		reached from SHUTDOWN.
27  * SHUTDOWN:	Device is powered-off. Can be reached from PERIODIC or ONESHOT.
28  * PERIODIC:	Device is programmed to generate events periodically. Can be
29  *		reached from DETACHED or SHUTDOWN.
30  * ONESHOT:	Device is programmed to generate event only once. Can be reached
31  *		from DETACHED or SHUTDOWN.
32  * ONESHOT_STOPPED: Device was programmed in ONESHOT mode and is temporarily
33  *		    stopped.
34  */
35 enum clock_event_state {
36 	CLOCK_EVT_STATE_DETACHED,
37 	CLOCK_EVT_STATE_SHUTDOWN,
38 	CLOCK_EVT_STATE_PERIODIC,
39 	CLOCK_EVT_STATE_ONESHOT,
40 	CLOCK_EVT_STATE_ONESHOT_STOPPED,
41 };
42 
43 /*
44  * Clock event features
45  */
46 # define CLOCK_EVT_FEAT_PERIODIC	0x000001
47 # define CLOCK_EVT_FEAT_ONESHOT		0x000002
48 # define CLOCK_EVT_FEAT_KTIME		0x000004
49 
50 /*
51  * x86(64) specific (mis)features:
52  *
53  * - Clockevent source stops in C3 State and needs broadcast support.
54  * - Local APIC timer is used as a dummy device.
55  */
56 # define CLOCK_EVT_FEAT_C3STOP		0x000008
57 # define CLOCK_EVT_FEAT_DUMMY		0x000010
58 
59 /*
60  * Core shall set the interrupt affinity dynamically in broadcast mode
61  */
62 # define CLOCK_EVT_FEAT_DYNIRQ		0x000020
63 # define CLOCK_EVT_FEAT_PERCPU		0x000040
64 
65 /*
66  * Clockevent device is based on a hrtimer for broadcast
67  */
68 # define CLOCK_EVT_FEAT_HRTIMER		0x000080
69 
70 /**
71  * struct clock_event_device - clock event device descriptor
72  * @event_handler:	Assigned by the framework to be called by the low
73  *			level handler of the event source
74  * @set_next_event:	set next event function using a clocksource delta
75  * @set_next_ktime:	set next event function using a direct ktime value
76  * @next_event:		local storage for the next event in oneshot mode
77  * @max_delta_ns:	maximum delta value in ns
78  * @min_delta_ns:	minimum delta value in ns
79  * @mult:		nanosecond to cycles multiplier
80  * @shift:		nanoseconds to cycles divisor (power of two)
81  * @state_use_accessors:current state of the device, assigned by the core code
82  * @features:		features
83  * @retries:		number of forced programming retries
84  * @set_state_periodic:	switch state to periodic
85  * @set_state_oneshot:	switch state to oneshot
86  * @set_state_oneshot_stopped: switch state to oneshot_stopped
87  * @set_state_shutdown:	switch state to shutdown
88  * @tick_resume:	resume clkevt device
89  * @broadcast:		function to broadcast events
90  * @min_delta_ticks:	minimum delta value in ticks stored for reconfiguration
91  * @max_delta_ticks:	maximum delta value in ticks stored for reconfiguration
92  * @name:		ptr to clock event name
93  * @rating:		variable to rate clock event devices
94  * @irq:		IRQ number (only for non CPU local devices)
95  * @bound_on:		Bound on CPU
96  * @cpumask:		cpumask to indicate for which CPUs this device works
97  * @list:		list head for the management code
98  * @owner:		module reference
99  */
100 struct clock_event_device {
101 	void			(*event_handler)(struct clock_event_device *);
102 	int			(*set_next_event)(unsigned long evt, struct clock_event_device *);
103 	int			(*set_next_ktime)(ktime_t expires, struct clock_event_device *);
104 	ktime_t			next_event;
105 	u64			max_delta_ns;
106 	u64			min_delta_ns;
107 	u32			mult;
108 	u32			shift;
109 	enum clock_event_state	state_use_accessors;
110 	unsigned int		features;
111 	unsigned long		retries;
112 
113 	int			(*set_state_periodic)(struct clock_event_device *);
114 	int			(*set_state_oneshot)(struct clock_event_device *);
115 	int			(*set_state_oneshot_stopped)(struct clock_event_device *);
116 	int			(*set_state_shutdown)(struct clock_event_device *);
117 	int			(*tick_resume)(struct clock_event_device *);
118 
119 	void			(*broadcast)(const struct cpumask *mask);
120 	void			(*suspend)(struct clock_event_device *);
121 	void			(*resume)(struct clock_event_device *);
122 	unsigned long		min_delta_ticks;
123 	unsigned long		max_delta_ticks;
124 
125 	const char		*name;
126 	int			rating;
127 	int			irq;
128 	int			bound_on;
129 	const struct cpumask	*cpumask;
130 	struct list_head	list;
131 	struct module		*owner;
132 } ____cacheline_aligned;
133 
134 /* Helpers to verify state of a clockevent device */
clockevent_state_detached(struct clock_event_device * dev)135 static inline bool clockevent_state_detached(struct clock_event_device *dev)
136 {
137 	return dev->state_use_accessors == CLOCK_EVT_STATE_DETACHED;
138 }
139 
clockevent_state_shutdown(struct clock_event_device * dev)140 static inline bool clockevent_state_shutdown(struct clock_event_device *dev)
141 {
142 	return dev->state_use_accessors == CLOCK_EVT_STATE_SHUTDOWN;
143 }
144 
clockevent_state_periodic(struct clock_event_device * dev)145 static inline bool clockevent_state_periodic(struct clock_event_device *dev)
146 {
147 	return dev->state_use_accessors == CLOCK_EVT_STATE_PERIODIC;
148 }
149 
clockevent_state_oneshot(struct clock_event_device * dev)150 static inline bool clockevent_state_oneshot(struct clock_event_device *dev)
151 {
152 	return dev->state_use_accessors == CLOCK_EVT_STATE_ONESHOT;
153 }
154 
clockevent_state_oneshot_stopped(struct clock_event_device * dev)155 static inline bool clockevent_state_oneshot_stopped(struct clock_event_device *dev)
156 {
157 	return dev->state_use_accessors == CLOCK_EVT_STATE_ONESHOT_STOPPED;
158 }
159 
160 /*
161  * Calculate a multiplication factor for scaled math, which is used to convert
162  * nanoseconds based values to clock ticks:
163  *
164  * clock_ticks = (nanoseconds * factor) >> shift.
165  *
166  * div_sc is the rearranged equation to calculate a factor from a given clock
167  * ticks / nanoseconds ratio:
168  *
169  * factor = (clock_ticks << shift) / nanoseconds
170  */
171 static inline unsigned long
div_sc(unsigned long ticks,unsigned long nsec,int shift)172 div_sc(unsigned long ticks, unsigned long nsec, int shift)
173 {
174 	u64 tmp = ((u64)ticks) << shift;
175 
176 	do_div(tmp, nsec);
177 
178 	return (unsigned long) tmp;
179 }
180 
181 /* Clock event layer functions */
182 extern u64 clockevent_delta2ns(unsigned long latch, struct clock_event_device *evt);
183 extern void clockevents_register_device(struct clock_event_device *dev);
184 extern int clockevents_unbind_device(struct clock_event_device *ced, int cpu);
185 
186 extern void clockevents_config_and_register(struct clock_event_device *dev,
187 					    u32 freq, unsigned long min_delta,
188 					    unsigned long max_delta);
189 
190 extern int clockevents_update_freq(struct clock_event_device *ce, u32 freq);
191 
192 static inline void
clockevents_calc_mult_shift(struct clock_event_device * ce,u32 freq,u32 maxsec)193 clockevents_calc_mult_shift(struct clock_event_device *ce, u32 freq, u32 maxsec)
194 {
195 	return clocks_calc_mult_shift(&ce->mult, &ce->shift, NSEC_PER_SEC, freq, maxsec);
196 }
197 
198 extern void clockevents_suspend(void);
199 extern void clockevents_resume(void);
200 
201 # ifdef CONFIG_GENERIC_CLOCKEVENTS_BROADCAST
202 #  ifdef CONFIG_ARCH_HAS_TICK_BROADCAST
203 extern void tick_broadcast(const struct cpumask *mask);
204 #  else
205 #   define tick_broadcast	NULL
206 #  endif
207 extern int tick_receive_broadcast(void);
208 # endif
209 
210 # if defined(CONFIG_GENERIC_CLOCKEVENTS_BROADCAST) && defined(CONFIG_TICK_ONESHOT)
211 extern void tick_setup_hrtimer_broadcast(void);
212 extern int tick_check_broadcast_expired(void);
213 # else
tick_check_broadcast_expired(void)214 static __always_inline int tick_check_broadcast_expired(void) { return 0; }
tick_setup_hrtimer_broadcast(void)215 static inline void tick_setup_hrtimer_broadcast(void) { }
216 # endif
217 
218 #else /* !CONFIG_GENERIC_CLOCKEVENTS: */
219 
clockevents_suspend(void)220 static inline void clockevents_suspend(void) { }
clockevents_resume(void)221 static inline void clockevents_resume(void) { }
tick_check_broadcast_expired(void)222 static __always_inline int tick_check_broadcast_expired(void) { return 0; }
tick_setup_hrtimer_broadcast(void)223 static inline void tick_setup_hrtimer_broadcast(void) { }
224 
225 #endif /* !CONFIG_GENERIC_CLOCKEVENTS */
226 
227 #endif /* _LINUX_CLOCKCHIPS_H */
228