1 /* SPDX-License-Identifier: GPL-2.0 */
2 #ifndef _FSM_H_
3 #define _FSM_H_
4 
5 #include <linux/kernel.h>
6 #include <linux/types.h>
7 #include <linux/timer.h>
8 #include <linux/time.h>
9 #include <linux/slab.h>
10 #include <linux/sched.h>
11 #include <linux/string.h>
12 #include <linux/atomic.h>
13 
14 /**
15  * Define this to get debugging messages.
16  */
17 #define FSM_DEBUG         0
18 
19 /**
20  * Define this to get debugging massages for
21  * timer handling.
22  */
23 #define FSM_TIMER_DEBUG   0
24 
25 /**
26  * Define these to record a history of
27  * Events/Statechanges and print it if a
28  * action_function is not found.
29  */
30 #define FSM_DEBUG_HISTORY 0
31 #define FSM_HISTORY_SIZE  40
32 
33 struct fsm_instance_t;
34 
35 /**
36  * Definition of an action function, called by a FSM
37  */
38 typedef void (*fsm_function_t)(struct fsm_instance_t *, int, void *);
39 
40 /**
41  * Internal jump table for a FSM
42  */
43 typedef struct {
44 	fsm_function_t *jumpmatrix;
45 	int nr_events;
46 	int nr_states;
47 	const char **event_names;
48 	const char **state_names;
49 } fsm;
50 
51 #if FSM_DEBUG_HISTORY
52 /**
53  * Element of State/Event history used for debugging.
54  */
55 typedef struct {
56 	int state;
57 	int event;
58 } fsm_history;
59 #endif
60 
61 /**
62  * Representation of a FSM
63  */
64 typedef struct fsm_instance_t {
65 	fsm *f;
66 	atomic_t state;
67 	char name[16];
68 	void *userdata;
69 	int userint;
70 	wait_queue_head_t wait_q;
71 #if FSM_DEBUG_HISTORY
72 	int         history_index;
73 	int         history_size;
74 	fsm_history history[FSM_HISTORY_SIZE];
75 #endif
76 } fsm_instance;
77 
78 /**
79  * Description of a state-event combination
80  */
81 typedef struct {
82 	int cond_state;
83 	int cond_event;
84 	fsm_function_t function;
85 } fsm_node;
86 
87 /**
88  * Description of a FSM Timer.
89  */
90 typedef struct {
91 	fsm_instance *fi;
92 	struct timer_list tl;
93 	int expire_event;
94 	void *event_arg;
95 } fsm_timer;
96 
97 /**
98  * Creates an FSM
99  *
100  * @param name        Name of this instance for logging purposes.
101  * @param state_names An array of names for all states for logging purposes.
102  * @param event_names An array of names for all events for logging purposes.
103  * @param nr_states   Number of states for this instance.
104  * @param nr_events   Number of events for this instance.
105  * @param tmpl        An array of fsm_nodes, describing this FSM.
106  * @param tmpl_len    Length of the describing array.
107  * @param order       Parameter for allocation of the FSM data structs.
108  */
109 extern fsm_instance *
110 init_fsm(char *name, const char **state_names,
111 	 const char **event_names,
112 	 int nr_states, int nr_events, const fsm_node *tmpl,
113 	 int tmpl_len, gfp_t order);
114 
115 /**
116  * Releases an FSM
117  *
118  * @param fi Pointer to an FSM, previously created with init_fsm.
119  */
120 extern void kfree_fsm(fsm_instance *fi);
121 
122 #if FSM_DEBUG_HISTORY
123 extern void
124 fsm_print_history(fsm_instance *fi);
125 
126 extern void
127 fsm_record_history(fsm_instance *fi, int state, int event);
128 #endif
129 
130 /**
131  * Emits an event to a FSM.
132  * If an action function is defined for the current state/event combination,
133  * this function is called.
134  *
135  * @param fi    Pointer to FSM which should receive the event.
136  * @param event The event do be delivered.
137  * @param arg   A generic argument, handed to the action function.
138  *
139  * @return      0  on success,
140  *              1  if current state or event is out of range
141  *              !0 if state and event in range, but no action defined.
142  */
143 static inline int
fsm_event(fsm_instance * fi,int event,void * arg)144 fsm_event(fsm_instance *fi, int event, void *arg)
145 {
146 	fsm_function_t r;
147 	int state = atomic_read(&fi->state);
148 
149 	if ((state >= fi->f->nr_states) ||
150 	    (event >= fi->f->nr_events)       ) {
151 		printk(KERN_ERR "fsm(%s): Invalid state st(%ld/%ld) ev(%d/%ld)\n",
152 			fi->name, (long)state,(long)fi->f->nr_states, event,
153 			(long)fi->f->nr_events);
154 #if FSM_DEBUG_HISTORY
155 		fsm_print_history(fi);
156 #endif
157 		return 1;
158 	}
159 	r = fi->f->jumpmatrix[fi->f->nr_states * event + state];
160 	if (r) {
161 #if FSM_DEBUG
162 		printk(KERN_DEBUG "fsm(%s): state %s event %s\n",
163 		       fi->name, fi->f->state_names[state],
164 		       fi->f->event_names[event]);
165 #endif
166 #if FSM_DEBUG_HISTORY
167 		fsm_record_history(fi, state, event);
168 #endif
169 		r(fi, event, arg);
170 		return 0;
171 	} else {
172 #if FSM_DEBUG || FSM_DEBUG_HISTORY
173 		printk(KERN_DEBUG "fsm(%s): no function for event %s in state %s\n",
174 		       fi->name, fi->f->event_names[event],
175 		       fi->f->state_names[state]);
176 #endif
177 #if FSM_DEBUG_HISTORY
178 		fsm_print_history(fi);
179 #endif
180 		return !0;
181 	}
182 }
183 
184 /**
185  * Modifies the state of an FSM.
186  * This does <em>not</em> trigger an event or calls an action function.
187  *
188  * @param fi    Pointer to FSM
189  * @param state The new state for this FSM.
190  */
191 static inline void
fsm_newstate(fsm_instance * fi,int newstate)192 fsm_newstate(fsm_instance *fi, int newstate)
193 {
194 	atomic_set(&fi->state,newstate);
195 #if FSM_DEBUG_HISTORY
196 	fsm_record_history(fi, newstate, -1);
197 #endif
198 #if FSM_DEBUG
199 	printk(KERN_DEBUG "fsm(%s): New state %s\n", fi->name,
200 		fi->f->state_names[newstate]);
201 #endif
202 	wake_up(&fi->wait_q);
203 }
204 
205 /**
206  * Retrieves the state of an FSM
207  *
208  * @param fi Pointer to FSM
209  *
210  * @return The current state of the FSM.
211  */
212 static inline int
fsm_getstate(fsm_instance * fi)213 fsm_getstate(fsm_instance *fi)
214 {
215 	return atomic_read(&fi->state);
216 }
217 
218 /**
219  * Retrieves the name of the state of an FSM
220  *
221  * @param fi Pointer to FSM
222  *
223  * @return The current state of the FSM in a human readable form.
224  */
225 extern const char *fsm_getstate_str(fsm_instance *fi);
226 
227 /**
228  * Initializes a timer for an FSM.
229  * This prepares an fsm_timer for usage with fsm_addtimer.
230  *
231  * @param fi    Pointer to FSM
232  * @param timer The timer to be initialized.
233  */
234 extern void fsm_settimer(fsm_instance *fi, fsm_timer *);
235 
236 /**
237  * Clears a pending timer of an FSM instance.
238  *
239  * @param timer The timer to clear.
240  */
241 extern void fsm_deltimer(fsm_timer *timer);
242 
243 /**
244  * Adds and starts a timer to an FSM instance.
245  *
246  * @param timer    The timer to be added. The field fi of that timer
247  *                 must have been set to point to the instance.
248  * @param millisec Duration, after which the timer should expire.
249  * @param event    Event, to trigger if timer expires.
250  * @param arg      Generic argument, provided to expiry function.
251  *
252  * @return         0 on success, -1 if timer is already active.
253  */
254 extern int fsm_addtimer(fsm_timer *timer, int millisec, int event, void *arg);
255 
256 /**
257  * Modifies a timer of an FSM.
258  *
259  * @param timer    The timer to modify.
260  * @param millisec Duration, after which the timer should expire.
261  * @param event    Event, to trigger if timer expires.
262  * @param arg      Generic argument, provided to expiry function.
263  */
264 extern void fsm_modtimer(fsm_timer *timer, int millisec, int event, void *arg);
265 
266 #endif /* _FSM_H_ */
267