]>
Commit | Line | Data |
---|---|---|
1da177e4 LT |
1 | /* $Id: fsm.h,v 1.1.1.1 2002/03/13 19:33:09 mschwide Exp $ |
2 | */ | |
3 | #ifndef _FSM_H_ | |
4 | #define _FSM_H_ | |
5 | ||
6 | #include <linux/kernel.h> | |
7 | #include <linux/types.h> | |
8 | #include <linux/timer.h> | |
9 | #include <linux/time.h> | |
10 | #include <linux/slab.h> | |
11 | #include <linux/sched.h> | |
12 | #include <linux/string.h> | |
13 | #include <asm/atomic.h> | |
14 | ||
15 | /** | |
16 | * Define this to get debugging messages. | |
17 | */ | |
18 | #define FSM_DEBUG 0 | |
19 | ||
20 | /** | |
21 | * Define this to get debugging massages for | |
22 | * timer handling. | |
23 | */ | |
24 | #define FSM_TIMER_DEBUG 0 | |
25 | ||
26 | /** | |
27 | * Define these to record a history of | |
28 | * Events/Statechanges and print it if a | |
29 | * action_function is not found. | |
30 | */ | |
31 | #define FSM_DEBUG_HISTORY 0 | |
32 | #define FSM_HISTORY_SIZE 40 | |
33 | ||
34 | struct fsm_instance_t; | |
35 | ||
36 | /** | |
37 | * Definition of an action function, called by a FSM | |
38 | */ | |
39 | typedef void (*fsm_function_t)(struct fsm_instance_t *, int, void *); | |
40 | ||
41 | /** | |
42 | * Internal jump table for a FSM | |
43 | */ | |
44 | typedef struct { | |
45 | fsm_function_t *jumpmatrix; | |
46 | int nr_events; | |
47 | int nr_states; | |
48 | const char **event_names; | |
49 | const char **state_names; | |
50 | } fsm; | |
51 | ||
52 | #if FSM_DEBUG_HISTORY | |
53 | /** | |
54 | * Element of State/Event history used for debugging. | |
55 | */ | |
56 | typedef struct { | |
57 | int state; | |
58 | int event; | |
59 | } fsm_history; | |
60 | #endif | |
61 | ||
62 | /** | |
63 | * Representation of a FSM | |
64 | */ | |
65 | typedef struct fsm_instance_t { | |
66 | fsm *f; | |
67 | atomic_t state; | |
68 | char name[16]; | |
69 | void *userdata; | |
70 | int userint; | |
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, int 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 | extern __inline__ int | |
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 | extern __inline__ void | |
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 | } | |
203 | ||
204 | /** | |
205 | * Retrieves the state of an FSM | |
206 | * | |
207 | * @param fi Pointer to FSM | |
208 | * | |
209 | * @return The current state of the FSM. | |
210 | */ | |
211 | extern __inline__ int | |
212 | fsm_getstate(fsm_instance *fi) | |
213 | { | |
214 | return atomic_read(&fi->state); | |
215 | } | |
216 | ||
217 | /** | |
218 | * Retrieves the name of the state of an FSM | |
219 | * | |
220 | * @param fi Pointer to FSM | |
221 | * | |
222 | * @return The current state of the FSM in a human readable form. | |
223 | */ | |
224 | extern const char *fsm_getstate_str(fsm_instance *fi); | |
225 | ||
226 | /** | |
227 | * Initializes a timer for an FSM. | |
228 | * This prepares an fsm_timer for usage with fsm_addtimer. | |
229 | * | |
230 | * @param fi Pointer to FSM | |
231 | * @param timer The timer to be initialized. | |
232 | */ | |
233 | extern void fsm_settimer(fsm_instance *fi, fsm_timer *); | |
234 | ||
235 | /** | |
236 | * Clears a pending timer of an FSM instance. | |
237 | * | |
238 | * @param timer The timer to clear. | |
239 | */ | |
240 | extern void fsm_deltimer(fsm_timer *timer); | |
241 | ||
242 | /** | |
243 | * Adds and starts a timer to an FSM instance. | |
244 | * | |
245 | * @param timer The timer to be added. The field fi of that timer | |
246 | * must have been set to point to the instance. | |
247 | * @param millisec Duration, after which the timer should expire. | |
248 | * @param event Event, to trigger if timer expires. | |
249 | * @param arg Generic argument, provided to expiry function. | |
250 | * | |
251 | * @return 0 on success, -1 if timer is already active. | |
252 | */ | |
253 | extern int fsm_addtimer(fsm_timer *timer, int millisec, int event, void *arg); | |
254 | ||
255 | /** | |
256 | * Modifies a timer of an FSM. | |
257 | * | |
258 | * @param timer The timer to modify. | |
259 | * @param millisec Duration, after which the timer should expire. | |
260 | * @param event Event, to trigger if timer expires. | |
261 | * @param arg Generic argument, provided to expiry function. | |
262 | */ | |
263 | extern void fsm_modtimer(fsm_timer *timer, int millisec, int event, void *arg); | |
264 | ||
265 | #endif /* _FSM_H_ */ |