]>
Commit | Line | Data |
---|---|---|
b2441318 | 1 | /* SPDX-License-Identifier: GPL-2.0 */ |
1da177e4 LT |
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> | |
60063497 | 12 | #include <linux/atomic.h> |
1da177e4 LT |
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; | |
1e1815be | 70 | wait_queue_head_t wait_q; |
1da177e4 LT |
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, | |
b4e3ca1a | 113 | int tmpl_len, gfp_t order); |
1da177e4 LT |
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 | */ | |
4448aaf0 | 143 | static inline int |
1da177e4 LT |
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 | */ | |
4448aaf0 | 191 | static inline void |
1da177e4 LT |
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 | |
1e1815be | 202 | wake_up(&fi->wait_q); |
1da177e4 LT |
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 | */ | |
4448aaf0 | 212 | static inline int |
1da177e4 LT |
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_ */ |